@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/dist/patterns/versions/version-list.js

@@ -0,0 +1,407 @@
+import { orderVersionsForDisplay } from "./graph-layout.js";
+import { escapeHtml, STATUS_LABELS } from "./shared.js";
+import { isVersionNodeRecord, resolveVersionKind, resolveVersionStatus } from "./types.js";
+import { formatItemDate } from "../content-explorer/adapters/item-summary.js";
+import { BaseElement } from "../../core/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { boePanel, boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-version-list";
+const elementStyles = `
+        [hidden] {
+          display: none !important;
+        }
+
+        :host {
+          display: block;
+          color: inherit;
+          font: inherit;
+        }
+
+        section[part="panel"] {
+          display: grid;
+          gap: ${boePanel.gap};
+          padding: ${boePanel.padding};
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 82%, transparent);
+          border-radius: ${boePanel.radius};
+          background: ${boePanel.background};
+        }
+
+        [part="title"] {
+          margin: 0;
+          font: inherit;
+          font-size: 1.1rem;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="rows"] {
+          list-style: none;
+          margin: 0;
+          padding: 0;
+          display: grid;
+          gap: 0.45rem;
+        }
+
+        [part="row"] {
+          display: grid;
+          gap: 0.3rem;
+          padding: 0.55rem 0.6rem;
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 52%, transparent);
+          border-radius: ${boeRadius.large};
+          background: color-mix(in srgb, var(--boe-token-surface-surface, #ffffff) 82%, transparent);
+        }
+
+        [part="row"][data-status="current"] {
+          border-color: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 45%, transparent);
+        }
+
+        [part="row"][data-compare-selected="true"] {
+          background: var(--boe-token-surface-item-surface-selected, #f2f7fd);
+        }
+
+        [part="row-header"] {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          gap: 0.45rem;
+        }
+
+        [part="marker"] {
+          inline-size: 0.7rem;
+          block-size: 0.7rem;
+          border-radius: 999px;
+          border: 2px solid var(--boe-token-text-text-secondary, #6f6f6f);
+          background: transparent;
+        }
+
+        [part="marker"][data-kind="major"],
+        [part="marker"][data-kind="merge"] {
+          background: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="row"][data-status="current"] [part="marker"] {
+          border-color: var(--boe-token-surface-surface-brand, #0061d5);
+          background: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+
+        [part="marker"][data-kind="draft"] {
+          border-style: dashed;
+        }
+
+        [part="row-title"] {
+          appearance: none;
+          border: none;
+          background: transparent;
+          padding: 0;
+          font: inherit;
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+          text-align: left;
+          cursor: pointer;
+        }
+
+        [part="row-title"]:hover {
+          color: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+
+        [part="row-title"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
+          border-radius: ${boeRadius.med};
+        }
+
+        [part="status"] {
+          display: inline-flex;
+          padding: 0.14rem 0.45rem;
+          border-radius: 999px;
+          background: var(--boe-token-surface-item-surface-selected, #f2f7fd);
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-size: 0.74rem;
+          font-weight: 700;
+        }
+
+        [part="status"][data-status="current"] {
+          background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 14%, transparent);
+          color: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+
+        [part="status"][data-status="executed"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26c281) 16%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-success, #26c281) 52%, black 48%);
+        }
+
+        [part="status"][data-status="abandoned"] {
+          background: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 12%, transparent);
+          color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 74%, black 26%);
+        }
+
+        [part="meta"] {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          gap: 0.45rem;
+          font-size: 0.8rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="note"] {
+          margin: 0;
+          font-size: 0.84rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="row-actions"] {
+          display: flex;
+          flex-wrap: wrap;
+          gap: 0.4rem;
+        }
+
+        [part="row-action"] {
+          appearance: none;
+          font: inherit;
+          font-size: 0.76rem;
+          font-weight: 600;
+          padding: 0.26rem 0.6rem;
+          border-radius: 999px;
+          border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 60%, transparent);
+          background: var(--boe-token-surface-surface, #ffffff);
+          color: inherit;
+          cursor: pointer;
+          transition: background ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
+        }
+
+        [part="row-action"]:hover {
+          background: var(--boe-token-surface-surface-hover, #f4f4f4);
+        }
+
+        [part="row-action"][aria-pressed="true"] {
+          border-color: var(--boe-token-surface-surface-brand, #0061d5);
+          color: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+
+        [part="row-action"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 18%, transparent);
+        }
+
+        [part="empty"] {
+          padding: ${boePanel.padding};
+          border-radius: ${boeRadius.large};
+          border: 1px dashed color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 70%, transparent);
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+      `;
+/**
+ * The accessible core of the versions surface (CLM gap 5): a topologically
+ * ordered, newest-first version history with status tones, two-version
+ * compare pairing, and restore/promote surfaced as intent events for the
+ * host's confirm-before-apply flow. `box-version-graph` renders the same
+ * model as a git-style network; this list is the contract, the graph is
+ * progressive enhancement.
+ */
+export class VersionList extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["can-promote", "can-restore", "heading", "versions"];
+    }
+    versionsValue = [];
+    compareIds = [];
+    hostEl;
+    get heading() {
+        return this.getAttribute("heading") ?? "Version history";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    /** Enables the per-row Restore intent button (non-current rows). */
+    get canRestore() {
+        return this.hasAttribute("can-restore");
+    }
+    set canRestore(value) {
+        this.toggleAttribute("can-restore", value);
+    }
+    /** Enables the per-row Promote intent button (non-current rows). */
+    get canPromote() {
+        return this.hasAttribute("can-promote");
+    }
+    set canPromote(value) {
+        this.toggleAttribute("can-promote", value);
+    }
+    get versions() {
+        return this.versionsValue;
+    }
+    set versions(value) {
+        this.versionsValue = Array.isArray(value) ? value.filter(isVersionNodeRecord) : [];
+        this.pruneCompareSelection();
+        if (this.isRendered) {
+            this.update();
+        }
+    }
+    /** Ids currently toggled for compare, in selection order (max two). */
+    get compareSelection() {
+        return [...this.compareIds];
+    }
+    clearCompareSelection() {
+        this.compareIds = [];
+        if (this.isRendered) {
+            this.update();
+        }
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "versions") {
+            this.versionsValue = this.parseVersionsAttribute(newValue);
+            this.pruneCompareSelection();
+        }
+        super.attributeChangedCallback(name, oldValue, newValue);
+    }
+    parseVersionsAttribute(raw) {
+        if (!raw) {
+            return [];
+        }
+        try {
+            const parsed = JSON.parse(raw);
+            return Array.isArray(parsed) ? parsed.filter(isVersionNodeRecord) : [];
+        }
+        catch {
+            return [];
+        }
+    }
+    pruneCompareSelection() {
+        const known = new Set(this.versionsValue.map(node => node.id));
+        this.compareIds = this.compareIds.filter(id => known.has(id));
+    }
+    getVersion(id) {
+        return this.versionsValue.find(node => node.id === id);
+    }
+    toggleCompare(id) {
+        if (this.compareIds.includes(id)) {
+            this.compareIds = this.compareIds.filter(other => other !== id);
+        }
+        else {
+            this.compareIds = [...this.compareIds, id].slice(-2);
+        }
+        if (this.compareIds.length === 2) {
+            const ordered = orderVersionsForDisplay(this.versionsValue).map(node => node.id);
+            // Display order is newest first, so the later index is the older side.
+            const [a, b] = this.compareIds;
+            const older = ordered.indexOf(a) > ordered.indexOf(b) ? a : b;
+            const newer = older === a ? b : a;
+            this.dispatchEvent(new CustomEvent("compare-requested", {
+                bubbles: true,
+                composed: true,
+                detail: { baseId: older, targetId: newer },
+            }));
+        }
+        this.update();
+    }
+    rowHtml(node) {
+        const kind = resolveVersionKind(node.kind);
+        const status = resolveVersionStatus(node.status);
+        const isCurrent = status === "current";
+        const compareSelected = this.compareIds.includes(node.id);
+        const when = node.timestamp ? formatItemDate(node.timestamp) : "";
+        const actions = [
+            `<button type="button" part="row-action" data-action="compare" data-id="${escapeHtml(node.id)}" aria-pressed="${compareSelected ? "true" : "false"}">Compare</button>`,
+        ];
+        if (this.canRestore && !isCurrent) {
+            actions.push(`<button type="button" part="row-action" data-action="restore" data-id="${escapeHtml(node.id)}">Restore</button>`);
+        }
+        if (this.canPromote && !isCurrent) {
+            actions.push(`<button type="button" part="row-action" data-action="promote" data-id="${escapeHtml(node.id)}">Promote</button>`);
+        }
+        return `
+      <li part="row" data-id="${escapeHtml(node.id)}" data-kind="${kind}"${status ? ` data-status="${status}"` : ""} data-compare-selected="${compareSelected ? "true" : "false"}">
+        <div part="row-header">
+          <span part="marker" data-kind="${kind}" aria-hidden="true"></span>
+          <button type="button" part="row-title" data-id="${escapeHtml(node.id)}">${escapeHtml(node.label)}</button>
+          ${status ? `<span part="status" data-status="${status}">${STATUS_LABELS[status]}</span>` : ""}
+        </div>
+        <div part="meta">
+          ${node.actor ? `<span part="actor">${escapeHtml(node.actor.name)}</span>` : ""}
+          ${when ? `<time part="when" datetime="${escapeHtml(node.timestamp ?? "")}">${escapeHtml(when)}</time>` : ""}
+        </div>
+        ${node.note ? `<p part="note">${escapeHtml(node.note)}</p>` : ""}
+        <div part="row-actions">${actions.join("")}</div>
+      </li>
+    `;
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${elementStyles}</style>
+      <div part="content-host"></div>
+    `;
+        this.hostEl = this.shadowRoot.querySelector('[part="content-host"]');
+    }
+    setupListeners() {
+        this.hostEl.addEventListener("click", event => {
+            const target = event.target;
+            const actionButton = target.closest('[part="row-action"]');
+            if (actionButton && this.hostEl.contains(actionButton)) {
+                const id = actionButton.getAttribute("data-id") ?? "";
+                const action = actionButton.getAttribute("data-action") ?? "";
+                const version = this.getVersion(id);
+                if (!version) {
+                    return;
+                }
+                if (action === "compare") {
+                    this.toggleCompare(id);
+                }
+                else if (action === "restore" || action === "promote") {
+                    // Restore/promote mutate governed records — the host owns the
+                    // confirm-before-apply flow, so these only surface intent.
+                    this.dispatchEvent(new CustomEvent(`${action}-requested`, {
+                        bubbles: true,
+                        composed: true,
+                        detail: { version },
+                    }));
+                }
+                return;
+            }
+            const titleButton = target.closest('[part="row-title"]');
+            if (titleButton && this.hostEl.contains(titleButton)) {
+                const version = this.getVersion(titleButton.getAttribute("data-id") ?? "");
+                if (version) {
+                    this.dispatchEvent(new CustomEvent("version-selected", {
+                        bubbles: true,
+                        composed: true,
+                        detail: { version },
+                    }));
+                }
+            }
+        });
+    }
+    update() {
+        if (!this.hostEl) {
+            return;
+        }
+        const active = this.shadowRoot?.activeElement;
+        const focusKey = active && this.hostEl.contains(active)
+            ? {
+                part: active.getAttribute("part") ?? "",
+                id: active.getAttribute("data-id"),
+                action: active.getAttribute("data-action"),
+            }
+            : null;
+        const ordered = orderVersionsForDisplay(this.versionsValue);
+        this.hostEl.innerHTML = `
+      <section part="panel" aria-label="${escapeHtml(this.heading)}">
+        <h2 part="title">${escapeHtml(this.heading)}</h2>
+        ${ordered.length > 0
+            ? `<ol part="rows" role="list">${ordered.map(node => this.rowHtml(node)).join("")}</ol>`
+            : `<div part="empty">No versions.</div>`}
+      </section>
+    `;
+        if (focusKey?.part) {
+            const target = Array.from(this.hostEl.querySelectorAll(`[part="${focusKey.part}"]`)).find(node => node.getAttribute("data-id") === focusKey.id &&
+                (!focusKey.action || node.getAttribute("data-action") === focusKey.action));
+            // The rebuild removed the focused control's version (or its action):
+            // keep keyboard focus inside the component instead of dropping to body.
+            const fallback = this.hostEl.querySelector('[part="row-title"], [part="row-action"]');
+            (target ?? fallback)?.focus();
+        }
+    }
+}
+VersionList.register();

package/dist/patterns/work-queue/controller.d.ts

@@ -0,0 +1,26 @@
+import { Controller } from "../../core/controller.js";
+import type { WorkItem, WorkQueueEvents, WorkQueueFilters, WorkQueueSessionConfig, WorkQueueState } from "./types.js";
+/**
+ * Headless work-queue session shared by both projections (`box-work-queue`
+ * and `box-workload-board`): filtered loads with abort-superseded requests,
+ * and the four governed mutations (claim / reassign / complete / escalate)
+ * with reload-on-success — the transport owns the actual state transition.
+ */
+export declare class WorkQueueController extends Controller<WorkQueueState, WorkQueueEvents> {
+    readonly config: WorkQueueSessionConfig;
+    private activeLoadRequestId;
+    private activeLoadAbortController;
+    constructor(config: WorkQueueSessionConfig);
+    connect(): Promise<void>;
+    disconnect(): void;
+    /** Merge a filter patch (undefined values clear a filter) and reload. */
+    setFilters(patch: WorkQueueFilters): Promise<void>;
+    reload(): Promise<void>;
+    getItem(itemId: string): WorkItem | undefined;
+    /** Claim an item for `assigneeId` (typically the current user). */
+    claimItem(itemId: string, assigneeId: string): Promise<WorkItem | null>;
+    reassignItem(itemId: string, assigneeId: string): Promise<WorkItem | null>;
+    completeItem(itemId: string): Promise<WorkItem | null>;
+    escalateItem(itemId: string, reason?: string): Promise<WorkItem | null>;
+    private runMutation;
+}

package/dist/patterns/work-queue/controller.js

@@ -0,0 +1,150 @@
+import { Controller } from "../../core/controller.js";
+const createInitialState = (config) => ({
+    connected: false,
+    loading: false,
+    items: [],
+    filters: { ...(config.filters ?? {}) },
+    error: null,
+});
+/**
+ * Headless work-queue session shared by both projections (`box-work-queue`
+ * and `box-workload-board`): filtered loads with abort-superseded requests,
+ * and the four governed mutations (claim / reassign / complete / escalate)
+ * with reload-on-success — the transport owns the actual state transition.
+ */
+export class WorkQueueController extends Controller {
+    config;
+    activeLoadRequestId = 0;
+    activeLoadAbortController = null;
+    constructor(config) {
+        super(createInitialState(config));
+        this.config = config;
+    }
+    async connect() {
+        if (this.state.connected) {
+            return;
+        }
+        this.setState({ ...this.state, connected: true });
+        this.emit("connected", undefined);
+        await this.reload();
+    }
+    disconnect() {
+        if (!this.state.connected) {
+            return;
+        }
+        this.activeLoadRequestId += 1;
+        this.activeLoadAbortController?.abort();
+        this.activeLoadAbortController = null;
+        this.setState(createInitialState(this.config));
+        this.emit("disconnected", undefined);
+    }
+    /** Merge a filter patch (undefined values clear a filter) and reload. */
+    async setFilters(patch) {
+        const filters = { ...this.state.filters };
+        for (const [key, value] of Object.entries(patch)) {
+            if (value === undefined) {
+                delete filters[key];
+            }
+            else {
+                filters[key] = value;
+            }
+        }
+        this.setState({ ...this.state, filters });
+        this.emit("filtersChanged", { filters });
+        if (this.state.connected) {
+            await this.reload();
+        }
+    }
+    async reload() {
+        if (!this.state.connected) {
+            return;
+        }
+        const requestId = this.activeLoadRequestId + 1;
+        this.activeLoadRequestId = requestId;
+        this.activeLoadAbortController?.abort();
+        const abortController = typeof AbortController === "function" ? new AbortController() : null;
+        this.activeLoadAbortController = abortController;
+        this.setState({ ...this.state, loading: true, error: null });
+        this.emit("loadingChanged", { loading: true });
+        try {
+            const result = await this.config.transport.loadItems({
+                filters: this.state.filters,
+                token: this.config.token,
+                ...(abortController ? { signal: abortController.signal } : {}),
+            });
+            if (requestId !== this.activeLoadRequestId) {
+                return;
+            }
+            this.setState({ ...this.state, items: result.items, loading: false });
+            this.emit("loadingChanged", { loading: false });
+            this.emit("itemsChanged", { items: result.items });
+        }
+        catch (error) {
+            if (requestId !== this.activeLoadRequestId) {
+                return;
+            }
+            const message = error instanceof Error ? error.message : "Failed to load work items";
+            this.setState({ ...this.state, loading: false, error: message });
+            this.emit("loadingChanged", { loading: false });
+            this.emit("loadFailed", { message });
+        }
+        finally {
+            if (this.activeLoadAbortController === abortController) {
+                this.activeLoadAbortController = null;
+            }
+        }
+    }
+    getItem(itemId) {
+        return this.state.items.find(item => item.id === itemId);
+    }
+    /** Claim an item for `assigneeId` (typically the current user). */
+    async claimItem(itemId, assigneeId) {
+        const transport = this.config.transport;
+        if (!transport.claimItem) {
+            throw new Error("Work-queue transport does not support claim");
+        }
+        // Called on the transport so class-based implementations keep `this`.
+        return this.runMutation("claim", itemId, () => transport.claimItem({ itemId, assigneeId, token: this.config.token }));
+    }
+    async reassignItem(itemId, assigneeId) {
+        const transport = this.config.transport;
+        if (!transport.reassignItem) {
+            throw new Error("Work-queue transport does not support reassign");
+        }
+        // Called on the transport so class-based implementations keep `this`.
+        return this.runMutation("reassign", itemId, () => transport.reassignItem({ itemId, assigneeId, token: this.config.token }));
+    }
+    async completeItem(itemId) {
+        const transport = this.config.transport;
+        if (!transport.completeItem) {
+            throw new Error("Work-queue transport does not support complete");
+        }
+        // Called on the transport so class-based implementations keep `this`.
+        return this.runMutation("complete", itemId, () => transport.completeItem({ itemId, token: this.config.token }));
+    }
+    async escalateItem(itemId, reason) {
+        const transport = this.config.transport;
+        if (!transport.escalateItem) {
+            throw new Error("Work-queue transport does not support escalate");
+        }
+        // Called on the transport so class-based implementations keep `this`.
+        return this.runMutation("escalate", itemId, () => transport.escalateItem({ itemId, reason, token: this.config.token }));
+    }
+    async runMutation(kind, itemId, perform) {
+        if (!this.state.connected || !this.getItem(itemId)) {
+            return null;
+        }
+        try {
+            const item = await perform();
+            this.emit("itemMutated", { kind, item });
+            await this.reload();
+            return item;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : `Work-queue ${kind} failed`;
+            this.setState({ ...this.state, error: message });
+            this.emit("mutationFailed", { kind, itemId, message });
+            return null;
+        }
+    }
+}

package/dist/patterns/work-queue/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./controller.js";
+export * from "./work-queue.js";
+export * from "./workload-board.js";

package/dist/patterns/work-queue/index.js

@@ -0,0 +1,7 @@
+// Work-item model, transport contract, buckets, and workload summaries
+export * from "./types.js";
+// Headless queue session shared by both projections
+export * from "./controller.js";
+// Composed surfaces: individual triage list + supervisor board
+export * from "./work-queue.js";
+export * from "./workload-board.js";