@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/dist/patterns/versions/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./types.js";
+export * from "./graph-layout.js";
+export * from "./version-list.js";
+export * from "./version-graph.js";

package/dist/patterns/versions/index.js

@@ -0,0 +1,8 @@
+// Version model + validation
+export * from "./types.js";
+// Pure git-network layout engine (shared with future lineage graphs)
+export * from "./graph-layout.js";
+// Accessible core contract
+export * from "./version-list.js";
+// Git-style visualization layer
+export * from "./version-graph.js";

package/dist/patterns/versions/shared.d.ts

@@ -0,0 +1,4 @@
+import type { VersionStatus } from "./types.js";
+/** Internal to the versions pattern — not part of the public barrel. */
+export declare const escapeHtml: (value: string) => string;
+export declare const STATUS_LABELS: Record<VersionStatus, string>;

package/dist/patterns/versions/shared.js

@@ -0,0 +1,13 @@
+/** Internal to the versions pattern — not part of the public barrel. */
+export const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+export const STATUS_LABELS = {
+    current: "Current",
+    executed: "Executed",
+    superseded: "Superseded",
+    abandoned: "Abandoned",
+};

package/dist/patterns/versions/types.d.ts

@@ -0,0 +1,37 @@
+/** Node emphasis in the version tree: majors are milestones, merges close branches. */
+export type VersionKind = "major" | "minor" | "merge" | "draft";
+/** Lifecycle status; rendered as tone on both projections. */
+export type VersionStatus = "current" | "executed" | "superseded" | "abandoned";
+export interface VersionActor {
+    name: string;
+    initials?: string;
+}
+/**
+ * One version in a branch/merge history. `parents` carries the topology the
+ * way git does: a root has none, a branch point has many children, and a
+ * merge node lists more than one parent. Hosts list nodes in creation order —
+ * that order (not timestamps) breaks topological ties.
+ */
+export interface VersionNode {
+    id: string;
+    /** Short display name: "v2.0", "Redline r2". */
+    label: string;
+    /** Ids of the versions this one was derived from. Empty/absent = root. */
+    parents?: string[];
+    kind?: VersionKind;
+    status?: VersionStatus;
+    actor?: VersionActor;
+    /** ISO timestamp; display only — `parents` defines the topology. */
+    timestamp?: string;
+    /** One-line description under the label. */
+    note?: string;
+}
+/** Detail payload for `compare-requested`; `baseId` is the older side. */
+export interface VersionCompareDetail {
+    baseId: string;
+    targetId: string;
+}
+export declare const resolveVersionKind: (value: string | null | undefined) => VersionKind;
+export declare const resolveVersionStatus: (value: string | null | undefined) => VersionStatus | null;
+/** Attribute payloads are author input — validate every record, not just the array. */
+export declare const isVersionNodeRecord: (value: unknown) => value is VersionNode;

package/dist/patterns/versions/types.js

@@ -0,0 +1,39 @@
+const KINDS = new Set(["major", "minor", "merge", "draft"]);
+const STATUSES = new Set(["current", "executed", "superseded", "abandoned"]);
+export const resolveVersionKind = (value) => value && KINDS.has(value) ? value : "minor";
+export const resolveVersionStatus = (value) => value && STATUSES.has(value) ? value : null;
+/** Attribute payloads are author input — validate every record, not just the array. */
+export const isVersionNodeRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const node = value;
+    if (typeof node.id !== "string" || node.id.length === 0 || typeof node.label !== "string") {
+        return false;
+    }
+    if (node.parents !== undefined) {
+        if (!Array.isArray(node.parents)) {
+            return false;
+        }
+        for (const parent of node.parents) {
+            if (typeof parent !== "string") {
+                return false;
+            }
+        }
+    }
+    for (const field of ["kind", "status", "timestamp", "note"]) {
+        if (node[field] !== undefined && typeof node[field] !== "string") {
+            return false;
+        }
+    }
+    if (node.actor !== undefined) {
+        const actor = node.actor;
+        if (typeof actor !== "object" || actor === null || typeof actor.name !== "string") {
+            return false;
+        }
+        if (actor.initials !== undefined && typeof actor.initials !== "string") {
+            return false;
+        }
+    }
+    return true;
+};

package/dist/patterns/versions/version-graph.d.ts

@@ -0,0 +1,36 @@
+import type { VersionNode } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * Git-network rendering of a version history (opportunity 4): lanes and
+ * branch/merge curves from the pure `computeVersionGraphLayout`, with one
+ * HTML button per node so activation, focus, and compare selection stay
+ * native. Click emits `version-selected`; a modified click (Shift/Ctrl/Meta)
+ * or the `toggleCompare` method pairs two nodes into `compare-requested`.
+ * `box-version-list` renders the same model as the accessible table-style
+ * fallback — pair them when the graph is the primary surface.
+ */
+export declare class VersionGraph extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private versionsValue;
+    private compareIds;
+    private rovingId;
+    private hostEl;
+    get heading(): string;
+    set heading(value: string);
+    get versions(): VersionNode[];
+    set versions(value: VersionNode[]);
+    /** Ids currently toggled for compare, in selection order (max two). */
+    get compareSelection(): string[];
+    clearCompareSelection(): void;
+    /** Toggle a node in the compare pair; two toggled nodes emit `compare-requested`. */
+    toggleCompare(id: string): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private parseVersionsAttribute;
+    private pruneSelection;
+    private getVersion;
+    private nodeButtons;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}

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

@@ -0,0 +1,438 @@
+import { computeVersionGraphLayout, 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 { boePanel, boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-version-graph";
+const LANE_WIDTH = 26;
+const ROW_HEIGHT = 46;
+const EDGE_PAD = 8;
+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="graph"] {
+          position: relative;
+          overflow-x: auto;
+        }
+
+        [part="edges"] {
+          position: absolute;
+          inset-block-start: 0;
+          inset-inline-start: 0;
+          pointer-events: none;
+        }
+
+        [part="edge"] {
+          fill: none;
+          stroke: color-mix(in srgb, var(--boe-token-text-text-secondary, #6f6f6f) 55%, transparent);
+          stroke-width: 2;
+        }
+
+        [part="rows"] {
+          list-style: none;
+          margin: 0;
+          padding: 0;
+          position: relative;
+        }
+
+        [part="row"] {
+          position: relative;
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          gap: 0.45rem;
+          block-size: ${ROW_HEIGHT}px;
+          border-radius: ${boeRadius.med};
+        }
+
+        [part="row"][data-compare-selected="true"] {
+          background: var(--boe-token-surface-item-surface-selected, #f2f7fd);
+        }
+
+        [part="node"] {
+          position: absolute;
+          inset-block-start: 50%;
+          transform: translate(-50%, -50%);
+          appearance: none;
+          padding: 0;
+          inline-size: 0.85rem;
+          block-size: 0.85rem;
+          border-radius: 999px;
+          border: 2px solid var(--boe-token-text-text-secondary, #6f6f6f);
+          background: var(--boe-token-surface-surface, #ffffff);
+          cursor: pointer;
+        }
+
+        [part="node"][data-kind="major"],
+        [part="node"][data-kind="merge"] {
+          background: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [part="node"][data-kind="major"] {
+          inline-size: 1.05rem;
+          block-size: 1.05rem;
+        }
+
+        [part="node"][data-kind="draft"] {
+          border-style: dashed;
+        }
+
+        [part="node"][data-status="current"] {
+          border-color: var(--boe-token-surface-surface-brand, #0061d5);
+          background: var(--boe-token-surface-surface-brand, #0061d5);
+        }
+
+        [part="node"][data-status="executed"] {
+          border-color: var(--boe-token-surface-status-surface-success, #26c281);
+          background: var(--boe-token-surface-status-surface-success, #26c281);
+        }
+
+        [part="node"][data-status="abandoned"] {
+          border-color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 70%, transparent);
+          background: transparent;
+        }
+
+        [part="node"][data-compare-selected="true"] {
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 30%, transparent);
+        }
+
+        [part="node"]:focus-visible {
+          outline: none;
+          box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 45%, transparent);
+        }
+
+        [part="row-label"] {
+          font-weight: 700;
+          color: var(--boe-token-text-text, #1f1e1b);
+        }
+
+        [part="row"][data-kind="minor"] [part="row-label"],
+        [part="row"][data-kind="draft"] [part="row-label"] {
+          font-weight: 600;
+          font-size: 0.9rem;
+        }
+
+        [part="status"] {
+          display: inline-flex;
+          padding: 0.1rem 0.4rem;
+          border-radius: 999px;
+          background: var(--boe-token-surface-item-surface-selected, #f2f7fd);
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+          font-size: 0.72rem;
+          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="row-meta"] {
+          font-size: 0.78rem;
+          color: var(--boe-token-text-text-secondary, #6f6f6f);
+        }
+
+        [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);
+        }
+      `;
+/**
+ * Git-network rendering of a version history (opportunity 4): lanes and
+ * branch/merge curves from the pure `computeVersionGraphLayout`, with one
+ * HTML button per node so activation, focus, and compare selection stay
+ * native. Click emits `version-selected`; a modified click (Shift/Ctrl/Meta)
+ * or the `toggleCompare` method pairs two nodes into `compare-requested`.
+ * `box-version-list` renders the same model as the accessible table-style
+ * fallback — pair them when the graph is the primary surface.
+ */
+export class VersionGraph extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
+    static get observedAttributes() {
+        return ["heading", "versions"];
+    }
+    versionsValue = [];
+    compareIds = [];
+    rovingId = null;
+    hostEl;
+    get heading() {
+        return this.getAttribute("heading") ?? "Version graph";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    get versions() {
+        return this.versionsValue;
+    }
+    set versions(value) {
+        this.versionsValue = Array.isArray(value) ? value.filter(isVersionNodeRecord) : [];
+        this.pruneSelection();
+        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();
+        }
+    }
+    /** Toggle a node in the compare pair; two toggled nodes emit `compare-requested`. */
+    toggleCompare(id) {
+        if (!this.versionsValue.some(node => node.id === id)) {
+            return;
+        }
+        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);
+            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 },
+            }));
+        }
+        if (this.isRendered) {
+            this.update();
+        }
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (name === "versions") {
+            this.versionsValue = this.parseVersionsAttribute(newValue);
+            this.pruneSelection();
+        }
+        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 [];
+        }
+    }
+    pruneSelection() {
+        const known = new Set(this.versionsValue.map(node => node.id));
+        this.compareIds = this.compareIds.filter(id => known.has(id));
+        if (this.rovingId && !known.has(this.rovingId)) {
+            this.rovingId = null;
+        }
+    }
+    getVersion(id) {
+        return this.versionsValue.find(node => node.id === id);
+    }
+    nodeButtons() {
+        return Array.from(this.hostEl.querySelectorAll('[part="node"]'));
+    }
+    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 nodeButton = target.closest('[part="node"]');
+            if (!nodeButton || !this.hostEl.contains(nodeButton)) {
+                return;
+            }
+            const id = nodeButton.getAttribute("data-id") ?? "";
+            const version = this.getVersion(id);
+            if (!version) {
+                return;
+            }
+            this.rovingId = id;
+            if (event.shiftKey || event.ctrlKey || event.metaKey) {
+                this.toggleCompare(id);
+                return;
+            }
+            this.dispatchEvent(new CustomEvent("version-selected", {
+                bubbles: true,
+                composed: true,
+                detail: { version },
+            }));
+        });
+        this.hostEl.addEventListener("keydown", event => {
+            const target = event.target;
+            if (target.getAttribute("part") !== "node") {
+                return;
+            }
+            const buttons = this.nodeButtons();
+            const index = buttons.indexOf(target);
+            if (index === -1) {
+                return;
+            }
+            let next = null;
+            if (event.key === "ArrowDown") {
+                next = Math.min(index + 1, buttons.length - 1);
+            }
+            else if (event.key === "ArrowUp") {
+                next = Math.max(index - 1, 0);
+            }
+            else if (event.key === "Home") {
+                next = 0;
+            }
+            else if (event.key === "End") {
+                next = buttons.length - 1;
+            }
+            if (next === null || next === index) {
+                return;
+            }
+            event.preventDefault();
+            const button = buttons[next];
+            this.rovingId = button.getAttribute("data-id");
+            for (const other of buttons) {
+                other.tabIndex = other === button ? 0 : -1;
+            }
+            button.focus();
+        });
+    }
+    update() {
+        if (!this.hostEl) {
+            return;
+        }
+        const active = this.shadowRoot?.activeElement;
+        const focusedId = active && this.hostEl.contains(active) && active.getAttribute("part") === "node"
+            ? active.getAttribute("data-id")
+            : null;
+        const layout = computeVersionGraphLayout(this.versionsValue);
+        const byId = new Map(this.versionsValue.map(node => [node.id, node]));
+        const graphWidth = EDGE_PAD * 2 + layout.laneCount * LANE_WIDTH;
+        const graphHeight = layout.rowCount * ROW_HEIGHT;
+        const centerX = (lane) => EDGE_PAD + lane * LANE_WIDTH + LANE_WIDTH / 2;
+        const centerY = (row) => row * ROW_HEIGHT + ROW_HEIGHT / 2;
+        const edgePaths = layout.edges
+            .map(edge => {
+            const x1 = centerX(edge.fromLane);
+            const y1 = centerY(edge.fromRow);
+            const x2 = centerX(edge.toLane);
+            const y2 = centerY(edge.toRow);
+            const d = edge.fromLane === edge.toLane
+                ? `M ${x1} ${y1} L ${x2} ${y2}`
+                : `M ${x1} ${y1} C ${x1} ${y1 - ROW_HEIGHT / 2}, ${x2} ${y2 + ROW_HEIGHT / 2}, ${x2} ${y2}`;
+            return `<path part="edge" data-from="${escapeHtml(edge.fromId)}" data-to="${escapeHtml(edge.toId)}" d="${d}"></path>`;
+        })
+            .join("");
+        const rovingId = this.rovingId && byId.has(this.rovingId)
+            ? this.rovingId
+            : (layout.placements[0]?.id ?? null);
+        const rows = layout.placements
+            .map(placement => {
+            const node = byId.get(placement.id);
+            const kind = resolveVersionKind(node.kind);
+            const status = resolveVersionStatus(node.status);
+            const compareSelected = this.compareIds.includes(node.id);
+            const when = node.timestamp ? formatItemDate(node.timestamp) : "";
+            const ariaLabel = [
+                node.label,
+                kind,
+                status ? STATUS_LABELS[status] : "",
+                node.actor?.name ?? "",
+                compareSelected ? "selected for comparison" : "",
+            ]
+                .filter(Boolean)
+                .join(", ");
+            return `
+          <li part="row" data-id="${escapeHtml(node.id)}" data-kind="${kind}"${status ? ` data-status="${status}"` : ""} data-compare-selected="${compareSelected ? "true" : "false"}" style="padding-inline-start: ${String(graphWidth + 10)}px;">
+            <button
+              type="button"
+              part="node"
+              data-id="${escapeHtml(node.id)}"
+              data-kind="${kind}"
+              ${status ? `data-status="${status}"` : ""}
+              data-compare-selected="${compareSelected ? "true" : "false"}"
+              tabindex="${node.id === rovingId ? "0" : "-1"}"
+              aria-label="${escapeHtml(ariaLabel)}"
+              style="inset-inline-start: ${String(centerX(placement.lane))}px;"
+            ></button>
+            <span part="row-label">${escapeHtml(node.label)}</span>
+            ${status ? `<span part="status" data-status="${status}">${STATUS_LABELS[status]}</span>` : ""}
+            <span part="row-meta">${[node.actor?.name, when].filter(Boolean).map(text => escapeHtml(text)).join(" · ")}</span>
+          </li>
+        `;
+        })
+            .join("");
+        this.hostEl.innerHTML = `
+      <section part="panel" aria-label="${escapeHtml(this.heading)}">
+        <h2 part="title">${escapeHtml(this.heading)}</h2>
+        ${layout.placements.length > 0
+            ? `
+              <div part="graph">
+                <svg part="edges" width="${String(graphWidth)}" height="${String(graphHeight)}" viewBox="0 0 ${String(graphWidth)} ${String(graphHeight)}" aria-hidden="true">${edgePaths}</svg>
+                <ol part="rows" role="list">${rows}</ol>
+              </div>
+            `
+            : `<div part="empty">No versions.</div>`}
+      </section>
+    `;
+        if (focusedId) {
+            // Compare data-id directly — ids are author input, and building a CSS
+            // selector from one can throw. Fall back to the current tab stop so
+            // focus stays inside the component when the focused node was removed.
+            const buttons = this.nodeButtons();
+            const target = buttons.find(button => button.getAttribute("data-id") === focusedId) ??
+                buttons.find(button => button.tabIndex === 0) ??
+                buttons[0];
+            target?.focus();
+        }
+    }
+}
+VersionGraph.register();

package/dist/patterns/versions/version-list.d.ts

@@ -0,0 +1,39 @@
+import type { VersionNode } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/**
+ * 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 declare class VersionList extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private versionsValue;
+    private compareIds;
+    private hostEl;
+    get heading(): string;
+    set heading(value: string);
+    /** Enables the per-row Restore intent button (non-current rows). */
+    get canRestore(): boolean;
+    set canRestore(value: boolean);
+    /** Enables the per-row Promote intent button (non-current rows). */
+    get canPromote(): boolean;
+    set canPromote(value: boolean);
+    get versions(): VersionNode[];
+    set versions(value: VersionNode[]);
+    /** Ids currently toggled for compare, in selection order (max two). */
+    get compareSelection(): string[];
+    clearCompareSelection(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    private parseVersionsAttribute;
+    private pruneCompareSelection;
+    private getVersion;
+    private toggleCompare;
+    private rowHtml;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}