Docs / Component Reference

Component Reference

Complete reference for all custom components shipped with the enterprise theme.

Components

---

ActionItems

A rich, stateful action item list with status lifecycle tracking, person assignments, priority badges, due dates, comment slots, tags, hierarchical numbering, inline editing, section-based grouping, drag-and-drop reordering, nesting, keyboard navigation, multi-select, bulk operations, faceted filtering, sorting, clipboard, and export.

Quick Start

<link rel="stylesheet" href="components/actionitems/actionitems.css">
<script src="components/actionitems/actionitems.js"></script>

const list = createActionItems({
    container: "my-container",
    items: [
        {
            id: "1",
            index: 1,
            order: 1,
            content: "Review Q3 budget",
            status: "not-started",
            priority: "high",
            dueDate: "2026-03-20",
            tags: [],
            commentCount: 0,
            createdAt: new Date().toISOString(),
            updatedAt: new Date().toISOString()
        }
    ],
    onStatusChange: (id, oldS, newS) => console.log(id, oldS, "->", newS)
});

Features

• Status lifecycle -- Not Started, In Progress, Done, Archived with click-to-cycle and keyboard toggle
• Priority badges -- High, Medium, Low with colour-coded indicators
• Due dates -- relative display (overdue, today, this week) with overdue highlighting
• Person assignment -- PersonChip integration with avatar and name display
• Tags -- Pill-based coloured labels per item
• Comment slots -- expandable comment area with count badge; consumer renders content via callback
• Hierarchical nesting -- parent/child items with indented rendering and Tab/Shift+Tab indent/outdent
• Inline editing -- double-click to edit content; Enter to confirm, Escape to cancel
• Section grouping -- items grouped by status with collapsible section headers and counts
• Drag-and-drop reordering -- drag handle with visual drop indicator and cross-section moves
• Keyboard navigation -- full arrow key nav, Space to cycle status, Enter to edit, Delete to remove
• Multi-select -- click with Ctrl/Shift for range selection; visual selection indicators
• Bulk operations -- bulk status change, bulk delete, bulk assign on selected items
• Faceted filtering -- filter by status, assignee, priority, due date facet, and tags
• Sorting -- 10 sort options including manual order, created, modified, priority, due date, assignee
• Clipboard -- Ctrl+C/X/V/A for copy/cut/paste/select-all in markdown checklist format
• Export -- JSON and markdown export with import from markdown checklists
• Full/Compact modes -- full mode with all features; compact mode for sidebars and dashboards
• Dark mode -- fully compatible via var(--theme-*) CSS custom properties

Configuration Options

Public API

Event Callbacks

Keyboard Shortcuts

Compact Mode

createActionItems({
    container: "sidebar-tasks",
    items: myItems,
    mode: "compact",
    groupByStatus: false,
    showComments: false,
    showTags: false,
    allowNesting: false,
    placeholder: "Quick add..."
});

Compact mode reduces padding and hides comment slots and tag displays for use in space-constrained contexts such as sidebar panels and dashboard widgets.

Sort Options

Integration Notes

• PersonChip -- assignee display renders as a PersonChip (avatar + name) when the PersonChip component is loaded. Falls back to a plain text span.
• Pill -- tags render as Pill elements when the Pill component is loaded. Falls back to coloured spans.
• Comment slot -- the onRenderCommentSlot callback receives a container element; the consumer is responsible for rendering comment UI (e.g., a CommentOverlay or custom thread) into it.
• Clipboard -- copy/paste uses markdown checklist format (- [ ] item, - [x] done) for interoperability with external tools.
• Export -- JSON export includes all item metadata; markdown export produces a human-readable checklist with priority and due date annotations.

Status Lifecycle

Not Started  ──>  In Progress  ──>  Done
    ⬡                ◐              ✓

Items cycle through statuses via click on the status indicator or Space key. The "archived" status is available programmatically via updateItem() but does not appear in the cycle.

---

ActivityFeed

Social-style activity feed with date grouping, infinite scroll, real-time additions, and compact mode.

Usage

<link rel="stylesheet" href="components/activityfeed/activityfeed.css">
<script src="components/activityfeed/activityfeed.js"></script>

const feed = createActivityFeed({
    events: [
        {
            id: "1",
            actor: { id: "u1", name: "Jane Doe" },
            action: "commented on",
            target: "Project Alpha",
            targetUrl: "/projects/alpha",
            timestamp: new Date(),
            eventType: "comment",
            content: "Looking great! Let's ship this week."
        }
    ],
    height: "400px",
    onLoadMore: async () => fetchMoreEvents(),
    onEventClick: (ev) => console.log("Clicked:", ev.id),
}, "my-container");

Options

API

Event Types

---

AnchorLayout

A constraint-based layout container that positions children by declaring anchor relationships between child edges and container edges. Children stretch or float based on which edges are anchored. Uses CSS position: relative on the container and position: absolute on children. Inspired by Android ConstraintLayout, Qt AnchorLayout, and WPF Canvas with anchoring.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/anchorlayout/anchorlayout.css">
<script src="components/anchorlayout/anchorlayout.js"></script>

<script>
    // Pin a button to the bottom-right corner
    var saveBtn = document.createElement("button");
    saveBtn.textContent = "Save";
    saveBtn.className = "btn btn-primary";

    var layout = createAnchorLayout({
        height: "400px",
        width: "100%",
        children: [
            {
                child: saveBtn,
                anchorBottom: 16,
                anchorRight: 16
            }
        ]
    });
</script>

How It Works

AnchorLayout creates a position: relative container. Each child is wrapped in a position: absolute div whose top, bottom, left, right, and transform properties are set based on anchor declarations.

Container (position: relative)
┌──────────────────────────────────────────────────────────┐
│                                                          │
│  anchorTop: 10 ──────────────────── anchorTop: 10        │
│  anchorLeft: 10                     anchorRight: 10      │
│  ┌──────────┐                       ┌──────────┐        │
│  │ Child A  │                       │ Child B  │        │
│  │ (floats  │                       │ (floats  │        │
│  │  top-left│                       │ top-right│        │
│  └──────────┘                       └──────────┘        │
│                                                          │
│                  ┌──────────┐                            │
│                  │ Child C  │ anchorCenterH: 0           │
│                  │ (centered│ anchorCenterV: 0           │
│                  │  both)   │                            │
│                  └──────────┘                            │
│                                                          │
│  anchorTop: 0    ┌────────────────────────────┐          │
│  anchorBottom: 0 │ Child D (stretches         │          │
│  anchorLeft: 0   │  to fill — all 4 edges     │          │
│                  │  anchored)                  │          │
│                  └────────────────────────────┘          │
│                                                          │
└──────────────────────────────────────────────────────────┘

Options

AnchorLayoutOptions

AnchorChildConfig

Anchor Rules

Dual-Edge Stretching

When both opposing edges are anchored, the child stretches to fill the space between them.

// Stretches horizontally between 10px from left and 10px from right
{ child: panel, anchorLeft: 10, anchorRight: 10 }

// Stretches both directions — fills the entire container with 20px margin
{ child: overlay, anchorTop: 20, anchorBottom: 20, anchorLeft: 20, anchorRight: 20 }

Single-Edge Floating

When only one edge is anchored, the child floats at that offset and uses its natural size.

// Floats at top-left corner
{ child: logo, anchorTop: 0, anchorLeft: 0 }

// Floats at bottom-right with 16px inset
{ child: fab, anchorBottom: 16, anchorRight: 16 }

Center Anchoring

Use anchorCenterH and anchorCenterV to center a child along one or both axes. The value is an optional offset from center.

// Centered both horizontally and vertically
{ child: spinner, anchorCenterH: 0, anchorCenterV: 0 }

// Centered horizontally, 30px from top
{ child: title, anchorCenterH: 0, anchorTop: 30 }

// Centered vertically with 20px rightward offset
{ child: sidebar, anchorCenterV: 0, anchorCenterH: 20 }

Note: Center anchoring uses CSS transform: translate(). When both anchorCenterH and anchorCenterV are set, they combine into a single translate(-50%, -50%). Non-zero offsets are applied via margin-left or margin-top.

Public API

AnchorLayoutState

interface AnchorLayoutState {
    childCount: number;
}

Composability

AnchorLayout implements the standard layout container contract. Any component with show(container) / hide() / destroy() can be used as a child. Plain HTMLElements are also supported.

// Pin a toolbar at the top, a status bar at the bottom,
// and fill the center with a content panel
var layout = new AnchorLayout({
    height: "100vh",
    width: "100%",
    children: [
        { child: toolbar, anchorTop: 0, anchorLeft: 0, anchorRight: 0 },
        { child: content, anchorTop: 48, anchorBottom: 32, anchorLeft: 0, anchorRight: 0 },
        { child: statusBar, anchorBottom: 0, anchorLeft: 0, anchorRight: 0 }
    ]
});

Global Exports

When loaded via <script> tag:

• window.AnchorLayout — AnchorLayout class
• window.createAnchorLayout — Factory function (creates and shows)

CSS Classes

---

AnglePicker

A circular dial input for selecting angles from 0 to 360 degrees. Supports both inline (always-visible dial for property panels) and dropdown (compact trigger button for toolbars) modes. Includes optional live shadow preview, tick mark labels, and snap-to-increment dragging.

Usage

Inline Mode

<link rel="stylesheet" href="components/anglepicker/anglepicker.css">
<script src="components/anglepicker/anglepicker.js"></script>

<div id="my-angle-picker"></div>

<script>
var picker = createAnglePicker("my-angle-picker", {
    value: 225,
    mode: "inline",
    showPreview: true,
    onChange: function(angle) {
        console.log("Angle:", angle + "°");
    }
});
</script>

Dropdown Mode

<div id="toolbar-angle"></div>

<script>
var picker = createAnglePicker("toolbar-angle", {
    value: 45,
    mode: "dropdown",
    size: "sm",
    onChange: function(angle) {
        console.log("Shadow angle:", angle);
    }
});
</script>

Options

API

Keyboard

Dial Focused

Dropdown Mode

Tick Labels

• "none" — no labels (default)
• "degrees" — shows 0°, 90°, 180°, 270° at cardinal positions
• "compass" — shows E, N, W, S at cardinal positions

Shadow Preview

When showPreview: true, a small square appears beside the dial showing a live CSS box-shadow at the currently selected angle. The shadow distance, blur, and color are configurable.

Sizes

---

AppLauncher

Grid-based application launcher with three view modes: dropdown (waffle icon trigger), modal (centered overlay), and fullpage (inline with sidebar). Supports search, favourites, recent apps, categories, badges, and full 2D grid keyboard navigation.

Quick Start

<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="components/applauncher/applauncher.css">
<script src="components/applauncher/applauncher.js"></script>

// Dropdown mode (default)
const launcher = createAppLauncher({
    apps: [
        { id: "crm", name: "CRM", icon: "bi bi-people" },
        { id: "mail", name: "Mail", icon: "bi bi-envelope" },
        { id: "files", name: "Files", icon: "bi bi-folder" },
    ],
    activeAppId: "crm",
    onSelect: (app) => console.log("Selected:", app.name),
}, "launcher-container");

// Modal mode
const modal = createAppLauncher({
    apps: myApps,
    mode: "modal",
    categories: [
        { id: "prod", label: "Productivity", icon: "bi bi-lightning" },
        { id: "admin", label: "Admin", icon: "bi bi-gear" },
    ],
    onSelect: (app) => window.location.href = app.url,
}, "modal-trigger-container");

// Fullpage mode
const fullpage = createAppLauncher({
    apps: myApps,
    mode: "fullpage",
    categories: myCategories,
}, "fullpage-container");

Options

AppItem

Methods

Keyboard

Default Key Bindings

{
    close: "Escape",
    focusDown: "ArrowDown",
    focusUp: "ArrowUp",
    focusLeft: "ArrowLeft",
    focusRight: "ArrowRight",
    focusFirst: "Home",
    focusLast: "End",
    select: "Enter",
    toggleFav: "Shift+F",
    focusSearch: "/",
}

CSS Classes

All classes use the applauncher- prefix. Key classes:

• .applauncher — root
• .applauncher-trigger — waffle button
• .applauncher-dropdown — dropdown portal
• .applauncher-modal / .applauncher-backdrop / .applauncher-modal-content — modal
• .applauncher-fullpage / .applauncher-sidebar — fullpage layout
• .applauncher-search / .applauncher-search-input — search
• .applauncher-tabs / .applauncher-tab — category tabs
• .applauncher-grid / .applauncher-tile — tile grid
• .applauncher-tile-active / .applauncher-tile-disabled — tile states
• .applauncher-tile-badge / .applauncher-tile-fav — badge and favourite star
• .applauncher-section-header — section labels
• .applauncher-sm / .applauncher-lg — size variants

Asset Paths

CSS: components/applauncher/applauncher.css
JS:  components/applauncher/applauncher.js

---

AuditLogViewer

Read-only filterable audit log viewer with severity badges, expandable detail rows, filter chips, pagination, and CSV/JSON export.

Usage

<link rel="stylesheet" href="components/auditlogviewer/auditlogviewer.css">
<script src="components/auditlogviewer/auditlogviewer.js"></script>

const viewer = createAuditLogViewer({
    entries: [
        {
            id: "1",
            timestamp: new Date(),
            actor: "admin",
            action: "user.login",
            resource: "Session #42",
            ipAddress: "10.0.1.5",
            severity: "info"
        }
    ],
    height: "500px",
    onRowClick: (entry) => console.log("Row clicked:", entry.id),
}, "my-container");

Options

API

Severity Levels

---

BannerBar

A fixed-to-top viewport banner for announcing significant events such as service status updates, critical issues, maintenance windows, and success confirmations.

Features

• Four severity presets: info, warning, critical, success
• Full colour override support for custom branding
• Optional bold title, icon, and action link/button
• Closeable via X button (configurable)
• Optional auto-dismiss timer
• Scrollable overflow at configurable max height
• Slide-in/slide-out animation
• Single-instance model (new banner replaces the previous)
• Sets --bannerbar-height CSS custom property on <html> for layout offset
• WCAG AA accessible with appropriate ARIA attributes

Assets

Requires: Bootstrap CSS (for SCSS variables), Bootstrap Icons CSS. Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/bannerbar/bannerbar.css">
<script src="components/bannerbar/bannerbar.js"></script>
<script>
    var banner = createBannerBar({
        message: "Scheduled maintenance tonight at 02:00 UTC.",
        variant: "warning"
    });
</script>

API

createBannerBar(options) / showBanner(options)

Creates, shows, and returns a BannerBar instance. showBanner is an ergonomic alias.

new BannerBar(options)

Creates a BannerBar instance without showing it. Call .show() to display.

Options

Instance Methods

Variants

Examples

Basic Info Banner

createBannerBar({
    message: "New dashboard analytics are now available."
});

Critical Banner with Title

createBannerBar({
    title: "Service Disruption",
    message: "Payment processing is currently unavailable. We are investigating.",
    variant: "critical"
});

Banner with Action Link

createBannerBar({
    message: "Your subscription expires in 3 days.",
    variant: "warning",
    actionLabel: "Renew Now",
    actionHref: "/billing/renew"
});

Auto-Dismissing Success Banner

createBannerBar({
    message: "All records imported successfully.",
    variant: "success",
    autoDismissMs: 5000
});

Custom Colours

createBannerBar({
    message: "Beta feature enabled for your account.",
    backgroundColor: "#f0e6ff",
    textColor: "#4a1d8e",
    borderColor: "#7c3aed"
});

CSS Custom Property

When visible, the banner sets --bannerbar-height on <html> to its measured pixel height. Other components (e.g., Sidebar) use this to offset their top position:

.my-fixed-element {
    top: var(--bannerbar-height, 0px);
}

The property is removed when the banner is hidden or destroyed.

Accessibility

• Root element has role="alert" with aria-live="assertive" for critical/warning variants, aria-live="polite" for info/success
• Close button has aria-label="Close banner"
• Action element is a standard focusable <a> or <button>
• All variant colour combinations meet WCAG AA contrast requirements

---

BorderLayout

A five-region CSS Grid layout container that divides its area into North, South, East, West, and Center regions. North and South span the full width; East and West fill the remaining height; Center takes all remaining space. Supports region collapsing and dynamic slot assignment.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/borderlayout/borderlayout.css">
<script src="components/borderlayout/borderlayout.js"></script>

<script>
    var header = document.createElement("header");
    header.textContent = "Application Header";
    header.style.padding = "12px";
    header.style.background = "#f0f0f0";

    var nav = document.createElement("nav");
    nav.textContent = "Navigation";
    nav.style.padding = "12px";

    var content = document.createElement("main");
    content.textContent = "Main Content Area";

    var layout = createBorderLayout({
        north: header,
        west: nav,
        center: content,
        westWidth: "200px",
        northHeight: "auto",
        gap: 1,
        height: "100vh",
        width: "100%",
        collapsible: ["west", "east"]
    });
</script>

How It Works

BorderLayout creates a CSS Grid with 5 named areas:

┌─────────────────────────────────────┐
│              north                  │  auto / fixed height
├──────┬──────────────────┬───────────┤
│      │                  │           │
│ west │     center       │   east    │  1fr (fills remaining)
│      │                  │           │
├──────┴──────────────────┴───────────┤
│              south                  │  auto / fixed height
└─────────────────────────────────────┘

When a component is passed to a region:

1. Calls component.setContained(true) if available
2. Calls component.show(cell) — mounts inside the grid cell
3. Grid template updates dynamically when regions change

Options

Public API

BorderLayoutState

interface BorderLayoutState {
    regions: Record<BorderRegion, boolean>;
    collapsed: BorderRegion[];
}

Nesting Example

// BorderLayout as an application shell
var appShell = createBorderLayout({
    north: toolbar,
    west: new BorderLayout({
        north: searchBox,
        center: treeView,
        south: userProfile,
        height: "100%"
    }),
    center: tabPanel,
    east: propertyInspector,
    south: statusBar,
    collapsible: ["west", "east"],
    height: "100vh"
});

Global Exports

When loaded via <script> tag:

• window.BorderLayout — BorderLayout class
• window.createBorderLayout — Factory function (creates and shows)

CSS Classes

---

BoxLayout

A single-axis flex layout container that arranges children sequentially along one axis (horizontal or vertical) with configurable flex factors, alignment, and gap. Inspired by Java Swing BoxLayout, WPF StackPanel, and CSS Flexbox.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/boxlayout/boxlayout.css">
<script src="components/boxlayout/boxlayout.js"></script>

<script>
    var layout = createBoxLayout({
        direction: "horizontal",
        gap: 8,
        align: "stretch",
        height: "100%",
        children: [
            { child: document.getElementById("sidebar"), flex: 0, minSize: 200 },
            { child: document.getElementById("content"), flex: 1 }
        ]
    });
</script>

How It Works

BoxLayout creates a CSS Flexbox container. Children are arranged sequentially along the main axis (row or column). Each child can be assigned a flex factor to consume proportional remaining space, or it can use its natural size.

direction: "horizontal"
┌──────────┬────────────────────────────────┬──────────┐
│ flex: 0  │          flex: 1               │ flex: 0  │
│ (200px)  │    (fills remaining space)     │ (auto)   │
└──────────┴────────────────────────────────┴──────────┘

direction: "vertical"
┌──────────────────────────────────────────────────────┐
│ flex: 0 (auto height)                                │
├──────────────────────────────────────────────────────┤
│                                                      │
│ flex: 1 (fills remaining space)                      │
│                                                      │
├──────────────────────────────────────────────────────┤
│ flex: 0 (auto height)                                │
└──────────────────────────────────────────────────────┘

Options

BoxLayoutChildConfig

Public API

BoxLayoutState

interface BoxLayoutState {
    direction: "horizontal" | "vertical";
    childCount: number;
}

Composability

BoxLayout implements the standard layout container contract. Any component with show(container) / hide() / destroy() can be used as a child. Plain HTMLElements are also supported.

// Nest a BoxLayout inside a BorderLayout
var innerBox = new BoxLayout({
    direction: "horizontal",
    gap: 8,
    children: [
        { child: buttonA, flex: 0 },
        { child: spacer, flex: 1 },
        { child: buttonB, flex: 0 }
    ]
});

borderLayout.setNorth(innerBox);

Global Exports

When loaded via <script> tag:

• window.BoxLayout — BoxLayout class
• window.createBoxLayout — Factory function (creates and shows)

CSS Classes

---

Breadcrumb Navigation

Hierarchical path display with clickable segments, optional terminal dropdown actions, and overflow truncation for deep hierarchies. Extends Bootstrap 5 breadcrumb base styles.

Assets

Requirements

• Bootstrap CSS — for .breadcrumb / .breadcrumb-item base classes and SCSS variables
• Bootstrap Icons — per-item and action icons (bi-* classes)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/breadcrumb/breadcrumb.css">
<script src="components/breadcrumb/breadcrumb.js"></script>
<script>
    var bc = createBreadcrumb({
        container: document.getElementById("my-breadcrumb"),
        items: [
            { label: "Home", icon: "bi-house-fill" },
            { label: "Projects" },
            { label: "Acme Corp" }
        ],
        onItemClick: function(item, index) {
            console.log("Navigate to:", item.label);
        }
    });
</script>

API

createBreadcrumb(options): BreadcrumbHandle

Factory function — creates and mounts a breadcrumb instance.

BreadcrumbOptions

BreadcrumbItem

BreadcrumbAction

BreadcrumbHandle

Overflow Truncation

When the number of items exceeds maxVisible, middle segments collapse into an ellipsis (…) that opens a dropdown listing the hidden items:

var bc = createBreadcrumb({
    container: el,
    maxVisible: 5,
    items: [
        { label: "Root" },
        { label: "Level 1" },
        { label: "Level 2" },
        { label: "Level 3" },
        { label: "Level 4" },
        { label: "Level 5" },
        { label: "Level 6" },
        { label: "Current" }
    ]
});
// Renders: Root > … > Level 4 > Level 5 > Level 6 > Current

Terminal Actions

Add a dropdown menu to the last segment for contextual actions:

var bc = createBreadcrumb({
    container: el,
    items: [
        { label: "Home" },
        { label: "Settings" }
    ],
    actions: [
        { id: "edit", label: "Edit", icon: "bi-pencil" },
        { id: "delete", label: "Delete", icon: "bi-trash", separator: true }
    ],
    onActionClick: function(actionId, item) {
        console.log("Action:", actionId, "on", item.label);
    }
});

Size Variants

Keyboard

Accessibility

• Root element: <nav aria-label="Breadcrumb">
• Active (terminal) item: aria-current="page"
• Dropdown triggers: aria-haspopup="true", aria-expanded
• Menu items: role="menu" / role="menuitem"
• Icons: aria-hidden="true"

CSS Custom Properties

---

CardLayout

An indexed-stack layout container that stacks all children in the same space but displays only one at a time. Supports animated transitions (fade, slide) between cards, lazy loading, and keyboard navigation via next()/previous().

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/cardlayout/cardlayout.css">
<script src="components/cardlayout/cardlayout.js"></script>

<script>
    var step1 = document.createElement("div");
    step1.innerHTML = "<h2>Step 1</h2><p>Enter your details</p>";

    var step2 = document.createElement("div");
    step2.innerHTML = "<h2>Step 2</h2><p>Choose your plan</p>";

    var step3 = document.createElement("div");
    step3.innerHTML = "<h2>Step 3</h2><p>Confirm and submit</p>";

    var wizard = createCardLayout({
        activeKey: "step1",
        transition: "slide-left",
        transitionDuration: 200,
        height: "400px",
        cards: [
            { key: "step1", child: step1 },
            { key: "step2", child: step2 },
            { key: "step3", child: step3 }
        ]
    });

    // Navigate programmatically
    document.getElementById("nextBtn").onclick = function() {
        wizard.next();
    };
</script>

How It Works

CardLayout creates a container where all card wrappers are stacked. Only the active card has display: block; all others have display: none. When switching cards, CSS animation classes are applied for the transition duration, then cleaned up.

┌──────────────────────────────────┐
│                                  │
│         Active Card              │   ← visible (display: block)
│       (e.g. "step2")            │
│                                  │
├──────────────────────────────────┤
│  Card "step1" (display: none)   │   ← hidden
│  Card "step3" (display: none)   │   ← hidden
└──────────────────────────────────┘

Options

CardConfig

Public API

CardLayoutState

interface CardLayoutState {
    activeKey: string | null;
    cardCount: number;
}

Transitions

All transitions respect prefers-reduced-motion: reduce — when enabled, transitions are disabled and cards switch immediately.

Global Exports

When loaded via <script> tag:

• window.CardLayout — CardLayout class
• window.createCardLayout — Factory function (creates and shows)

CSS Classes

---

CodeEditor

Bootstrap 5-themed code editor wrapping CodeMirror 6 with syntax highlighting, toolbar, and diagnostics.

Prerequisites

CodeMirror 6 is required. The component checks for window.EditorView and window.EditorState at show() time. If these globals are missing, it displays an error message instead of rendering an editor.

Required Globals

Recommended Globals

These are optional but provide the full editing experience:

Language Globals

Add language support by exposing factory functions as globals:

Loading via ESM CDN

CodeMirror 6 is ESM-native. Use a <script type="module"> with an ESM CDN to expose globals:

<script type="module">
    import { EditorView, keymap, lineNumbers, drawSelection, dropCursor,
             highlightActiveLine, highlightSelectionMatches }
        from "https://esm.sh/@codemirror/view@6";
    import { EditorState } from "https://esm.sh/@codemirror/state@6";
    import { history, historyKeymap, defaultKeymap, undo, redo, indentSelection }
        from "https://esm.sh/@codemirror/commands@6";
    import { syntaxHighlighting, defaultHighlightStyle, indentOnInput }
        from "https://esm.sh/@codemirror/language@6";
    import { search, searchKeymap } from "https://esm.sh/@codemirror/search@6";
    import { closeBrackets, closeBracketsKeymap } from "https://esm.sh/@codemirror/autocomplete@6";
    import { bracketMatching } from "https://esm.sh/@codemirror/language@6";
    import { javascript } from "https://esm.sh/@codemirror/lang-javascript@6";
    import { json } from "https://esm.sh/@codemirror/lang-json@6";
    import { html } from "https://esm.sh/@codemirror/lang-html@6";
    import { css } from "https://esm.sh/@codemirror/lang-css@6";
    import { sql } from "https://esm.sh/@codemirror/lang-sql@6";
    import { python } from "https://esm.sh/@codemirror/lang-python@6";
    import { markdown } from "https://esm.sh/@codemirror/lang-markdown@6";

    // Expose as globals for CodeEditor
    Object.assign(window, {
        EditorView, EditorState, keymap, lineNumbers, drawSelection, dropCursor,
        highlightActiveLine, highlightSelectionMatches, history, historyKeymap,
        defaultKeymap, undo, redo, indentSelection, syntaxHighlighting,
        defaultHighlightStyle, indentOnInput, search, searchKeymap,
        closeBrackets, closeBracketsKeymap, bracketMatching,
        javascript, json, html, css, sql, python, markdown
    });
    window.dispatchEvent(new Event("codemirror-ready"));
</script>

Alternatively, provide a pre-bundled UMD build that sets these globals.

Quick Start

<link rel="stylesheet" href="components/codeeditor/codeeditor.css">
<script src="components/codeeditor/codeeditor.js"></script>
<script>
    var editor = createCodeEditor("my-container", {
        value: "function greet() {\n    console.log('Hello!');\n}",
        language: "javascript",
        onSave: function(value) { console.log("Saved:", value); }
    });
</script>

API

CodeEditorOptions

Callbacks

Methods

Features

• Syntax highlighting — JavaScript, TypeScript, JSON, YAML, HTML, CSS, SQL, Python, Markdown
• Toolbar — Language selector, undo/redo, word wrap, copy, format, save
• Light & dark themes — CSS custom properties integrating with Bootstrap variables
• Diagnostics — Gutter markers for errors, warnings, info (CodeMirror mode)
• Copy to clipboard — With visual checkmark feedback
• Auto-grow — Height adjusts with content up to maxHeight
• Read-only mode — Editing blocked, copy/save still available
• Tab handling — Tab inserts spaces (respects tabSize)
• Ctrl+S — Fires onSave callback

Keyboard

Accessibility

• role="group" with aria-label="Code editor" on root
• role="toolbar" with aria-label="Editor actions" on toolbar
• aria-label on all buttons and the language selector
• aria-pressed on word wrap toggle
• aria-readonly and aria-disabled states
• Live region for language change and diagnostic announcements

---

ColorPicker

A canvas-based colour selection control with saturation/brightness gradient, vertical hue strip, optional opacity slider, hex/RGB/HSL format tabs, text inputs, and configurable preset swatches. Operates in popup or inline mode.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $primary, etc.)
• Bootstrap Icons — bi-clipboard, bi-check2
• Does not require Bootstrap JS.
• No external colour libraries — all conversions are internal.

Quick Start

<link rel="stylesheet" href="components/colorpicker/colorpicker.css">
<script src="components/colorpicker/colorpicker.js"></script>
<script>
    var picker = createColorPicker("my-container", {
        value: "#FF5733",
        showOpacity: true,
        swatches: ["#EF4444", "#F59E0B", "#10B981", "#3B82F6", "#8B5CF6"],
        onChange: function(color, alpha) {
            console.log("Selected:", color, "Alpha:", alpha);
        }
    });
</script>

Options (ColorPickerOptions)

API

Convenience Function

createColorPicker(containerId, options?)  // Create, show, and return

Global Exports

window.ColorPicker
window.createColorPicker

Keyboard Accessibility

Accessibility

• Palette, hue strip, and opacity have role="slider" with aria-valuenow/min/max
• Swatch grid has role="listbox" with role="option" items
• Format tabs use role="tablist" and role="tab" with aria-selected
• Trigger button has aria-haspopup="dialog" and aria-expanded
• aria-live="polite" region announces colour changes

onInput vs onChange

Both callbacks receive (color: string, alpha?: number). During a drag, onInput fires continuously and onChange fires once on pointer release. On discrete actions (keyboard, swatch, Enter), both fire together.

Disabled State

When disabled (disabled: true or disable() method):

• Inline mode: entire picker has opacity: 0.5, all interactions disabled, swatches show cursor: not-allowed with no hover scale.
• Popup mode: trigger shows cursor: not-allowed, hover border suppressed, click does not open popup. Trigger has aria-disabled="true".

Examples

Live preview with onInput

var picker = createColorPicker("canvas-tools", {
    value: "#3B82F6",
    label: "Fill",
    onInput: function(color) {
        // Real-time preview while dragging
        selectedShape.style.fill = color;
    },
    onChange: function(color) {
        // Commit: save to backend
        api.updateShapeFill(shapeId, color);
    }
});

Accessing the popup element

var picker = createColorPicker("dock-panel", {
    value: "#10B981",
    onOpen: function() {
        var popup = picker.getPopupElement();
        if (popup) { popup.style.zIndex = "2000"; }
    }
});

Label option

var fill = createColorPicker("fill-container", {
    label: "Fill",
    inline: true,
    value: "#3B82F6"
});

var stroke = createColorPicker("stroke-container", {
    label: "Stroke",
    inline: true,
    value: "#1F2937"
});

Inline picker with opacity

var picker = createColorPicker("theme-editor", {
    value: "#6366F1",
    inline: true,
    showOpacity: true,
    format: "rgb",
    onChange: function(color, alpha) {
        document.getElementById("preview").style.backgroundColor = color;
    }
});

Popup with preset swatches

var picker = createColorPicker("brand-color", {
    value: "#10B981",
    swatches: [
        "#EF4444", "#F59E0B", "#10B981", "#3B82F6",
        "#8B5CF6", "#EC4899", "#6B7280", "#1F2937"
    ],
    onChange: function(color) {
        console.log("Brand colour:", color);
    }
});

See specs/colorpicker.prd.md for the complete specification.

---

ColumnsPicker

A dropdown showing column layout presets with visual SVG page thumbnails. Each option displays a small page icon with vertical column dividers and horizontal placeholder lines illustrating the layout. Designed for use in Ribbon toolbars, standalone toolbars, and property panels.

Usage

<link rel="stylesheet" href="components/columnspicker/columnspicker.css">
<script src="components/columnspicker/columnspicker.js"></script>

<div id="my-columns"></div>

<script>
var picker = createColumnsPicker({
    container: "my-columns",
    value: "Two",
    onChange: function(preset) {
        console.log("Columns:", preset.columns, "Widths:", preset.widths);
    }
});
</script>

Options

Default Presets

API

Keyboard

CSS Classes

---

CommandPalette

Keyboard-first command palette (Ctrl+K omnibar) for searching and executing registered commands with fuzzy matching, category grouping, recent history, and match highlighting.

Assets

Usage

<link rel="stylesheet" href="components/commandpalette/commandpalette.css">
<script src="components/commandpalette/commandpalette.js"></script>

Basic — Register Commands

CommandPalette.configure({
    commands: [
        { id: "save", label: "Save Document", icon: "bi-save", category: "Actions", shortcut: "Ctrl+S", action: function() { console.log("Save!"); } },
        { id: "settings", label: "Open Settings", icon: "bi-gear", category: "Navigation", shortcut: "Ctrl+,", action: function() { console.log("Settings!"); } }
    ]
});
// Now press Ctrl+K (or Cmd+K on macOS) to open

Programmatic Open

openCommandPalette();

Register Commands Individually

registerCommand({
    id: "toggle-sidebar",
    label: "Toggle Sidebar",
    icon: "bi-layout-sidebar",
    category: "View",
    shortcut: "Ctrl+B",
    action: function() { sidebar.toggleCollapse(); }
});

Interfaces

PaletteCommand

interface PaletteCommand {
    id: string;
    label: string;
    icon?: string;                   // Bootstrap Icons class
    category?: string;               // Grouping category
    shortcut?: string;               // Display-only shortcut badge
    keywords?: string[];             // Additional search terms
    description?: string;            // Secondary text
    disabled?: boolean;              // Default: false
    hidden?: boolean;                // Excluded from search. Default: false
    action: () => void | Promise<void>;
}

CommandPaletteOptions

interface CommandPaletteOptions {
    commands?: PaletteCommand[];
    placeholder?: string;            // Default: "Type a command..."
    hotkey?: string;                 // Default: "ctrl+k" ("meta+k" on macOS)
    maxResults?: number;             // Default: 20
    showRecent?: boolean;            // Default: true
    maxRecent?: number;              // Default: 5
    showShortcuts?: boolean;         // Default: true
    showCategories?: boolean;        // Default: true
    width?: string;                  // Default: "600px"
    zIndex?: number;                 // Default: 1080
    backdropOpacity?: number;        // Default: 0.5
    cssClass?: string;
    onOpen?: () => void;
    onClose?: () => void;
    onSelect?: (command: PaletteCommand) => void;
    onSearch?: (query: string) => void;
}

API

Keyboard

Fuzzy Search

The palette implements a lightweight fuzzy search:

1. Exact prefix match — Highest score
2. Substring match — High score
3. Character-skip match — Score based on contiguity
4. Keyword match — 70% of label match score
5. Description match — 50% of label match score

Matched characters are highlighted with <mark> elements.

Singleton Pattern

Only one CommandPalette exists per page. Use CommandPalette.configure() or the global registerCommand() functions.

Dependencies

• Required: Bootstrap 5 CSS, Bootstrap Icons

---

CommentOverlay

Transparent overlay system for anchoring comment pins to DOM elements, enabling inline annotation with threaded discussions, @mentions, resolve/unresolve, drag-to-reposition, and visual connector lines.

Quick Start

<link rel="stylesheet" href="components/commentoverlay/commentoverlay.css">
<script src="components/commentoverlay/commentoverlay.js"></script>
<script>
    var overlay = createCommentOverlay("my-container", {
        currentUser: { id: "u1", name: "Alice Chen" },
        mentionUsers: [
            { id: "u1", name: "Alice Chen" },
            { id: "u2", name: "Bob Smith", email: "bob@example.com" }
        ],
        pins: [
            {
                id: "pin-1",
                anchorElement: document.getElementById("my-paragraph"),
                offsetX: 12, offsetY: -8,
                thread: {
                    id: "pin-1",
                    rootComment: {
                        id: "c1", author: { id: "u2", name: "Bob Smith" },
                        text: "Check this value @[u1]",
                        createdAt: "2025-12-01T10:00:00Z",
                        edited: false, mentions: ["u1"]
                    },
                    replies: [],
                    resolved: false
                }
            }
        ],
        onCommentCreate: function(threadId, comment) {
            console.log("New comment:", threadId, comment.text);
        }
    });
</script>

Assets

Requires: Bootstrap CSS, Bootstrap Icons CSS.

Interfaces

MentionUser

CommentData

CommentThread

CommentPinData

Options (CommentOverlayOptions)

API Methods

Keyboard

@Mention Format

Mentions are stored as @[userId] in comment text. When rendered, they are resolved against the mentionUsers list and displayed as styled chips. Use onMentionSearch for async user lookups.

See specs/commentoverlay.prd.md for the full specification.

---

ConfirmDialog

A general-purpose confirmation modal with customizable title, message, icon, buttons, and a promise-based API. Use this for "Are you sure?" / "Do you want to proceed?" flows. Distinct from ErrorDialog, which is designed for literate error messages with technical details and correlation IDs.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables and .btn-* classes
• Bootstrap Icons -- variant icons (bi-question-circle, bi-exclamation-triangle, etc.)
• Enterprise theme CSS -- css/custom.css
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="icons/bootstrap-icons.css">
<link rel="stylesheet" href="components/confirmdialog/confirmdialog.css">

<script src="components/confirmdialog/confirmdialog.js"></script>
<script>
    async function handleDelete() {
        const confirmed = await showConfirmDialog({
            title: "Delete Item",
            message: "Are you sure you want to delete this item? This action cannot be undone.",
            variant: "danger",
            confirmLabel: "Delete",
        });

        if (confirmed) {
            deleteItem();
        }
    }

    // Danger shortcut
    async function handleQuickDelete() {
        const confirmed = await showDangerConfirmDialog(
            "This will permanently delete the project and all its data."
        );
        if (confirmed) { deleteProject(); }
    }
</script>

API

Global Functions

Class: ConfirmDialog

const dialog = new ConfirmDialog({ message: "Proceed with this action?" });
const confirmed = await dialog.show();

• show() -- Builds, mounts, and displays the dialog. Returns Promise<boolean>.

ConfirmDialogOptions

Variants

Keyboard

Key bindings can be overridden via the keyBindings option:

showConfirmDialog({
    message: "Proceed?",
    keyBindings: { confirm: "Ctrl+Enter" },
});

Accessibility

• Dialog uses role="alertdialog" and aria-modal="true"
• Title linked via aria-labelledby
• Message linked via aria-describedby
• Focus is trapped within the dialog buttons (Tab cycles between them)
• On open, focus moves to the confirm button
• On close, focus returns to the previously focused element
• Close button has aria-label="Close"
• Animations respect prefers-reduced-motion: reduce

DOM Structure

div.confirmdialog-backdrop
  div.confirmdialog.confirmdialog-{variant} [role="alertdialog" aria-modal="true"]
    div.confirmdialog-header
      i.bi.{icon}.confirmdialog-icon.confirmdialog-icon-{variant}
      h5.confirmdialog-title "Confirm Action"
      button.confirmdialog-close [aria-label="Close"]
    div.confirmdialog-body
      p.confirmdialog-message "Are you sure?"
    div.confirmdialog-footer
      button.confirmdialog-cancel.btn.btn-secondary "Cancel"
      button.confirmdialog-confirm.btn.btn-{variant} "Confirm"

Features

• Promise-based -- await showConfirmDialog(...) returns true/false
• Four variants -- default, danger, warning, info with matching icon and button colours
• Focus trap -- Tab cycles within the dialog; no focus escape
• Focus restore -- Returns focus to the previously active element on close
• Backdrop dismiss -- Click outside to cancel (configurable)
• XSS safe -- All content set via textContent, never innerHTML
• Auto-cleanup -- DOM is removed when the dialog resolves
• No Bootstrap JS dependency -- Fully standalone modal implementation

---

ContextMenu

A theme-aware, accessible context menu component with icons, keyboard shortcuts, separators, sub-menus, checked/radio states, and viewport edge detection. Designed for right-click (desktop) or programmatic invocation across all applications.

Assets

Requirements

• Bootstrap CSS — for SCSS variables
• Bootstrap Icons — item icons (bi-* classes)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/contextmenu/contextmenu.css">
<script src="components/contextmenu/contextmenu.js"></script>
<script>
    document.addEventListener("contextmenu", function(e) {
        e.preventDefault();
        createContextMenu({
            x: e.clientX,
            y: e.clientY,
            items: [
                { id: "cut", label: "Cut", icon: "scissors", shortcut: "Ctrl+X" },
                { id: "copy", label: "Copy", icon: "files", shortcut: "Ctrl+C" },
                { id: "paste", label: "Paste", icon: "clipboard", shortcut: "Ctrl+V" },
                { id: "sep1", label: "", type: "separator" },
                { id: "delete", label: "Delete", icon: "trash", shortcut: "Del", danger: true }
            ],
            onClose: function() { console.log("Menu closed"); }
        });
    });
</script>

API

Global Functions

ContextMenuOptions

ContextMenuItem

ContextMenu (Handle)

Features

• Theme-aware — follows system light/dark mode via CSS custom properties; explicit light/dark override available
• Keyboard navigation — Arrow Up/Down to navigate, Enter to select, Escape to close, Right to open sub-menu, Left to close sub-menu
• Sub-menus — nested menus with hover delay and arrow indicator
• Viewport edge detection — flips up/left when near viewport edges
• Checked/radio states — checkmark icon with aria-checked
• Disabled items — 50% opacity, no pointer events, aria-disabled
• Danger items — red text and icon for destructive actions
• Headers — bold, non-clickable section labels
• Separators — horizontal dividers with role="separator"
• Animation — fade-in (150ms), scale, or none
• Icons — Bootstrap Icons with 20px icon column
• Shortcuts — right-aligned muted shortcut hints

Accessibility

• Container: role="menu", aria-label="Context menu"
• Items: role="menuitem", tabindex="-1"
• Separators: role="separator"
• Disabled items: aria-disabled="true"
• Sub-menu triggers: aria-haspopup="menu"
• Checked items: aria-checked="true" or "false"
• Focus management: first non-disabled item focused on open
• Focus visible: 2px inset primary ring

Visual Design

• Border radius: 8px
• Box shadow: 0 4px 16px rgba(0,0,0,0.12), 0 0 0 1px rgba(0,0,0,0.05)
• Item height: 32px
• Icon column: 20px wide
• Shortcut column: right-aligned, muted
• Hover: theme-aware hover background
• z-index: 1080

See specs/explorer-context-menu.req.md for the full specification.

---

Conversation

A programmable turn-by-turn conversation UI component for AI agent interactions in enterprise SaaS applications. Supports rich text rendering via Vditor, streaming responses, session management, user feedback, copy in multiple formats, and inline error display.

Features

• Turn-by-turn messaging — user, assistant, system, and error message roles
• Rich text rendering — assistant messages rendered as Markdown via Vditor with syntax highlighting, math (KaTeX), and footnotes
• Token streaming — stream assistant responses chunk-by-chunk with a final Vditor render on completion
• Session management — create, load, save, and clear conversation sessions with async callbacks
• Feedback — thumbs-up/down with optional written comments on assistant messages
• Copy to clipboard — copy single messages or the entire conversation in Markdown, HTML, or plain text
• Inline errors — structured error display with title, message, suggestion, and expandable technical details
• Typing indicator — animated dots with configurable label text
• Customisable avatars — Bootstrap Icons class names or image URLs for user and assistant
• Full accessibility — ARIA roles, live regions, keyboard navigation
• MCP App rendering — embed interactive MCP apps in sandboxed iframes within message bubbles with JSON-RPC 2.0 postMessage communication and automatic theme injection
• Canvas side panel — optional resizable side panel for full-size MCP app display with pointer-capture resize, keyboard navigation, and expand-from-inline

Assets

Dependencies:

Quick Start

<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5/css/bootstrap.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons/font/bootstrap-icons.css">
<link rel="stylesheet" href="components/conversation/conversation.css">

<script src="https://cdn.jsdelivr.net/npm/vditor/dist/index.min.js"></script>
<script src="https://cdn.jsdelivr.net/npm/dompurify/dist/purify.min.js"></script>
<script src="components/conversation/conversation.js"></script>

<div id="chat-container" style="height: 600px;"></div>

<script>
    var chat = createConversation(
    {
        title: "Support Agent",
        onSendMessage: function(message, session)
        {
            // Call your backend API here
            chat.showTypingIndicator();
            fetch("/api/chat", { method: "POST", body: JSON.stringify({ message: message }) })
                .then(function(res) { return res.json(); })
                .then(function(data)
                {
                    chat.hideTypingIndicator();
                    chat.addAssistantMessage(data.reply);
                });
        }
    }, "chat-container");
</script>

API

Constructor

const chat = new Conversation(options?: ConversationOptions);

Creates the conversation DOM but does not attach it to the page. Call show() to mount.

ConversationOptions

McpAppConfig

Configuration for an MCP App resource to render within a message. The app HTML runs in a sandboxed iframe with no access to the host page.

ConversationMessage

ConversationSession

StreamHandle

ConversationError

FeedbackData

Methods

Convenience Functions

createConversation(options?, container?)    // Create, show, and return

Global Exports

window.Conversation
window.createConversation

Streaming Example

Use startAssistantMessage() to stream tokens from your backend into the conversation. During streaming, chunks are displayed as plain text. On complete(), the full content is rendered through Vditor.

chat.showTypingIndicator();

fetch("/api/stream", { method: "POST", body: JSON.stringify({ prompt: userText }) })
    .then(function(response)
    {
        chat.hideTypingIndicator();
        var stream = chat.startAssistantMessage();
        var reader = response.body.getReader();
        var decoder = new TextDecoder();

        function pump()
        {
            reader.read().then(function(result)
            {
                if (result.done)
                {
                    stream.complete();
                    return;
                }
                var chunk = decoder.decode(result.value, { stream: true });
                stream.appendChunk(chunk);
                pump();
            }).catch(function(err)
            {
                stream.error("Connection lost: " + err.message);
            });
        }

        pump();
    });

Session Management Example

Provide session lifecycle callbacks to persist conversations to your backend.

var chat = createConversation(
{
    title: "Project Assistant",

    onNewSession: function()
    {
        return fetch("/api/sessions", { method: "POST" })
            .then(function(res) { return res.json(); });
    },

    onSaveSession: function(session)
    {
        return fetch("/api/sessions/" + session.id,
        {
            method: "PUT",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(session)
        });
    },

    onClearSession: function(sessionId)
    {
        return fetch("/api/sessions/" + sessionId + "/clear",
        {
            method: "POST"
        });
    },

    onLoadSession: function(sessionId)
    {
        return fetch("/api/sessions/" + sessionId)
            .then(function(res) { return res.json(); });
    },

    onSendMessage: function(message, session)
    {
        // Handle message and respond
    }
}, "chat-container");

You can also load a session programmatically:

var savedSession = {
    id: "session-abc123",
    title: "Previous chat",
    messages: [],
    createdAt: new Date("2026-01-15"),
    updatedAt: new Date("2026-01-15")
};

chat.loadSession(savedSession);

Feedback Example

When feedback buttons are enabled (showFeedback: true), users can rate assistant messages as helpful or unhelpful. Clicking a feedback button opens a modal for an optional written comment.

var chat = createConversation(
{
    showFeedback: true,

    onFeedback: function(messageId, feedback, session)
    {
        console.log("Feedback on", messageId, ":", feedback.sentiment);
        if (feedback.comment)
        {
            console.log("Comment:", feedback.comment);
        }

        fetch("/api/feedback",
        {
            method: "POST",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify(
            {
                messageId: messageId,
                sentiment: feedback.sentiment,
                comment: feedback.comment,
                sessionId: session.id
            })
        });
    }
}, "chat-container");

Copy Functionality

The component supports copying content in three formats:

Conversation-level copy is available through a dropdown in the header (when showConversationCopy is true). Each message is prefixed with the sender's display name.

Message-level copy is available through a clipboard button on individual assistant messages (when showMessageCopy is true). Message-level copy defaults to Markdown format.

The onCopy callback is fired after each copy operation:

var chat = createConversation(
{
    onCopy: function(content, format)
    {
        console.log("Copied as", format, ":", content.length, "characters");
    }
}, "chat-container");

Error Display

Use addError() to display structured, user-friendly error messages inline in the conversation. Errors follow the literate error pattern with a title, explanation, suggestion, and expandable technical details.

chat.addError(
{
    title: "Request failed",
    message: "The assistant could not process your request because the service is temporarily unavailable.",
    suggestion: "Wait a moment and try again, or contact support if the problem persists.",
    technicalDetail: "HTTP 503 Service Unavailable\nEndpoint: POST /api/v2/chat/completions",
    errorCode: "CHAT-503",
    correlationId: "req-7f3a-4b2c-9d1e"
});

The error code and correlation ID appear in the expandable "Technical Details" section, making it straightforward for support teams to trace issues in backend logs.

MCP App Rendering

The component supports the MCP Apps specification (stable 2026-01-26) for embedding interactive content within chat messages. MCP apps run in sandboxed iframes with JSON-RPC 2.0 communication via postMessage.

Inline MCP App

Add a message with an inline MCP app using addAppMessage():

var chat = createConversation(
{
    enableMcpApps: true,

    onMcpAppMessage: function(appId, method, params)
    {
        console.log("MCP message from", appId, ":", method, params);

        // Example: respond to a data request from the app
        if (method === "getData")
        {
            // Send response back to the iframe
            // (handled internally via the McpAppFrame postMessage bridge)
        }
    },

    onSendMessage: function(message, session)
    {
        // Simulate an API response that returns MCP app content
        chat.showTypingIndicator();
        setTimeout(function()
        {
            chat.hideTypingIndicator();
            chat.addAppMessage("Here are the server metrics:", {
                html: "<html><body><h2>CPU Usage</h2><p>42%</p></body></html>",
                title: "Server Metrics",
                preferredHeight: 200
            });
        }, 1000);
    }
}, "chat-container");

Streaming into MCP App

Stream text first, then transition to an MCP app on completion:

var stream = chat.startAssistantMessage();
stream.appendChunk("Analysing your data");
stream.appendChunk("...");

// On completion, attach MCP app content
stream.complete({
    mcpApp: {
        html: "<html><body><div id='chart'>...</div></body></html>",
        title: "Analysis Results",
        preferredHeight: 400
    }
});

Canvas Side Panel

Enable the canvas panel for full-size MCP app display:

var chat = createConversation(
{
    enableMcpApps: true,
    showCanvas: true,
    canvasWidth: 500,

    onCanvasToggle: function(open)
    {
        console.log("Canvas", open ? "opened" : "closed");
    }
}, "chat-container");

// Programmatically open an app in the canvas
chat.openCanvas({
    html: "<html><body><div id='editor'>Full-size editor...</div></body></html>",
    title: "Code Editor",
    preferredWidth: 600
});

// Close the canvas
chat.closeCanvas();

When showCanvas is true, inline MCP apps display an "expand" button. Clicking it moves the app to the canvas panel. The canvas panel supports pointer-capture resize with min/max width constraints and keyboard navigation (Esc to close, Arrow keys to resize).

MCP App HTML Structure

MCP app HTML is injected into a sandboxed iframe via srcdoc. The component automatically prepends:

1. A Content Security Policy meta tag restricting resource access
2. A theme style block injecting --mcp-* CSS custom properties (colours, fonts) computed from the host page's Bootstrap theme at runtime
3. A bridge script providing window.mcpBridge.send(method, params) and window.mcpBridge.onMessage for JSON-RPC 2.0 communication with the host

Example MCP app HTML that communicates with the host:

<html>
<body>
    <button id="btn">Request Data</button>
    <pre id="output"></pre>
    <script>
        document.getElementById("btn").addEventListener("click", function()
        {
            window.mcpBridge.send("getData", { query: "metrics" });
        });

        window.mcpBridge.onMessage = function(method, params)
        {
            document.getElementById("output").textContent = JSON.stringify(params, null, 2);
        };
    </script>
</body>
</html>

Security

The Conversation component applies defence-in-depth to prevent cross-site scripting (XSS):

• User messages are rendered using textContent only. HTML in user input is never interpreted.
• Assistant messages are rendered through Vditor.preview() with sanitize: true, which strips dangerous markup before rendering Markdown.
• HTML copy export passes through DOMPurify.sanitize() before being written to the clipboard. If DOMPurify is not loaded, a console warning is emitted.
• System messages and error messages use textContent for all user-visible strings.
• MCP App iframes are sandboxed with sandbox="allow-scripts allow-forms" — no allow-same-origin, preventing access to the host page's DOM, cookies, or storage. A CSP meta tag is injected restricting default-src to 'none', script-src and style-src to 'unsafe-inline', and connect-src to explicitly listed domains only. PostMessage validation uses event.source === iframe.contentWindow (not origin, since sandboxed iframe origin is "null"). Each frame gets a unique ID for routing.

Loading DOMPurify via CDN is recommended for production deployments to ensure HTML export paths are sanitised.

Accessibility

The component implements the following accessibility features:

See specs/conversation.prd.md and specs/conversation-mcpui.prd.md for the complete specifications.

---

CronPicker

A visual builder for extended 6-field CRON expressions (second, minute, hour, day-of-month, month, day-of-week) with presets, mode-based field editors, human-readable descriptions, and bidirectional raw expression editing.

Quick Start

<link rel="stylesheet" href="components/cronpicker/cronpicker.css">
<script src="components/cronpicker/cronpicker.js"></script>

<div id="my-cron"></div>
<script>
    var picker = createCronPicker("my-cron", {
        value: "0 0 9 * * 1-5",
        onChange: function(expr) { console.log("Expression:", expr); }
    });
</script>

Configuration Options

CronPreset Interface

interface CronPreset {
    label: string;  // Display label
    value: string;  // CRON expression
}

Public API

CRON Expression Format

Six-field extended format: second minute hour day-of-month month day-of-week

Supported Syntax

Default Presets

Features

• Visual field builder with 4 modes per field: Every, Specific, Range, Step
• Chip grid for specific value selection with named labels for months and days
• Bidirectional sync between visual builder and raw expression input
• Human-readable description generated live from the expression
• Presets for common schedules with custom preset support
• Accessible with ARIA roles on all interactive elements

Dependencies

• Bootstrap CSS (form-control, form-select, btn)
• Bootstrap Icons CSS
• Does not require Bootstrap JS

---

DataGrid

High-performance flat data table with sorting, filtering, pagination, column resize, row selection, inline editing, virtual scrolling, footer aggregation, and CSV export.

Quick Start

<link rel="stylesheet" href="components/datagrid/datagrid.css">
<script src="components/datagrid/datagrid.js"></script>
<script>
    var grid = createDataGrid({
        columns: [
            { id: "name", label: "Name", sortable: true, filterable: true },
            { id: "status", label: "Status", filterType: "select",
              filterOptions: [
                  { value: "active", label: "Active" },
                  { value: "inactive", label: "Inactive" }
              ]},
            { id: "amount", label: "Amount", align: "right", aggregate: "sum" }
        ],
        rows: [
            { id: "1", data: { name: "Acme Corp", status: "active", amount: 1234.56 } },
            { id: "2", data: { name: "Beta Inc", status: "inactive", amount: 567.89 } }
        ],
        showFooter: true,
        selectable: "checkbox"
    }, "my-container");
</script>

API

DataGridOptions

DataGridColumn

DataGridRow

Callbacks

Methods

Features

• Sorting — Click header to sort (asc/desc/none). Shift+Click for multi-column sort.
• Filtering — Text search (250ms debounce), select dropdown, number range, date range.
• Pagination — Page buttons with ellipsis, page size dropdown, "Showing X-Y of Z" info.
• Column resize — Pointer-capture drag on header borders with min/max constraints.
• Column reorder — HTML5 drag-and-drop on header cells.
• Row selection — Single, multi (Ctrl/Shift+Click), or checkbox with select-all.
• Inline editing — Text, number, select, date editors. Enter/Tab commit, Escape cancel.
• Virtual scrolling — Auto-activates above 5,000 rows. DOM recycling for 100K+ rows.
• Footer aggregation — Sum, average, count, min, max, or custom function per column.
• CSV export — RFC 4180 compliant. Downloads filtered/sorted visible data.
• Dense mode — Compact 24px rows for high-density data display.
• Row striping — Alternating backgrounds for readability (enabled by default).

Keyboard

Accessibility

• Full WAI-ARIA Grid pattern: role="grid", role="row", role="columnheader", role="gridcell"
• aria-sort on sortable headers
• aria-rowindex on body rows
• Roving tabindex for single Tab stop
• Live region announcements for sort, filter, page, selection, and edit changes
• Checkbox role="checkbox" with aria-checked and aria-label
• Pagination <nav> with aria-label="Pagination" and aria-current="page"

---

DatePicker

A calendar date picker with day, month, and year navigation views.

Quick Start

Script Tag

<link rel="stylesheet" href="https://theme.priyavijai-kalyan2007.workers.dev/components/datepicker/datepicker.css">
<script src="https://theme.priyavijai-kalyan2007.workers.dev/components/datepicker/datepicker.js"></script>

<div id="my-date"></div>
<script>
    var picker = createDatePicker("my-date", {
        format: "yyyy-MM-dd",
        firstDayOfWeek: 0,
        onSelect: function(date) { console.log("Selected:", date); }
    });
</script>

Configuration Options

Instance Methods

Keyboard Interactions

Dependencies

• Bootstrap 5 CSS (input-group, form-control, btn)
• Bootstrap Icons (bi-calendar3, bi-chevron-left, bi-chevron-right)
• Enterprise Theme CSS

---

DiagramEngine

Universal vector canvas engine for diagramming, graph visualization, technical drawing, poster creation, and embedded document surfaces. 22,000+ lines across 26 source modules with full gradient, image, text-along-path, and raster painting support.

Quick Start

<link rel="stylesheet" href="components/diagramengine/diagramengine.css">
<script src="components/diagramengine/diagramengine.js"></script>

<div id="canvas" style="width: 100%; height: 600px;"></div>

<script>
var engine = createDiagramEngine("canvas", {
    grid: { visible: true, size: 20, style: "dots" },
    editable: true,
    textEditable: true,
});

engine.loadStencilPack("flowchart");

engine.addObject({
    semantic: { type: "process", data: { label: "Start" } },
    presentation: {
        shape: "rectangle",
        bounds: { x: 100, y: 100, width: 160, height: 80 },
        textContent: {
            runs: [{ text: "Start", bold: true }],
            overflow: "visible",
            verticalAlign: "middle",
            horizontalAlign: "center",
            padding: 8,
        },
    },
});
</script>

Features

Core

• 38+ built-in shapes across 7 stencil packs (basic, extended, flowchart, UML, BPMN, ER, network) plus paintable canvas shapes
• 12 tools: select, draw, text, connect, pen, brush, highlighter, paintbrush, measure, pan, zoom
• Semantic/presentation split — domain meaning separate from visual appearance
• SVG rendering with theme-aware colours (var(--theme-*))
• Dark mode via MutationObserver on data-bs-theme

Drawing & Painting

• Pen tool — click to place anchor points, click near first point to close shape with fill
• Brush tool — freehand drawing with point simplification
• Highlighter tool — semi-transparent thick strokes in 6 preset colours (yellow, pink, blue, green, orange, red)
• Paintbrush tool — raster painting inside paintable shapes with configurable brush size, shape (circle/square), colour, alpha, and hardness (0 = airbrush, 1 = hard edge)
• Paintable shapes — HTML <canvas> inside SVG clip masks (rectangle, circle, ellipse, triangle) with data URI persistence

Gradients

• Gradient fills — linear and radial gradients on any shape (solid, gradient, pattern, or none)
• Gradient strokes — gradient colours on shape borders and connector lines
• Per-edge stroke control — independent top/right/bottom/left borders with separate colour, width, dash pattern, and gradient per side
• Gradient text — per-run gradient colours on text via CSS background-clip: text (foreignObject) or SVG fill="url(#gradient)" (textPath)
• GradientPicker integration — compose with the GradientPicker component for interactive gradient editing

Text

• Rich text via <foreignObject> with inline editing on double-click
• Text along path (WordArt) — text follows SVG paths (arcs, bezier curves) via <textPath>
• Per-run styling — bold, italic, underline, strikethrough, font family, font size, colour (solid or gradient), letter spacing, superscript, subscript
• Template engine with {{variable | filter}} data binding

Connectors

• Straight, orthogonal, curved, manhattan, elbow, entity routing algorithms
• 7 arrow markers — none, block, classic, open, diamond, oval, dash
• Selectable connectors — click to select with dashed highlight, 12px transparent hit area
• Port hover indicators — blue circles appear at edge/corner ports during connect drag
• Gradient connector strokes — solid or gradient colours on connector lines
• Connector labels — positioned at start, middle, or end of path

Images

• SVG <image> rendering from URL or data URI with preserveAspectRatio fit modes (cover, contain, stretch, original)
• Custom HTTP headers for authenticated image loading — fetched via XHR, converted to data URI
• Transparency preserved — PNG/WebP/GIF alpha channels render correctly

Viewport

• Ultra Zoom — 10% to 3200% (32x) for pixel-level precision
• Pan — click+drag, middle-mouse, Space+drag
• Zoom to fit, zoom to selection, zoom to object
• Coordinate conversion — screenToCanvas(), canvasToScreen(), canvasToContainer()

Organisation

• Groups with collapse/expand, nested groups
• Layers with visibility, lock, opacity, z-ordering
• Page frames — 40+ predefined sizes (paper, cards, photo, presentation, social, mobile, screen) with customisable margins and borders
• Alignment guides — snap to edges, centres, equal spacing during drag
• Z-ordering — bring to front, send to back, bring forward, send backward

Persistence & Export

• JSON — full document serialisation with toJSON() / fromJSON()
• SVG — vector export with exportSVG()
• Dirty tracking — isDirty() / markClean() / getChangeCount()
• PNG export — deprecated (CORS limitations); use exportSVG() + server-side rendering

Analysis & Collaboration

• Graph analysis — shortest path, connected components, incoming/outgoing connectors
• Find and replace across all text content
• Format painter — pick and apply styles between objects
• Comments anchored to objects, connectors, or canvas positions
• Deep linking via diagram:// URI scheme
• Undo/redo with command merge window

Stencil Packs

Custom shapes can be registered via registerStencilPack(name, shapes).

Tools

Tool Configuration

// Access any tool instance for property configuration
var brush = engine.getToolInstance("paintbrush");
brush.brushSize = 12;
brush.brushHardness = 0.3;  // 0 = airbrush, 1 = hard edge
brush.brushColor = "#ff0000";
brush.brushAlpha = 0.6;
brush.brushShape = "circle";  // or "square"

var highlighter = engine.getToolInstance("highlighter");
highlighter.highlightColor = "rgba(255, 182, 193, 0.4)";  // pink

Style System

Fill Types

// Solid fill
{ type: "solid", color: "#1c7ed6" }

// Linear gradient fill
{ type: "gradient", gradient: {
    type: "linear", angle: 90,
    stops: [
        { offset: 0, color: "rgba(255, 0, 0, 0.8)" },
        { offset: 1, color: "rgba(0, 0, 255, 0.8)" }
    ]
}}

// Radial gradient fill
{ type: "gradient", gradient: {
    type: "radial", center: { x: 0.3, y: 0.3 }, radius: 0.8,
    stops: [
        { offset: 0, color: "#ffffff" },
        { offset: 1, color: "#000000" }
    ]
}}

// No fill
{ type: "none" }

Stroke Types

// Solid stroke
{ color: "#000000", width: 2 }

// Gradient stroke
{ color: { type: "linear", angle: 90, stops: [...] }, width: 3 }

// Dashed stroke
{ color: "#333", width: 1.5, dashPattern: [6, 3] }

Per-Edge Borders

perEdgeStroke: {
    top: { visible: true, color: "#1c7ed6", width: 3 },
    right: { visible: true, color: { type: "linear", stops: [...] }, width: 4 },
    bottom: { visible: true, color: "#dc2626", width: 3 },
    left: { visible: false }  // hidden
}

Text Styling

textContent: {
    runs: [
        { text: "Bold ", bold: true, color: "#1c7ed6" },
        { text: "Gradient ", color: { type: "linear", angle: 0,
            stops: [{ offset: 0, color: "#FF0000" }, { offset: 1, color: "#0000FF" }]
        }},
        { text: "Alpha", color: "rgba(111, 66, 193, 0.5)" }
    ],
    overflow: "visible",
    verticalAlign: "middle",
    horizontalAlign: "center",
    padding: 8
}

Text Along Path (WordArt)

textContent: {
    runs: [{ text: "Curved Text!", fontSize: 24, bold: true }],
    textPath: {
        path: "M 0,100 Q 200,0 400,100",  // SVG path in local coordinates
        startOffset: 0.5,                   // 50% along path
        textAnchor: "middle"                // centre text at offset
    },
    overflow: "visible",
    verticalAlign: "middle",
    horizontalAlign: "center",
    padding: 0
}

Image Objects

presentation: {
    shape: "image",
    image: {
        src: "https://example.com/photo.png",
        fit: "contain",  // cover, contain, stretch, original
        headers: { "Authorization": "Bearer token123" }  // optional auth
    }
}

Paintable Shapes

presentation: {
    shape: "paintable",
    paintable: {
        clipShape: "rectangle",  // rectangle, circle, ellipse, triangle
        clipToBounds: true,      // clip paint to shape boundary
        canvasData: "data:image/png;base64,..."  // persisted canvas content
    }
}

API Reference

Document

Objects

Connectors

Selection

Viewport

Tools

Transform

Groups & Layers

Clipboard & History

Page Frames

Export

Format & Search

Graph Analysis

Spatial Queries

Comments & Navigation

Events

Lifecycle

Keyboard Shortcuts

Architecture

components/diagramengine/
├── diagramengine.ts        # Bundled output (22,000+ lines)
├── diagramengine.scss      # Component styles
├── diagramengine.test.ts   # Per-edge stroke + gradient tests
├── diagramengine-core.test.ts      # Factory, CRUD, selection, zoom, undo, serialisation
├── diagramengine-features.test.ts  # Connectors, layers, groups, transforms, clipboard
├── diagramengine-advanced.test.ts  # Find/replace, format painter, graph analysis, events
├── README.md               # This file
└── src/                    # 26 source modules (concatenated by bundle script)
    ├── types.ts            # All interfaces and type definitions
    ├── event-bus.ts        # Pub/sub event system
    ├── undo-stack.ts       # Command pattern undo/redo
    ├── shape-registry.ts   # Shape registration + SVG rendering utilities
    ├── shapes-basic.ts     # 5 basic shapes (rectangle, ellipse, diamond, triangle, text)
    ├── shapes-extended.ts  # 12 extended shapes (hexagon, star, path, paintable, etc.)
    ├── stencils-*.ts       # Flowchart, UML, BPMN, ER, Network stencil packs
    ├── connectors.ts       # Connector routing, rendering, hit testing
    ├── guides.ts           # Alignment and spacing guides
    ├── render-engine.ts    # SVG DOM rendering, selection, inline editing, images, text
    ├── tool-select.ts      # Selection, move, resize, rotate, connector selection
    ├── tool-draw.ts        # Shape placement
    ├── tool-text.ts        # Text object creation
    ├── tool-connect.ts     # Connector creation with port indicators
    ├── tool-pen.ts         # Vector path drawing with close-shape support
    ├── tool-brush.ts       # Freehand vector drawing
    ├── tool-highlighter.ts # Semi-transparent marker strokes
    ├── tool-paintbrush.ts  # Raster painting with hardness control
    ├── tool-measure.ts     # Distance measurement
    ├── tool-pan.ts         # Canvas panning
    ├── tool-manager.ts     # Tool lifecycle, cursor management
    ├── templates.ts        # Template variable resolution
    ├── page-frames.ts      # Page frame rendering (40+ sizes)
    └── engine.ts           # Main engine class (public API)

Spec

Full PRD: specs/diagramengine.prd.md (3,685 lines, 21 sections)

---

DockLayout

A CSS Grid-based layout coordinator that arranges Toolbar, Sidebar, TabbedPanel, StatusBar, and content into a 5-zone application shell. Inspired by Java Swing's BorderLayout — child components are automatically positioned and resized without manual pixel-positioning.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Component CSS/JS for each slot component used (Toolbar, Sidebar, TabbedPanel, StatusBar)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/docklayout/docklayout.css">
<link rel="stylesheet" href="components/toolbar/toolbar.css">
<link rel="stylesheet" href="components/sidebar/sidebar.css">
<link rel="stylesheet" href="components/statusbar/statusbar.css">

<script src="components/toolbar/toolbar.js"></script>
<script src="components/sidebar/sidebar.js"></script>
<script src="components/statusbar/statusbar.js"></script>
<script src="components/docklayout/docklayout.js"></script>

<div id="my-content">
    <h1>Hello World</h1>
</div>

<script>
    var toolbar = new Toolbar({
        label: "My App",
        mode: "docked",
        dockPosition: "top",
        regions: [{ id: "main", tools: [{ id: "save", label: "Save", icon: "bi-floppy" }] }]
    });

    var sidebar = new Sidebar({
        title: "Explorer",
        dockPosition: "left",
        width: 260
    });

    var statusBar = new StatusBar({
        size: "sm",
        regions: [{ id: "status", label: "Ready" }]
    });

    var layout = createDockLayout({
        toolbar: toolbar,
        leftSidebar: sidebar,
        statusBar: statusBar,
        content: document.getElementById("my-content")
    });
</script>

How It Works

DockLayout creates a CSS Grid with 6 named areas:

┌─────────────────────────────────────┐
│              toolbar                │  auto height
├──────┬──────────────────┬───────────┤
│      │                  │           │
│ left │     center       │   right   │  1fr (fills remaining)
│      │                  │           │
├──────┴──────────────────┴───────────┤
│              bottom                 │  auto height
├─────────────────────────────────────┤
│              status                 │  auto height
└─────────────────────────────────────┘

When a component is passed to DockLayout, it automatically:

1. Calls component.setContained(true) — switches from position: fixed to position: relative
2. Calls component.show(gridCell) — mounts inside the grid cell
3. Hooks resize/collapse listeners — updates grid template dynamically

Options

Public API

LayoutState

interface LayoutState {
    toolbar: { height: number } | null;
    leftSidebar: { width: number; collapsed: boolean } | null;
    rightSidebar: { width: number; collapsed: boolean } | null;
    bottomPanel: { height: number; collapsed: boolean } | null;
    statusBar: { height: number } | null;
    content: { width: number; height: number };
}

Contained Mode

DockLayout automatically sets contained: true on child components. This switches them from viewport-fixed positioning to parent-relative positioning. All existing component features (resize, collapse, callbacks) continue to work.

Components that support contained mode:

• Sidebar — width controlled by resize handle, fills parent height
• Toolbar — auto height, fills parent width
• StatusBar — fixed height based on size, fills parent width
• TabbedPanel — height controlled by resize handle, fills parent width
• BannerBar — fixed to top of container instead of viewport

Dynamic Slot Management

// Add a bottom panel later
var chatPanel = new TabbedPanel({
    dockPosition: "bottom",
    height: 250,
    tabs: [{ id: "chat", title: "Chat", icon: "bi-chat" }]
});
layout.setBottomPanel(chatPanel);

// Remove it later
layout.setBottomPanel(null);

Integration with Content Components

Content placed in the center cell automatically fills it via CSS:

.dock-layout-center > * {
    width: 100%;
    height: 100%;
}

Components like TreeGrid, TreeView, Conversation, and Timeline work naturally in the center cell. For MarkdownEditor, pass contained: true to use height: "100%" instead of the default "70vh".

Global Exports

When loaded via <script> tag:

• window.DockLayout — DockLayout class
• window.createDockLayout — Factory function (creates and shows)

CSS Classes

---

DocViewer

Full-page three-column documentation layout.

Overview

DocViewer renders documentation in a three-column CSS Grid layout: a hierarchical TOC tree on the left, Vditor-rendered content in the center, and an "On This Page" outline on the right with IntersectionObserver-based scroll tracking.

Usage

<!-- Vditor CDN (required) -->
<link rel="stylesheet" href="https://unpkg.com/vditor@3.11.2/dist/index.css" />
<script src="https://unpkg.com/vditor@3.11.2/dist/index.min.js"></script>

<!-- DocViewer -->
<link rel="stylesheet" href="components/docviewer/docviewer.css" />
<script src="components/docviewer/docviewer.js"></script>

var viewer = createDocViewer({
    container: document.getElementById("docs-container"),
    pages: [
        {
            id: "intro",
            title: "Introduction",
            markdown: "# Introduction\n\nWelcome to the docs.",
            children: [
                { id: "getting-started", title: "Getting Started", url: "/docs/getting-started.md" },
                { id: "installation", title: "Installation", url: "/docs/installation.md" }
            ]
        },
        {
            id: "api",
            title: "API Reference",
            icon: "bi-code-slash",
            url: "/docs/api.md"
        }
    ],
    activePage: "intro",
    onPageChange: function(pageId) { console.log("Page:", pageId); }
});

// Navigate programmatically
viewer.navigateTo("api");

Factory

Options

DocPage

API

Layout

Three-column CSS Grid: 260px 1fr 220px (configurable).

Content Enhancements

• Code blocks: copy-to-clipboard button
• Images: CSS drop-shadow
• Videos: responsive 16:9 wrapper
• Headings: auto-assigned anchor IDs

Responsive

• < 1200px: outline panel hides
• < 768px: TOC hides, hamburger toggle appears

Keyboard

Dependencies

• Vditor ≥3.11.2 — CDN; falls back to plain text
• Bootstrap Icons — TOC icons

Asset Paths

CSS: components/docviewer/docviewer.css
JS:  components/docviewer/docviewer.js

---

DurationPicker

A duration/interval picker with configurable unit patterns and ISO 8601 support.

Quick Start

<link rel="stylesheet" href="https://theme.priyavijai-kalyan2007.workers.dev/components/durationpicker/durationpicker.css">
<script src="https://theme.priyavijai-kalyan2007.workers.dev/components/durationpicker/durationpicker.js"></script>

<div id="my-duration"></div>
<script>
    var picker = createDurationPicker("my-duration", {
        pattern: "h-m",
        onChange: function(val) { console.log("Duration:", val); }
    });
</script>

Supported Patterns

d-h-m, h-m, h-m-s, h, m, s, m-s, w, fn, mo, q, y, y-mo, y-mo-d, w-d, w-d-h, d-h-m-s

Configuration Options

Instance Methods

Manual Input

Accepts ISO 8601 (PT4H30M) or shorthand (4h 30m).

Dependencies

• Bootstrap 5 CSS, Bootstrap Icons, Enterprise Theme CSS

---

EditableComboBox

A combined text input and dropdown list component built on Bootstrap 5. Users can type free text or select a value from a filterable dropdown.

Purpose and Use Cases

• Searchable selectors with large option lists
• Fields where users may type a custom value or pick from suggestions
• Tag entry with auto-complete suggestions
• Country, region, or status selectors

Quick Start

Script Tag

<!-- Dependencies -->
<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="icons/bootstrap-icons.css">
<link rel="stylesheet" href="components/editablecombobox/editablecombobox.css">

<!-- Component -->
<div id="my-combo"></div>
<script src="components/editablecombobox/editablecombobox.js"></script>
<script>
    createEditableComboBox("my-combo", {
        items: [
            { label: "Apple" },
            { label: "Banana" },
            { label: "Cherry" }
        ],
        placeholder: "Pick a fruit..."
    });
</script>

ES Module

import { createEditableComboBox } from "./components/editablecombobox/editablecombobox.js";

const combo = createEditableComboBox("my-combo", {
    items: [{ label: "Red" }, { label: "Green" }, { label: "Blue" }],
    onSelect: (item) => console.log("Selected:", item.label)
});

Configuration Options

ComboBoxItem

Instance Methods

Keyboard Interactions

Accessibility

• Implements the WAI-ARIA Combobox pattern
• role="combobox" on the input with aria-expanded, aria-controls, aria-activedescendant
• role="listbox" on the dropdown, role="option" on each item
• Focus stays on the input; items are highlighted via aria-activedescendant
• "No matches" message uses role="status" for screen reader announcement

Dependencies

---

EmptyState

A centered placeholder component shown when a view, list, table, or container has no data. Presents a large icon (or custom illustration), heading, optional description, primary CTA button, and secondary link. Supports three size variants and compact mode.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*) and .btn-* classes
• Bootstrap Icons — for default and CTA button icons
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/emptystate/emptystate.css">
<script src="components/emptystate/emptystate.js"></script>
<script>
    var empty = createEmptyState("my-container", {
        heading: "No projects found",
        description: "Create your first project to get started.",
        actionLabel: "Create Project",
        actionIcon: "bi-plus-lg",
        onAction: function() { console.log("Create clicked"); }
    });
</script>

Options (EmptyStateOptions)

API

Global Exports

window.EmptyState
window.createEmptyState

Accessibility

• Heading uses native <h3>/<h4>/<h5> for document outline
• Icon/illustration has aria-hidden="true" (decorative)
• CTA button references description via aria-describedby
• Secondary link is a native <button> element

See specs/emptystate.prd.md for the complete specification.

---

ErrorDialog Component

A Bootstrap 5 modal that displays literate error messages with user-friendly narrative and collapsible technical details.

Dependencies

• Bootstrap 5 JS (Modal API) — loaded as a global script
• Bootstrap Icons CSS — for header and UI icons
• Enterprise theme CSS — css/custom.css
• Component CSS — components/errordialog/errordialog.css

Quick Start

<!-- In your HTML head -->
<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="icons/bootstrap-icons.css">
<link rel="stylesheet" href="components/errordialog/errordialog.css">

<!-- Container where modals will be injected -->
<div id="error-dialog-container"></div>

<!-- Scripts -->
<script src="js/bootstrap.bundle.min.js"></script>
<script src="components/errordialog/errordialog.js"></script>
<script>
    showErrorDialog("error-dialog-container", {
        title: "Document Could Not Be Saved",
        message: "The server rejected the save request.",
        suggestion: "Please try again in a moment.",
        errorCode: "DOC_SAVE_FAILED",
        correlationId: "a1b2c3d4-e5f6-7890"
    });
</script>

LiterateError Interface

API

Class: ErrorDialog

const dialog = new ErrorDialog("container-id");
dialog.show({ title: "Error", message: "Something went wrong." });
dialog.hide();
dialog.destroy();

• show(error) — Builds and displays the modal
• hide() — Hides the modal (triggers cleanup)
• destroy() — Removes the modal element from the DOM

Function: showErrorDialog(containerId, error)

One-liner convenience function. Creates an ErrorDialog instance and immediately shows it.

Features

• Danger header — Red header strip with exclamation icon
• Suggestion box — Light alert with lightbulb icon (only when suggestion provided)
• Technical accordion — Collapsible section with error code, correlation ID, timestamp, context, and stack trace
• Copy to clipboard — Copies all technical details with visual feedback
• Retry button — Shown only when onRetry callback is provided
• XSS safe — All content set via textContent, never innerHTML
• Auto-cleanup — Modal DOM is removed when dismissed

Accessibility

• Modal uses aria-labelledby pointing to the title
• Close button has aria-label="Close"
• Suggestion box has role="alert"
• Tab navigation works across all focusable elements
• Escape key closes the modal

---

ExplorerPicker

A reusable resource-selection widget that renders an Explorer tree in "picker mode." Users browse the organisational hierarchy or search by name to select one or more resources, then confirm their selection. Self-contained — a single CSS + JS file pair deployable via CDN with no runtime dependency on other library components.

Usage

CDN

<link rel="stylesheet" href="components/explorerpicker/explorerpicker.css">
<script src="components/explorerpicker/explorerpicker.js"></script>

Basic Example

const picker = createExplorerPicker({
    container: "my-picker-container",
    mode: "single",
    selectionTarget: "resource",
    onConfirm: (selections) =>
    {
        console.log("Selected:", selections);
    },
    onCancel: () =>
    {
        console.log("Cancelled");
    },
});

Modal via FormDialog

const dialog = createFormDialog({
    title: "Link to Resource",
    size: "large",
    fields: [],
    customContent: (container) =>
    {
        createExplorerPicker({
            container,
            mode: "multi",
            height: "100%",
            onConfirm: (selections) =>
            {
                dialog.close();
                createRelationships(selections);
            },
            onCancel: () => dialog.close(),
        });
    },
    hideDefaultButtons: true,
});
dialog.open();

Options

Instance API

Data Types

ExplorerNode

interface ExplorerNode
{
    id: string;
    name: string;
    nodeType: "ORG_UNIT" | "FOLDER" | "ASSET_REF" | "LINK";
    resourceId: string | null;
    resourceType: string | null;
    sourceId: string | null;
    url: string | null;
    linkType: string | null;
    hasChildren: boolean;
    parentId: string | null;
}

ExplorerPickerSelection

interface ExplorerPickerSelection
{
    nodeId: string;
    resourceId: string | null;
    name: string;
    nodeType: ExplorerNodeType;
    resourceType: string | null;
    sourceId: string | null;
    breadcrumb: string;
    url: string | null;
}

Features

• Tree browsing with lazy-loaded children
• Search with 300ms debounce, breadcrumb paths, pagination
• Quick-access sections for recent and starred items
• Ontology-driven icons with colour and external badges
• Virtual scrolling for trees with 200+ visible nodes
• Keyboard navigation (Arrow keys, Home/End, Enter, Space, Escape, /)
• State export/restore for session continuity
• Chrome integration with hover-glow, focus-glow, edge-shadow
• Accessibility with ARIA roles, live region announcements
• Dark mode with lightness-clamped ontology colours
• Reduced motion support

Keyboard Shortcuts

Chrome Effects

The component uses the Enterprise Theme chrome system:

• Node rows: hover-glow on hover
• Search input: focus-glow on focus
• Buttons: focus-glow on focus
• Search bar: edge-shadow("bottom") separator
• Section headers: chrome-transition for smooth state changes

Tests

82 unit tests covering:

• Factory and lifecycle
• DOM structure and ARIA roles
• Single-select and multi-select
• Confirm/cancel callbacks
• API data layer (mock fetch)
• Search input and clear
• Quick-access sections
• Ontology integration
• Exclude nodes and pre-selection
• Breadcrumbs and selection change
• State export/restore
• Keyboard navigation
• Accessibility attributes

npx vitest run components/explorerpicker/explorerpicker.test.ts

---

FacetSearch

Facet-aware search bar that combines free-text search with structured key:value query facets. Parsed facets appear as removable chips inline, while an autocomplete dropdown assists with facet key discovery and value selection.

Quick Start

<link rel="stylesheet" href="components/facetsearch/facetsearch.css">
<script src="components/facetsearch/facetsearch.js"></script>
<script>
    var search = createFacetSearch("my-container", {
        facets: [
            { key: "status", label: "Status", valueType: "enum",
              values: ["open", "closed", "pending"], icon: "bi bi-circle" },
            { key: "priority", label: "Priority", valueType: "enum",
              values: ["critical", "high", "medium", "low"] },
            { key: "author", label: "Author", valueType: "text" }
        ],
        onSearch: function(query) {
            console.log("Facets:", query.facets, "Text:", query.text);
        }
    });
</script>

Assets

Requires: Bootstrap CSS, Bootstrap Icons CSS.

Facet Definition (FacetDefinition)

Options (FacetSearchOptions)

API Methods

Query Syntax

Keyboard Interaction

Standalone Parser

The query parser is exported as a standalone pure function:

var result = parseFacetQuery("status:open priority:high bug fix", facetDefs);
// result.facets = [{key:"status", op:":", value:"open", negated:false}, ...]
// result.text = "bug fix"

See specs/facetsearch.prd.md for the full specification.

---

FileExplorer

Two-pane file navigation component with a folder tree sidebar, breadcrumb navigation, three view modes (grid, list, detail), multi-selection, context menu, inline rename, sorting, drag-and-drop, and callback-driven file operations. Supports both tree mode (sidebar + hierarchy) and flat mode (host-driven items + breadcrumbs).

Quick Start

Tree Mode (Default)

<link rel="stylesheet" href="components/fileexplorer/fileexplorer.css">
<script src="components/fileexplorer/fileexplorer.js"></script>
<script>
    var explorer = createFileExplorer("my-container", {
        roots: [
            {
                id: "root", name: "Documents", type: "folder",
                children: [
                    { id: "f1", name: "Report.pdf", type: "file", size: 245000 },
                    { id: "f2", name: "Budget.xlsx", type: "file", size: 89000 },
                    {
                        id: "sub", name: "Images", type: "folder",
                        children: [
                            { id: "f3", name: "logo.png", type: "file", size: 34000 }
                        ]
                    }
                ]
            }
        ],
        onOpen: function(file) { console.log("Open:", file.name); },
        onNavigate: function(folder) { console.log("Navigate:", folder.name); }
    });
</script>

Flat Mode (Host-Driven)

<script>
    var explorer = createFileExplorer(document.getElementById("panel"), {
        showTreePane: false,
        items: [
            { id: "d1", name: "Projects", type: "folder" },
            { id: "d2", name: "Design.fig", type: "file", typeLabel: "Diagram", iconColor: "#e74c3c" },
        ],
        breadcrumb: [
            { id: null, label: "Home" },
            { id: "org1", label: "My Org" },
        ],
        onBreadcrumbNavigate: function(segmentId) { loadFolder(segmentId); },
        onOpen: function(node) { openItem(node); },
    });
</script>

See the FileExplorer Flat Mode Guide for the full Apps Team Integration Guide.

Assets

Requires: Bootstrap CSS, Bootstrap Icons CSS.

FileNode Interface

BreadcrumbSegment Interface

FileExplorerColumn Interface

Options (FileExplorerOptions)

API Methods

View Modes

• Grid: Thumbnail-style cards with large icons and file names in a CSS grid
• List: Compact single-line rows with icon, name, and size
• Detail: Table-like layout with sortable column headers (customizable via columns)

Grouping

• type-first: Folders group, then files grouped by typeLabel or extension
• none: No visual grouping
• Custom function: (items) => Array<{ label: string; items: FileNode[] }>

Keyboard

CSS Custom Properties

Override on .fileexplorer:

.fileexplorer {
    --file-explorer-bg: #1a1a2e;
    --file-explorer-border: #2d2d44;
    --file-explorer-row-selected-bg: rgba(59, 130, 246, 0.2);
}

File Type Icons

Extensions are auto-mapped to Bootstrap Icons (PDF, Word, Excel, images, video, audio, code, text, markdown, archives). Set FileNode.icon to override. Set FileNode.iconColor for custom icon colors.

See specs/fileexplorer.component.prd.md for the full specification.

---

FileUpload

A drag-and-drop file upload zone with progress bars, file type validation, size limits, batch upload, and an optional download queue. Modelled after Dropbox, Google Drive, and AWS S3 Console upload patterns.

Features

• Drag-and-drop -- dashed-border dropzone with visual feedback on drag-over
• Click to browse -- hidden file input triggered by click or keyboard
• File validation -- max file size, max total size, max file count, MIME/extension filtering
• Progress tracking -- per-file progress bars with ARIA progressbar role
• Status transitions -- queued, uploading, completed, failed with distinct visual states
• Retry failed uploads -- action button changes to retry icon on failure
• Batch upload -- auto-upload on add or manual uploadAll() call
• Download section -- optional list of downloadable files with links
• Disabled state -- disables all interaction and applies visual indicator
• Size variants -- sm, md (default), lg for different layout contexts
• Accessible -- ARIA live region, button roles, progressbar roles, keyboard support
• Reduced motion -- respects prefers-reduced-motion media query

Assets

Requires: Bootstrap CSS (for SCSS variables), Bootstrap Icons (for file type and action icons). Does not require Bootstrap JS.

Quick Start

Basic Upload

<link rel="stylesheet" href="components/fileupload/fileupload.css">
<script src="components/fileupload/fileupload.js"></script>

<div id="upload-container"></div>

<script>
    var uploader = createFileUpload("upload-container", {
        accept: "image/*,.pdf",
        maxFileSize: 5 * 1024 * 1024,
        maxFiles: 5,
        onUpload: function(file, onProgress) {
            return new Promise(function(resolve, reject) {
                // Simulate upload with progress
                var progress = 0;
                var interval = setInterval(function() {
                    progress += 0.1;
                    onProgress(progress);
                    if (progress >= 1) {
                        clearInterval(interval);
                        resolve();
                    }
                }, 200);
            });
        }
    });
</script>

With Downloads

<script>
    var uploader = createFileUpload("upload-container", {
        showDownloads: true,
        downloads: [
            { name: "report.pdf", size: 1258291, url: "/files/report.pdf" },
            { name: "data.csv", size: 45032, url: "/files/data.csv", icon: "bi-file-text" }
        ],
        onUpload: function(file, onProgress) {
            // Your upload logic here
            return fetch("/api/upload", { method: "POST", body: file });
        }
    });
</script>

ES Module

import { FileUpload, createFileUpload } from "./components/fileupload/fileupload";

const uploader = createFileUpload("my-container", {
    accept: "image/*",
    maxFileSize: 10 * 1024 * 1024,
    autoUpload: false,
    onUpload: async (file, onProgress) => {
        const formData = new FormData();
        formData.append("file", file);
        await uploadWithProgress("/api/upload", formData, onProgress);
    },
});

// Later, start all uploads manually
uploader.uploadAll();

API

Factory Function

createFileUpload(containerId: string, options: FileUploadOptions): FileUpload

Creates a FileUpload instance, appends it to the container, and returns the instance.

Constructor

const uploader = new FileUpload(options: FileUploadOptions);

Creates the FileUpload DOM but does not attach to the page. Call show() to attach.

FileUploadOptions

FileDownloadItem

Methods

Global Exports

window.FileUpload
window.createFileUpload

File States

Keyboard Shortcuts

Override key bindings via the keyBindings option:

createFileUpload("container", {
    keyBindings: {
        browse: "Ctrl+O",
    },
});

Available Action Names

Accessibility

• Dropzone uses role="button" with tabindex="0" and descriptive aria-label
• File list uses role="list" with role="listitem" on each file row
• Progress bars use role="progressbar" with aria-valuenow, aria-valuemin, aria-valuemax
• Action buttons have descriptive aria-label (e.g., "Remove photo.jpg", "Retry report.pdf")
• Live region (aria-live="polite") announces file additions, removals, and upload status changes
• Download links have descriptive aria-label (e.g., "Download report.pdf")
• Focus-visible outline on dropzone for keyboard navigation
• Disabled state uses aria-disabled="true" and removes from tab order

---

FlexGridLayout

An advanced CSS Grid layout container with mixed track sizes and cell spanning. Supports variable column and row definitions (px, fr, auto), named grid areas, per-cell alignment overrides, and multi-column/multi-row spanning. Designed for complex enterprise form layouts, dashboard grids, and any arrangement requiring non-uniform track sizing.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/flexgridlayout/flexgridlayout.css">
<script src="components/flexgridlayout/flexgridlayout.js"></script>

<script>
    // A two-column form layout: fixed label column, flexible field column
    var layout = createFlexGridLayout({
        columns: ["160px", "1fr"],
        rows: ["auto", "auto", "auto"],
        gap: 8,
        padding: "16px",
        cells: [
            { child: document.getElementById("label-name"),  column: 0, row: 0 },
            { child: document.getElementById("field-name"),  column: 1, row: 0 },
            { child: document.getElementById("label-email"), column: 0, row: 1 },
            { child: document.getElementById("field-email"), column: 1, row: 1 },
            { child: document.getElementById("label-notes"), column: 0, row: 2, alignSelf: "start" },
            { child: document.getElementById("field-notes"), column: 1, row: 2 }
        ]
    });
</script>

How It Works

FlexGridLayout creates a CSS Grid container. Columns and rows are defined as arrays of track size strings. Each cell is placed at a specific column/row position and can optionally span multiple tracks.

columns: ["160px", "1fr", "1fr"]
rows:    ["auto", "1fr", "auto"]

     160px        1fr           1fr
   +----------+-------------+-------------+
   |  Header (columnSpan: 3)              |  auto
   +----------+-------------+-------------+
   |  Nav     |  Main content             |  1fr
   |  (fixed) |  (columnSpan: 2)          |
   +----------+-------------+-------------+
   |  Footer (columnSpan: 3)              |  auto
   +----------+-------------+-------------+

Track sizes can be mixed freely:

• px -- fixed pixel widths (labels, icons, gutters)
• fr -- fractional units that share remaining space
• auto -- sizes to content
• minmax() -- responsive ranges

Options

FlexGridLayoutOptions

FlexGridCellConfig

Public API

FlexGridLayoutState

interface FlexGridLayoutState {
    columns: string[];
    rows: string[];
    cellCount: number;
}

Composability

FlexGridLayout implements the standard layout container contract. Any component with show(container) / hide() / destroy() can be used as a child. Plain HTMLElements are also supported. Components with a setContained(true) method are automatically put into contained mode.

// A dashboard layout with mixed track sizes
var dashboard = new FlexGridLayout({
    columns: ["240px", "1fr", "1fr"],
    rows: ["48px", "1fr", "32px"],
    gap: 4,
    height: "100vh",
    cells: [
        { child: toolbar,    column: 0, row: 0, columnSpan: 3 },
        { child: sidebar,    column: 0, row: 1 },
        { child: mainPanel,  column: 1, row: 1, columnSpan: 2 },
        { child: statusBar,  column: 0, row: 2, columnSpan: 3 }
    ]
});

Global Exports

When loaded via <script> tag:

• window.FlexGridLayout -- FlexGridLayout class
• window.createFlexGridLayout -- Factory function (creates and shows)

CSS Classes

---

FlowLayout

A wrapping flex layout container that arranges children sequentially and wraps to the next line when the boundary is reached. Supports configurable gap, alignment, content distribution, and separate row/column gaps.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/flowlayout/flowlayout.css">
<script src="components/flowlayout/flowlayout.js"></script>

<script>
    var tags = ["JavaScript", "TypeScript", "CSS", "HTML", "React", "Vue"];
    var children = tags.map(function(tag) {
        var el = document.createElement("span");
        el.className = "badge bg-primary";
        el.textContent = tag;
        return el;
    });

    var layout = createFlowLayout({
        direction: "horizontal",
        gap: 8,
        align: "center",
        children: children
    });
</script>

How It Works

FlowLayout creates a CSS Flexbox container with flex-wrap: wrap. Children are placed sequentially along the primary axis and wrap to new lines when they exceed the container boundary.

direction: "horizontal", gap: 8
┌─────────────────────────────────────────────┐
│ [Tag 1] [Tag 2] [Tag 3] [Tag 4] [Tag 5]   │
│ [Tag 6] [Tag 7] [Tag 8]                    │
└─────────────────────────────────────────────┘

Options

Public API

Global Exports

When loaded via <script> tag:

• window.FlowLayout — FlowLayout class
• window.createFlowLayout — Factory function (creates and shows)

CSS Classes

---

FontDropdown

A dropdown where each font name renders in its own typeface, similar to the font picker in Google Docs. Includes a search input for filtering, recently-used tracking via localStorage, and full keyboard navigation.

Purpose and Use Cases

• Rich text editors that need a font family picker
• Document formatting toolbars and Ribbon controls
• Theme or typography configuration panels
• Any UI where users select from a list of fonts with live preview

Quick Start

Script Tag

<!-- Dependencies -->
<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="icons/bootstrap-icons.css">
<link rel="stylesheet" href="components/fontdropdown/fontdropdown.css">

<!-- Component -->
<div id="my-fonts"></div>
<script src="components/fontdropdown/fontdropdown.js"></script>
<script>
    createFontDropdown("my-fonts", {
        value: "Georgia, serif",
        showRecent: true,
        onChange: (font) => console.log("Selected:", font.label)
    });
</script>

ES Module

import { createFontDropdown } from "./components/fontdropdown/fontdropdown.js";

const picker = createFontDropdown("my-fonts", {
    placeholder: "Choose a font...",
    previewText: "The quick brown fox",
    onChange: (font) => applyFont(font.value)
});

Configuration Options

FontItem

Instance Methods

Default Fonts

The component ships with 17 web-safe fonts when no custom fonts array is provided:

Arial, Calibri, Cambria, Comic Sans MS, Consolas, Courier New, Georgia, Helvetica, Impact, JetBrains Mono, Lucida Console, Open Sans, Palatino, Tahoma, Times New Roman, Trebuchet MS, Verdana.

Keyboard Interactions

Key bindings can be overridden via the keyBindings option using action names: openOrMoveDown, openOrMoveUp, confirmSelection, closeDropdown, jumpToFirst, jumpToLast, pageDown, pageUp.

Recently Used Fonts

When showRecent: true, the dropdown displays a "Recently Used" section above the full font list. Selections are persisted to localStorage under the key fontdropdown-recent. Configure the maximum count with maxRecent (default 5).

Size Variants

<script>createFontDropdown("sm-picker", { size: "sm" });</script>
<script>createFontDropdown("default-picker", {});</script>
<script>createFontDropdown("lg-picker", { size: "lg" });</script>

Size classes applied: fontdropdown-sm, fontdropdown-lg.

Ribbon Integration

Register FontDropdown as a custom control in the Ribbon component:

const ribbon = createRibbon("ribbon-host", {
    tabs: [{
        label: "Home",
        groups: [{
            label: "Font",
            controls: [{
                type: "custom",
                render: (container) => {
                    createFontDropdown(container.id, {
                        size: "sm",
                        showRecent: true,
                        onChange: (font) => applyFont(font.value)
                    });
                }
            }]
        }]
    }]
});

Accessibility

• role="combobox" on the trigger with aria-expanded, aria-haspopup="listbox"
• role="listbox" on the font list, role="option" on each item
• aria-selected="true" on the currently selected item
• aria-activedescendant tracks the highlighted item during keyboard navigation
• aria-label on both trigger ("Font selector") and search input ("Filter fonts")
• Search match highlighting via <mark> elements
• "No matching fonts" message uses role="presentation"

Dependencies

---

FormDialog

A modal dialog optimized for form-based workflows (create, edit, invite, assign). Supports two mutually exclusive modes: single-page (scrollable form body with optional collapsible sections) and wizard (multi-step form with step indicator, Back/Next navigation, and per-step validation). Optionally includes a resizable sidebar panel for help text, previews, or contextual information.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables and .btn-* classes
• Bootstrap Icons -- bi-x-lg, bi-chevron-down, bi-chevron-right, bi-check-lg
• Enterprise theme CSS -- css/custom.css
• Optional: window.showConfirmDialog (from ConfirmDialog) for dirty-change warnings
• Optional: window.showErrorToast (from Toast) for rejected promise errors
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="icons/bootstrap-icons.css">
<link rel="stylesheet" href="components/formdialog/formdialog.css">

<script src="components/formdialog/formdialog.js"></script>
<script>
    const dialog = createFormDialog({
        title: "Invite New User",
        size: "sm",
        description: "Send an invitation to join your workspace.",
        submitLabel: "Send Invitation",
        fields: [
            { name: "email", label: "Email Address", type: "email", required: true, placeholder: "user@example.com" },
            { name: "role", label: "Role", type: "select", required: true, value: "MEMBER",
              options: [{ value: "MEMBER", label: "Member" }, { value: "ADMIN", label: "Admin" }] }
        ],
        onSubmit: async (values) => {
            await fetch("/api/invitations", { method: "POST", body: JSON.stringify(values) });
        }
    });

    dialog.show();
</script>

API

Factory Function

FormDialog Instance

FormDialogOptions

Field Types

FormFieldDef

FormSection

FormStep (Wizard Mode)

FormDialogPanel

Modes

Single-Page Mode

Provide fields (and optionally sections) for a single scrollable form. Fields are rendered in order; adjacent half or third fields are placed in multi-column rows.

createFormDialog({
    title: "Edit User",
    size: "lg",
    sections: [
        { id: "personal", label: "Personal Information" },
        { id: "access", label: "Access & Permissions", collapsed: true }
    ],
    fields: [
        { name: "first", label: "First Name", type: "text", required: true, width: "third", section: "personal" },
        { name: "middle", label: "Middle Name", type: "text", width: "third", section: "personal" },
        { name: "last", label: "Last Name", type: "text", required: true, width: "third", section: "personal" },
        { name: "role", label: "Role", type: "select", width: "half", section: "access",
          options: [{ value: "admin", label: "Admin" }, { value: "member", label: "Member" }] },
        { name: "status", label: "Status", type: "select", width: "half", section: "access",
          options: [{ value: "active", label: "Active" }, { value: "inactive", label: "Inactive" }] }
    ],
    onSubmit: async (values) => { /* save */ }
});

Wizard Mode

Provide steps for a multi-step wizard. Each step has its own fields. The step indicator shows progress, and Back/Next buttons navigate between steps.

createFormDialog({
    title: "Create Workspace",
    size: "xl",
    stepTransition: "slide",
    steps: [
        { id: "basics", label: "Basics", fields: [
            { name: "name", label: "Workspace Name", type: "text", required: true }
        ]},
        { id: "members", label: "Members", description: "Invite team members.", fields: [
            { name: "email", label: "Email", type: "email", required: true },
            { name: "role", label: "Role", type: "select", options: [
                { value: "member", label: "Member" }, { value: "admin", label: "Admin" }
            ]}
        ]},
        { id: "review", label: "Review", fields: [] }
    ],
    onSubmit: async (values) => { /* create workspace */ }
});

With Panel

Add a resizable sidebar panel for help text or previews. If panel.content is a function, it re-renders reactively when fields change.

createFormDialog({
    title: "Create Role",
    size: "xl",
    panel: {
        title: "Help",
        width: 280,
        content: (values) => {
            const el = document.createElement("div");
            el.textContent = values.name
                ? `Role "${values.name}" will be created.`
                : "Fill in the role details.";
            return el;
        }
    },
    fields: [
        { name: "name", label: "Role Name", type: "text", required: true },
        { name: "description", label: "Description", type: "textarea" }
    ],
    onSubmit: async (values) => { /* save */ }
});

Keyboard

Key bindings can be overridden via the keyBindings option.

Validation

• Required fields -- non-empty trimmed value; inline error "This field is required"
• Email fields -- basic @ + . check; inline error "Please enter a valid email address"
• Custom per-field -- field.validate(value) returns error string or null
• Custom per-step (wizard) -- step.validate(values) for cross-field validation
• Errors clear automatically on field input
• On submit/next: all visible fields validated, first invalid field focused

Accessibility

• Dialog: role="dialog", aria-modal="true", aria-labelledby pointing to title
• Close button: aria-label="Close"
• Required fields: aria-required="true"
• Error fields: aria-invalid="true", aria-describedby linked to error element
• Section toggles: aria-expanded, aria-controls
• Step indicator: aria-current="step" on active step
• Live region: aria-live="polite" for announcements
• Focus trap: Tab/Shift+Tab cycles within dialog
• Focus restore: returns focus to previously active element on close
• Animations respect prefers-reduced-motion: reduce

DOM Structure

Single-Page (with panel)

div.formdialog-overlay
  div.formdialog-backdrop
  div.formdialog-dialog.formdialog-dialog-{size} [role="dialog" aria-modal="true"]
    div.formdialog-header
      h2.formdialog-title
      button.formdialog-close [aria-label="Close"]
    div.formdialog-description?
    div.formdialog-body.formdialog-body-split?
      div.formdialog-form
        div.formdialog-section
          button.formdialog-section-toggle [aria-expanded]
            i.formdialog-section-chevron
            i.formdialog-section-icon?
            span (label)
          div.formdialog-section-body [id]
            div.formdialog-row.formdialog-row-half?
              div.formdialog-group
                label.formdialog-label
                input.formdialog-input
                span.formdialog-help
                span.formdialog-error
      div.formdialog-divider?
      div.formdialog-panel?
        div.formdialog-panel-header?
        div.formdialog-panel-content
    div.formdialog-footer
      div.formdialog-footer-left
      div.formdialog-actions
        button.btn.btn-secondary (Cancel)
        button.btn.btn-primary (Submit)

Wizard Mode

div.formdialog-overlay
  div.formdialog-backdrop
  div.formdialog-dialog [role="dialog"]
    div.formdialog-header
    div.formdialog-steps
      button.formdialog-step.formdialog-step-complete
        span.formdialog-step-number (check icon)
        span.formdialog-step-label
      span.formdialog-step-connector.formdialog-step-connector-done
      button.formdialog-step.formdialog-step-active [aria-current="step"]
        span.formdialog-step-number (2)
        span.formdialog-step-label
      span.formdialog-step-connector
      button.formdialog-step.formdialog-step-pending
        span.formdialog-step-number (3)
        span.formdialog-step-label
    div.formdialog-body
      div.formdialog-form (current step fields)
    div.formdialog-footer
      div.formdialog-footer-left "Step 2 of 3"
      div.formdialog-actions
        button (Back)
        button (Next / Submit)

Features

• Two modes -- single-page or wizard, mutually exclusive
• 12 field types -- text, email, password, number, select, textarea, readonly, hidden, checkbox, toggle, date, custom
• Multi-column layout -- width: "half" or "third" for side-by-side fields
• Collapsible sections -- group related fields with expand/collapse
• Resizable panel -- pointer-capture drag sidebar for help or previews
• Reactive panel -- panel content re-renders when fields change (function mode)
• Wizard stepping -- numbered step indicator with connectors, configurable transitions
• Built-in validation -- required, email, custom per-field, custom per-step
• Loading state -- spinner on submit button, all fields disabled during async submit
• Dirty tracking -- optional warnOnDirty prompts ConfirmDialog before discarding changes
• Focus trap -- Tab cycles within dialog; no escape
• Focus restore -- returns focus to previously active element
• XSS safe -- all content set via textContent, never innerHTML
• Auto-cleanup -- DOM removed on destroy()
• No Bootstrap JS dependency -- fully standalone modal implementation

---

Gauge

A visual measure component modeled after the ASN.1 Gauge type. Displays a value on a scale with configurable colour thresholds. Supports three shapes (tile, ring, bar) and two modes (value, time countdown).

Features

• Three shapes — square tile, circular ring (SVG), horizontal/vertical bar
• Value mode — numeric value with min/max/units (e.g., storage, licenses, CPU)
• Time mode — countdown to a target date with auto-tick and overdue state
• Configurable thresholds — colour changes at user-defined percentage boundaries
• Over-limit / Overdue — distinct colour and label when value exceeds max or time passes
• Fluid or explicit sizing — fills parent container or uses preset/pixel sizes
• Custom formatting — provide a formatValue callback for custom display
• Full accessibility — role="meter" / role="timer", ARIA value attributes, descriptive labels

Assets

Requires: Bootstrap CSS (for SCSS variables). Does not require Bootstrap JS or Bootstrap Icons.

Quick Start

<link rel="stylesheet" href="components/gauge/gauge.css">
<script src="components/gauge/gauge.js"></script>
<script>
    // Value tile
    var storage = createTileGauge({
        mode: "value",
        title: "Storage",
        value: 50,
        max: 100,
        unit: "GiB"
    }, "my-container");

    // Countdown ring
    var deadline = createRingGauge({
        mode: "time",
        title: "Sprint End",
        targetDate: new Date("2026-03-01"),
        max: 30 * 86400000  // 30 days in ms
    }, "timer-container");
</script>

API

Constructor

const gauge = new Gauge(options: GaugeOptions);

Creates the gauge DOM but does not attach to the page.

GaugeOptions

Methods

Convenience Functions

createGauge(options, container?)        // Create, show, and return
createTileGauge(options, container?)    // Shorthand for tile shape
createRingGauge(options, container?)    // Shorthand for ring shape
createBarGauge(options, container?)     // Shorthand for bar shape

Global Exports

window.Gauge
window.createGauge
window.createTileGauge
window.createRingGauge
window.createBarGauge

Shapes

Tile

Square card with large value text on a coloured background. Best for dashboard KPI tiles.

Ring

Circular SVG arc that fills based on percentage. Value displayed in the centre. Best for utilisation metrics.

Bar

Horizontal or vertical bar with percentage fill. Best for inline progress/quota indicators.

Threshold Configuration

Thresholds define colour boundaries based on percentage:

createTileGauge({
    mode: "value",
    value: 75,
    max: 100,
    thresholds: [
        { value: 70, color: "#2b8a3e", label: "Good" },
        { value: 30, color: "#e67700", label: "Warning" },
        { value: 10, color: "#d9480f", label: "Danger" },
        { value: 0,  color: "#c92a2a", label: "Critical" }
    ]
}, "container");

For "remaining" scenarios where lower is worse, use invertThresholds: true.

Size Variants

Omit size for fluid mode — the gauge fills its parent container with aspect-ratio: 1 (tile/ring) and scales typography via CSS container queries.

Keyboard Accessibility

Gauge elements use role="meter" (value mode) or role="timer" (time mode) with aria-valuenow, aria-valuemin, aria-valuemax, and aria-label attributes.

See specs/gauge.prd.md for the complete specification.

---

GradientPicker

A gradient colour picker that enables users to create, edit, and preview linear and radial gradients with full alpha support. Features draggable stop handles, live CSS preview, preset swatches, and configurable min/max stops. Composes the existing ColorPicker and AnglePicker components for stop colour and angle editing. Operates in popup or inline mode.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $primary, etc.) and form controls
• Bootstrap Icons — bi-arrow-left-right, bi-x-lg, bi-chevron-down
• Does not require Bootstrap JS.
• ColorPicker (optional) — for per-stop colour + alpha editing. Falls back to native <input type="color"> + alpha slider.
• AnglePicker (optional) — for linear gradient angle control. Falls back to <input type="number">.

Quick Start

<link rel="stylesheet" href="components/gradientpicker/gradientpicker.css">
<script src="components/gradientpicker/gradientpicker.js"></script>
<script>
    var gradient = createGradientPicker("my-container", {
        value: {
            type: "linear",
            angle: 90,
            stops: [
                { position: 0, color: "#3B82F6", alpha: 1 },
                { position: 1, color: "#8B5CF6", alpha: 1 }
            ]
        },
        onChange: function(value) {
            console.log("Gradient:", value);
        }
    });
</script>

Options (GradientPickerOptions)

API

Factory Function

createGradientPicker(containerId, options?)  // Create, show, and return

Global Exports

window.GradientPicker
window.createGradientPicker

GradientStop

Each stop defines a colour at a position along the gradient axis.

interface GradientStop
{
    /** Position along the gradient axis. 0.0 = start, 1.0 = end. */
    position: number;

    /** Colour in hex (#RRGGBB) or rgba string. */
    color: string;

    /** Opacity for this stop. 0.0 = transparent, 1.0 = opaque. Default: 1.0. */
    alpha: number;
}

GradientValue

The complete gradient state, including type, stops, angle, and radial parameters.

interface GradientValue
{
    /** Gradient interpolation type. */
    type: "linear" | "radial";

    /** Ordered colour stops (minimum 2). */
    stops: GradientStop[];

    /** Angle in degrees for linear gradients (0 = right, 90 = down). */
    angle: number;

    /** Centre point for radial gradients (0-1 normalised). */
    center: { x: number; y: number };

    /** Radius for radial gradients (0-1 normalised). */
    radius: number;
}

GradientPreset

A named preset with a full gradient definition.

interface GradientPreset
{
    /** Display name for tooltip. */
    name: string;

    /** Gradient definition for this preset. */
    value: GradientValue;
}

Size Variants

Panel width applies to both inline and popup modes. In popup mode, the trigger inherits the size variant height; the popup panel always uses the width above regardless of trigger size.

Composition Dependencies

GradientPicker composes two sibling components at runtime via window factory lookup. Both are optional -- the picker degrades gracefully without them.

ColorPicker Composition

• Created once per GradientPicker instance, reused for all stops
• Options: { inline: true, showOpacity: true, showFormatTabs: false, size: "sm" }
• Shown/hidden when a stop is selected/deselected
• onInput updates the selected stop's colour and alpha in real time
• onChange commits the final colour

AnglePicker Composition

• Created once, embedded in the angle controls section
• Options: { mode: "dropdown", size: "sm", showTicks: true, showInput: true }
• onChange updates the gradient angle and preview bar
• Falls back to <input type="number"> if not available

DiagramEngine Integration

GradientValue maps to DiagramEngine's GradientDefinition format. Use the conversion helpers:

// Export to DiagramEngine
var gradDef = gradient.toGradientDefinition();
diagramEngine.setShapeFill(shapeId, gradDef);

// Import from DiagramEngine
var def = diagramEngine.getShapeFill(shapeId);
gradient.fromGradientDefinition(def);

Keyboard Accessibility

Stop Handle Interactions

Default Presets

When presets is not provided, these built-in presets are available:

onInput vs onChange

Both callbacks receive (value: GradientValue). During a drag, onInput fires continuously and onChange fires once on pointer release.

Examples

Inline gradient editor

var gradient = createGradientPicker("fill-editor", {
    mode: "inline",
    value: {
        type: "linear",
        angle: 135,
        stops: [
            { position: 0, color: "#6366F1", alpha: 1 },
            { position: 0.5, color: "#EC4899", alpha: 0.8 },
            { position: 1, color: "#F59E0B", alpha: 1 }
        ]
    },
    onChange: function(value) {
        document.getElementById("preview").style.background = toCssGradient(value);
    }
});

Popup with custom presets

var gradient = createGradientPicker("toolbar-fill", {
    size: "sm",
    presets: [
        {
            name: "Brand",
            value: {
                type: "linear", angle: 90,
                stops: [
                    { position: 0, color: "#1E40AF", alpha: 1 },
                    { position: 1, color: "#7C3AED", alpha: 1 }
                ],
                center: { x: 0.5, y: 0.5 }, radius: 0.5
            }
        }
    ],
    onChange: function(value) {
        console.log("Gradient:", value);
    }
});

DiagramEngine integration

var gradient = createGradientPicker("shape-fill", {
    mode: "popup",
    size: "mini",
    onOpen: function() {
        // Load current shape gradient when picker opens
        var def = diagramEngine.getSelectedShapeFill();
        if (def) { gradient.fromGradientDefinition(def); }
    },
    onChange: function(value) {
        diagramEngine.setSelectedShapeFill(gradient.toGradientDefinition());
    }
});

CDN Usage

<!-- Bootstrap CSS and Icons -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css">
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap-icons@1.11.3/font/bootstrap-icons.css">

<!-- Optional: ColorPicker (for full colour editing) -->
<link rel="stylesheet" href="components/colorpicker/colorpicker.css">
<script src="components/colorpicker/colorpicker.js"></script>

<!-- Optional: AnglePicker (for angle dial) -->
<link rel="stylesheet" href="components/anglepicker/anglepicker.css">
<script src="components/anglepicker/anglepicker.js"></script>

<!-- GradientPicker -->
<link rel="stylesheet" href="components/gradientpicker/gradientpicker.css">
<script src="components/gradientpicker/gradientpicker.js"></script>

<div id="gradient-container"></div>
<script>
    var gradient = createGradientPicker("gradient-container", {
        mode: "inline",
        showTypeToggle: true,
        onChange: function(value) {
            console.log("Type:", value.type, "Stops:", value.stops.length);
        }
    });
</script>

See specs/gradientpicker.prd.md for the complete specification.

---

GraphCanvas

Interactive SVG graph visualization with multiple layout algorithms, zoom/pan, selection, edge creation, keyboard shortcuts, and export.

Usage

<link rel="stylesheet" href="components/graphcanvas/graphcanvas.css" />
<script src="components/graphcanvas/graphcanvas.js"></script>

const canvas = createGraphCanvas({
    container: document.getElementById("graph"),
    mode: "schema",
    layout: "force",
    nodes: [
        { id: "1", label: "OKR", type: "strategy.okr", color: "#C0392B" },
        { id: "2", label: "Project", type: "work.project", color: "#2196f3" }
    ],
    edges: [
        { id: "e1", sourceId: "1", targetId: "2", label: "aligns_to", type: "aligns_to" }
    ],
    onNodeClick: (node) => console.log("Clicked:", node.label),
    onSelectionChange: (nodes, edges) => console.log("Selected:", nodes.length)
});

Modes

• schema — Type definitions and relationship edges (the meta-model)
• instance — Resource instances and actual relationships

Layout Algorithms

Keyboard Shortcuts

Interactions

• Click node — Select, triggers onNodeClick
• Ctrl+click — Multi-select
• Drag node — Move and pin position
• Shift+drag canvas — Rubber-band selection
• Scroll wheel — Zoom (focal point under cursor)
• Click+drag canvas — Pan
• Right-click — Context menu
• Double-click node — Triggers onNodeDoubleClick

Public API

Data

• setData(nodes, edges) — Replace all data
• addNode(node) / removeNode(id) / updateNode(id, updates)
• addEdge(edge) / removeEdge(id) / updateEdge(id, updates)
• getNodes() / getEdges()

Selection

• selectNode(id) / selectEdge(id) / clearSelection()
• getSelectedNodes() / getSelectedEdges()

Viewport

• zoomIn() / zoomOut() / zoomToFit() / zoomToNode(id)
• getZoomLevel() / setZoomLevel(level) / centerOnNode(id)

Layout

• setLayout(layout, direction?) / relayout()

Filtering

• setNodeFilter(typeKeys) / setEdgeFilter(keys) / setDepthFilter(maxDepth)

Highlighting

• highlightPath(nodeIds) / highlightNeighbors(nodeId, depth)
• highlightBlastRadius(nodeId) / clearHighlights()

Export

• exportSVG() — SVG markup string
• exportPNG() — Promise resolving to Blob
• exportJSON() — { nodes, edges } object

Lifecycle

• setMode(mode) / getMode() / resize() / destroy()

Global

window.createGraphCanvas(options)

---

GraphLegend

Collapsible legend panel showing color/icon/shape key for graph node types and edge types. Designed for the Ontology Visualizer but works with any graph canvas that needs a visual key.

Usage

<link rel="stylesheet" href="components/graphlegend/graphlegend.css" />
<link rel="stylesheet" href="components/typebadge/typebadge.css" />
<script src="components/typebadge/typebadge.js"></script>
<script src="components/graphlegend/graphlegend.js"></script>

const legend = createGraphLegend({
    container: document.getElementById("graph-container"),
    nodeTypes: [
        {
            typeKey: "strategy.okr",
            displayName: "OKR",
            icon: "crosshair",
            color: "#C0392B",
            count: 5
        },
        {
            typeKey: "org.team",
            displayName: "Team",
            icon: "people",
            color: "#2980B9",
            count: 3
        }
    ],
    edgeTypes: [
        {
            relationshipKey: "owned_by",
            displayName: "owned by",
            color: "#94a3b8",
            style: "solid",
            count: 8
        }
    ],
    showCounts: true,
    position: "bottom-left"
});

Options

LegendNodeType

LegendEdgeType

Public API

Callbacks

Dependencies

• TypeBadge — used internally for node type rendering. Falls back to a simple color-dot badge when TypeBadge is not loaded.

Status Indicators

• planned — Dashed border around the item row.
• deprecated — Reduced opacity (50%).
• external — Small external-link icon appended.

Accessibility

• Root element has role="complementary" with aria-label="Graph legend".
• Toggle button has aria-expanded and aria-label reflecting state.
• Items are focusable (tabindex="0") when onTypeClick is set, with keyboard activation via Enter or Space.

Global

window.createGraphLegend(options)

---

GraphMinimap

A small, always-visible overview widget that shows a miniaturised view of the entire graph canvas. Displays a viewport rectangle indicating the currently visible region. Users can click or drag the viewport rectangle to pan the main canvas.

Assets

Requirements

• Bootstrap CSS — for SCSS variables
• A GraphCanvasHandle-compatible graph canvas instance
• Does not require Bootstrap JS

Quick Start

<link rel="stylesheet" href="components/graphminimap/graphminimap.css">
<script src="components/graphminimap/graphminimap.js"></script>
<script>
    var minimap = createGraphMinimap({
        container: document.getElementById("minimap-host"),
        graphCanvas: myGraphCanvasInstance
    });

    // Manually refresh after data changes
    minimap.refresh();

    // Toggle visibility
    minimap.toggle();

    // Clean up
    minimap.destroy();
</script>

API

Factory Function

GraphMinimapOptions

GraphCanvasHandle Interface

The graph canvas passed to the minimap must implement this interface:

interface GraphCanvasHandle {
    getNodes(): { id: string; x: number; y: number; color?: string }[];
    getEdges(): { source: string; target: string }[];
    getViewport(): { x: number; y: number; zoom: number; width: number; height: number };
    panTo(x: number, y: number): void;
    on(event: string, callback: Function): void;
    off(event: string, callback: Function): void;
}

GraphMinimap Handle

Behaviour

1. Nodes are rendered as small filled circles (3px radius). Nodes with a color property use that colour; otherwise the configured nodeColor is used.
2. Edges are rendered as 1px lines connecting source and target nodes.
3. Viewport rectangle shows the currently visible region with a semi-transparent fill and solid border.
4. Click anywhere on the minimap to pan the main canvas to that position.
5. Drag the viewport rectangle (or anywhere) to pan the main canvas in real-time.
6. Auto-refresh occurs when the graph canvas fires a layoutComplete event.
7. Collapse/expand via the toggle button in the header.
8. Performance: For graphs with more than 500 nodes, edge rendering is automatically skipped.

Accessibility

• role="img" with aria-label="Graph minimap showing overview of the graph" on the wrapper.
• Toggle button has aria-label="Toggle minimap" and aria-expanded state.
• No keyboard interaction required — the minimap is a visual navigation aid.

Dark Mode

The component uses var(--theme-*) CSS tokens for backgrounds, borders, and text. SVG fill colours are passed by the consumer and do not change automatically on theme toggle.

---

GraphToolbar

Factory function that creates a preconfigured Toolbar instance for graph visualization applications. Assembles standard regions for graph editing (undo/redo/delete), layout algorithm selection, zoom controls, grid snap/minimap toggles, export, and node search.

GraphToolbar is not a new component class — it wraps the existing Toolbar component (ADR-030).

Usage

<link rel="stylesheet" href="components/toolbar/toolbar.css">
<link rel="stylesheet" href="components/graphtoolbar/graphtoolbar.css">
<script src="components/toolbar/toolbar.js"></script>
<script src="components/graphtoolbar/graphtoolbar.js"></script>

const handle = createGraphToolbar({
    onUndo: () => graph.undo(),
    onRedo: () => graph.redo(),
    onDelete: () => graph.deleteSelected(),
    onApplyLayout: (id) => graph.applyLayout(id),
    onZoomIn: () => { graph.zoomIn(); handle.setZoomLabel(graph.getZoom()); },
    onZoomOut: () => { graph.zoomOut(); handle.setZoomLabel(graph.getZoom()); },
    onZoomToFit: () => { graph.fitToView(); handle.setZoomLabel(graph.getZoom()); },
    onGridSnapToggle: (on) => graph.setGridSnap(on),
    onMinimapToggle: (on) => graph.setMinimapVisible(on),
    onExport: (format) => graph.export(format),
    onSearch: (query) => graph.highlightMatches(query),
    onSearchSubmit: (query) => graph.selectFirstMatch(query)
});

Options

Handle API

Keyboard Shortcuts

Shortcuts are suppressed when focus is in an input field or a modal is open.

---

GridLayout

A uniform CSS Grid layout container where all cells are the same size, arranged via grid-template-columns: repeat(N, 1fr). Supports a fixed column count or responsive auto-fit columns calculated from container width and a minimum cell width. Optional aspect ratio enforcement keeps cells proportional.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/gridlayout/gridlayout.css">
<script src="components/gridlayout/gridlayout.js"></script>

<script>
    var cards = [];
    for (var i = 0; i < 6; i++) {
        var card = document.createElement("div");
        card.className = "p-3 border bg-white";
        card.textContent = "Card " + (i + 1);
        cards.push(card);
    }

    var grid = createGridLayout({
        columns: 3,
        gap: 12,
        padding: "16px",
        children: cards
    });
</script>

How It Works

GridLayout creates a CSS Grid container with equal-width columns. When columns is a number, the grid uses a fixed column count. When columns is "auto", a ResizeObserver monitors the container width and recalculates the column count as Math.floor(containerWidth / minCellWidth), clamped to the child count.

columns: 3, gap: 12
+----------+----------+----------+
|  Cell 1  |  Cell 2  |  Cell 3  |
+----------+----------+----------+
|  Cell 4  |  Cell 5  |  Cell 6  |
+----------+----------+----------+

columns: "auto", minCellWidth: 200 (container: 650px -> 3 cols)
+----------+----------+----------+
|  Cell 1  |  Cell 2  |  Cell 3  |
+----------+----------+----------+
|  Cell 4  |  Cell 5  |  Cell 6  |
+----------+----------+----------+

columns: "auto", minCellWidth: 200 (container: 350px -> 1 col)
+------------------------------+
|           Cell 1             |
+------------------------------+
|           Cell 2             |
+------------------------------+
|           Cell 3             |
+------------------------------+

Options

Public API

GridLayoutState

interface GridLayoutState {
    columns: number;
    rows: number;
    childCount: number;
}

Composability

GridLayout implements the standard layout container contract. Any component with show(container) / hide() / destroy() can be used as a child. Plain HTMLElements are also supported. Duck-typed child mounting checks for setContained, show, getRootElement, and falls back to direct appendChild.

// Place gauges in a 2x2 grid
var grid = new GridLayout({
    columns: 2,
    gap: 16,
    aspectRatio: 1,
    children: [gaugeA, gaugeB, gaugeC, gaugeD]
});
grid.show(document.getElementById("dashboard"));

Global Exports

When loaded via <script> tag:

• window.GridLayout -- GridLayout class
• window.createGridLayout -- Factory function (creates and shows)

CSS Classes

---

GuidedTour

Product walkthrough component wrapping Driver.js.

Overview

GuidedTour creates in-app product tours using Driver.js (MIT, ~5KB, zero deps) with enterprise-themed popovers. It supports step progression, conditional visibility, localStorage persistence, and analytics hooks.

Usage

<!-- Driver.js CDN (required) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/driver.js@1.4.1/dist/driver.css" />
<script src="https://cdn.jsdelivr.net/npm/driver.js@1.4.1/dist/driver.js.iife.js"></script>

<!-- GuidedTour -->
<link rel="stylesheet" href="components/guidedtour/guidedtour.css" />
<script src="components/guidedtour/guidedtour.js"></script>

var tour = createGuidedTour({
    tourId: "onboarding",
    steps: [
        {
            target: "#sidebar",
            title: "Navigation",
            description: "Use the sidebar to browse between sections."
        },
        {
            target: "#search-box",
            title: "Search",
            description: "Search across all your projects and documents.",
            side: "bottom"
        },
        {
            target: "#user-menu",
            title: "Your Account",
            description: "Access settings, notifications, and sign out.",
            side: "left"
        }
    ],
    onTourStart: function() { console.log("Tour started"); },
    onStepView: function(i) { console.log("Viewing step", i); },
    onTourComplete: function() { console.log("Tour completed"); },
    onTourDismiss: function(i) { console.log("Tour dismissed at step", i); }
});

// Start the tour
if (tour && !tour.isCompleted()) {
    tour.start();
}

Factory

Options

TourStep

API

Keyboard

Persistence

Tour completion is stored in localStorage under the key guidedtour-{tourId}-complete. Call resetProgress() to clear.

Dependencies

• Driver.js ~1.4 — loaded via CDN; factory returns null if missing
• Bootstrap 5 — button classes used for nav buttons

Asset Paths

CSS: components/guidedtour/guidedtour.css
JS:  components/guidedtour/guidedtour.js

---

HelpDrawer

Right-side sliding panel for in-context documentation display.

Overview

HelpDrawer is a singleton component — one per page. It slides in from the right edge, renders markdown documentation via Vditor display mode, and supports topic history with a back button.

Usage

<!-- Vditor CDN (required for markdown rendering) -->
<link rel="stylesheet" href="https://unpkg.com/vditor@3.11.2/dist/index.css" />
<script src="https://unpkg.com/vditor@3.11.2/dist/index.min.js"></script>

<!-- HelpDrawer -->
<link rel="stylesheet" href="components/helpdrawer/helpdrawer.css" />
<script src="components/helpdrawer/helpdrawer.js"></script>

// Create (or get existing) singleton
var drawer = createHelpDrawer({ width: 420 });

// Open with inline markdown
drawer.open({
    id: "getting-started",
    title: "Getting Started",
    markdown: "# Welcome\n\nThis is the getting started guide."
});

// Open with URL
drawer.open({
    id: "api-reference",
    title: "API Reference",
    url: "/docs/api-reference.md"
});

// Navigate back
drawer.back();

// Close
drawer.close();

Factory

Options

API

HelpTopic

Keyboard

Dependencies

• Vditor ≥3.11.2 — loaded via CDN; falls back to plain text if unavailable
• Bootstrap Icons — header icons

CSS Classes

Asset Paths

CSS: components/helpdrawer/helpdrawer.css
JS:  components/helpdrawer/helpdrawer.js

---

HelpTooltip

A small ? icon that attaches to any element for in-context help.

Overview

HelpTooltip renders a 14px blue circle ? icon positioned relative to a target element. Hovering shows a plain-text tooltip (400ms delay); clicking opens the HelpDrawer with linked documentation.

Usage

<link rel="stylesheet" href="components/helptooltip/helptooltip.css" />
<script src="components/helptooltip/helptooltip.js"></script>
<!-- HelpDrawer must also be loaded for click behaviour -->
<script src="components/helpdrawer/helpdrawer.js"></script>

var tooltip = createHelpTooltip(document.getElementById("my-field"), {
    text: "Enter your project name here",
    topic: {
        id: "project-name",
        title: "Project Name",
        markdown: "# Project Name\n\nThe project name must be unique."
    },
    position: "top-right"
});

Factory

Options

Positions

• top-right — upper right corner of target
• top-left — upper left corner of target
• bottom-right — lower right corner of target
• bottom-left — lower left corner of target
• inline-end — inline after target content

API

Keyboard

Dependencies

• HelpDrawer — lazy-loaded via window.createHelpDrawer
• Bootstrap Icons — optional (icon is a text ?)

Asset Paths

CSS: components/helptooltip/helptooltip.css
JS:  components/helptooltip/helptooltip.js

---

InlineToolbar

A compact inline toolbar that renders INSIDE a container element as a flex row. Designed for sidebars, panel headers, and other embedded contexts where a full docked toolbar is inappropriate.

Assets

Requirements

• Bootstrap Icons — for icon rendering (bi bi-* classes)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/inlinetoolbar/inlinetoolbar.css">
<script src="components/inlinetoolbar/inlinetoolbar.js"></script>
<script>
    var toolbar = createInlineToolbar({
        container: document.getElementById("sidebar-header"),
        items: [
            { id: "filter", icon: "funnel", tooltip: "Filter", type: "toggle" },
            { id: "sep1", icon: "", tooltip: "", type: "separator" },
            { id: "expand", icon: "arrows-expand", tooltip: "Expand All" },
            { id: "collapse", icon: "arrows-collapse", tooltip: "Collapse All" },
            { id: "refresh", icon: "arrow-clockwise", tooltip: "Refresh",
              onClick: function(item) { console.log("Refresh clicked"); } }
        ],
        size: "sm",
        compact: true
    });
</script>

API

Global Functions

InlineToolbarOptions

InlineToolbarItem

InlineToolbar Handle

Features

• Renders inline (no fixed/absolute positioning)
• Icon buttons with hover highlight
• Toggle buttons with active state (accent background)
• Separators (1px vertical dividers)
• Three sizes: xs (24px), sm (28px), md (32px)
• Compact mode with reduced gaps
• Theme-aware via CSS custom properties (light/dark mode)

Accessibility

• Toolbar: role="toolbar", aria-label="Inline toolbar"
• Buttons: aria-label set from tooltip text
• Icons: aria-hidden="true"
• Focus: visible focus ring via outline on :focus-visible
• Disabled: disabled attribute + pointer-events: none

See specs/explorer-inline-toolbar.req.md for the original requirement.

---

LatexEditor

A LaTeX equation editor component with two editing modes: Visual (WYSIWYG via MathLive) and Source (raw LaTeX textarea). Includes a live KaTeX-rendered preview, tabbed symbol palette with 12 categories (including chemistry via mhchem), and styling controls for colour, bold, size, and highlight.

Designed for embedding in DiagramEngine shapes, FormDialog popups, Sidebar tabs, and standalone page layouts.

Files

CDN Dependencies

<!-- KaTeX (required for preview) -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.css">
<script src="https://cdn.jsdelivr.net/npm/katex@0.16.21/dist/katex.min.js"></script>

<!-- MathLive (optional, for visual editing mode) -->
<script src="https://cdn.jsdelivr.net/npm/mathlive@0.107.3/dist/mathlive.min.js"></script>

<!-- LatexEditor -->
<link rel="stylesheet" href="components/latexeditor/latexeditor.css">
<script src="components/latexeditor/latexeditor.js"></script>

Quick Start

var editor = createLatexEditor({
    container: "#my-editor",
    expression: "x = \\frac{-b \\pm \\sqrt{b^2 - 4ac}}{2a}",
    onChange: function(latex) { console.log("Updated:", latex); },
});

Factory

createLatexEditor(options): LatexEditor

Creates and mounts a LatexEditor instance.

Options

Public API

Keyboard Shortcuts

Symbol Palette Categories

Styling Controls

DiagramEngine Embedding

// Register as embeddable component
engine.registerEmbeddableComponent("latexeditor", {
    factory: "createLatexEditor",
    label: "Equation",
    icon: "bi-calculator",
    category: "data",
    defaultWidth: 300,
    defaultHeight: 80,
});

In view mode, equations render as lightweight KaTeX HTML (no MathLive loaded). Double-click enters interactive edit mode with the full editor.

---

LayerLayout

A z-stack layout container where all children are simultaneously visible, layered in z-order. The container uses position: relative and each layer uses position: absolute, enabling overlapping content such as floating action buttons, overlays, watermarks, and heads-up displays.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables ($gray-*, $font-size-*, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/layerlayout/layerlayout.css">
<script src="components/layerlayout/layerlayout.js"></script>

<script>
    // Background canvas with a floating action button in the bottom-right
    var stack = createLayerLayout({
        sizing: "fixed",
        width: "100%",
        height: "400px",
        layers: [
            { child: document.getElementById("canvas"), fill: true },
            { child: document.getElementById("fab"), align: "bottom-right", zIndex: 10 }
        ]
    });
</script>

How It Works

LayerLayout creates a position: relative container. Each layer is wrapped in a position: absolute div and positioned according to its configuration -- fill the entire container, anchor to specific edges, or snap to one of nine alignment points.

Container (position: relative)
+-------------------------------------------------------+
|  Layer 0: fill (background image)                     |
|  +---------------------------------------------------+|
|  |                                                   ||
|  |         Layer 1: align "center"                   ||
|  |              (watermark)                          ||
|  |                                                   ||
|  +---------------------------------------------------+|
|                                                       |
|                              Layer 2: align           |
|                              "bottom-right"           |
|                                   [FAB]               |
+-------------------------------------------------------+

All layers are rendered simultaneously. Higher z-index values appear on top of lower ones. Layers added later appear above earlier layers by default.

Options

LayerLayoutOptions

LayerConfig

Alignment Shortcuts

The align property maps to CSS absolute positioning:

Public API

State

interface LayerLayoutState {
    layerCount: number;
    sizing: string;
}

Composability

LayerLayout implements the standard layout container contract. Any component with show(container) / hide() / destroy() can be used as a layer child. Plain HTMLElements are also supported.

// Overlay a loading spinner on top of a content area
var overlay = new LayerLayout({
    sizing: "fixed",
    width: "100%",
    height: "100%",
    layers: [
        { child: contentPanel, fill: true },
        { child: spinner, align: "center", zIndex: 100 }
    ]
});

overlay.show(document.getElementById("main"));

Global Exports

When loaded via <script> tag:

• window.LayerLayout -- LayerLayout class
• window.createLayerLayout -- Factory function (creates and shows)

CSS Classes

---

LineEndingPicker

A dropdown picker that displays line ending (arrowhead / marker) styles with inline SVG previews, letting users select marker shapes for the start or end of lines in graph and drawing tools. Marker values are aligned with maxGraph native arrow types for direct interop with GraphCanvasMx.

Usage

<link rel="stylesheet" href="components/lineendingpicker/lineendingpicker.css">
<script src="components/lineendingpicker/lineendingpicker.js"></script>

<div id="my-ending-picker"></div>

<script>
var picker = createLineEndingPicker("my-ending-picker", {
    value: "classic",
    mode: "end",
    onChange: function(ending) {
        console.log("Selected:", ending.label, ending.value);
    }
});
</script>

Options

Default Endings (maxGraph-aligned)

ER Notation Endings

When showERNotation: true is set (and no custom endings array is provided), the following Entity-Relationship endings are appended after the standard endings, with a visual group separator.

// Enable ER notation endings alongside standard endings
var picker = createLineEndingPicker("er-picker", {
    value: "classic",
    showERNotation: true,
    onChange: function(ending) {
        console.log("Selected:", ending.value);
    }
});

API

Mode

The mode option controls which end of the preview line displays the marker:

• "end" (default) -- marker appears on the right end of the line (marker-end)
• "start" -- marker appears on the left end of the line (marker-start)

You can change the mode at runtime with setMode(), which re-renders the trigger preview.

// Create a start-of-line ending picker
var startPicker = createLineEndingPicker("start-picker", {
    value: "classic",
    mode: "start"
});

// Switch mode at runtime
startPicker.setMode("end");

Keyboard

---

LineShapePicker

A dropdown picker that displays line shape/routing patterns with inline SVG previews, letting users select connector shapes for graph and drawing tools. Default shapes align with maxGraph edge routing styles.

Usage

<link rel="stylesheet" href="components/lineshapepicker/lineshapepicker.css">
<script src="components/lineshapepicker/lineshapepicker.js"></script>

<div id="my-shape-picker"></div>

<script>
var picker = createLineShapePicker("my-shape-picker", {
    value: "orthogonal",
    onChange: function(shape) {
        console.log("Selected:", shape.label, shape.value);
    }
});
</script>

Options

Default Shapes

API

Keyboard

---

LineTypePicker

A dropdown picker that displays line dash patterns with inline SVG previews, letting users select stroke styles for graph and drawing tools.

Usage

<link rel="stylesheet" href="components/linetypepicker/linetypepicker.css">
<script src="components/linetypepicker/linetypepicker.js"></script>

<div id="my-type-picker"></div>

<script>
var picker = createLineTypePicker("my-type-picker", {
    value: "dashed",
    onChange: function(type) {
        console.log("Selected:", type.label, type.value, type.dashArray);
    }
});
</script>

Options

Default Types

LineTypeItem

API

Keyboard

---

LineWidthPicker

A dropdown picker that displays line widths with visual CSS border previews, letting users select stroke thickness for graph and drawing tools.

Usage

<link rel="stylesheet" href="components/linewidthpicker/linewidthpicker.css">
<script src="components/linewidthpicker/linewidthpicker.js"></script>

<div id="my-width-picker"></div>

<script>
var picker = createLineWidthPicker("my-width-picker", {
    value: 2,
    onChange: function(width) {
        console.log("Selected:", width.label, width.value);
    }
});
</script>

Options

Default Widths

0.5, 1, 1.5, 2, 2.5, 3, 4, 5, 6, 8, 10, 15, 20px

API

Keyboard

---

LogConsole

A reusable in-app logging console for displaying high-level user actions and system events. Renders a scrollable, level-filterable log feed with dark/light theming, per-level colour customisation, Clear/Export actions, rAF-batched DOM updates, and FIFO eviction.

Features

• 5 log levels — DEBUG, INFO, WARN, ERROR, SUCCESS with configurable colours
• Level filtering — Toggleable header chips; CSS show/hide (entries stay in memory)
• Dark / light themes — Full colour token override support
• Clear & Export — Clear all entries or download as .txt
• rAF batching — Multiple entries per frame batched into a single DOM update
• FIFO eviction — Oldest entries removed from memory and DOM when cap exceeded
• Contained mode — Relative positioning for embedding within parent containers
• Full customisation — Font family, font size, all theme colours, level colours, height

Assets

Requires: Bootstrap Icons CSS (optional, for action button icons). Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/logconsole/logconsole.css">
<script src="components/logconsole/logconsole.js"></script>
<script>
    var log = createLogConsole({ theme: "dark", maxEntries: 500 });
    document.getElementById("my-container").appendChild(log.getElement());

    log.info("Application started");
    log.warn("Retry attempt 2/3");
    log.error("Request failed (status 500)");
    log.success("Session saved");
</script>

API

Constructor

const log = new LogConsole(options?: LogConsoleOptions);

Creates the log console DOM element. Attach with getElement().

LogConsoleOptions

Default Level Colours

Shorthand Methods

log.debug("Initialising...");
log.info("Session loaded");
log.warn("Retry attempt 2/3");
log.error("Request failed");
log.success("Diagram saved");

Each generates a timestamp automatically and calls log().

Structured Logging

log.log({
    timestamp: "10:53:04.123",
    level: "INFO",
    message: "Custom timestamp entry"
});

Methods

Convenience Functions

createLogConsole(options?)  // Create and return

Global Exports

window.LogConsole
window.createLogConsole

Theme Tokens

All tokens can be overridden individually via options.

Integration with TabbedPanel

var logConsole = createLogConsole({ theme: "dark" });
var panel = createDockedTabbedPanel({
    tabs: [
        { id: "log", title: "Log Console", icon: "bi-terminal",
          content: logConsole.getElement() }
    ]
});

logConsole.info("Application started");

Export Format

[10:53:04.123] [INFO   ] Saving session data to backend...
[10:53:04.198] [INFO   ] Session data saved successfully
[10:53:06.829] [WARN   ] Retry attempt 2/3
[10:53:14.200] [ERROR  ] Request failed (status 500)

Filename: {prefix}-YYYY-MM-DDTHH-MM-SS.txt

Accessibility

• All text is natively selectable (no user-select: none on entries)
• Filter chips and action buttons are keyboard-focusable
• role="log" with aria-live="polite" for screen reader announcements

See specs/2026-02-17-shared-log-console-requirements.md for the full specification.

---

LogUtility

A non-visual, centralised logging utility that replaces per-component logInfo/logWarn/logError/logDebug helper functions with a singleton providing named loggers, level filtering, timestamp control, and optional LogConsole routing.

Assets

Requirements

• No external dependencies.
• Does not require Bootstrap CSS or JS.
• Optional integration with the LogConsole component for user-visible event routing.

Quick Start

<script src="components/logutility/logutility.js"></script>
<script>
    // Create the singleton (or retrieve it if already created).
    var logUtil = createLogUtility({ level: "info" });

    // Create a named logger for a component.
    var log = logUtil.getLogger("MyComponent");

    log.info("initialised");
    log.warn("deprecation notice");
    log.error("failed to load", new Error("timeout"));
    log.debug("internal state", { count: 42 });
</script>

API

Factory Function

LogUtilityOptions

LogUtility Methods

Logger Methods

Output Format

Each log message is formatted as:

[ISO-TIMESTAMP] [LEVEL] [ComponentName] message args...

Examples:

2026-03-29T14:30:00.000Z [INFO] [MyComponent] initialised
2026-03-29T14:30:00.001Z [WARN] [MyComponent] deprecation notice
2026-03-29T14:30:00.002Z [ERROR] [MyComponent] failed to load Error: timeout
2026-03-29T14:30:00.003Z [DEBUG] [MyComponent] internal state { count: 42 }

Timestamps can be disabled by passing timestamps: false.

Level Filtering

Log levels have a numeric hierarchy: trace (-1) < debug (0) < info (1) < warn (2) < error (3).

Setting the level to "warn" suppresses trace, debug, and info messages. Warnings and errors are never filtered.

var logUtil = createLogUtility({ level: "warn" });
var log = logUtil.getLogger("Filtered");

log.trace("suppressed");  // Not output (most verbose)
log.debug("suppressed");  // Not output
log.info("suppressed");   // Not output
log.warn("visible");      // Always output
log.error("always");      // Always output

Trace Level

Trace is the most verbose level — intended for very low-level output such as DOM mutations, render cycles, and event propagation. It uses console.debug for output.

var logUtil = createLogUtility({ level: "trace" });
var log = logUtil.getLogger("Renderer");

log.trace("DOM mutation", { target: el, type: "childList" });
log.trace("render cycle", { frameId: 42, objects: 15 });

LogConsole Integration

When a LogConsoleHandle is attached, calls to logger.event() are routed to the LogConsole in addition to the browser console. This is useful for displaying user-visible events in an in-app log panel.

var logUtil = createLogUtility();

// Attach a LogConsole later.
logUtil.setLogConsole(myLogConsoleInstance);

var log = logUtil.getLogger("Auth");
log.event("User logged in", { userId: 42 });
// Console: [INFO] [Auth] User logged in { userId: 42 }
// LogConsole: "[Auth] User logged in"

Console Output Toggle

Console output can be disabled entirely for production or testing scenarios.

logUtil.setConsoleOutput(false);  // Silence all console output
logUtil.setConsoleOutput(true);   // Re-enable console output

Singleton Behaviour

createLogUtility() returns the same instance on every call. The options argument is only used on the first call. To create a fresh instance with different options, call resetLogUtility() first.

var lu1 = createLogUtility({ level: "info" });
var lu2 = createLogUtility({ level: "error" });  // Same instance as lu1

resetLogUtility();

var lu3 = createLogUtility({ level: "error" });  // Fresh instance

Runtime Debug Flags

Global variables on window allow customer support or developers to enable verbose logging at runtime without reloading the page:

WARN and ERROR are always enabled — they cannot be suppressed. Only INFO, DEBUG, and TRACE are controlled by these flags.

Flags are checked on every log call, so toggling them at runtime takes effect immediately:

// In the browser console:
window.__ebt_debug_logging = true;   // verbose debug output starts
window.__ebt_debug_logging = false;  // back to normal

The flags work as an override — if the LogUtility is configured with level: "error" but __ebt_debug_logging is true, debug messages will still be emitted.

Studio Apps

All 4 studio apps (Ribbon, Layout, Shape, Component) automatically enable all log levels by setting:

window.__ebt_debug_logging = true;
window.__ebt_info_logging = true;
window.__ebt_trace_logging = true;

Window Globals

---

Magnifier

A cursor-following magnifying glass overlay that clones and scales the content of a target element within a circular lens. The lens tracks the mouse cursor and shows a magnified view of the area directly under the pointer.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables ($gray-*, $shadow-md)
• Does not require Bootstrap JS or Bootstrap Icons.
• No external dependencies.

Quick Start

<link rel="stylesheet" href="components/magnifier/magnifier.css">
<script src="components/magnifier/magnifier.js"></script>

<div id="magnify-target" style="width: 600px; height: 400px; overflow: auto;">
    <p>Hover over this content to see it magnified in the lens.</p>
    <img src="sample-image.png" alt="Sample" style="width: 100%;">
</div>

<script>
    var magnifier = createMagnifier("my-container", {
        target: "magnify-target",
        zoom: 2.5,
        diameter: 180,
        showCrosshair: true,
        onMove: function(x, y) {
            console.log("Cursor at:", x, y);
        }
    });
</script>

Options (MagnifierOptions)

API

Factory Function

var magnifier = createMagnifier("container-id", { zoom: 3, diameter: 200 });

The containerId parameter serves as the logical owner identifier. The lens element itself is appended to document.body because it uses position: fixed to follow the cursor across the viewport.

How It Works

1. On mouseenter over the target, the component clones the target element's DOM subtree into the lens.
2. The clone is scaled by the zoom factor using CSS transform: scale().
3. On each mousemove, the lens repositions near the cursor (offset by offset.x and offset.y), and the clone is translated so that the area directly under the cursor appears centred in the lens.
4. On mouseleave, the lens hides and the clone is removed.

Global Exports

window.Magnifier;          // Class constructor
window.createMagnifier;    // Factory function

Examples

Basic Usage with Default Settings

var mag = createMagnifier("app", { target: "photo-gallery" });

High Zoom with Large Lens

var mag = createMagnifier("app", {
    target: document.getElementById("blueprint"),
    zoom: 4,
    diameter: 250,
    borderColor: "#1c7ed6",
    borderWidth: 3,
    showCrosshair: true
});

Programmatic Control

var mag = createMagnifier("app", { target: "map-view", disabled: true });

// Enable on button click
document.getElementById("toggle-btn").addEventListener("click", function() {
    mag.enable();
});

// Change zoom dynamically
document.getElementById("zoom-slider").addEventListener("input", function(e) {
    mag.setZoom(parseFloat(e.target.value));
});

// Clean up
document.getElementById("remove-btn").addEventListener("click", function() {
    mag.destroy();
});

---

MarginsPicker

A dropdown component showing page margin presets with visual page thumbnails, modelled after Microsoft Word's Margins dropdown. Each option displays a small SVG page illustration with margin boundaries drawn, plus the preset name and exact Top/Bottom/Left/Right values in inches.

Usage

<link rel="stylesheet" href="components/marginspicker/marginspicker.css">
<script src="components/marginspicker/marginspicker.js"></script>

<div id="my-margins-picker"></div>

<script>
var picker = createMarginsPicker({
    container: "my-margins-picker",
    value: "Normal",
    onChange: function(preset) {
        console.log("Selected:", preset.name,
            "Top:", preset.top, "Bottom:", preset.bottom,
            "Left:", preset.left, "Right:", preset.right);
    }
});
</script>

Configuration

Default Presets

Public API

interface MarginsPicker {
    getValue(): MarginPreset;
    setValue(presetName: string): void;
    setPresets(presets: MarginPreset[]): void;
    show(): void;
    hide(): void;
    destroy(): void;
    getElement(): HTMLElement;
}

Custom Presets

var picker = createMarginsPicker({
    container: "my-picker",
    presets: [
        { name: "A4 Standard", top: 1.5, bottom: 1.5, left: 1, right: 1 },
        { name: "Legal Tight", top: 0.75, bottom: 0.75, left: 0.5, right: 0.5 },
        { name: "Book Mirror", top: 1, bottom: 1, left: 1, right: 1,
          inside: 1.5, outside: 0.75 },
    ],
    showCustom: true,
    onCustom: function() {
        openCustomMarginsDialog();
    }
});

Keyboard Navigation

Dark Mode

All colours use var(--theme-*) CSS custom properties and automatically adapt to dark mode when data-bs-theme="dark" is set on the <html> element.

---

MarkdownEditor

A Bootstrap 5-themed Markdown editor wrapper around Vditor with tab/side-by-side layout modes, collapsible panes, inline selection toolbar, export, and optional modal hosting.

Dependencies

This component requires external libraries loaded before the component script:

<!-- Vditor (>= 3.8.13 required for security fixes; 3.11.2 recommended) -->
<link rel="stylesheet" href="https://unpkg.com/vditor@3.11.2/dist/index.css" />
<script src="https://unpkg.com/vditor@3.11.2/dist/index.min.js"></script>

<!-- DOMPurify (strongly recommended for XSS protection) -->
<script src="https://unpkg.com/dompurify@3.2.4/dist/purify.min.js"></script>

<!-- Component CSS + JS -->
<link rel="stylesheet" href="components/markdowneditor/markdowneditor.css">
<script src="components/markdowneditor/markdowneditor.js"></script>

Quick Start

<div id="my-editor"></div>
<script>
    var editor = createMarkdownEditor("my-editor", {
        title: "My Document",
        value: "# Hello World\n\nStart writing...",
        onChange: function(value) { console.log("Content changed"); }
    });
</script>

Modal Usage

<script>
    showMarkdownEditorModal({
        modalTitle: "Edit Description",
        value: existingMarkdown,
        onSave: function(value) {
            console.log("Saved:", value);
        },
        onClose: function(value) {
            // value is null if cancelled
            if (value !== null) {
                console.log("Closed with content");
            }
        }
    });
</script>

Configuration Options

Display Mode

The "display" mode renders markdown as read-only HTML with no UI chrome — no header bar, toolbar, tabs, resize handle, or border. This is ideal for embedding rendered markdown in tooltips, popovers, hover cards, or any read-only container.

createMarkdownEditor("tooltip-content", {
    mode: "display",
    value: "**Status:** Approved\n\nSee [JIRA-1234](#) for details."
});

In display mode:

• No Vditor editor instance is created (lightweight)
• Full rendering of Mermaid diagrams, PlantUML, code highlighting, and KaTeX math via Vditor.preview()
• Resizable from the bottom-right corner (CSS resize: both)
• setValue(md) re-renders the preview
• getValue() returns the stored markdown string
• setMode("tabs") or setMode("sidebyside") transitions to a full editor
• onReady fires after markdown is rendered and inserted into the DOM

CSS Isolation (isolated: true)

When multiple display-mode instances are embedded in a sidebar or panel, Vditor's CSS (margins, heading sizes, code block styles) can bleed into the parent container. Setting isolated: true applies a CSS reset boundary:

createMarkdownEditor("sidebar-idea", {
    mode: "display",
    value: ideaMarkdown,
    isolated: true
});

Compact Spacing (compact: true)

Reduces vertical spacing for dense embedded contexts: tighter paragraph margins (0.25em), smaller headings (relative to container), reduced code block padding, collapsed list item spacing.

createMarkdownEditor("category-idea", {
    mode: "display",
    value: ideaMarkdown,
    compact: true
});

Dark Theme (theme: "dark")

Renders with light text on a dark background — suitable for dark tooltips, popovers, and panels. Code blocks use native syntax highlighting, and link colors contrast against dark backgrounds.

createMarkdownEditor("hover-popover", {
    mode: "display",
    value: nodeMarkdown,
    theme: "dark"
});

onReady in Display Mode

The onReady callback fires after the markdown has been rendered to HTML and inserted into the DOM. This allows consumers to measure content height, attach event listeners, or adjust layout:

createMarkdownEditor("idea-container", {
    mode: "display",
    value: ideaMarkdown,
    onReady: function() {
        var el = document.getElementById("idea-container");
        if (el.scrollHeight > el.clientHeight) {
            showOverflowIndicator(el);
        }
    }
});

Naked Mode

The "naked" mode renders a fully editable Vditor surface with no UI chrome — no header bar, toolbar, tabs, or mode toggle. It feels like a <textarea> that understands markdown. The editor has a form-control-style border and is resizable via CSS resize: both.

createMarkdownEditor("notes-field", {
    mode: "naked",
    value: "- [ ] Review PR\n- [x] Update docs",
    placeholder: "Type markdown here...",
    height: "200px",
    onChange: function(md) { console.log("Changed:", md.length); }
});

In naked mode:

• Full Vditor editor instance (all markdown shortcuts, GFM task lists, formatting)
• No header, toolbar, tabs, mode toggle, or export buttons
• Resizable from the bottom-right corner (CSS resize: both)
• Border matches Bootstrap form-control style
• getValue() / setValue() work as in tabs/sidebyside mode
• onSave fires on Ctrl+Enter
• setMode("tabs") transitions to the full chrome editor
• Supports size, placeholder, disabled, vditorMode, and all callback options

Use naked mode for expanded detail panels, wiki-style paragraph editing, or any context where you want markdown editing power without the editor chrome. For per-row lightweight editing (todo items, checklist entries), use the RichTextInput component instead.

Modal Options

Extends all options above plus:

The modal dialog is horizontally resizable — drag the right edge to adjust width (min 480 px, max 95 vw).

Public API

Supported Markdown Features

Via Vditor, the editor supports:

• GFM: Headings, bold, italic, strikethrough, lists, task lists, tables, blockquotes, code blocks, inline code, horizontal rules, images, links
• Extended: Footnotes, superscript (^text^), subscript (~text~), mark (==text==), table of contents
• Diagrams: MermaidJS, Graphviz (DOT), PlantUML (rendered inline)
• Syntax highlighting: 170+ languages in fenced code blocks
• Math: LaTeX formulas via KaTeX

Keyboard Shortcuts

Security

Important: This component requires security-conscious deployment.

1. Vditor version: Always use >= 3.8.13 (fixes CVE-2022-0341, CVE-2022-0350, CVE-2021-4103, CVE-2021-32855). Pin the version in production.
2. DOMPurify: Always load DOMPurify alongside this component. All HTML output is sanitised through DOMPurify before DOM insertion or export.
3. Content-Security-Policy: Configure CSP headers to restrict script-src to trusted CDN domains only.
4. SRI hashes: Use Subresource Integrity attributes on CDN <script> and <link> tags in production.
5. getHTML() is safe: The public getHTML() method returns sanitised HTML. If you bypass the component and call Vditor's getHTML() directly, you must sanitise the output yourself.

Window Globals

---

MarkdownRenderer

Shared markdown-to-HTML rendering utility for the Enterprise Theme. Converts markdown to styled HTML using marked with optional extensions for code highlighting, math, and diagrams. Zero CSS injection — renders using the theme's native fonts and colours.

Dependencies

Required

Optional (auto-detected)

These libraries are probed on window at render time. If present, they are used automatically. If absent, the corresponding features are silently skipped.

PlantUML (server-based)

PlantUML diagrams are rendered by sending the source text to a PlantUML server which returns SVG. No client-side library is needed.

• Default server: https://www.plantuml.com/plantuml/svg/ (public, community-maintained, no SLA)
• Recommended for production: Self-host a PlantUML server via Docker:

  docker run -d -p 8080:8080 plantuml/plantuml-server:jetty
  

  Then configure: plantumlServer: "http://localhost:8080/svg/"

The encoding uses native CompressionStream('deflate-raw') + PlantUML's custom base64 — no encoder library needed.

Usage

Basic (markdown only)

<script src="marked.min.js"></script>
<script src="markdownrenderer.js"></script>
<script>
var renderer = createMarkdownRenderer();
renderer.render("# Hello\n\nSome **bold** text.", targetElement);
</script>

With code highlighting

<link rel="stylesheet" href="highlight.js/styles/github.min.css">
<script src="marked.min.js"></script>
<script src="highlight.min.js"></script>
<script src="markdownrenderer.js"></script>
<script>
var renderer = createMarkdownRenderer();
renderer.render("```js\nconsole.log('hi');\n```", targetElement);
</script>

With all extensions

<link rel="stylesheet" href="highlight.js/styles/github.min.css">
<link rel="stylesheet" href="katex/dist/katex.min.css">
<script src="marked.min.js"></script>
<script src="highlight.min.js"></script>
<script src="katex.min.js"></script>
<script src="mermaid.min.js"></script>
<script src="viz-standalone.js"></script>
<script src="markdownrenderer.js"></script>
<script>
var renderer = createMarkdownRenderer({
    plantumlServer: "http://localhost:8080/svg/"
});
renderer.render(markdownContent, targetElement);
</script>

Configuration options

createMarkdownRenderer({
    highlight: true,        // Use highlight.js if available (default: true)
    math: true,             // Use KaTeX if available (default: true)
    mermaid: true,          // Use Mermaid if available (default: true)
    graphviz: true,         // Use @viz-js/viz if available (default: true)
    plantuml: true,         // Enable PlantUML server rendering (default: true)
    plantumlServer: "...",  // PlantUML server URL (default: public server)
});

Disabling specific features

// Only markdown + code highlighting, no diagrams or math
createMarkdownRenderer({
    math: false,
    mermaid: false,
    graphviz: false,
    plantuml: false,
});

API

createMarkdownRenderer(opts?): MarkdownRendererHandle

Creates a renderer instance. Registered on window.createMarkdownRenderer.

MarkdownRendererHandle

Supported markdown features

Standard markdown

Headings, paragraphs, bold, italic, links, images, lists, blockquotes, horizontal rules, tables.

Code blocks

Fenced code blocks with language tags. Syntax highlighted when highlight.js is loaded.

```javascript
function greet() { console.log("hello"); }
```

Math (KaTeX)

Inline math with $E = mc^2$ and block math with:

$$
\int_0^\infty e^{-x^2} dx = \frac{\sqrt{\pi}}{2}
$$

Mermaid diagrams

```mermaid
graph TD
    A[Start] --> B{Decision}
    B -->|Yes| C[OK]
    B -->|No| D[End]
```

Graphviz / dot diagrams

Rendered entirely client-side via @viz-js/viz (WASM). No server needed.

```dot
digraph G {
    A -> B -> C;
    B -> D;
}
```

Also supports the graphviz language tag:

```graphviz
digraph G { rankdir=LR; A -> B; }
```

PlantUML diagrams

Rendered via server. Source is deflate-compressed, base64-encoded, and fetched as SVG.

```plantuml
@startuml
Alice -> Bob: Hello
Bob --> Alice: Hi back
@enduml
```

Security

• All HTML output is sanitised: <script>, <iframe>, <object>, <embed>, and <form> elements are stripped
• Event handler attributes (onclick, onload, etc.) and javascript: URLs are removed
• PlantUML server calls send only diagram source text (no cookies, no credentials)
• Consumer-provided markdown is never trusted

Architecture

The renderer is designed as a thin orchestration layer:

[marked]  ──parse──>  HTML string  ──sanitize──>  Safe HTML
                          │
              ┌───────────┼───────────┐
              │           │           │
         [highlight.js] [KaTeX]   [code blocks]
                                      │
                            ┌─────────┼─────────┐
                            │         │         │
                       [Mermaid]  [Viz.js]  [PlantUML]
                       (client)  (client)  (server)

• marked handles all parsing and standard HTML generation
• highlight.js is wired into marked's code renderer
• KaTeX is wired as a marked tokenizer/renderer extension
• Mermaid, Graphviz, and PlantUML are post-render steps that find placeholder <div> elements and replace them with rendered diagrams

Used by

• HelpDrawer — slide-out documentation panel
• DocViewer — three-column documentation layout

Both components call window.createMarkdownRenderer() internally. Load markdownrenderer.js before their scripts.

---

MaskedEntry

A specialised input field that masks sensitive non-password data — API keys, tokens, SSNs, connection strings, and similar secrets. Provides a show/hide toggle, copy-to-clipboard, and configurable masking strategy.

Assets

Requirements

• Bootstrap CSS — for input-group, form-control, btn, btn-outline-secondary
• Bootstrap Icons CSS — for bi-eye, bi-eye-slash, bi-clipboard, bi-check-lg
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/maskedentry/maskedentry.css">
<script src="components/maskedentry/maskedentry.js"></script>
<script>
    var entry = createMaskedEntry("my-container", {
        value: "sk-abc123def456ghi789",
        label: "API Key",
        readonly: true
    });
</script>

Options

API

Convenience Function

createMaskedEntry(containerId, options)  // Create, show, and return

Global Exports

window.MaskedEntry
window.createMaskedEntry

Masking Modes

Native mode (maskMode: "native") toggles the input between type="password" and type="text". This leverages the browser's built-in masking and is the default.

Custom mode (maskMode: "custom") keeps the input as type="text" at all times. When concealed, the component replaces the display value with repeated mask characters. The actual value is stored internally.

Accessibility

• Input linked to label via for/id, or has aria-label when no label
• Toggle button has aria-pressed and dynamic aria-label ("Show value" / "Hide value")
• Copy button has aria-label of "Copy to clipboard"
• Visually hidden role="status" live region announces state changes
• Disabled state uses native disabled attribute
• Standard tab navigation through input, toggle, and copy buttons

Examples

Read-only API key display

var entry = createMaskedEntry("api-key-container", {
    value: "sk-abc123def456ghi789jkl012mno345",
    label: "API Key",
    readonly: true,
    onCopy: function() { console.log("Key copied"); }
});

Custom mask character

var entry = createMaskedEntry("token-container", {
    value: "ghp_xxxxxxxxxxxxxxxxxxxx",
    maskMode: "custom",
    maskChar: "*",
    label: "GitHub Token"
});

Small size variant

var entry = createMaskedEntry("inline-container", {
    value: "bearer_token_value",
    size: "sm",
    showToggleButton: false
});

See specs/maskedentry.prd.md for the complete specification.

---

MultiselectCombo

A multi-select combo box that allows users to choose multiple items from a filterable dropdown list. Selected items appear as removable chips or a compact count badge. Each dropdown item has a checkbox that toggles selection without closing the dropdown.

Assets

Requirements

• Bootstrap CSS — for SCSS variables
• Bootstrap Icons — for bi-chevron-down, bi-search, bi-x icons
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/multiselectcombo/multiselectcombo.css">
<script src="components/multiselectcombo/multiselectcombo.js"></script>
<script>
    var combo = createMultiselectCombo({
        items: [
            { value: "a", label: "Apple" },
            { value: "b", label: "Banana" },
            { value: "c", label: "Cherry" },
            { value: "d", label: "Date" }
        ],
        placeholder: "Pick fruits...",
        onChange: function(values) { console.log("Selected:", values); }
    }, "my-container");
</script>

API

Interfaces

ComboItem

MultiselectComboOptions

Class: MultiselectCombo

Convenience Function

Features

• Chips or count badge display mode
• Checkboxes in dropdown (selection without closing)
• Select All / Deselect All with indeterminate state
• Substring filtering with debounce for large lists
• Item grouping with group headers
• Maximum selections limit with visual feedback
• "+N more" overflow badge for chip display
• Dropdown positioning (above/below based on viewport)
• Full keyboard navigation
• prefers-reduced-motion support

Keyboard

Accessibility

• Root: role="combobox", aria-haspopup="listbox", aria-expanded
• Input area: tabindex="0", aria-multiselectable="true", aria-activedescendant
• Chip container: role="list", chips: role="listitem"
• Listbox: role="listbox", aria-multiselectable="true"
• Items: role="option", aria-selected, aria-checked
• Select All: aria-checked with "mixed" indeterminate state
• Filter: role="searchbox", aria-label="Filter items"
• Live region: aria-live="polite" for selection announcements
• Chip remove: aria-label="Remove [item label]"

See specs/multiselectcombo.prd.md for the complete specification.

---

Notification Center (In-App Bell)

Aggregated notification panel with bell trigger, unread badge, category filters, read/unread state, dismiss per item, date grouping, and deep-link navigation.

Assets

Requirements

• Bootstrap CSS — SCSS variables and utility classes
• Bootstrap Icons — bell icon, notification icons (bi-* classes)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/notificationcenter/notificationcenter.css">
<script src="components/notificationcenter/notificationcenter.js"></script>
<script>
    var nc = createNotificationCenter({
        container: document.getElementById("bell-slot"),
        notifications: [
            { id: "1", title: "New comment", message: "Alice mentioned you", category: "mentions", timestamp: new Date() }
        ],
        categories: [
            { id: "mentions", label: "Mentions", icon: "bi-at" },
            { id: "alerts", label: "Alerts", icon: "bi-exclamation-triangle" }
        ],
        onNotificationClick: function(n) { console.log("Open:", n.id); }
    });

    // Push a new notification
    nc.addNotification({ id: "2", title: "Build complete", timestamp: new Date() });
</script>

API

createNotificationCenter(options): NotificationCenterHandle

NotificationCenterOptions

NotificationItem

NotificationCategory

NotificationCenterHandle

Keyboard

Accessibility

• Bell: aria-label="Notifications", aria-haspopup, aria-expanded
• Panel: role="region", aria-label="Notification Center"
• List: role="list", items role="listitem"
• Live region: aria-live="polite" announces new notifications

---

OrientationPicker

A simple dropdown picker for selecting page orientation (Portrait or Landscape). Each option displays a small SVG page icon in the corresponding orientation. Clicking an option selects it and fires the onChange callback. The trigger button shows the current selection with a chevron indicator.

Usage

<link rel="stylesheet" href="components/orientationpicker/orientationpicker.css">
<script src="components/orientationpicker/orientationpicker.js"></script>

<div id="my-orientation"></div>

<script>
var picker = createOrientationPicker({
    container: "my-orientation",
    value: "portrait",
    onChange: function(orientation) {
        console.log("Orientation:", orientation);
    }
});
</script>

Using an HTMLElement Container

<div id="toolbar-orient"></div>

<script>
var el = document.getElementById("toolbar-orient");
var picker = createOrientationPicker({
    container: el,
    value: "landscape",
    onChange: function(orientation) {
        console.log("Changed to:", orientation);
    }
});
</script>

Options

API

Keyboard

Visual

Each orientation displays a small SVG page icon:

• Portrait: 24x32 white rectangle with 1px #dee2e6 border and a small triangle fold in the top-right corner.
• Landscape: 32x24 white rectangle with the same border and fold styling.

The selected item shows a checkmark indicator.

---

PeoplePicker

Searchable person selector for share dialogs, assignment fields, and permission lists. Provides a dropdown with frequent contacts, async API lookup, and PersonChip integration. Supports single-select and multi-select modes.

Usage

HTML

<link rel="stylesheet" href="components/personchip/personchip.css">
<link rel="stylesheet" href="components/peoplepicker/peoplepicker.css">

<div id="my-picker"></div>

<script src="components/personchip/personchip.js"></script>
<script src="components/peoplepicker/peoplepicker.js"></script>

JavaScript — Multi-Select with Frequent Contacts

var picker = createPeoplePicker("my-picker", {
    frequentContacts: [
        { id: "u1", name: "Alice Chen", email: "alice@acme.com", status: "online" },
        { id: "u2", name: "Bob Smith", email: "bob@acme.com" },
        { id: "u3", name: "Carol Davis", avatarUrl: "https://i.pravatar.cc/56?u=carol" }
    ],
    onSearch: function(query) {
        return fetch("/api/people?q=" + encodeURIComponent(query))
            .then(function(r) { return r.json(); });
    },
    onChange: function(selected) {
        console.log("Selected:", selected);
    }
});

JavaScript — Single-Select (Assign To)

var assignPicker = createPeoplePicker("assign-to", {
    multiple: false,
    frequentContacts: contacts,
    onSelect: function(person) {
        console.log("Assigned to:", person.name);
    }
});

JavaScript — URL-Based Search

var urlPicker = createPeoplePicker("url-picker", {
    searchUrl: "https://api.example.com/people",
    debounceMs: 500
});

Options

PersonData

interface PersonData {
    id: string;
    name: string;
    email?: string;
    avatarUrl?: string;
    role?: string;
    status?: "online" | "offline" | "busy" | "away";
    metadata?: Record<string, string>;
}

Public API

Keyboard Navigation

Dropdown Positioning

The dropdown is appended to document.body with position: fixed to avoid containing-block traps from ancestor transform, will-change, or filter properties. This means the dropdown is not a child of the .peoplepicker root element in the DOM. The aria-owns attribute on the combobox root links the dropdown for assistive technology.

This architecture ensures the dropdown renders correctly when the PeoplePicker is placed inside FormDialog, modals, or any container with CSS transforms or overflow: hidden.

Accessibility

• role="combobox" on root with aria-haspopup="listbox"
• aria-owns links the body-mounted dropdown to the picker root
• aria-activedescendant tracks highlighted row
• aria-live="polite" announces selection changes
• Remove buttons include aria-label="Remove <name>"

PersonChip Integration

PeoplePicker uses PersonChip for rich person display in dropdown rows (md size) and selected chips (sm size). Load personchip.js before peoplepicker.js. If PersonChip is not loaded, falls back to simple span elements with initials.

---

PeriodPicker

Coarse time-period selector for enterprise project planning. Select months, quarters, halves, or years (e.g., "Q1 2026", "H2 2028") with automatic date resolution based on start/end mode.

Usage

CSS

<link rel="stylesheet" href="components/periodpicker/periodpicker.css">

JavaScript

<script src="components/periodpicker/periodpicker.js"></script>

Basic

<div id="my-period-picker"></div>

<script>
const picker = createPeriodPicker("my-period-picker", {
    mode: "start",
    onSelect: function(value) {
        console.log("Selected:", value.period, value.year, value.date);
    }
});
</script>

End Mode (Quarters Only)

<div id="quarter-picker"></div>

<script>
const picker = createPeriodPicker("quarter-picker", {
    mode: "end",
    granularities: ["quarter", "year"],
    onSelect: function(value) {
        console.log("End date:", value.date);
    }
});
</script>

Options

PeriodValue

interface PeriodValue {
    year: number;           // e.g., 2026
    period: string;         // "Jan", "Q1", "H1", "2026"
    type: PeriodGranularity; // "month" | "quarter" | "half" | "year"
    date: Date;             // Resolved date based on mode
    monthIndex?: number;    // 0-11 for months
}

Date Resolution

Public API

Keyboard

Dropdown Positioning

The dropdown is portaled to document.body with position: fixed and z-index: 2050, ensuring it renders above FormDialog overlays (z-index 2001).

---

PermissionMatrix

Interactive RBAC permission matrix with roles as columns and grouped permissions as rows. Features tri-state checkboxes, inheritance resolution, bulk operations, search/filter, change tracking, sticky headers, and JSON export.

Usage

<link rel="stylesheet" href="components/permissionmatrix/permissionmatrix.css">
<script src="components/permissionmatrix/permissionmatrix.js"></script>

const matrix = createPermissionMatrix({
    roles: [
        { id: "admin", name: "Admin", description: "Full access" },
        { id: "editor", name: "Editor", inheritsFrom: "viewer" },
        { id: "viewer", name: "Viewer" }
    ],
    groups: [
        {
            id: "content",
            name: "Content",
            permissions: [
                { id: "content.read", name: "Read" },
                { id: "content.write", name: "Write" },
                { id: "content.delete", name: "Delete" }
            ]
        }
    ],
    cells: [
        { roleId: "admin", permissionId: "content.read", state: "granted" },
        { roleId: "admin", permissionId: "content.write", state: "granted" },
        { roleId: "viewer", permissionId: "content.read", state: "granted" }
    ],
    onChange: (change) => console.log("Changed:", change)
}, "my-container");

Options

API

Permission States

Keyboard

---

PersonChip

A compact inline element displaying a person's identity: circular avatar (image or deterministic initials), name, optional status dot, and email/role detail at large size. Visual style matches the UserMenu trigger — transparent background at rest, subtle gray on hover, zero border-radius.

Designed for share dialogs, assignment fields, permission lists, and future PeoplePicker dropdown rows.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-100, $gray-300, $blue-600, etc.)
• Bootstrap Icons — not required (no icons used)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/personchip/personchip.css">
<script src="components/personchip/personchip.js"></script>
<script>
    var chip = createPersonChip({
        name: "Alice Chen",
        email: "alice@acme.com",
        status: "online"
    });
    document.getElementById("container").appendChild(chip.getElement());
</script>

API

Global Functions

PersonChip Class

PersonChipOptions

Size Variants

Status Indicators

Accessibility

• Clickable chips receive tabindex="0" and role="button".
• Href chips render as <a> (natively focusable).
• Enter and Space activate clickable chips.
• Focus-visible outline: 2px solid $blue-600.
• Avatar content is aria-hidden="true" (decorative).
• Auto-generated tooltip shows email and role.

Keyboard

Examples

Basic with initials

var chip = createPersonChip({ name: "Bob Smith" });
container.appendChild(chip.getElement());

With avatar image and status

var chip = createPersonChip({
    name: "Alice Chen",
    email: "alice@acme.com",
    avatarUrl: "https://example.com/alice.jpg",
    status: "online",
    size: "lg"
});
container.appendChild(chip.getElement());

Clickable with callback

var chip = createPersonChip({
    name: "Carol Davis",
    clickable: true,
    onClick: function(c) { console.log("Clicked:", c.getElement().title); }
});
container.appendChild(chip.getElement());

Share dialog composition

var people = ["Alice Chen", "Bob Smith", "Carol Davis"];
var row = document.createElement("div");
row.style.display = "flex";
row.style.flexWrap = "wrap";
row.style.gap = "4px";

people.forEach(function(name) {
    var chip = createPersonChip({ name: name, status: "online" });
    row.appendChild(chip.getElement());
});
container.appendChild(row);

ADR

ADR-036: PersonChip replicates UserMenu trigger style as standalone reusable element.

---

Pill

A reusable inline pill element for mentions, issues, documents, tags, and other entity references. Designed to flow naturally within text content, following the rounded-end style of Google Docs and GitHub.

Note: The rounded border-radius (9999px) is an explicit exception to the theme's zero-radius rule (see ADR-034).

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($blue-500, $gray-100, etc.)
• Bootstrap Icons — for optional icon and dismiss button (bi bi-x)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/pill/pill.css">
<script src="components/pill/pill.js"></script>
<script>
    var pill = createPill({ label: "@Alice Chen", icon: "bi bi-person" });
    document.getElementById("container").appendChild(pill.getElement());

    var dismissible = createPill({
        label: "PROJ-101",
        color: "green",
        dismissible: true,
        onDismiss: function(p) { console.log("Dismissed"); }
    });
    document.getElementById("container").appendChild(dismissible.getElement());
</script>

API

Global Functions

Pill Class

PillOptions

PillStyleOverrides

Colour Presets

Size Variants

CSS Custom Properties

All visual properties use CSS custom properties for runtime override:

.pill {
    --pill-bg: ...;
    --pill-fg: ...;
    --pill-border-color: ...;
    --pill-border-radius: ...;
    --pill-padding: ...;
    --pill-font-size: ...;
    --pill-max-width: ...;
}

Override via JavaScript:

pill.setStyle({ background: "pink", borderRadius: "4px" });

Or via inline style:

pill.getElement().style.setProperty("--pill-max-width", "300px");

STIE Integration

Pill is designed to complement the Smart Text Input Engine (STIE). Apps wanting full Pill features in STIE tokens use both class sets:

className: "stie-token-pill pill pill-blue"

When Pill CSS is loaded alongside STIE CSS, the Pill's custom properties layer on top.

Accessibility

• role="status" and aria-label on root element
• Dismiss button has aria-label="Remove"
• Clickable pills have tabindex="0" and respond to Enter/Space
• Icons use aria-hidden="true"
• Entrance animation respects prefers-reduced-motion

DOM Structure

<span class="pill pill-blue pill-md" role="status" aria-label="Alice Chen">
    <i class="bi bi-person pill-icon" aria-hidden="true"></i>
    <span class="pill-label">@Alice Chen</span>
    <button class="pill-dismiss" aria-label="Remove" tabindex="-1">
        <i class="bi bi-x" aria-hidden="true"></i>
    </button>
</span>

---

PresenceIndicator

A compact overlapping avatar stack showing who is actively viewing or editing a shared resource. Collapsed state shows overlapping circles with white ring borders and a "+N" overflow badge. Click to expand and reveal full PersonChip instances with names.

Designed for document headers, toolbar corners, and collaborative editing UIs similar to Google Docs' presence avatars.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-50, $gray-300, $blue-600, etc.)
• PersonChip JS — optional but recommended for rich avatars with status dots
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/personchip/personchip.css">
<link rel="stylesheet" href="components/presenceindicator/presenceindicator.css">
<script src="components/personchip/personchip.js"></script>
<script src="components/presenceindicator/presenceindicator.js"></script>
<script>
    var indicator = createPresenceIndicator("container-id", {
        people: [
            { id: "u1", name: "Alice Chen", status: "online" },
            { id: "u2", name: "Bob Smith", status: "busy" },
            { id: "u3", name: "Carol Davis", status: "away" }
        ]
    });
</script>

API

Global Functions

PresenceIndicator Class

PresenceIndicatorOptions

PersonData

Size Variants

Accessibility

• Root element: role="group" with aria-label describing person count.
• Stack: tabindex="0" and role="button" when expandable.
• Live region announces expand/collapse state changes.
• Focus-visible: 2px solid $blue-600 outline on stack.

Keyboard

Examples

Basic collapsed

var indicator = createPresenceIndicator("my-container", {
    people: [
        { id: "1", name: "Alice Chen", status: "online" },
        { id: "2", name: "Bob Smith" },
        { id: "3", name: "Carol Davis", status: "away" }
    ]
});

With overflow

createPresenceIndicator("container", {
    people: sevenPeople,
    maxVisible: 4   // Shows 4 avatars + "+3" badge
});

Programmatic control

var pi = createPresenceIndicator(null, { people: initialPeople });
document.getElementById("target").appendChild(pi.getElement());

pi.addPerson({ id: "new", name: "Dave Wilson", status: "online" });
pi.expand();
pi.removePerson("new");

ADR

ADR-038: PresenceIndicator composes PersonChip avatarOnly mode with runtime bridge pattern.

---

ProgressModal

A modal dialog for displaying progress of long-running operations.

Quick Start

<link rel="stylesheet" href="https://theme.priyavijai-kalyan2007.workers.dev/components/progressmodal/progressmodal.css">
<script src="https://theme.priyavijai-kalyan2007.workers.dev/components/progressmodal/progressmodal.js"></script>

<script>
    // Indeterminate spinner
    var modal = showProgressModal({ title: "Processing..." });
    modal.logInfo("Starting operation...");
    modal.setStatus("Connecting...");
    // ... later
    modal.logSuccess("Done!");
    modal.complete("Operation finished.");

    // Stepped progress
    var stepped = showSteppedProgressModal("Uploading", 5);
    stepped.setStep(1);
    stepped.logInfo("Uploading file 1...");
    // ... later
    stepped.setStep(5);
    stepped.complete();
</script>

Configuration Options

Instance Methods

Log Entry Levels

Dependencies

• Bootstrap 5 CSS, Bootstrap Icons, Enterprise Theme CSS
• Does NOT require Bootstrap JS

---

PromptTemplateManager

Two-pane CRUD interface for creating, editing, organising, and testing prompt templates with {{variable}} extraction, preview, tags, categories, and import/export.

Assets

Usage

<link rel="stylesheet" href="components/prompttemplatemanager/prompttemplatemanager.css">
<script src="components/splitlayout/splitlayout.js"></script>
<script src="components/prompttemplatemanager/prompttemplatemanager.js"></script>

Basic

var manager = createPromptTemplateManager({
    templates: [
        {
            id: "tpl-1",
            name: "Customer Support",
            content: "You are a support agent for {{company}}. Help {{customer}} with: {{issue}}",
            category: "Support",
            tags: ["support", "customer"],
            version: 1
        }
    ],
    categories: ["Support", "Sales", "Engineering"],
    onSave: function(tpl) {
        console.log("Saving:", tpl);
        return Promise.resolve(tpl);
    },
    onDelete: function(id) {
        console.log("Deleting:", id);
        return Promise.resolve(true);
    }
}, "my-container");

Read-Only Mode

var manager = createPromptTemplateManager({
    templates: myTemplates,
    readOnly: true
}, "container");

Interfaces

PromptVariable

interface PromptVariable {
    name: string;
    defaultValue?: string;
    description?: string;
    type?: "text" | "number" | "select" | "textarea";
    options?: string[];
    required?: boolean;
}

PromptTemplate

interface PromptTemplate {
    id: string;
    name: string;
    description?: string;
    content: string;
    category?: string;
    tags?: string[];
    variables?: PromptVariable[];
    version?: number;
    createdAt?: string;
    updatedAt?: string;
    author?: string;
    metadata?: Record<string, unknown>;
}

PromptTemplateManagerOptions

interface PromptTemplateManagerOptions {
    templates?: PromptTemplate[];
    categories?: string[];
    showPreview?: boolean;           // Default: true
    showVariableEditor?: boolean;    // Default: true
    showImportExport?: boolean;      // Default: true
    showSearch?: boolean;            // Default: true
    editorHeight?: string;           // Default: "300px"
    listWidth?: number;              // Default: 300
    height?: string;                 // Default: "600px"
    readOnly?: boolean;              // Default: false
    cssClass?: string;
    onSave?: (template: PromptTemplate) => Promise<PromptTemplate>;
    onDelete?: (templateId: string) => Promise<boolean>;
    onDuplicate?: (template: PromptTemplate) => Promise<PromptTemplate>;
    onPreview?: (content: string, variables: Record<string, string>) => Promise<string>;
    onLoadTemplates?: () => Promise<PromptTemplate[]>;
    onSelect?: (template: PromptTemplate) => void;
    onChange?: (template: PromptTemplate) => void;
}

API

Keyboard

Variable Extraction

Templates use {{variableName}} syntax. Variables are extracted automatically from content using /\{\{(\w+)\}\}/g. Detected variables appear as editable fields below the prompt editor.

Dependencies

• Required: Bootstrap 5 CSS, Bootstrap Icons, SplitLayout component

---

Property Inspector (Slide-out Drawer)

Non-modal right-side panel for viewing and editing entity details without navigating away from the parent list. Supports tabbed sections, resize handle, header actions, and footer.

Assets

Requirements

• Bootstrap CSS — SCSS variables
• Bootstrap Icons — header/action icons (bi-* classes)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/propertyinspector/propertyinspector.css">
<script src="components/propertyinspector/propertyinspector.js"></script>
<script>
    var inspector = createPropertyInspector({
        container: document.getElementById("main-content"),
        onClose: function() { console.log("Closed"); },
        onAction: function(id) { console.log("Action:", id); }
    });

    // Open with content
    var content = document.createElement("div");
    content.textContent = "Entity details here...";

    inspector.open({
        title: "Task #1234",
        subtitle: "High Priority",
        icon: "bi-clipboard-check",
        content: content,
        actions: [{ id: "edit", label: "Edit", icon: "bi-pencil" }]
    });
</script>

API

createPropertyInspector(options): PropertyInspectorHandle

PropertyInspectorOptions

InspectorOpenOptions

PropertyInspectorHandle

Keyboard

Accessibility

• Drawer: role="complementary", aria-label="Property Inspector"
• Tab bar: role="tablist", role="tab", aria-selected
• Close/action buttons: aria-label

---

ReasoningAccordion

Collapsible accordion for displaying AI chain-of-thought reasoning steps with status indicators, shimmer animation, timing metadata, confidence bars, and Vditor markdown rendering.

Assets

Usage

<link rel="stylesheet" href="components/reasoningaccordion/reasoningaccordion.css">
<script src="components/reasoningaccordion/reasoningaccordion.js"></script>

Basic — Static Steps

var acc = createReasoningAccordion("container-id", {
    title: "Reasoning",
    steps: [
        { id: "s1", title: "Analyzing input", status: "complete", duration: 820, content: "Parsed query entities." },
        { id: "s2", title: "Querying sources", status: "complete", duration: 1540, content: "Retrieved 12 documents." },
        { id: "s3", title: "Generating response", status: "complete", duration: 950, content: "Synthesized final answer." }
    ]
});

Streaming — Add Steps Over Time

var acc = createReasoningAccordion("container-id", {
    title: "AI Reasoning",
    autoExpandActive: true,
    autoCollapseCompleted: true
});

// Step 1 starts thinking
acc.addStep({ id: "s1", title: "Parsing query", status: "thinking" });

// Later — step 1 completes, step 2 starts
acc.updateStep("s1", { status: "complete", duration: 800, content: "Parsed OK." });
acc.addStep({ id: "s2", title: "Searching", status: "thinking" });

Interfaces

ReasoningStep

interface ReasoningStep {
    id: string;
    title: string;
    content?: string;               // Markdown rendered via Vditor
    status: "pending" | "thinking" | "complete" | "error";
    duration?: number;               // Milliseconds
    confidence?: number;             // 0-1
    icon?: string;                   // Bootstrap icon class override
    metadata?: Record<string, unknown>;
}

ReasoningAccordionOptions

interface ReasoningAccordionOptions {
    id?: string;
    steps?: ReasoningStep[];
    title?: string;                  // Default: "Reasoning"
    expandAll?: boolean;
    showTimings?: boolean;           // Default: true
    showStepNumbers?: boolean;       // Default: true
    showConfidence?: boolean;        // Default: false
    showExpandAllButton?: boolean;   // Default: true
    autoExpandActive?: boolean;      // Default: true
    autoCollapseCompleted?: boolean; // Default: false
    size?: "sm" | "default" | "lg"; // Default: "default"
    cssClass?: string;
    onStepClick?: (step: ReasoningStep) => void;
    onExpandChange?: (stepId: string, expanded: boolean) => void;
}

API

Keyboard

Status States

Size Variants

• sm — Compact padding, smaller fonts
• default — Standard sizing
• lg — Generous padding, larger fonts

Dependencies

• Required: Bootstrap 5 CSS, Bootstrap Icons
• Optional: Vditor (markdown rendering), DOMPurify (additional sanitisation)

---

RelationshipManager

Component for creating, viewing, and managing typed relationships between entities. Embeddable in any resource detail view as a "Relationships" section.

Usage

<link rel="stylesheet" href="components/relationshipmanager/relationshipmanager.css" />
<script src="components/relationshipmanager/relationshipmanager.js"></script>
<!-- Optional: TypeBadge for rich type display -->
<script src="components/typebadge/typebadge.js"></script>

const rm = createRelationshipManager({
    container: document.getElementById("relationships"),
    resourceId: "proj-123",
    resourceType: "work.project",
    resourceDisplayName: "Payment Redesign",
    relationshipDefinitions: [
        {
            key: "aligns_to",
            displayName: "aligns to",
            inverseName: "aligned by",
            targetTypeKeys: ["strategy.okr", "strategy.goal"],
            sourceTypeKeys: null,
            cardinality: "MANY_TO_MANY"
        }
    ],
    relationships: [
        {
            id: "rel-1",
            relationshipKey: "aligns_to",
            relationshipDisplayName: "aligns to",
            direction: "outbound",
            otherResourceId: "okr-456",
            otherResourceDisplayName: "Q2 Revenue Growth OKR",
            otherResourceType: "strategy.okr",
            properties: {},
            provenance: "manual",
            createdAt: "2026-02-15"
        }
    ],
    onCreateRelationship: async (req) => { /* POST to API */ },
    onDeleteRelationship: async (id) => { /* DELETE from API */ },
    onSearchResources: async (query, types) => { /* GET search results */ },
    onNavigate: (resourceId) => { /* Navigate to resource */ }
});

Features

• Grouped list — Relationships grouped by type with collapsible sections
• AI suggestions — Special section for AI-inferred relationships with confirm/dismiss
• 3-step add flow — Inline panel (not modal): select type, search target, set properties
• TypeBadge integration — Uses window.createTypeBadge if available, fallback to plain text
• ConfirmDialog integration — Uses window.showConfirmDialog if available, fallback to confirm()

Options

Add Button Visibility

By default, the "+Add" button is shown only when onCreateRelationship is provided and readOnly is false. Use the explicit showAddButton option to override inference:

show = showAddButton ?? (typeof onCreateRelationship === 'function')
effective = !readOnly && show

Public API

• setRelationships(rels) — Replace all relationships
• addRelationship(rel) — Add one relationship
• removeRelationship(id) — Remove by ID
• setReadOnly(readOnly) — Toggle read-only mode
• expandAll() / collapseAll() — Group expand/collapse
• refresh() — Re-render
• destroy() — Clean up

Global

window.createRelationshipManager(options)

---

Ribbon

A Microsoft Office-style tabbed toolbar for organizing commands and controls into logical groups. Each tab reveals a panel of grouped controls arranged in rows, supporting large, small, and mini button sizes. Includes an optional traditional menu bar, Quick Access Toolbar (QAT), contextual tabs, backstage panel, adaptive group collapsing, multi-level KeyTips, and inline gallery controls.

Features

• Tabbed panels — context-based tool switching (Home, Insert, Design, etc.)
• 13 control types — button, split-button, gallery, dropdown, input, color, number, checkbox, toggle, separator, label, custom
• Three button sizes — large (icon above label), small (icon left of label), mini (icon only)
• Adaptive collapse — groups progressively collapse (full → medium → small → mini → overflow) as the ribbon narrows
• Quick Access Toolbar — thin strip of pinned actions above or below the tab bar
• Menu bar — optional traditional dropdown menus with nested submenus above the tabs
• Contextual tabs — dynamic tabs that appear based on selection context with coloured accent
• Backstage panel — full-overlay panel (like File tab) with sidebar navigation and content area
• Multi-level KeyTips — Alt shows letter badges on tabs → type letter → badges on controls
• Gallery controls — inline preview row with "More" dropdown grid or list
• Collapsible — minimize ribbon to just the tab bar; click a tab to temporarily expand
• Component hosting — embed pickers, switchers, and other components via custom control type
• Configurable colours — 13 CSS custom properties, all settable via options or setColors()
• Full keyboard accessibility — WAI-ARIA roles, roving tabindex, arrow navigation
• Layout integration — position: relative for embedding in DockLayout, BorderLayout, etc.

Assets

Requires: Bootstrap CSS (for SCSS variables), Bootstrap Icons CSS. Does not require a JavaScript framework.

Quick Start

<link rel="stylesheet" href="components/ribbon/ribbon.css">
<script src="components/ribbon/ribbon.js"></script>
<script>
    var ribbon = createRibbon({
        tabs: [
            {
                id: "home",
                label: "Home",
                keyTip: "H",
                groups: [
                    {
                        id: "clipboard",
                        label: "Clipboard",
                        collapsePriority: 30,
                        controls: [
                            { type: "button", id: "paste", label: "Paste", icon: "bi bi-clipboard", size: "large", keyTip: "V" },
                            { type: "button", id: "cut", label: "Cut", icon: "bi bi-scissors", size: "small", keyTip: "X" },
                            { type: "button", id: "copy", label: "Copy", icon: "bi bi-files", size: "small", keyTip: "C" }
                        ]
                    },
                    {
                        id: "font",
                        label: "Font",
                        collapsePriority: 50,
                        controls: [
                            { type: "dropdown", id: "font-family", options: [{ value: "Arial", label: "Arial" }, { value: "Times New Roman", label: "Times New Roman" }], value: "Arial", width: "120px" },
                            { type: "dropdown", id: "font-size", options: [{ value: "11", label: "11" }, { value: "12", label: "12" }, { value: "14", label: "14" }], value: "11", width: "55px" },
                            { type: "button", id: "bold", label: "Bold", icon: "bi bi-type-bold", size: "mini", toggle: true, keyTip: "B" },
                            { type: "button", id: "italic", label: "Italic", icon: "bi bi-type-italic", size: "mini", toggle: true, keyTip: "I" }
                        ]
                    }
                ]
            }
        ],
        qat: [
            { id: "save", icon: "bi bi-floppy", tooltip: "Save", keyTip: "1" },
            { id: "undo", icon: "bi bi-arrow-counterclockwise", tooltip: "Undo", keyTip: "2" },
            { id: "redo", icon: "bi bi-arrow-clockwise", tooltip: "Redo", keyTip: "3" }
        ]
    }, "ribbon-container");
</script>

API

Factory

createRibbon(options: RibbonOptions, containerId?: string): Ribbon

Creates a Ribbon instance. If containerId is provided, the ribbon is shown immediately.

RibbonOptions

RibbonTab

RibbonGroup

Control Types

button

split-button

Same properties as button plus:

gallery

dropdown

input

color

number

checkbox / toggle

separator / row-break / label / custom

Instance Methods

Status Bar

The optional statusBar slot places a right-aligned area in the tab bar between the tabs and the collapse button. The Ribbon provides the container; consumers provide the content (user chip, entity name, version badge, PresenceIndicator, etc.).

var ribbon = createRibbon({
    tabs: [ /* ... */ ],
    statusBar: function() {
        var bar = document.createElement("div");
        bar.style.display = "inline-flex";
        bar.style.alignItems = "center";
        bar.style.gap = "8px";

        var user = document.createElement("span");
        user.textContent = "Jane Doe";
        bar.appendChild(user);

        var badge = document.createElement("span");
        badge.textContent = "v2.4.1";
        bar.appendChild(badge);
        return bar;
    }
}, "container");

// Update at runtime
ribbon.setStatusBar(newElement);

// Remove
ribbon.setStatusBar(null);

// Get the wrapper element
var wrapper = ribbon.getStatusBarElement();

Keyboard

Colour Configuration

All visual properties are configurable via options and setColors():

ribbon.setColors({
    backgroundColor: "#1a1a2e",
    tabBarBackgroundColor: "#16213e",
    tabTextColor: "#a0a0c0",
    tabActiveTextColor: "#ffffff",
    controlColor: "#e0e0f0"
});

Row Layout

By default, small/mini controls stack into vertical columns of 3. Use row-break controls to arrange items into explicit horizontal rows instead — ideal for Office-style groups like Font or Paragraph.

controls: [
    { type: "row-break", id: "r1" },        // start row 1
    { type: "dropdown", id: "font-family", ... },
    { type: "dropdown", id: "font-size", ... },
    { type: "row-break", id: "r2" },        // start row 2
    { type: "button", id: "bold", size: "mini", ... },
    { type: "button", id: "italic", size: "mini", ... },
    { type: "button", id: "underline", size: "mini", ... }
]

This produces:

Row 1: [Arial ▼] [11 ▼]
Row 2: [B] [I] [U]

All rows are wrapped in a vertical .ribbon-stack container so they tile top-to-bottom within the horizontal group flow.

Stack Alignment

Stacks use CSS subgrid to align labels and controls across rows. When multiple labeled controls are stacked (e.g. three dropdowns or a mix of dropdowns, inputs, and custom controls), all labels share one column width and all controls share another — producing uniform alignment. The width property on custom controls is applied as min-width so it sets a floor without conflicting with grid column sizing. In mini collapse, labels are hidden and the stack collapses to a single column.

Adaptive Collapse

Groups progressively collapse as the ribbon narrows:

1. Full — all controls at configured sizes
2. Medium — large buttons become small
3. Small — all buttons become small
4. Mini — all buttons become icon-only
5. Overflow — entire group collapses into a single dropdown

Groups with lower collapsePriority collapse first. A ResizeObserver triggers recalculation (debounced 150ms).

Layout Integration

The Ribbon uses position: relative (not fixed), making it embeddable in any layout container:

Component Hosting

The custom control type embeds existing components inside ribbon groups:

{
    type: "custom",
    id: "workspace",
    label: "Workspace",
    size: "large",
    element: function() {
        var div = document.createElement("div");
        var ws = new WorkspaceSwitcher({ workspaces: [...], size: "sm" });
        ws.show(div);
        return div;
    }
}

The optional label property renders a text label whose position depends on size: small/mini place the label on the left (row layout, matching built-in controls), while large places it below (column layout). The optional width property sets the wrapper's minimum width (e.g. width: "120px"), useful for components like FontDropdown or Slider that need space at mini height. Inside stacks the grid controls the actual width; the width value acts as a floor. The ribbon uses overflow: visible on group content so hosted component dropdowns are not clipped.

Icon Support

The icon property on controls accepts any space-separated CSS class string. The Ribbon applies each class individually, so any CSS icon library works:

• Bootstrap Icons: "bi bi-house", "bi bi-pencil"
• Font Awesome (Solid): "fa-solid fa-home", "fa-solid fa-pen"
• Font Awesome (Regular): "fa-regular fa-heart"
• Font Awesome (Brands): "fa-brands fa-github"

Ensure the corresponding icon library CSS is loaded in the page.

DOM Structure

div.ribbon
├── div.ribbon-qat [role="toolbar"]
├── div.ribbon-menubar [role="menubar"]
│   └── div.ribbon-menu-item
│       ├── button.ribbon-menu-trigger
│       └── div.ribbon-menu-dropdown [role="menu"]
├── div.ribbon-tabbar [role="tablist"]
│   ├── button.ribbon-tab [role="tab"]
│   ├── div.ribbon-tabbar-status          ← optional right-aligned status slot
│   │   └── [consumer HTMLElement]
│   └── button.ribbon-collapse-btn
├── div.ribbon-panel [role="tabpanel"]
│   └── div.ribbon-tab-content
│       ├── div.ribbon-group [role="group"]
│       │   ├── div.ribbon-group-content
│       │   │   ├── button.ribbon-btn-large
│       │   │   ├── div.ribbon-stack
│       │   │   │   └── button.ribbon-btn-small
│       │   │   └── div.ribbon-custom.ribbon-custom-{size}
│       │   │       ├── span.ribbon-custom-label    ← before element for small/mini
│       │   │       ├── [consumer HTMLElement]
│       │   │       └── span.ribbon-custom-label    ← after element for large
│       │   └── div.ribbon-group-label
│       └── div.ribbon-group-separator
├── div.ribbon-backstage [role="dialog"]
└── div.ribbon-keytip-layer [aria-hidden]

Auto-Collapse

When the ribbon is collapsed and a user clicks a tab, the panel temporarily expands. With autoCollapseDelay set to a positive value (minimum 5000 ms), the panel automatically collapses after the specified delay of inactivity. Any interaction (click, tap) inside the ribbon resets the timer.

var ribbon = createRibbon({
    tabs: [ /* ... */ ],
    collapsed: true,
    autoCollapseDelay: 8000  // auto-hide after 8 seconds
}, "container");

// Change at runtime
ribbon.setAutoCollapseDelay(5000);

// Disable
ribbon.setAutoCollapseDelay(0);

State Persistence

Save and restore the ribbon's UI state across sessions using getState() and restoreState(). The returned RibbonState object is JSON-serialisable.

// Save
var state = ribbon.getState();
localStorage.setItem("ribbon-state", JSON.stringify(state));

// Restore (on next load)
var saved = JSON.parse(localStorage.getItem("ribbon-state"));
if (saved) { ribbon.restoreState(saved); }

restoreState() accepts a Partial<RibbonState>, so consumers can restore only the fields they saved. The state includes: activeTabId, collapsed, contextualTabs visibility, controlValues, and autoCollapseDelay.

Deferred State

State methods (setControlDisabled, setControlActive, setControlHidden, setControlValue) work on controls in any tab — even tabs not yet rendered. The Ribbon queues changes internally and applies them when the tab is first activated. Multiple calls before render are supported; the last value wins.

getControlValue and getControlState also return queued state for unrendered controls, so consuming apps never need to track parallel state variables.

When setControlActive is called on a toggle: true button, the Ribbon syncs the internal toggle state so the next click always produces the correct opposite value — whether the state was set by click or by API.

Accessibility

• Tab bar: role="tablist", tabs: role="tab", aria-selected
• Panel: role="tabpanel", aria-labelledby
• Groups: role="group", aria-label
• Buttons: aria-pressed (toggles), aria-disabled
• Menu bar: role="menubar" → role="menu" → role="menuitem"
• QAT: role="toolbar", aria-label="Quick Access"
• Backstage: role="dialog", aria-modal="true"
• KeyTip badges: aria-hidden="true"
• Focus visible outlines on all interactive elements
• prefers-reduced-motion: reduce disables all transitions

---

RibbonBuilder

Visual WYSIWYG editor for composing Ribbon toolbar layouts via drag-and-drop. Exports Markdown specs consumable by coding agents and JSON configs for direct use with createRibbon().

Usage

HTML

<link rel="stylesheet" href="components/ribbonbuilder/ribbonbuilder.css">
<script src="components/ribbon/ribbon.js"></script>
<script src="components/ribbonbuilder/ribbonbuilder.js"></script>

<div id="my-ribbon-builder"></div>

Enhanced Icon Picker

When the SymbolPicker component is loaded, the icon picker auto-discovers all Bootstrap Icons and Font Awesome icons from loaded stylesheets (hundreds of icons). Falls back to a built-in curated set of 62 icons if SymbolPicker is not loaded.

<!-- Optional: load for enhanced icon picker -->
<link rel="stylesheet" href="components/symbolpicker/symbolpicker.css">
<script src="components/symbolpicker/symbolpicker.js"></script>

JavaScript

var builder = createRibbonBuilder({
    onChange: function(config) {
        console.log("Config updated:", config);
    },
    onExport: function(markdown) {
        console.log("Markdown exported:", markdown);
    }
}, "my-ribbon-builder");

Options

Handle API

Layout

The editor has three panels:

1. Toolbar (top) — Add Tab, Add Group, Add Control dropdown, Delete, Export MD, Export JSON, Import JSON
2. Live Preview (middle) — Real-time Ribbon preview rebuilt on every change (250ms debounce)
3. Bottom Split — Structure tree (left, resizable) and Property panel with Icon picker (right)

Keyboard Shortcuts

Drag-and-Drop

• Controls can be dragged between groups
• Groups can be dragged between tabs
• Tabs can be reordered
• Drop position: top 25% = before, middle 50% = inside, bottom 25% = after

Export Formats

Markdown

Structured tables per group with columns: #, Type, ID, Label, Icon, Size, Extra. Full JSON appended at end.

JSON

Standard RibbonOptions object — paste directly into createRibbon() calls.

Dependencies

• Ribbon (ribbon.js + ribbon.css) — required for live preview
• Bootstrap Icons — icon picker uses Bootstrap Icon classes

---

RichTextInput

A lightweight contenteditable-based rich text input that composes STIE and Pill for per-row editing contexts — todo items, checklist entries, inline detail fields. Fills the gap between a plain <input> and the full MarkdownEditor. No external dependencies; suitable for 20–50 instances on a single page.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($input-bg, $gray-900, etc.)
• Bootstrap Icons — for toolbar button icons (bi bi-type-bold, etc.)
• Does not require Bootstrap JS.
• STIE (optional) — for trigger-based entity references (@mentions, #issues)
• Pill (optional) — for styled inline tokens

Quick Start

<link rel="stylesheet" href="components/richtextinput/richtextinput.css">
<script src="components/richtextinput/richtextinput.js"></script>
<script>
    var editor = createRichTextInput({
        placeholder: "Type here...",
        formatting: true,
        onChange: function(html) { console.log("Content:", html); }
    });
    document.getElementById("container").appendChild(editor.getElement());
</script>

API

Global Functions

RichTextInput Class

RichTextInputOptions

FormattingAction Type

type FormattingAction =
    | "bold" | "italic" | "strikethrough" | "link" | "code"
    | "orderedList" | "unorderedList" | "taskList";

Default toolbar actions: ["bold", "italic", "strikethrough", "link", "code"]

Keyboard Shortcuts

CSS Custom Properties

Override these on .richtextinput to customize appearance:

STIE Integration

When STIE and Pill are loaded before RichTextInput, pass trigger definitions to enable inline entity references:

<script src="components/smarttextinput/smarttextinput.js"></script>
<script src="components/pill/pill.js"></script>
<script src="components/richtextinput/richtextinput.js"></script>
<script>
    var mentionTrigger = {
        trigger: "@",
        name: "mention",
        activation: { precedingChar: "whitespace", minLength: 1, maxLength: 30 },
        dataSource: {
            query: function(text) {
                return Promise.resolve([
                    { id: "u1", label: "Alice Chen", sublabel: "Engineering" }
                ].filter(function(u) {
                    return u.label.toLowerCase().includes(text.toLowerCase());
                }));
            }
        },
        tokenRenderer: { display: "label", className: "pill pill-blue", icon: "bi bi-person" },
        tokenSerializer: {
            prefix: "@",
            pattern: /^@\[(.+?)\]\(user:(\w+)\)$/,
            serialize: function(t) { return "@[" + t.label + "](user:" + t.id + ")"; },
            deserialize: function(m) { return { id: m[2], label: m[1] }; }
        }
    };

    var editor = createRichTextInput({
        placeholder: "Type @ to mention someone...",
        triggers: [mentionTrigger],
        stieOptions: {
            queryDebounceMs: 100,
            onTriggerQuery: function(ev) { /* show popover */ }
        }
    });
    document.getElementById("container").appendChild(editor.getElement());
</script>

If STIE is not loaded, triggers are silently ignored and the component works as plain rich text.

---

Ruler

A canvas-based calibrated ruler with cursor tracking, multiple unit systems, and DPI-aware rendering. Supports horizontal and vertical orientations with configurable tick marks, labelling, and real-time cursor position tracking.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables only
• Does not require Bootstrap JS or Bootstrap Icons.
• A container element with a defined width (horizontal) or height (vertical).

Quick Start

Horizontal Pixel Ruler

<link rel="stylesheet" href="components/ruler/ruler.css">
<script src="components/ruler/ruler.js"></script>

<div id="my-ruler" style="width: 800px;"></div>
<script>
    var ruler = createRuler("my-ruler", {
        orientation: "horizontal",
        unit: "px",
        showCursor: true
    });
</script>

Vertical Centimetre Ruler

<div id="cm-ruler" style="height: 600px;"></div>
<script>
    var cmRuler = createRuler("cm-ruler", {
        orientation: "vertical",
        unit: "cm",
        markingSide: "right",
        cursorColor: "#228be6"
    });
</script>

Inch Ruler with Custom Origin

<div id="inch-ruler" style="width: 600px;"></div>
<script>
    var inchRuler = createRuler("inch-ruler", {
        unit: "in",
        origin: 96,
        showCursor: true
    });
</script>

Custom Unit Ruler

<div id="unit-ruler" style="width: 500px;"></div>
<script>
    // 1 custom unit = 50 CSS pixels
    var unitRuler = createRuler("unit-ruler", {
        unit: "unit",
        unitScale: 50,
        majorInterval: 2
    });
</script>

API

Factory Function

The Ruler class is also available globally for direct instantiation:

var ruler = new Ruler("container-id", { unit: "cm" });

RulerOptions

Instance Methods

Unit Systems

The ruler supports five unit systems with automatic tick subdivision:

When majorInterval is provided, it overrides the default major tick interval. Minor ticks are placed at half the major interval and sub-minor ticks at one-tenth.

DPI Awareness

The ruler measures the physical DPI of the display using a hidden 1-inch DOM element. This allows cm, mm, and in units to render at accurate physical sizes. The measurement accounts for window.devicePixelRatio to render sharp lines on high-DPI (Retina) displays.

Call calibrate() after display changes (e.g., moving the window to a different monitor).

Cursor Tracking

When showCursor is true (the default), the ruler draws a coloured line that follows the mouse position. The cursor automatically tracks when the mouse is over the ruler canvas.

External code can also drive the cursor position programmatically:

// Sync cursor with mouse position over another element
document.getElementById("workspace").addEventListener("mousemove", function(e) {
    ruler.setCursorPosition(e.clientX - workspaceRect.left);
});

CSS Classes

Accessibility

• The wrapper element has aria-label="Ruler" for screen reader identification.
• When disabled, pointer-events: none prevents interaction.
• The component is a visual measurement aid; screen readers will announce the label.

See specs/ruler.prd.md for the complete specification.

---

SearchBox

A debounced search input with search icon, clear button, loading spinner, and optional suggestions dropdown. Designed for embedding in app shells, sidebars, and toolbars. Supports static and async suggestion sources, full keyboard navigation, and screen reader announcements.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables ($gray-*, $blue-*, etc.)
• Bootstrap Icons CSS -- for search and clear icons (bi-search, bi-x-lg)
• Does not require Bootstrap JS.

Quick Start (Script Tag)

<link rel="stylesheet" href="components/searchbox/searchbox.css">
<script src="components/searchbox/searchbox.js"></script>

<div id="search-container"></div>

<script>
    // Basic search box
    var sb = createSearchBox("search-container", {
        placeholder: "Search items...",
        onSearch: function(query) {
            console.log("Search:", query);
        },
        onSubmit: function(query) {
            console.log("Submit:", query);
        }
    });
</script>

Quick Start with Suggestions

<div id="search-suggestions"></div>

<script>
    // Static suggestions
    var sb = createSearchBox("search-suggestions", {
        placeholder: "Search fruits...",
        suggestions: ["Apple", "Apricot", "Banana", "Blueberry", "Cherry", "Date"],
        onSearch: function(query) {
            console.log("Search:", query);
        }
    });

    // Async suggestions
    var sbAsync = createSearchBox("search-async", {
        placeholder: "Search users...",
        suggestions: function(query) {
            return fetch("/api/users?q=" + encodeURIComponent(query))
                .then(function(r) { return r.json(); })
                .then(function(data) { return data.map(function(u) { return u.name; }); });
        },
        minChars: 3,
        debounceMs: 500
    });
</script>

Quick Start (ES Module)

import { createSearchBox, SearchBox } from "./components/searchbox/searchbox.js";

const sb = createSearchBox("my-container", {
    placeholder: "Search...",
    onSearch: (query) => console.log("Search:", query),
    suggestions: ["Alpha", "Beta", "Gamma"]
});

// Programmatic control
sb.setValue("Beta");
sb.focus();
sb.clearValue();

API

createSearchBox(containerId, options)

Creates a SearchBox and appends it to the specified container. Returns the SearchBox instance.

SearchBox Methods

SearchBoxOptions

Features

• Debounced search -- configurable delay prevents excessive callbacks during rapid typing
• Static suggestions -- client-side case-insensitive filtering of a string array
• Async suggestions -- call an async function with loading spinner feedback
• Clear button -- appears when input has a value; clears and refocuses
• Size variants -- sm, md, and lg for different contexts
• Disabled state -- greys out the component and prevents interaction
• Zero border-radius -- consistent with the enterprise theme rectangular style
• Reduced motion -- spinner and transitions respect prefers-reduced-motion

Keyboard Shortcuts

All key bindings can be overridden via the keyBindings option:

var sb = createSearchBox("container", {
    keyBindings: {
        clear: "Escape",
        submit: "Enter",
        nextSuggestion: "ArrowDown",
        prevSuggestion: "ArrowUp"
    }
});

Accessibility

• Root element: role="search"
• Input element: role="searchbox" with aria-label="Search"
• Input: aria-autocomplete="list", aria-expanded, aria-controls, aria-activedescendant
• Suggestions panel: role="listbox" with unique ID
• Suggestion items: role="option" with unique IDs and aria-selected
• Live region: role="status" with aria-live="polite" announces result count
• Clear button: aria-label="Clear search"
• Search icon: aria-hidden="true"
• Full keyboard navigation without requiring a mouse

---

ShareDialog

A modal dialog for sharing resources with configurable access levels. Composes PeoplePicker for person search/selection and PersonChip for existing access display. Returns a diff of added, changed, and removed access when the user clicks Done.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables, .btn-*, .form-select classes
• Bootstrap Icons -- optional, used if PersonChip is loaded
• Enterprise theme CSS -- css/custom.css
• PeoplePicker -- components/peoplepicker/peoplepicker.js (optional but recommended)
• PersonChip -- components/personchip/personchip.js (optional, falls back to simple spans)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="components/personchip/personchip.css">
<link rel="stylesheet" href="components/peoplepicker/peoplepicker.css">
<link rel="stylesheet" href="components/sharedialog/sharedialog.css">

<script src="components/personchip/personchip.js"></script>
<script src="components/peoplepicker/peoplepicker.js"></script>
<script src="components/sharedialog/sharedialog.js"></script>
<script>
    async function shareDocument() {
        const result = await showShareDialog({
            title: "Share Document",
            accessLevels: [
                { id: "viewer", label: "Viewer" },
                { id: "commenter", label: "Commenter" },
                { id: "editor", label: "Editor" },
            ],
            defaultAccessLevelId: "viewer",
            existingAccess: [
                { person: { id: "1", name: "Alice Smith", email: "alice@example.com" }, accessLevelId: "editor" },
            ],
            frequentContacts: [
                { id: "2", name: "Bob Jones", email: "bob@example.com" },
                { id: "3", name: "Carol Lee", email: "carol@example.com" },
            ],
            onSearch: async (query) => {
                const resp = await fetch(`/api/people?q=${encodeURIComponent(query)}`);
                return resp.json();
            },
        });

        if (result) {
            console.log("Added:", result.added);
            console.log("Changed:", result.changed);
            console.log("Removed:", result.removed);
        }
    }
</script>

API

Global Functions

Class: ShareDialog

const dialog = createShareDialog({ title: "Share", accessLevels: [...] });
const result = await dialog.show();

• show() -- Build, mount, display. Returns Promise<ShareDialogResult | null>.
• close() -- Close and cancel (resolves null).
• destroy() -- Tear down and release all resources.
• getElement() -- Get the root overlay element.
• setLoading(loading) -- Toggle loading state (dims dialog, disables interaction).

ShareDialogOptions

Data Types

AccessLevel

{ id: string; label: string; description?: string }

SharedPerson

{ person: PersonData; accessLevelId: string }

ShareDialogResult

{
    added: SharedPerson[];    // newly added people
    changed: SharedPerson[];  // people whose access level changed
    removed: string[];        // IDs of removed people
}

Keyboard

Key bindings can be overridden via the keyBindings option:

showShareDialog({
    title: "Share",
    accessLevels: [...],
    keyBindings: { close: "Ctrl+Escape" },
});

Accessibility

• Dialog uses role="dialog" and aria-modal="true"
• Title linked via aria-labelledby
• aria-live="polite" region announces access changes to screen readers
• Remove buttons have aria-label="Remove <name>"
• Close button has aria-label="Close"
• Native <select> elements for access levels (inherently accessible)
• Focus trapped within dialog on Tab
• Focus restored to previously active element on close
• Animations respect prefers-reduced-motion: reduce

DOM Structure

div.sharedialog-overlay [z-index 2000]
  div.sharedialog-backdrop
  div.sharedialog.sharedialog-{size} [role="dialog" aria-modal="true"]
    div.sharedialog-header
      h2.sharedialog-title
      button.sharedialog-close [aria-label="Close"]
    div.sharedialog-body
      div.sharedialog-add-section
        div.sharedialog-picker-row
          div.sharedialog-picker-wrap [PeoplePicker mounts here]
          select.sharedialog-access-select.form-select
        button.sharedialog-add-btn.btn.btn-primary
      div.sharedialog-divider
      div.sharedialog-existing-section
        h3.sharedialog-section-label "People with access"
        div.sharedialog-access-list
          div.sharedialog-access-row [data-person-id] x N
            div.sharedialog-access-person [PersonChip md]
            select.sharedialog-access-level.form-select
            button.sharedialog-access-remove
    div.sharedialog-footer
      span.sharedialog-status
      div.sharedialog-actions
        button.sharedialog-cancel-btn.btn.btn-secondary
        button.sharedialog-done-btn.btn.btn-primary
    div.visually-hidden [aria-live="polite"]

Features

• Promise-based -- await showShareDialog(...) returns result diff or null
• Diff computation -- Returns only what changed: { added, changed, removed }
• Configurable access levels -- Define your own (Viewer, Editor, Owner, etc.)
• PeoplePicker integration -- Searchable person selector with frequent contacts
• PersonChip display -- Rich person identity chips in access list
• Focus trap -- Tab cycles within the dialog
• Focus restore -- Returns focus to the previously active element
• Loading state -- Async onShare callback with dimmed dialog
• Backdrop dismiss -- Click outside to cancel (configurable)
• XSS safe -- All content set via textContent, never innerHTML
• Graceful degradation -- Works without PeoplePicker/PersonChip via fallbacks
• Auto-cleanup -- DOM removed when dialog resolves
• No Bootstrap JS dependency -- Fully standalone modal implementation

---

Sidebar

A dockable, floatable, resizable sidebar panel component that acts as a container for other components. Supports docking to left/right viewport edges, free-positioned floating with drag-based positioning, collapsing to a 40px icon strip, resizing via drag handles, tab grouping when multiple sidebars share the same dock edge, and drag-to-dock with visual drop zones.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Bootstrap Icons CSS — for title bar action icons and optional sidebar icon
• Does not require Bootstrap JS.

Usage (Script Tag)

<link rel="stylesheet" href="components/sidebar/sidebar.css">
<script src="components/sidebar/sidebar.js"></script>
<script>
    // Docked sidebar
    var explorer = createDockedSidebar({
        title: "Explorer",
        icon: "bi-folder",
        dockPosition: "left",
        width: 280
    });
    explorer.getContentElement().innerHTML = "<p style='padding:1rem'>Content here</p>";

    // Floating sidebar
    var tools = createFloatingSidebar({
        title: "Tools",
        icon: "bi-tools",
        floatX: 400,
        floatY: 100,
        width: 300,
        height: 400
    });
</script>

Usage (ES Module)

import { createSidebar, createDockedSidebar } from "./components/sidebar/sidebar.js";

const sb = createDockedSidebar({
    title: "Explorer",
    icon: "bi-folder",
    dockPosition: "left",
    onModeChange: (mode, sidebar) => console.log("Mode:", mode),
    onResize: (w, h) => console.log("Resized:", w, h)
});

Options

API

Sidebar

SidebarManager

Convenience Functions

CSS Custom Properties

The component sets these properties on <html> for layout integration:

Consumers can offset main content with:

.main-content {
    margin-left: var(--sidebar-left-width, 0px);
    margin-right: var(--sidebar-right-width, 0px);
}

Tab Grouping

When multiple sidebars dock to the same edge, they automatically form a tab group. Only one sidebar is visible at a time; the others are hidden. A tab bar appears at the top of the dock zone.

Drag-to-Dock

In floating mode, dragging the sidebar near a viewport edge (within 40px) shows a translucent drop-zone indicator. Releasing within the zone docks the sidebar to that edge.

Z-Index Layering

Accessibility

• Root: role="complementary" with descriptive aria-label
• Title bar: role="heading" with aria-level="2"
• Collapse button: aria-expanded="true|false"
• Tab bar: role="tablist", tabs: role="tab" + aria-selected
• Resize handle: role="separator", aria-valuenow/min/max, arrow keys (10px steps)
• Collapsed strip: keyboard-accessible (Enter/Space to expand)
• No focus trapping (persistent panel, not modal)

---

SizesPicker

A dropdown listing page and frame sizes with proportional page thumbnails and dimensions. Each item shows a small proportional SVG rectangle, the size name, and width by height. Items are grouped by category (Paper, Screen, Mobile, Tablet). An optional "More Paper Sizes..." link at the bottom allows integration with custom size dialogs.

Usage

<link rel="stylesheet" href="components/sizespicker/sizespicker.css">
<script src="components/sizespicker/sizespicker.js"></script>

<div id="my-sizes-picker"></div>

<script>
var picker = createSizesPicker({
    container: "my-sizes-picker",
    value: "A4",
    onChange: function(size) {
        console.log("Selected:", size.name, size.width, "x", size.height);
    }
});
</script>

With Custom Sizes

<div id="custom-sizes"></div>

<script>
var picker = createSizesPicker({
    container: "custom-sizes",
    sizes: [
        { name: "Poster", width: 2400, height: 3600, category: "Print", displayWidth: '25"', displayHeight: '37.5"' },
        { name: "Banner", width: 4800, height: 1200, category: "Print", displayWidth: '50"', displayHeight: '12.5"' },
    ],
    onCustom: function() {
        alert("Open custom size dialog");
    }
});
</script>

Filtered by Category

<div id="paper-only"></div>

<script>
var picker = createSizesPicker({
    container: "paper-only",
    category: "Paper",
    onChange: function(size) {
        console.log("Paper size:", size.name);
    }
});
</script>

Options

API

Default Sizes

SizePreset Interface

interface SizePreset {
    name: string;
    width: number;          // pixels at 96 DPI
    height: number;
    category?: string;      // "Paper", "Screen", "Mobile", etc.
    displayWidth?: string;  // human-readable width
    displayHeight?: string; // human-readable height
}

Keyboard

SVG Thumbnails

Each size item renders a proportional page rectangle as an inline SVG. The tallest page in the current list is scaled to 40px; all other widths and heights scale proportionally relative to the tallest entry. The rectangle uses a white fill with a #dee2e6 border.

---

SkeletonLoader

Animated placeholder component that mimics content layout during loading. CSS shimmer animation with six presets: text, avatar, card, table, paragraph, and custom.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-100, $gray-200)
• Does not require Bootstrap JS or Bootstrap Icons.

Quick Start

<link rel="stylesheet" href="components/skeletonloader/skeletonloader.css">
<script src="components/skeletonloader/skeletonloader.js"></script>
<script>
    var skeleton = createSkeletonLoader(
        { preset: "card" },
        "my-container"
    );
    // Later when data loads:
    skeleton.destroy();
</script>

Options (SkeletonLoaderOptions)

API

Global Exports

window.SkeletonLoader
window.createSkeletonLoader

Accessibility

• Root has role="status", aria-busy="true", aria-label="Loading content"
• prefers-reduced-motion: reduce disables shimmer animation
• Consumer should set aria-busy="false" on parent when content loads

See specs/skeletonloader.prd.md for the complete specification.

---

Slider

A range input component with single-value and dual-thumb range modes, optional tick marks, value labels, keyboard navigation, and size variants. Supports both horizontal and vertical orientations.

Purpose and Use Cases

• Numeric value selection in forms and settings panels
• Range selection (e.g., price range filters, date range bounds)
• Zoom, volume, opacity, and other continuous controls
• Ribbon toolbar controls for line width, font size, etc.

Quick Start

<!-- Dependencies -->
<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="components/slider/slider.css">

<!-- Component -->
<div id="my-slider"></div>
<script src="components/slider/slider.js"></script>
<script>
    createSlider("my-slider", {
        min: 0,
        max: 100,
        value: 50,
        onChange: (v) => console.log("Value:", v)
    });
</script>

Range Mode

<div id="range-slider"></div>
<script>
    createSlider("range-slider", {
        mode: "range",
        min: 0,
        max: 1000,
        valueLow: 200,
        valueHigh: 800,
        formatValue: (v) => "$" + v,
        onChange: (r) => console.log("Range:", r.low, "-", r.high)
    });
</script>

Configuration Options

Instance Methods

Keyboard Interactions

In vertical orientation, ArrowUp/Down are the primary directional keys.

Size Variants

<div id="sm-slider"></div>
<div id="lg-slider"></div>
<script>
    createSlider("sm-slider", { size: "sm", value: 30 });
    createSlider("lg-slider", { size: "lg", value: 70 });
</script>

Accessibility

• Each thumb has role="slider" with aria-valuemin, aria-valuemax, and aria-valuenow
• aria-orientation reflects horizontal or vertical mode
• aria-label is set from the label option
• Full keyboard navigation with arrow keys, Home, End, PageUp, PageDown
• Focus indicator uses :focus-visible ring

Dependencies

---

SmartTextInput

A behavioral middleware engine (non-UI) that attaches to text inputs and provides trigger-based inline references such as @mentions, #resources, and $formulas. The host application is responsible for rendering the popover/dropdown UI and supplying data sources; the engine handles trigger detection, keyboard delegation, token lifecycle, serialization, and accessibility announcements.

Quick Start

<link rel="stylesheet" href="components/smarttextinput/smarttextinput.css">
<script src="components/smarttextinput/smarttextinput.js"></script>

<textarea id="my-input"></textarea>
<script>
    var engine = createSmartTextInput({
        queryDebounceMs: 150,
        delegateKeyboard: true
    });

    // Register an @mention trigger
    engine.register({
        trigger: "@",
        name: "mention",
        activation: {
            requireWhitespaceBefore: true,
            minQueryLength: 0,
            maxQueryLength: 50,
            cancelChars: [" ", "\n"],
            escapeChar: "\\",
            suppressIn: ["codeBlock", "inlineCode", "url"]
        },
        dataSource: { query: (text) => fetchUsers(text) },
        tokenRenderer: {
            type: "pill",
            display: (token) => "@" + token.label,
            className: "stie-token-pill"
        },
        tokenSerializer: {
            serialize: (token) => "[@" + token.label + "](user:" + token.id + ")",
            deserialize: (raw) => parseMentions(raw)
        }
    });

    // Attach to the input element
    engine.attach(document.getElementById("my-input"));

    // Listen for trigger lifecycle events
    engine.on("trigger:open", function(e) {
        showPopover(e.position, e.triggerName);
    });

    engine.on("trigger:query", function(e) {
        updatePopoverResults(e.queryText);
    });

    engine.on("trigger:close", function(e) {
        hidePopover(e.reason);
    });

    // When the user picks an item from the host popover:
    engine.resolve({ id: "42", label: "Jane Doe" });
</script>

Configuration Options

SmartTextInputOptions passed to createSmartTextInput():

Trigger Definition

Each trigger registered via engine.register(def) conforms to TriggerDefinition:

TriggerActivation

Adapter Types

The engine auto-detects the adapter from the attached element. You can also pass an explicit type to attach().

The plaintext and contenteditable adapters are built in. The others require the host to implement the InputAdapter interface.

Public API

Events

Subscribe via engine.on(eventName, handler). Each returns an Unsubscribe function.

Token Model

ResolvedToken represents an inserted token:

Token Rendering Types

The TokenRenderer.type field controls visual appearance. Built-in CSS classes are provided for each type:

Serialization

Tokens are serialized to and from raw text using TokenSerializer. This allows content with tokens to be stored, transmitted, and restored.

The default pattern uses a markdown-link-inspired format:

[@Jane Doe](user:42)
[#PROJ-100](issue:100)
[$revenue](formula:rev-2024)

Each trigger's serializer defines serialize(token) (token to string) and deserialize(rawContent) (string to DeserializedToken[]). The engine's setSerializedContent() runs all registered deserializers to reconstruct tokens from stored content.

Use SmartTextInputEngine.renderTokens() to render serialized content into a read-only container with styled token spans.

Keyboard Behavior

When delegateKeyboard is true (default) and a trigger session is active:

All four keys call preventDefault() during an active session to avoid interfering with the input's default behavior. When no session is active, keys pass through normally.

Accessibility

The engine creates a visually-hidden ARIA live region (role="status", aria-live="polite") that announces:

• "<triggerName> suggestions available" when a trigger opens
• "Inserted <label>" when a token is resolved
• "Suggestions closed" when a session ends

The host popover should implement the WAI-ARIA combobox pattern (role="combobox" on the input, role="listbox" on the results list, aria-activedescendant for the highlighted item) to provide full screen reader support.

Security

• All DOM text is set via textContent -- innerHTML is never used for user content.
• Token display text comes from renderer.display(), which should return sanitized strings.
• Validate all data returned by dataSource.query() callbacks before passing to resolve().
• The engine does not fetch remote data itself; the host controls all network calls.

Window Globals

---

SpacingPicker

A dropdown showing line/paragraph spacing presets with visual SVG thumbnails. Each option displays a small box with horizontal lines at different vertical spacings to illustrate the visual difference. Designed for use in Ribbon toolbars, standalone toolbars, and property panels.

Usage

<link rel="stylesheet" href="components/spacingpicker/spacingpicker.css">
<script src="components/spacingpicker/spacingpicker.js"></script>

<div id="my-spacing"></div>

<script>
var picker = createSpacingPicker({
    container: "my-spacing",
    value: "1.5",
    onChange: function(preset) {
        console.log("Line height:", preset.lineHeight);
        console.log("After paragraph:", preset.afterParagraph, "px");
    }
});
</script>

Options

Default Presets

API

Keyboard

CSS Classes

---

SpineMap

Interactive SVG capability/feature map with a central spine, branching sub-nodes, four layout algorithms, zoom/pan, status color coding, cross-branch connections, and integrated editing.

Assets

Quick Start

<link rel="stylesheet" href="components/spinemap/spinemap.css">
<script src="components/spinemap/spinemap.js"></script>

<div id="my-map" style="width:100%; height:600px;"></div>

<script>
const map = createSpineMap({
    container: document.getElementById("my-map"),
    layout: "vertical",
    data: {
        hubs: [
            {
                id: "admin",
                label: "Tenant Admin",
                status: "available",
                branches: [
                    { id: "rbac", label: "RBAC", status: "available" },
                    { id: "fgac", label: "FGAC", status: "planned", timeframe: "Q3 2026" }
                ]
            },
            {
                id: "apps",
                label: "Apps",
                status: "available",
                branches: [
                    { id: "diagrams", label: "Diagrams", status: "available" },
                    { id: "todo", label: "ToDo", status: "in-progress" },
                    { id: "checklists", label: "Checklists", status: "available" },
                    { id: "workitems", label: "Work Items", status: "planned" }
                ]
            }
        ],
        connections: [
            { from: "fgac", to: "rbac", type: "depends-on" }
        ]
    }
});
</script>

Global Functions

Class API

Data

Nodes

Connections

Layout

Zoom & Pan

Selection

Export

Lifecycle

Options

Popover Fields

The popoverFields option lets consumers configure which fields appear in the node popover, their order, and what widget renders each field.

SpinePopoverFieldConfig

{
    key: string;             // Node property name or metadata key
    label: string;           // Display label
    type: SpinePopoverFieldType;  // Widget type (see below)
    source?: "property" | "metadata";  // Where to read/write the value
    showInView?: boolean;    // Show in view mode (default: true)
    showInEdit?: boolean;    // Show in edit mode (default: true)
    componentOptions?: Record<string, unknown>;  // Forwarded to component factory
    selectOptions?: { value: string; label: string }[];  // For "select" type
    serialize?: (value: unknown) => string;    // Custom serializer
    deserialize?: (stored: string) => unknown; // Custom deserializer
    renderView?: (value: unknown, node) => HTMLElement;  // Custom view renderer
    required?: boolean;
    hint?: string;           // Help text below field in edit mode
    cssClass?: string;       // Extra CSS class on field wrapper
    width?: "compact" | "full";  // "full" forces min-height for editors
}

Supported Field Types

Library component types require the corresponding component JS to be loaded. If unavailable, the field falls back to a plain text input with a console warning.

Source Auto-Detection

If source is not specified, known node properties (label, status, timeframe, link, description, statusLabel, statusColor) default to "property". All other keys default to "metadata" and are stored in node.metadata.

Default Configuration

When popoverFields is omitted, the popover uses this default (identical to previous behavior):

[
    { key: "status",      label: "Status",      type: "status"      },
    { key: "timeframe",   label: "Timeframe",   type: "text"        },
    { key: "link",        label: "Link",        type: "link"        },
    { key: "description", label: "Description", type: "textarea"    },
    { key: "connections", label: "Connections",  type: "connections" }
]

Example: Custom Fields with Metadata

const map = createSpineMap({
    container: document.getElementById("my-map"),
    editable: true,
    popoverFields: [
        { key: "status",   label: "Status",   type: "status"   },
        { key: "timeframe", label: "Timeframe", type: "periodpicker" },
        { key: "priority", label: "Priority",  type: "select",
          source: "metadata",
          selectOptions: [
              { value: "high", label: "High" },
              { value: "medium", label: "Medium" },
              { value: "low", label: "Low" }
          ]
        },
        { key: "owner", label: "Owner", type: "text",
          source: "metadata", hint: "Assignee name" },
        { key: "description", label: "Description",
          type: "richtextinput", width: "full" },
        { key: "connections", label: "Connections",
          type: "connections" }
    ],
    popoverWidth: 380,
    data: { hubs: [ /* ... */ ] }
});

Callbacks

Data Types

SpineHub

{
    id: string;
    label: string;
    status?: "available" | "in-progress" | "planned" | "not-supported" | "deprecated" | "custom";
    statusLabel?: string;
    statusColor?: string;
    link?: string;
    timeframe?: string;
    description?: string;
    metadata?: Record<string, string>;
    branches: SpineBranch[];
}

SpineBranch

Same as SpineHub but with children?: SpineBranch[] instead of branches.

SpineConnection

{
    from: string;           // node id
    to: string;             // node id
    type: "depends-on" | "works-with" | "blocks" | "enhances";
    label?: string;
}

Keyboard Shortcuts

Accessibility

• role="button" and tabindex="0" on each node for keyboard focus
• aria-label on nodes includes label and status
• aria-live="polite" region announces node changes
• Popover has role="dialog"
• Toolbar buttons have aria-label and title
• Focus-visible indicators with 2px blue outline

Connection Types

Layout Modes

Editing Modes

Sidebar (TreeGrid)

When editable: true, a sidebar with a TreeGrid shows the full hierarchy. Edit labels, status, and timeframe inline. Drag rows to reparent nodes. Requires TreeGrid JS to be loaded; falls back to a simple tree list otherwise.

Popover

Click any node to see its details. In editable mode, use Edit/Add Child/Remove buttons. Double-click to open directly in edit mode.

Visual

Drag nodes to reposition. Shift+drag from one node to another to create a connection. Click a connection path to remove it.

Export Formats

---

SplitLayout

A split layout container that divides available space into two or more panes separated by draggable dividers. Supports horizontal/vertical orientation, pane collapsing, nested layouts, and state persistence via localStorage.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $primary, etc.)
• Does not require Bootstrap JS or Bootstrap Icons.

Quick Start

<link rel="stylesheet" href="components/splitlayout/splitlayout.css">
<script src="components/splitlayout/splitlayout.js"></script>
<script>
    var layout = createSplitLayout({
        orientation: "horizontal",
        panes: [
            { id: "left", initialSize: "30%", minSize: 200, collapsible: true },
            { id: "center", initialSize: "1fr" },
            { id: "right", initialSize: 300, collapsible: true }
        ]
    }, "my-container");

    // Add content to panes
    layout.getPaneElement("left").textContent = "Left pane";
    layout.getPaneElement("center").textContent = "Center pane";
    layout.getPaneElement("right").textContent = "Right pane";
</script>

Options (SplitLayoutOptions)

Pane Config (SplitPaneConfig)

API

Convenience Function

createSplitLayout(options, containerId?)  // Create, show, and return

Global Exports

window.SplitLayout
window.createSplitLayout

Size Calculation

Initial sizes are resolved in priority order:

1. Persisted state from persistKey (if available)
2. Explicit initialSize values from pane config
3. Equal distribution of remaining space

Supports pixels (200), percentages ("30%"), and fractional units ("1fr").

Keyboard Accessibility

Accessibility

• Dividers have role="separator" with aria-orientation, aria-valuenow/min/max
• Panes have role="region" with aria-label
• Dividers are focusable via tabindex="0"
• No focus trapping — persistent layout container, not modal

Examples

Two-pane editor layout

var layout = createSplitLayout({
    orientation: "horizontal",
    panes: [
        { id: "explorer", initialSize: 250, minSize: 180, collapsible: true },
        { id: "editor", initialSize: "1fr", minSize: 300 }
    ],
    persistKey: "editor-layout"
}, "app-container");

Nested three-pane IDE layout

var outer = createSplitLayout({
    orientation: "horizontal",
    panes: [
        { id: "sidebar", initialSize: "20%", collapsible: true },
        { id: "main", initialSize: "1fr" }
    ]
}, "ide-container");

var inner = new SplitLayout({
    orientation: "vertical",
    panes: [
        { id: "editor", initialSize: "70%", minSize: 200 },
        { id: "terminal", initialSize: "30%", minSize: 100, collapsible: true }
    ]
});

outer.setPaneContent("main", inner.getElement());
inner.show();

See specs/splitlayout.prd.md for the complete specification.

---

SprintPicker

Agile sprint selector with list and calendar views. Computes sprints from anchor date, sprint length, and week start day. Supports configurable naming and colored sprint band overlays.

Usage

CSS

<link rel="stylesheet" href="components/sprintpicker/sprintpicker.css">

JavaScript

<script src="components/sprintpicker/sprintpicker.js"></script>

Basic (List View)

<div id="my-sprint-picker"></div>

<script>
const picker = createSprintPicker("my-sprint-picker", {
    anchorDate: new Date(2026, 0, 5), // Mon Jan 5 2026
    sprintLength: 2,
    onSelect: function(value) {
        console.log("Selected:", value.sprintName, value.date);
    }
});
</script>

Calendar View

<div id="calendar-sprint"></div>

<script>
const picker = createSprintPicker("calendar-sprint", {
    anchorDate: "2026-01-05",
    sprintLength: 1,
    viewMode: "calendar",
    onSelect: function(value) {
        console.log("Sprint:", value.sprintName);
    }
});
</script>

Custom Naming

<div id="custom-sprint"></div>

<script>
const picker = createSprintPicker("custom-sprint", {
    anchorDate: new Date(2026, 0, 5),
    sprintLength: 2,
    sprintNaming: function(index, start, end) {
        return "Iteration " + (index + 1);
    }
});
</script>

Options

Sprint Naming Modes

SprintValue

interface SprintValue {
    sprintIndex: number;   // 0-based
    sprintName: string;    // Display name
    startDate: Date;       // Sprint start (Monday)
    endDate: Date;         // Sprint end (Friday)
    date: Date;            // Resolved date based on mode
}

Public API

Keyboard

List View

Calendar View

Sprint Computation

Sprints are computed from the anchor date:

start[i] = anchorDate + (i × sprintLength × 7) days
end[i]   = start[i] + (sprintLength × 7 - 3) days  // Friday

Example (2-week sprints, Mon Jan 5 2026):

• Sprint 1: Jan 5 – Jan 16
• Sprint 2: Jan 19 – Jan 30
• Sprint 3: Feb 2 – Feb 13

Dropdown Positioning

The dropdown is portaled to document.body with position: fixed and z-index: 2050, ensuring it renders above FormDialog overlays (z-index 2001).

---

StackLayout

A vertically stacked panel layout where each panel has a collapsible header (with icon, title, and chevron toggle) and a content area. Draggable dividers between panels allow resizing. When a panel is collapsed, only its 28px header is visible and the remaining panels expand proportionally.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables ($gray-*, $primary, spacing tokens).
• Does not require Bootstrap JS.
• Optional: Bootstrap Icons for panel header icons.

Quick Start

<link rel="stylesheet" href="components/stacklayout/stacklayout.css">
<script src="components/stacklayout/stacklayout.js"></script>
<script>
    var propsEl = document.createElement("div");
    propsEl.textContent = "Properties content";

    var relsEl = document.createElement("div");
    relsEl.textContent = "Relationships content";

    var stack = createStackLayout({
        container: document.getElementById("sidebar-content"),
        panels: [
            { id: "properties", title: "Properties", icon: "bi-gear", content: propsEl },
            { id: "relationships", title: "Relationships", icon: "bi-diagram-3", content: relsEl, collapsed: true },
        ],
        resizable: true,
        onResize: function(sizes) { console.log("Sizes:", sizes); },
        onCollapse: function(id, collapsed) { console.log(id, collapsed); },
    });
</script>

Options (StackLayoutOptions)

Panel Config (StackedPanelConfig)

API

Panel Handle

Returned by getPanel(id):

Global Export

window.createStackLayout

Keyboard Accessibility

Accessibility

• Panels have role="region" with aria-label from the panel title
• Panel headers have role="button" with aria-expanded
• Headers are focusable via tabindex="0" (when collapsible)
• Dividers have role="separator" with aria-orientation="horizontal"
• Dividers are focusable via tabindex="0" (when resizable)

Visual Layout

+---------------------+
| > Properties    [-] |  <-- Collapsible header with chevron
|                     |
|  Name: Deploy Plan  |  <-- Panel 1 content
|  Type: Checklist    |
|                     |
+- - - - - - - - - - -+  <-- 4px draggable divider
| > Relationships [-] |  <-- Collapsible header
|                     |
|  derived_from (1)   |  <-- Panel 2 content
|  owned_by (1)       |
|                     |
+---------------------+

When a panel is collapsed, only its 28px header row is visible. The remaining expanded panels redistribute to fill available space.

Composition with Sidebar

var rightSidebar = createDockedSidebar({ position: "right", width: 380 });
var stack = createStackLayout({
    container: rightSidebar.getContentElement(),
    panels: [
        { id: "properties", title: "Properties", content: propsEl },
        { id: "relationships", title: "Relationships", content: relsEl, collapsed: true },
    ],
    resizable: true,
});

See specs/stackable-sidebars.req.md for the full requirement document.

---

StatusBadge

Colour-coded pills/dots communicating process or system state with animated pulse and click-for-detail support. Supports seven built-in statuses plus a custom mode, three visual variants, and four sizes.

Assets

Quick Start

<link rel="stylesheet" href="components/statusbadge/statusbadge.css">
<script src="components/statusbadge/statusbadge.js"></script>

<div id="status-container"></div>

<script>
    // Factory function — creates and shows in one call
    var badge = createStatusBadge("status-container", {
        status: "operational",
        variant: "indicator"
    });

    // Update status dynamically
    badge.setStatus("degraded");

    // Update label text
    badge.setLabel("Service Degraded");

    // Toggle pulse animation
    badge.setPulse(false);
</script>

API

createStatusBadge(containerId, options)

Creates a StatusBadge instance and appends it to the specified container. Returns the instance for further manipulation.

var badge = createStatusBadge("my-container", {
    status: "in-progress",
    variant: "pill",
    clickable: true,
    onClick: function() { console.log("Clicked!"); }
});

StatusBadgeOptions

Instance Methods

Status Values

Variants

Dot (variant: "dot")

Displays only the coloured dot with no text label. Useful for compact status indicators in tables or lists.

Pill (variant: "pill")

Displays only the label text with a coloured background. The label inherits the status colour as its background and uses light text for contrast.

Indicator (variant: "indicator")

Default variant. Displays both the coloured dot and the text label side-by-side. Provides the most informative visual representation.

Features

• 7 built-in status states plus a custom mode
• Animated pulse for live/active states (operational, in-progress)
• Clickable with callback support
• Keyboard accessible (Enter/Space activation, focus-visible ring)
• Size variants (xs, sm, md, lg)
• prefers-reduced-motion support disables pulse animation
• role="status" and aria-label for screen reader compatibility
• Tooltip support via the title attribute

Accessibility

• role="status" with aria-label set to "Status: {label}" for screen reader announcements.
• When clickable, role="button" and tabindex="0" are applied for keyboard navigation.
• Enter and Space keys activate the click handler, matching native button semantics.
• focus-visible outline provides a clear keyboard focus indicator.
• prefers-reduced-motion: reduce disables the pulse animation for users who prefer reduced motion.

Dependencies

• Bootstrap 5 CSS (for SCSS variables) and Enterprise Theme CSS.
• Does NOT require Bootstrap JS.

---

StatusBar

A fixed-to-bottom viewport status bar with configurable label/value regions separated by pipe dividers. Text is natively selectable for Ctrl+C copying.

Quick Start

<link rel="stylesheet" href="https://theme.priyavijai-kalyan2007.workers.dev/components/statusbar/statusbar.css">
<script src="https://theme.priyavijai-kalyan2007.workers.dev/components/statusbar/statusbar.js"></script>

<script>
    var bar = createStatusBar({
        regions: [
            { id: "status", icon: "bi-circle-fill", value: "Connected" },
            { id: "env", label: "Environment:", value: "Production" },
            { id: "user", label: "User:", value: "jsmith" },
            { id: "version", value: "v2.4.1" }
        ]
    });

    // Update a value dynamically
    bar.setValue("user", "adoe");

    // Read a value
    var user = bar.getValue("user"); // "adoe"

    // Get all text (including dividers)
    var text = bar.getAllText();
    // "Connected | Environment: Production | User: adoe | v2.4.1"
</script>

Configuration Options

Region Definition

Instance Methods

Size Variants

CSS Custom Property

When visible, the bar sets --statusbar-height on <html>. Other components can use:

.my-fixed-element {
    bottom: var(--statusbar-height, 0px);
}

Accessibility

• role="status" with aria-live="polite" for screen reader announcements.
• No user-select: none — all text is natively selectable.
• Light text on dark background meets WCAG AA contrast requirements.

Dependencies

• Bootstrap 5 CSS (for SCSS variables), Bootstrap Icons (optional), Enterprise Theme CSS.
• Does NOT require Bootstrap JS.

---

Multi-Stage Stepper (Wizard)

Linear or non-linear step progression UI for complex multi-step processes with validation gates, save-as-draft, step summary, and completion percentage.

Assets

Requirements

• Bootstrap CSS — SCSS variables and .btn-* classes
• Bootstrap Icons — step state icons (bi-check-lg, bi-exclamation-lg)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/stepper/stepper.css">
<script src="components/stepper/stepper.js"></script>
<script>
    var stepper = createStepper({
        container: document.getElementById("my-wizard"),
        steps: [
            { label: "Account", description: "Create your account", content: step1El },
            { label: "Profile", description: "Set up your profile", content: step2El },
            { label: "Confirm", description: "Review and submit", content: step3El }
        ],
        onFinish: function() { console.log("Done!"); }
    });
</script>

API

createStepper(options): StepperHandle

StepperOptions

StepConfig

StepperHandle

Step States

Keyboard

Accessibility

• Root: role="group", aria-label="Progress"
• Step indicator: <nav aria-label="Steps">
• Active step: aria-current="step"
• Content panes: role="tabpanel", aria-label

---

SymbolPicker

A grid-based symbol and icon picker for inserting Unicode characters and Bootstrap Icons. Includes categorized tabs, search filtering, recently-used tracking via localStorage, hover preview, and full keyboard navigation. Supports inline and popup display modes.

Purpose and Use Cases

• Rich text editors that need a special character insertion dialog
• Form fields that require symbol or icon selection
• Document formatting toolbars and Ribbon controls
• Any UI where users browse and insert symbols or icons from a categorized grid

Quick Start

Inline Mode

<!-- Dependencies -->
<link rel="stylesheet" href="css/custom.css">
<link rel="stylesheet" href="icons/bootstrap-icons.css">
<link rel="stylesheet" href="components/symbolpicker/symbolpicker.css">

<!-- Component -->
<div id="my-symbols"></div>
<script src="components/symbolpicker/symbolpicker.js"></script>
<script>
    createSymbolPicker("my-symbols", {
        inline: true,
        mode: "both",
        onInsert: (sym) => console.log("Inserted:", sym.char, sym.name)
    });
</script>

Popup Mode

<button id="sym-trigger">Insert Symbol</button>
<div id="sym-host"></div>
<script src="components/symbolpicker/symbolpicker.js"></script>
<script>
    createSymbolPicker("sym-host", {
        inline: false,
        triggerElement: document.getElementById("sym-trigger"),
        onInsert: (sym) => editor.insertText(sym.char)
    });
</script>

ES Module

import { createSymbolPicker } from "./components/symbolpicker/symbolpicker.js";

const picker = createSymbolPicker("my-symbols", {
    mode: "unicode",
    showRecent: true,
    onInsert: (sym) => insertCharacter(sym.char)
});

Configuration Options

SymbolItem

SymbolCategory

Instance Methods

Built-in Categories

Unicode Categories (~500 symbols)

Bootstrap Icons Categories (~200 icons)

Icon Auto-Discovery

The SymbolPicker automatically scans all loaded CSS stylesheets at initialization to discover available icons. This works for both Bootstrap Icons and Font Awesome icons.

How It Works

1. On first instantiation, the picker scans document.styleSheets for CSS rules matching .bi-*::before and .fa-*::before selectors.
2. Discovered icons are automatically categorized into heuristic groups (Arrows, Files, Communication, Media, People, Charts, Alerts, Technology, Commerce, Places, General).
3. Results are cached at the module level — subsequent picker instances reuse the cache.
4. If no icon stylesheets are detected (e.g., Bootstrap Icons CSS is not loaded), the picker falls back to the built-in curated set of ~178 icons.

Font Awesome Support

When Font Awesome CSS is loaded, the picker detects the available style class (fa-solid, fa-regular, fa-brands, fa-light, or fa-thin) by probing the DOM. Icons render with the correct style prefix automatically.

<!-- Load Font Awesome alongside Bootstrap Icons -->
<link rel="stylesheet" href="icons/bootstrap-icons.css">
<link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.5.0/css/all.min.css">

<script>
    // SymbolPicker will auto-discover both BI and FA icons
    createSymbolPicker("my-picker", { mode: "icons" });
</script>

Discovery Limitations

• Cross-origin stylesheets (e.g., CDN fonts without CORS headers) may not be scannable due to browser security restrictions. The picker handles this gracefully and skips inaccessible sheets.
• Discovery runs synchronously at construction time. Stylesheets loaded after the picker is created will not be included unless the cache is cleared.

Keyboard Interactions

Key bindings can be overridden via the keyBindings option using action names: moveLeft, moveRight, moveUp, moveDown, confirmInsert, closePopup, jumpToFirst, jumpToLast, focusSearch.

Recently Used

When showRecent: true (the default), the picker displays a "Recently Used" row above the category grid. Selections are persisted to localStorage under the key symbolpicker-recent. Configure the maximum count with maxRecent (default 20).

Size Variants

<script>createSymbolPicker("sm-picker", { inline: true, size: "sm" });</script>
<script>createSymbolPicker("default-picker", { inline: true });</script>
<script>createSymbolPicker("lg-picker", { inline: true, size: "lg" });</script>

Size classes applied: symbolpicker-sm, symbolpicker-lg.

Accessibility

• Trigger button has aria-haspopup="true", aria-expanded, and aria-label="Insert symbol"
• Mode tabs use role="tablist" with aria-label="Symbol mode" and aria-selected on each tab
• Category bar uses role="tablist" with aria-label="Symbol categories" and aria-selected per tab
• Symbol grid has aria-label="Symbol grid" for screen reader context
• Preview area uses aria-live="polite" to announce the selected symbol
• Search input has aria-label="Search symbols"
• Full keyboard navigation with arrow keys, Home, End, and Ctrl+F for search focus

Dependencies

---

TabbedPanel

A dockable, collapsible, resizable tabbed panel component for grouping related content into tabs. Supports docking to top/bottom viewport edges, free-positioned floating with drag-based positioning, collapsing to a 32px strip, resizing via drag handles, configurable tab bar position (top/left/bottom/right), and drag-to-dock with visual drop zones.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $font-size-*, etc.)
• Bootstrap Icons CSS — for tab icons and action buttons
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/tabbedpanel/tabbedpanel.css">
<script src="components/tabbedpanel/tabbedpanel.js"></script>
<script>
    var panel = createTabbedPanel({
        tabs: [
            { id: "terminal", title: "Terminal", icon: "bi-terminal" },
            { id: "output", title: "Output", icon: "bi-journal-text" },
            { id: "problems", title: "Problems", icon: "bi-exclamation-triangle" }
        ],
        dockPosition: "bottom",
        height: 250,
        onTabSelect: function(tabId) { console.log("Selected:", tabId); }
    });
</script>

Options

TabDefinition

interface TabDefinition {
    id: string;          // Unique tab identifier
    title: string;       // Display title
    icon?: string;       // Bootstrap Icons class (e.g., "bi-terminal")
    closable?: boolean;  // Show close button (default: false)
    content?: HTMLElement | string;  // Initial tab content
    cssClass?: string;   // Additional CSS class for the tab panel
    data?: Record<string, unknown>;  // User data passed to callbacks
    disabled?: boolean;  // Disabled state (default: false)
}

API

Tab Management

Mode & Position

Collapse

Size

Lifecycle

Convenience Functions

createTabbedPanel(options, container?)       // Create, show, and return
createDockedTabbedPanel(options, container?)  // Shorthand for docked mode
createFloatingTabbedPanel(options, container?) // Shorthand for floating mode

Global Exports

window.TabbedPanel
window.TabbedPanelManager
window.createTabbedPanel
window.createDockedTabbedPanel
window.createFloatingTabbedPanel

CSS Custom Properties

When docked, the panel sets a CSS custom property on <html>:

Properties are cleared when the panel is hidden or undocked.

Keyboard Accessibility

Examples

Docked bottom with icon-text tabs

var panel = createTabbedPanel({
    tabs: [
        { id: "terminal", title: "Terminal", icon: "bi-terminal" },
        { id: "output", title: "Output", icon: "bi-journal-text" },
        { id: "problems", title: "Problems", icon: "bi-exclamation-triangle", closable: true }
    ],
    dockPosition: "bottom",
    height: 250,
    onTabSelect: function(tabId) { console.log("Selected:", tabId); }
});
// Add content to a tab
var termEl = panel.getTabContentElement("terminal");
termEl.style.padding = "0.5rem";
termEl.textContent = "$ npm run build";

Floating panel with title bar

var props = createFloatingTabbedPanel({
    title: "Properties",
    tabs: [
        { id: "props", title: "Properties", icon: "bi-sliders" },
        { id: "events", title: "Events", icon: "bi-lightning" },
        { id: "styles", title: "Styles", icon: "bi-palette" }
    ],
    floatX: 400,
    floatY: 120,
    width: 360,
    height: 300
});

Dynamic tab management

// Add a tab at runtime
panel.addTab({
    id: "debug-console",
    title: "Debug Console",
    icon: "bi-bug",
    closable: true
});

// Prevent tab close with confirmation
var panel = createTabbedPanel({
    tabs: [ /* ... */ ],
    onTabClose: function(tabId) {
        return confirm("Close " + tabId + "?");
    }
});

// Remove a tab
panel.removeTab("debug-console");

Collapse and expand

panel.collapse();   // Collapse to 32px strip
panel.expand();     // Restore full size
panel.toggleCollapse();

panel.onCollapse = function(collapsed) {
    console.log(collapsed ? "Panel collapsed" : "Panel expanded");
};

Tab bar position variants

// Tab bar on the left (vertical)
createTabbedPanel({
    tabBarPosition: "left",
    tabTitleMode: "icon",
    tabs: [ /* ... */ ]
});

// Tab bar on the bottom
createTabbedPanel({
    tabBarPosition: "bottom",
    tabs: [ /* ... */ ]
});

Drag-to-dock

// Start floating, drag to top/bottom edge to dock
var panel = createFloatingTabbedPanel({
    title: "Dockable Panel",
    tabs: [ /* ... */ ],
    onModeChange: function(mode) {
        console.log("Mode changed to:", mode);
    }
});

See specs/tabbedpanel.prd.md for the complete specification.

---

Tagger

Combined freeform and controlled-vocabulary tag input with autocomplete, colored chips, taxonomy categories, and validation.

Quick Start

<link rel="stylesheet" href="components/tagger/tagger.css">
<script src="components/tagger/tagger.js"></script>
<script>
    var tagger = createTagger("my-container", {
        taxonomy: [
            { id: "priority", label: "Priority", color: "#c92a2a", values: ["High", "Medium", "Low"] },
            { id: "status", label: "Status", color: "#2b8a3e", values: ["Open", "Closed", "Pending"] }
        ],
        allowFreeform: true,
        onAdd: function(tag) { console.log("Added:", tag); },
        onRemove: function(tag) { console.log("Removed:", tag); }
    });
</script>

Assets

Requires: Bootstrap CSS, Bootstrap Icons CSS.

Options (TaggerOptions)

Interfaces

TagCategory

TagItem

API Methods

Color Modes

• category (default): Chips show a 3px left border using the category's colour. Freeform chips have no colour accent.
• hash: All chips get a deterministic colour based on a DJB2 hash of the tag value, mapped to a 12-colour palette.
• none: All chips use neutral grey styling with no colour accent.

Keyboard Interaction

Accessibility

• Container uses role="group" with aria-label
• Input uses role="combobox" with aria-expanded, aria-controls, aria-activedescendant
• Dropdown uses role="listbox" with role="option" items
• aria-live="polite" region announces tag add/remove/validation events
• Chip remove buttons have descriptive aria-label attributes

Size Variants

Paste Handling

Pasting comma-separated values (e.g., "tag1, tag2, tag3") automatically splits and adds each value through the validation pipeline.

Example: Full-Featured

<div id="full-tagger"></div>
<script>
    var tagger = createTagger("full-tagger", {
        tags: [
            { value: "High", category: "priority" },
            { value: "custom-label" }
        ],
        taxonomy: [
            { id: "priority", label: "Priority", color: "#c92a2a",
              values: ["Critical", "High", "Medium", "Low"], maxTags: 1 },
            { id: "type", label: "Type", color: "#1c7ed6",
              values: ["Bug", "Feature", "Enhancement", "Docs"] }
        ],
        maxTags: 10,
        allowFreeform: true,
        colorMode: "category",
        duplicateMode: "reject",
        size: "default",
        validator: function(v) {
            return v.length >= 2 || "Tag must be at least 2 characters";
        },
        onChange: function(tags) {
            console.log("Tags:", tags);
        }
    });
</script>

See specs/tagger.prd.md for the full specification.

---

ThemeToggle

Compact three-state theme switcher — Light, Auto (OS preference), and Dark. Sets data-bs-theme on <html> for Bootstrap 5 dark mode. Does not persist preferences; the host application controls storage via defaultTheme and the onChange callback.

Assets

Requirements

• Bootstrap Icons (for bi-sun, bi-circle-half, bi-moon-fill)
• Enterprise theme CSS (custom.css which includes dark-mode tokens)

Quick Start

<link rel="stylesheet" href="components/themetoggle/themetoggle.css">
<script src="components/themetoggle/themetoggle.js"></script>

<div id="theme-toggle"></div>

<script>
    var toggle = createThemeToggle({
        container: document.getElementById("theme-toggle"),
        defaultTheme: "auto",
        onChange: function(theme, mode) {
            console.log("Theme:", theme, "Mode:", mode);
            // Persist `mode` to localStorage, cookie, or server
        }
    });
</script>

FOUC Prevention

Place this inline script in <head> before any CSS to prevent a flash of unstyled content:

<script>
(function() {
    var mode = localStorage.getItem("theme-mode") || "auto";
    var dark = mode === "dark" ||
               (mode === "auto" && matchMedia("(prefers-color-scheme: dark)").matches);
    if (dark) document.documentElement.setAttribute("data-bs-theme", "dark");
})();
</script>

API

createThemeToggle(options): ThemeToggleHandle

ThemeToggleHandle

Keyboard

Accessibility

• Button group uses role="group" with aria-label="Theme switcher"
• Each button has aria-pressed and aria-label
• Focus ring visible via :focus-visible
• OS preference changes are detected in real-time when mode is "auto"

---

Timeline

A horizontal event timeline component for displaying point and span events along a time axis. Supports grouped rows, collapsible sections, viewport panning, a "now" marker, and item selection.

Features

• Point and span events -- circular markers for moments; horizontal bars for durations
• Grouped rows -- organise items into labelled, sortable groups
• Collapsible groups -- expand or collapse groups to manage visual density
• Viewport control -- set, pan, and query the visible date range programmatically
• Drag-to-pan -- drag left/right on the body or axis, Shift+wheel for fine panning
• Timezone support -- display labels in any IANA timezone; optional built-in selector
• Configurable tick intervals -- auto or explicit (5min, 10min, 15min, 30min, 1h, etc.)
• Now marker -- optional vertical line indicating the current time
• Item selection -- click or programmatic selection with change callbacks
• Size variants -- small, medium, and large density presets (sm, md, lg)
• Scrollable rows -- vertical scroll after a configurable maximum row count
• Full keyboard accessibility -- ARIA roles, roving tabindex, keyboard navigation
• Security -- all user-supplied text rendered via textContent; no innerHTML

Assets

Requires: Bootstrap CSS (for SCSS variables). Does not require Bootstrap JS or Bootstrap Icons.

Quick Start

<link rel="stylesheet" href="components/timeline/timeline.css">
<script src="components/timeline/timeline.js"></script>

<div id="my-timeline"></div>

<script>
    var timeline = createTimeline({
        containerId: "my-timeline",
        start: new Date("2026-01-01"),
        end: new Date("2026-12-31"),
        items: [
            {
                id: "release-1",
                type: "point",
                start: new Date("2026-03-15"),
                label: "v2.0 Release"
            },
            {
                id: "sprint-4",
                type: "span",
                start: new Date("2026-04-01"),
                end: new Date("2026-04-14"),
                label: "Sprint 4",
                color: "#2b8a3e"
            }
        ],
        onItemClick: function(item) { console.log("Clicked:", item.id); }
    });
</script>

API Reference

5.1 Types

type TimelineItemType = "point" | "span";
type TimelineSize = "sm" | "md" | "lg";
type TickIntervalPreset = "1min" | "5min" | "10min" | "15min" | "30min" | "1h" | "3h" | "6h" | "12h" | "1d";

5.2 TimelineItem Interface

5.3 TimelineGroup Interface

5.4 TimelineOptions Interface

5.5 Methods

Item API

Selection API

Group API

Viewport API

Timezone API

Tick Interval API

Lifecycle

Convenience Functions

createTimeline(options)    // Create, show, and return

Global Exports

window.Timeline
window.createTimeline

Examples

Grouped timeline with collapsible sections

var timeline = createTimeline({
    containerId: "project-timeline",
    start: new Date("2026-01-01"),
    end: new Date("2026-06-30"),
    groups: [
        { id: "backend", label: "Backend", order: 1 },
        { id: "frontend", label: "Frontend", order: 2 },
        { id: "milestones", label: "Milestones", order: 0, collapsible: false }
    ],
    items: [
        { id: "api", type: "span", start: new Date("2026-01-15"),
          end: new Date("2026-02-28"), label: "API Design", group: "backend" },
        { id: "ui", type: "span", start: new Date("2026-02-01"),
          end: new Date("2026-04-15"), label: "UI Build", group: "frontend", color: "#2b8a3e" },
        { id: "launch", type: "point", start: new Date("2026-05-01"),
          label: "Launch", group: "milestones", color: "#e67700" }
    ],
    showNowMarker: true,
    onGroupToggle: function(group, collapsed)
    {
        console.log(group.label, collapsed ? "collapsed" : "expanded");
    }
});

Dynamic item management

timeline.addItem({ id: "hotfix-1", type: "point", start: new Date("2026-03-10"), label: "Hotfix deployed" });

timeline.addItems([
    { id: "testing", type: "span", start: new Date("2026-03-01"),
      end: new Date("2026-03-14"), label: "QA Testing", group: "backend" },
    { id: "freeze", type: "point", start: new Date("2026-03-15"), label: "Code Freeze" }
]);

timeline.updateItem({ id: "hotfix-1", type: "point", start: new Date("2026-03-12"),
    label: "Hotfix (rescheduled)", color: "#dc3545" });

timeline.removeItem("hotfix-1");

Viewport control and selection

timeline.setViewport(new Date("2026-04-01"), new Date("2026-06-30"));
timeline.scrollToDate(new Date());
timeline.selectItem("sprint-4");
timeline.selectItem(null);

var vp = timeline.getViewport();
console.log("Showing:", vp.start, "to", vp.end);

Timezone and tick interval control

var timeline = createTimeline({
    containerId: "tz-timeline",
    start: new Date("2026-02-13T00:00:00Z"),
    end: new Date("2026-02-14T00:00:00Z"),
    timezone: "UTC",
    showTimezoneSelector: true,
    tickInterval: "1h",
    onTimezoneChange: function(tz) { console.log("Now showing:", tz); }
});

// Switch timezone programmatically
timeline.setTimezone("America/New_York");

// Change tick interval
timeline.setTickInterval("15min");
timeline.setTickInterval("auto");

Drag-to-pan

var timeline = createTimeline({
    containerId: "pan-timeline",
    start: new Date("2026-02-10"),
    end: new Date("2026-02-17"),
    pannable: true,
    onViewportChange: function(start, end)
    {
        console.log("Viewport:", start, "to", end);
    }
});

Drag left/right on the body or axis to scroll through time. Shift+mouse wheel also pans horizontally.

Callbacks for application integration

var timeline = createTimeline({
    containerId: "ops-timeline",
    start: new Date("2026-01-01"),
    end: new Date("2026-12-31"),
    onItemClick: function(item) { showDetailPanel(item.data); },
    onItemSelect: function(item) { item ? highlightRelated(item.id) : clearHighlights(); },
    onViewportChange: function(start, end)
    {
        fetchEventsForRange(start, end).then(function(events) { timeline.addItems(events); });
    },
    onItemVisible: function(items) { console.log(items.length, "items visible"); }
});

Accessibility

Security

The Timeline component applies the following measures to prevent cross-site scripting (XSS):

• All labels and tooltips are rendered using textContent only. User-supplied strings are never interpreted as HTML.
• No innerHTML is used anywhere in the component. All DOM construction uses createElement and textContent.
• Colour values are applied via inline style properties and are restricted to CSS colour syntax.
• The data field is opaque to the component and is never rendered into the DOM.

See specs/timeline.prd.md for the complete specification.

---

TimePicker

A time-of-day picker with spinner columns and optional timezone selector.

Quick Start

<link rel="stylesheet" href="https://theme.priyavijai-kalyan2007.workers.dev/components/timepicker/timepicker.css">
<script src="https://theme.priyavijai-kalyan2007.workers.dev/components/timepicker/timepicker.js"></script>

<div id="my-time"></div>
<script>
    var picker = createTimePicker("my-time", {
        clockMode: "24",
        showSeconds: true,
        onSelect: function(time) { console.log("Selected:", time); }
    });
</script>

Configuration Options

TimeValue Interface

interface TimeValue {
    hours: number;   // 0–23
    minutes: number; // 0–59
    seconds?: number; // 0–59
}

Instance Methods

Dependencies

• Bootstrap 5 CSS, Bootstrap Icons, Enterprise Theme CSS
• Intl API (for timezone support)

---

TimezonePicker

A searchable dropdown selector for IANA timezones with grouped regions, UTC offset display, and live current-time preview.

Quick Start

<link rel="stylesheet" href="components/timezonepicker/timezonepicker.css">
<script src="components/timezonepicker/timezonepicker.js"></script>

<div id="my-tz"></div>
<script>
    var picker = createTimezonePicker("my-tz", {
        timezone: "America/New_York",
        onSelect: function(tz) { console.log("Selected:", tz); }
    });
</script>

Configuration Options

Public API

Features

• Searchable dropdown with substring matching on timezone name and offset
• Grouped by region — Common timezones first, then Americas, Europe, Asia, Pacific, etc.
• Live time preview — Shows current time in the selected timezone, updated every second
• UTC offset display — Each timezone shows its current GMT offset
• Keyboard navigation — Arrow keys, Enter to select, Escape to close
• Accessible — WAI-ARIA combobox/listbox pattern

Keyboard Shortcuts

Dependencies

• Bootstrap CSS (input-group, form-control, btn)
• Bootstrap Icons CSS
• Does not require Bootstrap JS

---

Toast

A transient, non-blocking notification system with stacking, auto-dismiss, progress bar, and action support. Toasts appear at configurable viewport corners and stack newest-on-top.

Assets

Requirements

• Bootstrap CSS — for SCSS variables and .btn-* classes
• Bootstrap Icons — variant icons (bi-info-circle-fill, etc.)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/toast/toast.css">
<script src="components/toast/toast.js"></script>
<script>
    showSuccessToast("Changes saved successfully", "Saved");
    showErrorToast("Failed to save changes", "Error");

    showToast({
        message: "Item deleted",
        variant: "warning",
        actionLabel: "Undo",
        onAction: function() { console.log("Undo clicked"); }
    });
</script>

API

Global Functions

ToastOptions

ToastContainerOptions

Features

• Auto-dismiss with countdown progress bar
• Pause on hover (timer and animation pause)
• Queue management (excess toasts queued, promoted on dismiss)
• Four severity variants with auto-icons
• Action button support
• Keyboard: Escape dismisses focused toast
• prefers-reduced-motion support

Accessibility

• Container: role="region", aria-label="Notifications", aria-live="polite"
• Error toasts: role="alert" (assertive announcement)
• Other toasts: role="status" (polite announcement)
• Close button: aria-label="Dismiss notification"
• Progress bar: role="progressbar" with aria-valuenow/min/max

See specs/toast.prd.md for the complete specification.

---

Toolbar

A programmable action bar component for grouping tools and actions into labelled regions. Inspired by the Microsoft Office Ribbon but adapted to the enterprise Bootstrap 5 aesthetic — single strip, no tabs.

Features

• Docked or floating positioning with drag-to-dock snapping
• Horizontal or vertical orientation in either mode
• Regions — named groups of related tools separated by dividers
• Tool types — standard buttons, toggle buttons, split buttons, gallery controls
• Overflow — Priority+ algorithm collapses excess tools into inline dropdown menus (dual buttons for left/right region groups)
• KeyTips — Office-style keyboard shortcut badges revealed on Alt press
• Layout persistence — save and restore toolbar position, orientation, and state
• Resize — drag handle along the orientation axis
• Tooltips — Bootstrap 5 native tooltips on every tool
• Full keyboard accessibility — WAI-ARIA toolbar pattern with roving tabindex

Assets

Requires: Bootstrap CSS (for SCSS variables), Bootstrap Icons CSS, Bootstrap JS (optional, for tooltips). Does not require a JavaScript framework.

Quick Start

<link rel="stylesheet" href="components/toolbar/toolbar.css">
<script src="components/toolbar/toolbar.js"></script>
<script>
    var toolbar = createToolbar({
        label: "Document formatting",
        regions: [
            {
                id: "formatting",
                title: "Formatting",
                items: [
                    { id: "bold", icon: "bi-type-bold", tooltip: "Bold", toggle: true },
                    { id: "italic", icon: "bi-type-italic", tooltip: "Italic", toggle: true },
                    { type: "separator" },
                    { id: "align-left", icon: "bi-text-left", tooltip: "Align left" }
                ]
            }
        ]
    });
</script>

API

Constructor

const toolbar = new Toolbar(options: ToolbarOptions);

Creates the toolbar DOM but does not attach to the page.

ToolbarOptions

Methods

Convenience Functions

createToolbar(options)         // Create, show, and return
createDockedToolbar(options)   // Shorthand for docked mode
createFloatingToolbar(options) // Shorthand for floating mode

Global Exports

window.Toolbar
window.createToolbar
window.createDockedToolbar
window.createFloatingToolbar

Title

The toolbar can display a non-interactive title at the left edge (or top, in vertical orientation). Pass a string for text-only, or a ToolbarTitle object for full control.

// Text-only
createToolbar({ label: "My App", title: "My App", regions: [...] });

// Icon + text with custom colours
createToolbar({
    label: "My App",
    title: {
        text: "My App",
        icon: "bi-app",
        backgroundColor: "#1864ab",
        color: "#ffffff"
    },
    regions: [...]
});

ToolbarTitle

Use setTitle() to update or remove at runtime:

toolbar.setTitle({ text: "New Title", icon: "bi-star" });
toolbar.setTitle(null);  // remove

Region Alignment

Regions can be aligned to the left (default) or right side of the toolbar. Right-aligned regions are pushed to the trailing edge with flexible space between the two groups.

createToolbar({
    label: "My App",
    title: { text: "My App", icon: "bi-app", backgroundColor: "#1864ab", color: "#fff", width: "200px" },
    regions: [
        {
            id: "editing",
            title: "Editing",
            items: [
                { id: "cut", icon: "bi-scissors", tooltip: "Cut" },
                { id: "copy", icon: "bi-clipboard", tooltip: "Copy" },
                { id: "paste", icon: "bi-clipboard-check", tooltip: "Paste" }
            ]
        },
        {
            id: "user",
            title: "User",
            align: "right",
            items: [
                { id: "settings", icon: "bi-gear", tooltip: "Settings" },
                { id: "help", icon: "bi-question-circle", tooltip: "Help" }
            ]
        }
    ]
});

In vertical orientation, "left" maps to top and "right" maps to bottom.

ToolbarRegion

Tool Types

Standard Tool

{ id: "bold", icon: "bi-type-bold", tooltip: "Bold", toggle: true }

Split Button

{
    type: "split-button",
    id: "paste",
    icon: "bi-clipboard",
    tooltip: "Paste",
    menuItems: [
        { id: "paste-plain", icon: "bi-file-text", label: "Paste as plain text" },
        { id: "paste-special", icon: "bi-file-earmark-code", label: "Paste special" }
    ]
}

Gallery Control

{
    type: "gallery",
    id: "font-color",
    icon: "bi-palette",
    tooltip: "Font colour",
    layout: "grid",
    columns: 4,
    options: [
        { id: "red", label: "Red", color: "#dc2626" },
        { id: "blue", label: "Blue", color: "#1c7ed6" }
    ],
    onSelect: function(option, gallery) { console.log("Selected:", option.id); }
}

Input

{
    type: "input",
    id: "search",
    placeholder: "Search...",
    icon: "bi-search",
    width: "200px",
    onInput: function(value) { console.log("Searching:", value); },
    onSubmit: function(value) { console.log("Submit:", value); }
}

Dropdown

{
    type: "dropdown",
    id: "zoom",
    tooltip: "Zoom level",
    value: "100",
    width: "80px",
    options: [
        { value: "50", label: "50%" },
        { value: "100", label: "100%" },
        { value: "200", label: "200%" }
    ],
    onChange: function(value) { console.log("Zoom:", value); }
}

Label

{
    type: "label",
    id: "status",
    text: "Ready",
    icon: "bi-check-circle",
    color: "#40c057"
}

Separator

{ type: "separator" }

Checkbox

{
    type: "checkbox",
    id: "show-grid",
    label: "Show Grid",
    tooltip: "Toggle grid visibility",
    checked: true,
    onChange: function(checked) { console.log("Grid:", checked); }
}

Toggle Switch

{
    type: "switch",
    id: "live-preview",
    label: "Live Preview",
    tooltip: "Toggle live preview",
    checked: false,
    onChange: function(checked) { console.log("Preview:", checked); }
}

Number Spinner

{
    type: "number",
    id: "font-size",
    tooltip: "Font size",
    value: 14,
    min: 8,
    max: 72,
    step: 1,
    width: "80px",
    suffix: "px",
    onChange: function(value) { console.log("Size:", value); }
}

Color Picker

{
    type: "color",
    id: "fg-color",
    tooltip: "Foreground color",
    value: "#333333",
    showLabel: true,
    onChange: function(value) { console.log("Color:", value); },
    onInput: function(value) { /* live drag updates */ }
}

CSS Custom Properties

When docked, the toolbar sets a CSS custom property on <html>:

Properties are cleared when the toolbar is hidden or undocked.

Overflow

When tools exceed the available space, the Priority+ algorithm hides excess tools into a dropdown menu. The overflow button ("...") appears inline, right after the last visible tool in each group.

• Left-only regions: One overflow button at the end of the left group
• Left + right regions: Two independent overflow buttons — one per group, each showing only its group's hidden tools
• Priority order: always (always overflow) > low > high > never (never overflow)

Set overflowPriority on each tool to control which tools collapse first:

{ id: "cut", icon: "bi-scissors", tooltip: "Cut", overflowPriority: "never" }
{ id: "help", icon: "bi-question-circle", tooltip: "Help", overflowPriority: "low" }

Disable overflow with overflow: false in toolbar options.

Keyboard Accessibility

See specs/toolbar.prd.md for the complete specification.

---

ToolColorPicker

A visual colour picker that displays colours as tool icons (pens, markers, pencils, highlighters, brushes). Each colour renders as the tool icon filled with that colour. The tool shape is configurable at creation and runtime.

Usage

Row Layout (default)

<link rel="stylesheet" href="components/toolcolorpicker/toolcolorpicker.css">
<script src="components/toolcolorpicker/toolcolorpicker.js"></script>

<div id="my-color-picker"></div>

<script>
var picker = createToolColorPicker({
    container: "my-color-picker",
    tool: "pen",
    onChange: function(color) {
        console.log("Selected:", color.label, color.hex);
    }
});
</script>

Grid Layout

<div id="brush-colors"></div>

<script>
var picker = createToolColorPicker({
    container: "brush-colors",
    tool: "brush",
    colors: createToolColorPicker.BRUSH_COLORS,
    layout: "grid",
    gridColumns: 4,
    onChange: function(color) {
        console.log("Brush:", color.hex);
    }
});
</script>

Highlighter with Alpha

<div id="highlighter-picker"></div>

<script>
var picker = createToolColorPicker({
    container: "highlighter-picker",
    tool: "highlighter",
    colors: createToolColorPicker.HIGHLIGHTER_COLORS,
    onChange: function(color) {
        console.log("Highlight:", color.hex, "alpha:", color.alpha);
    }
});
</script>

Options

API

Built-in Color Packs

Access via static properties on the factory function:

Tool Icons

Each tool renders a distinct 24x36px SVG icon:

Keyboard

ToolColor Interface

interface ToolColor {
    hex: string;      // CSS hex colour
    label: string;    // Human-readable name
    alpha?: number;   // 0-1 opacity (default: 1)
}

---

TreeGrid

A highly configurable tree-grid hybrid component for displaying hierarchical data with multi-column tabular views. Supports expandable tree structure in the first column, inline cell editing, column sorting, resizing, drag-and-drop, context menu, virtual scrolling for large datasets, and full WAI-ARIA grid pattern keyboard navigation.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $primary, $font-size-*, etc.)
• Bootstrap Icons CSS — for tree toggle chevrons, column sort icons, and node icons
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/treegrid/treegrid.css">
<script src="components/treegrid/treegrid.js"></script>

<div id="my-grid" style="height: 400px"></div>

<script>
    var grid = createTreeGrid({
        containerId: "my-grid",
        label: "Project Files",
        nodes: [
            {
                id: "1",
                label: "src",
                icon: "bi-folder",
                data: { size: "4.2 MB", modified: "2026-02-10" },
                children: [
                    {
                        id: "2",
                        label: "main.ts",
                        icon: "bi-file-code",
                        data: { size: "1.5 KB", modified: "2026-02-12" }
                    },
                    {
                        id: "3",
                        label: "utils.ts",
                        icon: "bi-file-code",
                        data: { size: "890 B", modified: "2026-02-11" }
                    }
                ],
                expanded: true
            },
            {
                id: "4",
                label: "package.json",
                icon: "bi-filetype-json",
                data: { size: "512 B", modified: "2026-02-09" }
            }
        ],
        columns: [
            { id: "size", label: "Size", width: 100, sortable: true, align: "right" },
            { id: "modified", label: "Modified", width: 150, sortable: true }
        ],
        treeColumnLabel: "Name",
        treeColumnWidth: 250,
        stickyHeader: true,
        rowStriping: true,
        onRowSelect: function(node, selected) {
            console.log(node.label, selected ? "selected" : "deselected");
        }
    });
</script>

Options

Column Definition

Node Definition

Callbacks

Keyboard Navigation

Public API

Convenience Functions

Global Exports

When loaded via <script> tag:

• window.TreeGrid — TreeGrid class
• window.createTreeGrid — Factory function

Performance

The TreeGrid is optimized for large datasets with 1M+ total nodes:

• O(1) node lookups — internal nodeMap and parentMap for instant access
• Cached visible array — flat visible-row list rebuilt lazily on expand/collapse
• Virtual scrolling — renders only viewport + buffer rows (~200 DOM elements) instead of all visible rows
• Incremental DOM updates — addNode() and removeNode() update only affected rows

Virtual Scrolling

Virtual scrolling activates automatically when visible row count exceeds 5000, or can be forced via virtualScrolling: "enabled". In virtual mode, only visible rows are rendered in the DOM, with spacer elements maintaining scroll height.

Requirements:

• Fixed rowHeight (default: 32px). Variable-height rows are not supported.
• Custom renderer functions are supported and called during row recycling.

Large Dataset Example

var grid = createTreeGrid({
    containerId: "large-grid",
    label: "Enterprise Data",
    virtualScrolling: "auto",
    rowHeight: 32,
    scrollBuffer: 50,
    stickyHeader: true,
    nodes: largeDataSet,
    columns: [
        { id: "col1", label: "Column 1", sortable: true },
        { id: "col2", label: "Column 2", sortable: true }
    ],
    onLoadChildren: function(node) {
        return fetch("/api/children/" + node.id)
            .then(function(r) { return r.json(); });
    }
});

Examples

Lazy Loading Tree

var grid = createTreeGrid({
    containerId: "lazy-grid",
    label: "File System",
    nodes: [
        {
            id: "root",
            label: "C:\\",
            icon: "bi-hdd",
            data: { type: "Drive" },
            children: null,
            lazy: true
        }
    ],
    columns: [
        { id: "type", label: "Type", width: 100 },
        { id: "size", label: "Size", width: 100, align: "right" }
    ],
    treeColumnLabel: "Path",
    onLoadChildren: function(node) {
        return fetch("/api/fs/children?path=" + encodeURIComponent(node.id))
            .then(function(r) { return r.json(); });
    }
});

Inline Editing

var grid = createTreeGrid({
    containerId: "editable-grid",
    label: "Product Catalog",
    nodes: [
        {
            id: "1",
            label: "Electronics",
            icon: "bi-lightning",
            data: { stock: 150, price: 0 },
            children: [
                {
                    id: "2",
                    label: "Laptop",
                    icon: "bi-laptop",
                    data: { stock: 25, price: 1299.99 }
                },
                {
                    id: "3",
                    label: "Mouse",
                    icon: "bi-mouse",
                    data: { stock: 125, price: 29.99 }
                }
            ]
        }
    ],
    columns: [
        {
            id: "stock",
            label: "Stock",
            width: 100,
            editable: true,
            editorType: "number",
            align: "right"
        },
        {
            id: "price",
            label: "Price",
            width: 100,
            editable: true,
            editorType: "number",
            align: "right",
            renderer: function(cell, node, value) {
                if (typeof value === "number") {
                    cell.textContent = "$" + value.toFixed(2);
                }
            }
        }
    ],
    treeColumnLabel: "Category / Item",
    onEditCommit: function(node, column, oldValue, newValue) {
        console.log("Updated", node.label, column.id, "from", oldValue, "to", newValue);
        // Persist to server
        fetch("/api/products/" + node.id, {
            method: "PATCH",
            headers: { "Content-Type": "application/json" },
            body: JSON.stringify({ [column.id]: newValue })
        });
    }
});

Sortable Columns with Custom Renderer

var grid = createTreeGrid({
    containerId: "sorted-grid",
    label: "Team Members",
    nodes: [
        {
            id: "eng",
            label: "Engineering",
            icon: "bi-code-slash",
            data: { count: 12, budget: 1200000 },
            children: [
                { id: "e1", label: "Alice", data: { role: "Senior", salary: 125000 } },
                { id: "e2", label: "Bob", data: { role: "Junior", salary: 85000 } }
            ]
        },
        {
            id: "des",
            label: "Design",
            icon: "bi-palette",
            data: { count: 5, budget: 500000 },
            children: [
                { id: "d1", label: "Carol", data: { role: "Lead", salary: 110000 } }
            ]
        }
    ],
    columns: [
        {
            id: "role",
            label: "Role",
            width: 120,
            sortable: true
        },
        {
            id: "salary",
            label: "Salary",
            width: 120,
            sortable: true,
            align: "right",
            renderer: function(cell, node, value) {
                if (typeof value === "number") {
                    cell.textContent = "$" + value.toLocaleString();
                }
            }
        }
    ],
    treeColumnLabel: "Department / Name",
    rowStriping: true,
    onColumnSort: function(column, direction) {
        console.log("Sorting by", column.label, direction);
    }
});

Context Menu

var grid = createTreeGrid({
    containerId: "context-grid",
    label: "Project Tasks",
    enableContextMenu: true,
    contextMenuItems: [
        { id: "add-child", label: "Add Subtask", icon: "bi-plus-circle" },
        { id: "edit", label: "Edit", icon: "bi-pencil", shortcutHint: "F2" },
        { id: "sep1", label: "", separator: true },
        { id: "delete", label: "Delete", icon: "bi-trash" }
    ],
    nodes: [
        {
            id: "t1",
            label: "Phase 1",
            data: { status: "In Progress", due: "2026-03-01" },
            children: [
                { id: "t2", label: "Design mockups", data: { status: "Done", due: "2026-02-15" } }
            ]
        }
    ],
    columns: [
        { id: "status", label: "Status", width: 120, sortable: true },
        { id: "due", label: "Due Date", width: 120, sortable: true }
    ],
    treeColumnLabel: "Task",
    onContextMenuAction: function(actionId, node) {
        console.log("Action:", actionId, "on", node.label);
        if (actionId === "delete") {
            grid.removeNode(node.id);
        }
    }
});

Column Management

The TreeGrid supports runtime column management:

• Resize: Drag the handle between column headers (visible as a thin border). All columns are resizable by default (resizable: true).
• Reorder: When enableColumnReorder: true, drag column headers to rearrange them.
• Show/Hide: When showColumnPicker: true, click the gear icon in the header to toggle column visibility via checkboxes.
• Programmatic: Use updateColumn(id, { editable: false }), showColumn(id), hideColumn(id), or setColumns(newArray) for full control.

// Toggle a column's editability at runtime
grid.updateColumn("status", { editable: false });

// Change column width
grid.updateColumn("estimate", { width: 200 });

// Hide a column
grid.updateColumn("priority", { hidden: true });

Sorting

Columns with sortable: true support click-to-sort (ascending → descending → none). The built-in sort is type-aware: numbers are compared numerically, strings lexicographically (case-insensitive), and nulls sort to the end.

Per-Column Comparator

Override the default sort logic for a specific column:

columns: [
    {
        id: "estimate",
        label: "Est. Hours",
        sortable: true,
        comparator: function(a, b) {
            // Custom numeric comparison with null handling
            if (a == null && b == null) return 0;
            if (a == null) return 1;
            if (b == null) return -1;
            return Number(a) - Number(b);
        }
    }
]

External Sort (Server-Side)

When the application needs full control over sorting (e.g., server-side sort, complex multi-column sort), set externalSort: true. The grid updates sort indicators and fires the callback, but does not rearrange data:

var grid = createTreeGrid({
    containerId: "server-sorted-grid",
    label: "Server Data",
    externalSort: true,
    columns: [
        { id: "name", label: "Name", sortable: true },
        { id: "created", label: "Created", sortable: true }
    ],
    nodes: serverData,
    onColumnSort: function(column, direction) {
        // Application fetches sorted data from server
        fetch("/api/data?sort=" + column.id + "&dir=" + direction)
            .then(function(r) { return r.json(); })
            .then(function(sorted) {
                grid.setNodes(sorted);
                grid.refresh();
            });
    }
});

---

TreeView

A highly configurable, generic tree view component for representing multi-tree structured data. Supports lazy loading, multi-select (Ctrl+Click / Shift+Click), drag and drop (internal + cross-tree + external), context menu, inline rename (F2), search with mark highlighting, starred/favourites group, sort modes, extensible node types with badges, toolbar actions, and full WAI-ARIA tree pattern keyboard navigation.

Assets

Requirements

• Bootstrap CSS — for SCSS variables ($gray-*, $primary, $font-size-*, etc.)
• Bootstrap Icons CSS — for node icons, toggle chevrons, star icons, and toolbar buttons
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/treeview/treeview.css">
<script src="components/treeview/treeview.js"></script>

<div id="my-tree" style="height: 400px"></div>

<script>
    var tree = createTreeView({
        containerId: "my-tree",
        roots: [
            { id: "1", label: "Documents", kind: "folder", children: [
                { id: "2", label: "Report.pdf", kind: "leaf", icon: "bi-file-earmark-pdf" },
                { id: "3", label: "Notes.txt", kind: "leaf", icon: "bi-file-text" }
            ]},
            { id: "4", label: "Images", kind: "folder", children: [] }
        ],
        nodeTypes: {
            folder: { kind: "folder", icon: "bi-folder", isParent: true },
            leaf: { kind: "leaf", icon: "bi-file-earmark" }
        },
        onSelect: function(node, selected) {
            console.log(node.label, selected ? "selected" : "deselected");
        }
    });
</script>

Options

Callbacks

TreeNode Interface

Public API

Convenience Functions

Global Exports

When loaded via <script> tag:

• window.TreeView — TreeView class
• window.createTreeView — Factory function

Keyboard Navigation

Drag and Drop

Internal drag uses MIME type application/x-treeview with a JSON payload containing the source tree ID and node IDs, enabling cross-tree drag between multiple TreeView instances. External drops (files, URLs) are passed to onExternalDrop with the raw DataTransfer object.

Drop position is determined by mouse Y within the target row thirds: top third = "before", middle third = "inside" (parent nodes only), bottom third = "after".

Performance

The TreeView is optimized for trees with 1M+ total nodes:

• O(1) node lookups — internal nodeMap and parentMap replace recursive tree walks
• Cached visible array — flat visible-node list rebuilt lazily on expand/collapse, not per keystroke
• Virtual scrolling — renders only viewport + buffer rows (~200 DOM elements) instead of all visible nodes
• Incremental DOM updates — addNode() and removeNode() update only the affected DOM, not full rebuild
• Three-tier search — sync (< 5K nodes), chunked rAF (>= 5K), or server-side async via onSearchAsync

Virtual Scrolling

Virtual scrolling activates automatically when visible node count exceeds 5000, or can be forced via virtualScrolling: "enabled". In virtual mode, the tree uses a flat <div> structure with explicit aria-level instead of nested <ul>/<li>. DOM elements are recycled from a pool during scroll.

Requirements:

• Fixed rowHeight (default: 28px). Variable-height rows are not supported in virtual mode.
• Custom nodeRenderer is not compatible with virtual scrolling.

Large Tree Example

var tree = createTreeView({
    containerId: "large-tree",
    virtualScrolling: "auto",
    rowHeight: 28,
    scrollBuffer: 50,
    roots: largeDataSet,
    nodeTypes: { folder: { kind: "folder", icon: "bi-folder", isParent: true } },
    onSearchAsync: function(query) {
        return fetch("/api/search?q=" + encodeURIComponent(query))
            .then(function(r) { return r.json(); });
    }
});

Examples

Lazy Loading

var tree = createTreeView({
    containerId: "lazy-tree",
    roots: [
        { id: "root", label: "Projects", kind: "folder", children: null, lazy: true }
    ],
    nodeTypes: {
        folder: { kind: "folder", icon: "bi-folder", isParent: true }
    },
    onLoadChildren: function(node) {
        return fetch("/api/children/" + node.id)
            .then(function(r) { return r.json(); });
    }
});

Multi-Select with Starred

var tree = createTreeView({
    containerId: "starred-tree",
    selectionMode: "multi",
    showStarred: true,
    roots: myNodes,
    onStarToggle: function(node, starred) {
        console.log(node.label, starred ? "starred" : "unstarred");
    }
});

Context Menu

var tree = createTreeView({
    containerId: "ctx-tree",
    enableContextMenu: true,
    nodeTypes: {
        folder: {
            kind: "folder", icon: "bi-folder", isParent: true,
            contextMenuItems: [
                { id: "new-folder", label: "New Folder", icon: "bi-folder-plus" },
                { id: "rename", label: "Rename", shortcutHint: "F2" },
                { id: "sep", label: "", separator: true },
                { id: "delete", label: "Delete", icon: "bi-trash" }
            ]
        }
    },
    onContextMenuAction: function(actionId, node) {
        console.log("Action:", actionId, "on", node.label);
    }
});

---

TypeBadge

Small inline chip/badge that visually identifies an ontology type via icon, color, and label.

Usage

<link rel="stylesheet" href="components/typebadge/typebadge.css" />
<script src="components/typebadge/typebadge.js"></script>

const badge = createTypeBadge({
    typeKey: "strategy.okr",
    icon: "crosshair",
    color: "#C0392B",
    size: "sm",
    variant: "subtle"
});
document.getElementById("container").appendChild(badge);

Options

Sizes

• sm — 20px height, 11px font
• md — 28px height, 12px font
• lg — 32px height, 13px font

Variants

• filled — Solid background = type color, white text
• outlined — Transparent background, colored border and text
• subtle — 10% opacity background, colored text

Global

window.createTypeBadge(options)

---

UserMenu

Avatar-triggered dropdown menu for user account actions. Shows user avatar (image or initials), name, role, status dot, and a dropdown menu with grouped items, dividers, headers, and a sign-out action.

Assets

Quick Start

Include Assets

<link rel="stylesheet" href="components/usermenu/usermenu.css">
<script src="components/usermenu/usermenu.js"></script>

With Image Avatar

var menu = createUserMenu("my-container", {
    userName: "John Smith",
    userRole: "Administrator",
    avatarUrl: "/img/john.png",
    status: "online",
    menuItems: [
        { id: "settings", label: "Settings", icon: "bi-gear" },
        { id: "profile",  label: "Profile",  icon: "bi-person" },
        { id: "divider-1", label: "", type: "divider" },
        { id: "sign-out", label: "Sign Out", icon: "bi-box-arrow-right", danger: true },
    ],
    onItemClick: function(itemId) { console.log("Clicked:", itemId); },
    onSignOut: function() { console.log("Signing out"); },
});

With Initials Avatar

var menu = createUserMenu("my-container", {
    userName: "Jane Doe",
    userRole: "Developer",
    status: "busy",
    menuItems: [
        { id: "account-header", label: "Account", type: "header" },
        { id: "settings", label: "Settings", icon: "bi-gear" },
        { id: "profile",  label: "Profile",  icon: "bi-person" },
        { id: "divider-1", label: "", type: "divider" },
        { id: "help-header", label: "Help", type: "header" },
        { id: "docs",     label: "Documentation", icon: "bi-book" },
        { id: "support",  label: "Support",       icon: "bi-life-preserver" },
        { id: "divider-2", label: "", type: "divider" },
        { id: "sign-out", label: "Sign Out", icon: "bi-box-arrow-right", danger: true },
    ],
    onItemClick: function(itemId) { console.log("Clicked:", itemId); },
});

Programmatic Status Change

// Update status dot
menu.setStatus("away");

// Update name and role
menu.setUserName("John A. Smith");
menu.setUserRole("Senior Administrator");

// Switch to image avatar
menu.setAvatarUrl("/img/john-new.png");

// Replace menu items
menu.setMenuItems([
    { id: "settings", label: "Settings", icon: "bi-gear" },
    { id: "sign-out", label: "Sign Out", icon: "bi-box-arrow-right", danger: true },
]);

API

Factory Function

Public Methods

UserMenuOptions

UserMenuItem

Status Values

Keyboard Shortcuts

When Trigger is Focused

When Dropdown is Open

All key bindings can be overridden via the keyBindings option. See DEFAULT_KEY_BINDINGS in the source for action names.

Accessibility

• Trigger button has role button with aria-haspopup="menu" and aria-expanded
• Dropdown container has role="menu" with aria-label="User menu"
• Each actionable item has role="menuitem" with tabindex="-1"
• Disabled items have aria-disabled="true"
• Full keyboard navigation: Enter/Space to toggle, arrows to navigate, Escape to close
• Focus is managed programmatically: opening focuses the first item, closing returns focus to trigger
• Icon elements have aria-hidden="true" to prevent screen reader noise

---

VisualTableEditor

A compact, embeddable table component for editing and viewing styled tabular data. Unlike DataGrid (which targets data management with sorting, filtering, and pagination), VisualTableEditor is a visual-first component for presenting and editing cell-level styled tables -- analogous to table widgets in PowerPoint, Figma, draw.io, or Notion. Supports per-cell formatting, inline rich content (bold/italic/links/images), cell merging, presets, live aggregate summaries, undo/redo, and clipboard operations.

Assets

Requirements

• Bootstrap CSS -- for SCSS variables and theme support
• Bootstrap Icons -- toolbar icons (bi-type-bold, bi-table, etc.)
• InlineToolbar -- formatting toolbar (reused)
• ContextMenu -- right-click menu (reused)
• ColorPicker -- text/background colour dropdowns (reused)
• Does not require Bootstrap JS.

Quick Start

<link rel="stylesheet" href="components/visualtableeditor/visualtableeditor.css">
<script src="components/visualtableeditor/visualtableeditor.js"></script>
<script>
    var table = createVisualTableEditor({
        container: "#my-container",
        mode: "edit",
        preset: "blue-header",
        data: {
            columns: [
                { id: "name", width: 180, align: "left" },
                { id: "role", width: 140, align: "left" },
                { id: "status", width: 100, align: "center" }
            ],
            rows: [
                {
                    id: "hdr",
                    cells: {
                        name: { value: "Name", style: { bold: true } },
                        role: { value: "Role", style: { bold: true } },
                        status: { value: "Status", style: { bold: true } }
                    }
                },
                {
                    id: "r1",
                    cells: {
                        name: { value: "Alice Chen" },
                        role: { value: "Engineer" },
                        status: { value: "Active", style: { color: "#198754" } }
                    }
                }
            ]
        }
    });
</script>

API

Factory

function createVisualTableEditor(options: VisualTableEditorOptions): VisualTableEditor;

Options

Callbacks

Methods

Data Model

VisualTableData

VisualTableCell

VisualTableCellContent

Rich content segment for mixed formatting within a cell (e.g., "Total: **$1,250**").

VisualTableCellStyle

Example JSON

{
    "meta": { "headerRows": 1, "alternatingRows": true, "bordered": true },
    "columns": [
        { "id": "name", "width": 180 },
        { "id": "role", "width": 140 },
        { "id": "status", "width": 100, "align": "center" }
    ],
    "rows": [
        {
            "id": "hdr",
            "cells": {
                "name": { "value": "Name", "style": { "bold": true, "background": "#0d6efd", "color": "#fff" } },
                "role": { "value": "Role", "style": { "bold": true, "background": "#0d6efd", "color": "#fff" } },
                "status": { "value": "Status", "style": { "bold": true, "background": "#0d6efd", "color": "#fff" } }
            }
        },
        { "id": "r1", "cells": { "name": { "value": "Alice" }, "role": { "value": "Engineer" }, "status": { "value": "Active", "style": { "color": "#198754" } } } },
        { "id": "r2", "cells": { "name": { "value": "Bob" }, "role": { "value": "Designer" }, "status": { "value": "Away", "style": { "color": "#fd7e14" } } } }
    ]
}

Presets

Six built-in presets applied via applyPreset(name) or the preset option.

Presets set meta and header-row styles without overwriting per-cell overrides. The "minimal" and "striped" presets use CSS variables and adapt to dark mode automatically.

Aggregates

Live aggregate computations on the current selection, displayed in an optional summary bar.

Aggregates are unit-aware: only computed when all numeric cells share the same unit signature (e.g., all $-prefixed or all %-suffixed). Mixed units produce no result. Results reattach the unit prefix/suffix for display (e.g., Sum: $1,250).

Footer aggregate rows can be configured per-table or per-column. They are non-editable and recompute automatically on cell value changes.

Keyboard Shortcuts

Accessibility

• role="grid" on table, role="row", role="gridcell" on cells
• aria-colindex / aria-rowindex on cells
• aria-selected="true" on selected cells
• aria-readonly="false" in edit mode
• Roving tabindex for single Tab stop
• aria-label on the table element
• Sufficient contrast ratios on all default colours

Window Globals

See specs/visualtableeditor.prd.md for the complete specification.

---

WorkspaceSwitcher

Dropdown or modal control for switching between organisational workspaces and tenants.

Usage

<link rel="stylesheet" href="components/workspaceswitcher/workspaceswitcher.css">
<script src="components/workspaceswitcher/workspaceswitcher.js"></script>

const switcher = createWorkspaceSwitcher({
    workspaces: [
        { id: "1", name: "Acme Corp", icon: "bi-building", role: "Owner" },
        { id: "2", name: "Beta Industries", role: "Admin", memberCount: 8 },
        { id: "3", name: "Gamma Retail", avatarUrl: "/img/gamma.png", role: "Member" },
    ],
    activeWorkspaceId: "1",
    mode: "dropdown",
    onSwitch: (ws) => console.log("Switched to:", ws.name),
    onCreate: () => console.log("Create workspace"),
}, "my-container");

Options

API

Keyboard

---