@unofficialbox/box-open-elements 0.20.0 → 0.22.0

package/dist/patterns/flow-builder/flow-builder.d.ts

@@ -0,0 +1,79 @@
+import { BaseElement } from "../../core/index.js";
+import { type FlowKind, type FlowModel, type FlowNode, type FlowNodeBase, type NodePath } from "./model.js";
+export type InspectorRenderer<N extends FlowNodeBase = FlowNode> = (node: N, container: HTMLElement) => void | (() => void);
+export interface ValidationOptions {
+    /**
+     * Show the message in the builder's own error line (default `true`). Pass
+     * `false` when the host already shows the error persistently, so the
+     * message isn't on screen twice; the step is still marked and announced.
+     */
+    showMessage?: boolean;
+}
+/**
+ * Host-owned document editing with accessible navigation and responsive inspection.
+ * `N` is the host's node type; it defaults to {@link FlowNode}, which the default
+ * model reads. Hosts with their own document shape set {@link model}.
+ */
+export declare class FlowBuilder<N extends FlowNodeBase = FlowNode> extends BaseElement {
+    static readonly tagName = "box-flow-builder";
+    private nodesValue;
+    private modelValue;
+    private catalogValue;
+    private selectedValue;
+    private invalidValue;
+    private renderer?;
+    private cleanupInspector?;
+    private inspected;
+    private headingEl?;
+    private renderedRenderer?;
+    private observer?;
+    private narrow;
+    private insertion?;
+    private invoker?;
+    private spine;
+    private palette;
+    private picker;
+    private popup;
+    private aside;
+    private inspector;
+    private drawer;
+    private error;
+    static get observedAttributes(): string[];
+    get nodes(): N[];
+    set nodes(value: N[]);
+    /** How to read the host document; defaults to `body` / `branches` ({@link FlowNode}). */
+    get model(): FlowModel<N>;
+    set model(value: FlowModel<N>);
+    /** Text above the first step (`start-label`). */
+    get startLabel(): string;
+    set startLabel(value: string);
+    /** Text below the last step (`end-label`). */
+    get endLabel(): string;
+    set endLabel(value: string);
+    get catalog(): readonly FlowKind<N>[];
+    set catalog(value: readonly FlowKind<N>[]);
+    get selected(): N | null;
+    set selected(node: N | null);
+    get renderInspector(): InspectorRenderer<N> | undefined;
+    set renderInspector(renderer: InspectorRenderer<N> | undefined);
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    private setNarrow;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    private closePicker;
+    private insert;
+    select(node: N | null): void;
+    /** Mark validation without opening a sheet over the error on a narrow screen. */
+    setValidation(message: string, path?: NodePath, document?: unknown, options?: ValidationOptions): void;
+    refresh(): void;
+    /**
+     * Re-render one step's card and the inspector heading after the host edits
+     * its fields. Structural edits (adding, removing, moving steps) need
+     * {@link refresh}.
+     */
+    refreshNode(node: N): void;
+    protected update(): void;
+    private updateInspector;
+}

package/dist/patterns/flow-builder/flow-builder.js

@@ -0,0 +1,243 @@
+import { BaseElement } from "../../core/index.js";
+import { announce } from "../../foundations/a11y/index.js";
+import { defaultFlowModel, nodeAtPath, nodeDescription, nodeTitle } from "./model.js";
+import { FLOW_SPINE_PARTS, InsertPoint, KIND_PICKER_PARTS } from "./primitives.js";
+/**
+ * Host-owned document editing with accessible navigation and responsive inspection.
+ * `N` is the host's node type; it defaults to {@link FlowNode}, which the default
+ * model reads. Hosts with their own document shape set {@link model}.
+ */
+export class FlowBuilder extends BaseElement {
+    static tagName = "box-flow-builder";
+    nodesValue = [];
+    modelValue = defaultFlowModel;
+    catalogValue = [];
+    selectedValue = null;
+    invalidValue = null;
+    renderer;
+    cleanupInspector;
+    inspected;
+    headingEl;
+    renderedRenderer;
+    observer;
+    narrow = false;
+    insertion;
+    invoker;
+    spine;
+    palette;
+    picker;
+    popup;
+    aside;
+    inspector;
+    drawer;
+    error;
+    static get observedAttributes() { return ["start-label", "end-label"]; }
+    get nodes() { return this.nodesValue; }
+    set nodes(value) { this.nodesValue = value; this.refresh(); }
+    /** How to read the host document; defaults to `body` / `branches` ({@link FlowNode}). */
+    get model() { return this.modelValue; }
+    set model(value) { this.modelValue = value; this.refresh(); }
+    /** Text above the first step (`start-label`). */
+    get startLabel() { return this.getAttribute("start-label") ?? "Flow starts"; }
+    set startLabel(value) { this.setAttribute("start-label", value); }
+    /** Text below the last step (`end-label`). */
+    get endLabel() { return this.getAttribute("end-label") ?? "Flow ends"; }
+    set endLabel(value) { this.setAttribute("end-label", value); }
+    get catalog() { return this.catalogValue; }
+    set catalog(value) { this.catalogValue = value; this.refresh(); }
+    get selected() { return this.selectedValue; }
+    set selected(node) { this.select(node); }
+    get renderInspector() { return this.renderer; }
+    set renderInspector(renderer) { this.renderer = renderer; if (this.isRendered)
+        this.updateInspector(); }
+    attributeChangedCallback(name, oldValue, newValue) {
+        super.attributeChangedCallback(name, oldValue, newValue);
+        if (oldValue !== newValue)
+            this.refresh();
+    }
+    connectedCallback() {
+        super.connectedCallback();
+        if (typeof ResizeObserver !== "undefined") {
+            this.observer = new ResizeObserver(entries => this.setNarrow(entries[0].contentRect.width < 800));
+            this.observer.observe(this);
+        }
+        this.setNarrow((this.getBoundingClientRect().width || this.ownerDocument.defaultView?.innerWidth || 1024) < 800);
+    }
+    disconnectedCallback() {
+        this.observer?.disconnect();
+        this.cleanupInspector?.();
+        this.cleanupInspector = undefined;
+        this.inspected = undefined;
+        this.closePicker(false);
+        this.selectedValue = null;
+        this.drawer.open = false;
+    }
+    setNarrow(narrow) {
+        if (this.narrow === narrow)
+            return;
+        this.narrow = narrow;
+        this.shadowRoot.querySelector("[part=layout]").dataset.narrow = String(narrow);
+        this.updateInspector();
+    }
+    renderTemplate() {
+        this.shadowRoot.innerHTML = `<style>
+      :host{display:block;min-width:0;font:inherit;color:var(--boe-token-text-text,#222)}
+      :host([hidden]){display:none!important}
+      [part=layout]{display:grid;grid-template-columns:minmax(0,1fr) minmax(240px,320px);gap:24px;align-items:start}
+      [part=layout][data-narrow=true]{grid-template-columns:minmax(0,1fr)}
+      aside{min-width:0;padding:16px;border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:12px;background:var(--boe-token-surface-surface,#fff)}
+      [part=picker-popup]{position:fixed;z-index:1000;max-width:min(360px,calc(100vw - 24px));max-height:65vh;overflow:auto;padding:16px;background:var(--boe-token-surface-surface,#fff);border:1px solid var(--boe-token-stroke-stroke,#ddd);border-radius:12px;box-shadow:0 8px 32px #0003}
+      [part=error]{color:var(--boe-token-text-status-text-error,#b92340);margin-bottom:16px;overflow-wrap:anywhere}
+      [hidden]{display:none!important} h2{font:inherit;font-weight:650;margin:0 0 12px}
+      </style><div part="error" hidden></div><div part="layout"><box-flow-spine exportparts="${FLOW_SPINE_PARTS.join(", ")}"></box-flow-spine><aside part="inspector"><box-kind-picker exportparts="${KIND_PICKER_PARTS.join(", ")}"></box-kind-picker><div part="editor"></div></aside></div><div part="picker-popup" hidden><box-kind-picker exportparts="${KIND_PICKER_PARTS.join(", ")}"></box-kind-picker></div><box-drawer position="bottom" size="large"></box-drawer>`;
+        this.spine = this.shadowRoot.querySelector("box-flow-spine");
+        this.aside = this.shadowRoot.querySelector("aside");
+        this.palette = this.aside.querySelector("box-kind-picker");
+        this.inspector = this.aside.querySelector("[part=editor]");
+        this.popup = this.shadowRoot.querySelector("[part=picker-popup]");
+        this.picker = this.popup.querySelector("box-kind-picker");
+        this.picker.variant = "menu";
+        this.drawer = this.shadowRoot.querySelector("box-drawer");
+        this.error = this.shadowRoot.querySelector("[part=error]");
+    }
+    setupListeners() {
+        this.spine.addEventListener("node-select", event => this.select(event.detail.node));
+        this.spine.addEventListener("insert-request", event => {
+            this.insertion = event.detail;
+            this.invoker = event.composedPath().find(item => item instanceof InsertPoint);
+            const rect = this.invoker.getBoundingClientRect();
+            this.popup.hidden = false;
+            this.picker.catalog = this.catalog;
+            this.picker.refresh();
+            const viewport = this.ownerDocument.defaultView;
+            const popupRect = this.popup.getBoundingClientRect();
+            this.popup.style.left = `${Math.max(12, Math.min(rect.left, viewport.innerWidth - popupRect.width - 12))}px`;
+            this.popup.style.top = `${Math.max(12, Math.min(rect.bottom + 8, viewport.innerHeight - popupRect.height - 12))}px`;
+            this.picker.focus();
+        });
+        this.picker.addEventListener("picker-cancel", () => this.closePicker(true));
+        this.picker.addEventListener("focusout", event => {
+            const next = event.relatedTarget;
+            if (next instanceof Node && (this.picker.contains(next) || this.picker.shadowRoot?.contains(next)))
+                return;
+            this.closePicker(false);
+        });
+        this.picker.addEventListener("kind-pick", event => {
+            const insertion = this.insertion;
+            if (!insertion)
+                return;
+            this.insert(event.detail.kind, insertion);
+        });
+        this.palette.addEventListener("kind-pick", event => this.insert(event.detail.kind, { list: this.nodes, index: this.nodes.length, label: "Append to flow" }));
+        this.drawer.addEventListener("open-changed", event => {
+            if (!event.detail.open && this.narrow && this.selectedValue)
+                this.select(null);
+        });
+    }
+    closePicker(restoreFocus) {
+        if (!this.popup)
+            return;
+        this.popup.hidden = true;
+        this.insertion = undefined;
+        if (restoreFocus)
+            this.invoker?.focus();
+    }
+    insert(kind, insertion) {
+        const node = kind.create();
+        insertion.list.splice(insertion.index, 0, node);
+        this.closePicker(false);
+        this.selectedValue = this.narrow ? null : node;
+        this.refresh();
+        // Keep the newly inserted card visible on small screens; explicit selection opens editing.
+        this.spine.focusNode(node);
+        announce(`Added ${nodeTitle(node, this.catalog, this.model)}`, "polite", this.ownerDocument);
+        this.dispatchEvent(new CustomEvent("flow-changed", { detail: { nodes: this.nodes, node, reason: "insert" }, bubbles: true, composed: true }));
+    }
+    select(node) {
+        this.selectedValue = node;
+        if (this.isRendered) {
+            this.spine.select(node, this.invalidValue);
+            this.updateInspector();
+        }
+        this.dispatchEvent(new CustomEvent("selection-changed", { detail: { node }, bubbles: true, composed: true }));
+    }
+    /** Mark validation without opening a sheet over the error on a narrow screen. */
+    setValidation(message, path = [], document = { body: this.nodes }, options = {}) {
+        this.invalidValue = message ? nodeAtPath(document, path) : null;
+        const show = options.showMessage ?? true;
+        this.error.textContent = show ? message : "";
+        this.error.hidden = !message || !show;
+        this.spine.select(this.selected, this.invalidValue);
+        if (message) {
+            if (!this.narrow && this.invalidValue)
+                this.select(this.invalidValue);
+            else if (this.narrow)
+                this.select(null);
+            announce(message, "assertive", this.ownerDocument);
+        }
+    }
+    refresh() { if (this.isRendered)
+        this.update(); }
+    /**
+     * Re-render one step's card and the inspector heading after the host edits
+     * its fields. Structural edits (adding, removing, moving steps) need
+     * {@link refresh}.
+     */
+    refreshNode(node) {
+        if (!this.isRendered)
+            return;
+        this.spine.refreshNode(node);
+        if (node === this.selected) {
+            const title = nodeTitle(node, this.catalog, this.model);
+            if (this.headingEl)
+                this.headingEl.textContent = title;
+            this.drawer.heading = title;
+        }
+    }
+    update() {
+        this.spine.nodes = this.nodes;
+        this.spine.catalog = this.catalog;
+        this.spine.model = this.model;
+        this.spine.startLabel = this.startLabel;
+        this.spine.endLabel = this.endLabel;
+        this.spine.selected = this.selected;
+        this.spine.invalid = this.invalidValue;
+        this.spine.refresh();
+        this.palette.catalog = this.catalog;
+        this.palette.refresh();
+        this.updateInspector();
+    }
+    updateInspector() {
+        this.aside.hidden = this.narrow;
+        this.palette.hidden = Boolean(this.selected);
+        const target = this.narrow ? this.drawer : this.aside;
+        if (this.inspector.parentElement !== target)
+            target.append(this.inspector);
+        if (this.inspected === this.selected && this.renderedRenderer === this.renderer) {
+            this.drawer.open = this.narrow && Boolean(this.selected);
+            return;
+        }
+        this.cleanupInspector?.();
+        this.cleanupInspector = undefined;
+        this.inspector.replaceChildren();
+        this.inspected = this.selected;
+        this.renderedRenderer = this.renderer;
+        if (this.selected) {
+            const heading = document.createElement("h2");
+            heading.setAttribute("part", "inspector-heading");
+            heading.textContent = nodeTitle(this.selected, this.catalog, this.model);
+            this.inspector.append(heading);
+            this.headingEl = heading;
+            if (this.renderer)
+                this.cleanupInspector = this.renderer(this.selected, this.inspector) || undefined;
+            else {
+                const description = document.createElement("p");
+                description.textContent = nodeDescription(this.selected, this.catalog, this.model) || "Select a step to inspect its configuration.";
+                this.inspector.append(description);
+            }
+            this.drawer.heading = nodeTitle(this.selected, this.catalog, this.model);
+        }
+        this.drawer.open = this.narrow && Boolean(this.selected);
+    }
+}
+FlowBuilder.register();

package/dist/patterns/flow-builder/index.d.ts

@@ -0,0 +1,3 @@
+export * from "./model.js";
+export * from "./primitives.js";
+export * from "./flow-builder.js";

package/dist/patterns/flow-builder/index.js

@@ -0,0 +1,3 @@
+export * from "./model.js";
+export * from "./primitives.js";
+export * from "./flow-builder.js";

package/dist/patterns/flow-builder/model.d.ts

@@ -0,0 +1,81 @@
+/**
+ * The least the flow builder needs from a node. Hosts keep their own
+ * document shape; a {@link FlowModel} tells the builder how to read it.
+ */
+export interface FlowNodeBase {
+    kind: string;
+}
+/** The document shape the default model reads. */
+export interface FlowNode extends FlowNodeBase {
+    id?: string;
+    title?: string;
+    description?: string;
+    status?: string;
+    body?: FlowNode[];
+    branches?: FlowBranch[];
+}
+export interface FlowBranch {
+    label: string;
+    body: FlowNode[];
+}
+/** One list of steps nested under a node. */
+export interface FlowChildList {
+    /** A branch label. Unlabeled lists render as the node's inline body; labeled lists render as branch columns. */
+    label?: string;
+    /** The host's own array. The builder splices new steps into it. */
+    list: FlowNodeBase[];
+    /** Show a remove control on this branch; the builder emits `branch-remove-request`. */
+    removable?: boolean;
+}
+/**
+ * How the builder reads a host document. Every traversal, title and insert
+ * label goes through the model, so hosts pass their own nodes — identity
+ * (selection, undo, validation paths) is preserved.
+ */
+export interface FlowModel<N extends FlowNodeBase = FlowNodeBase> {
+    /** Nested lists under `node`, in display order. */
+    children(node: N): FlowChildList[];
+    /** A distinct name for the node; falls back to its kind's label. */
+    title?(node: N): string | undefined;
+    /** One sentence about what the node does at run time; falls back to its kind's description. */
+    description?(node: N): string | undefined;
+    /** A short status line shown on the card. */
+    status?(node: N): string | undefined;
+    /** When it returns a label, the node's branches get an add control; the builder emits `branch-add-request`. */
+    addBranchLabel?(node: N): string | undefined;
+}
+/** Reads {@link FlowNode}: `body` renders inline and `branches` render as labeled columns. */
+export declare const defaultFlowModel: FlowModel<FlowNode>;
+export interface FlowKind<N extends FlowNodeBase = FlowNodeBase> {
+    kind: string;
+    label: string;
+    description: string;
+    group?: string;
+    /** Supply an authored SVG node (for example from a named glyph import). */
+    icon?: () => Node;
+    /**
+     * Icon color. `accent` (the default) uses the brand color; `neutral` uses
+     * secondary text, so a host can reserve the accent for its primary object.
+     */
+    tone?: "accent" | "neutral";
+    create(): N;
+}
+export interface FlowInsertDetail {
+    list: FlowNodeBase[];
+    index: number;
+    label: string;
+}
+export interface FlowBranchRequestDetail {
+    node: FlowNodeBase;
+    /** The branch's position among the node's labeled lists (remove requests only). */
+    index?: number;
+    /** The branch's own list (remove requests only). */
+    list?: FlowNodeBase[];
+}
+export type NodePath = readonly (string | number)[];
+export declare const nodeTitle: (node: FlowNodeBase, catalog?: readonly FlowKind[], model?: FlowModel<FlowNodeBase>) => string;
+export declare const nodeDescription: (node: FlowNodeBase, catalog?: readonly FlowKind[], model?: FlowModel<FlowNodeBase>) => string;
+export declare function cardLabel(node: FlowNodeBase, catalog?: readonly FlowKind[], invalid?: boolean, model?: FlowModel<FlowNodeBase>): string;
+export declare function insertLabel(list: readonly FlowNodeBase[], index: number, where?: string, catalog?: readonly FlowKind[], model?: FlowModel<FlowNodeBase>): string;
+/** Return the deepest node on a validation path, including paths ending in a field. */
+export declare function nodeAtPath(document: unknown, path: NodePath): FlowNodeBase | null;

package/dist/patterns/flow-builder/model.js

@@ -0,0 +1,40 @@
+/** Reads {@link FlowNode}: `body` renders inline and `branches` render as labeled columns. */
+export const defaultFlowModel = {
+    children: node => [
+        ...(node.body ? [{ list: node.body }] : []),
+        ...(node.branches ?? []).map(branch => ({ label: branch.label, list: branch.body })),
+    ],
+    title: node => node.title,
+    description: node => node.description,
+    status: node => node.status,
+};
+export const nodeTitle = (node, catalog = [], model = defaultFlowModel) => model.title?.(node) || catalog.find(kind => kind.kind === node.kind)?.label || "Step";
+export const nodeDescription = (node, catalog = [], model = defaultFlowModel) => model.description?.(node) || catalog.find(kind => kind.kind === node.kind)?.description || "";
+export function cardLabel(node, catalog = [], invalid = false, model = defaultFlowModel) {
+    const kind = catalog.find(entry => entry.kind === node.kind);
+    const title = nodeTitle(node, catalog, model);
+    return [title, kind?.label !== title ? kind?.label : "", nodeDescription(node, catalog, model), model.status?.(node), invalid ? "Needs attention" : ""].filter(Boolean).join(". ");
+}
+export function insertLabel(list, index, where = "in the flow", catalog = [], model = defaultFlowModel) {
+    const title = (node) => nodeTitle(node, catalog, model);
+    if (!list.length)
+        return `Add the first step ${where}`;
+    if (index === 0)
+        return `Insert before ${title(list[0])} ${where}`;
+    if (index >= list.length)
+        return `Insert after ${title(list[list.length - 1])} ${where}`;
+    return `Insert between ${title(list[index - 1])} and ${title(list[index])} ${where}`;
+}
+/** Return the deepest node on a validation path, including paths ending in a field. */
+export function nodeAtPath(document, path) {
+    let current = document;
+    let result = null;
+    for (const segment of path) {
+        if (!current || typeof current !== "object" || !Object.hasOwn(current, segment))
+            break;
+        current = current[segment];
+        if (current && typeof current === "object" && "kind" in current && typeof current.kind === "string")
+            result = current;
+    }
+    return result;
+}

package/dist/patterns/flow-builder/primitives.d.ts

@@ -0,0 +1,57 @@
+import { BaseElement } from "../../core/index.js";
+import { type FlowInsertDetail, type FlowKind, type FlowModel, type FlowNodeBase } from "./model.js";
+/** Parts a card exposes; the spine and builder forward them unchanged. */
+export declare const FLOW_CARD_PARTS: readonly ["card", "icon", "title", "kind", "description", "status", "error"];
+/** Parts the spine exposes (its own plus forwarded card and insert-point parts). */
+export declare const FLOW_SPINE_PARTS: readonly ["spine", "endpoint", "body", "branches", "branch", "branch-header", "branch-label", "branch-remove", "branch-add", "insert", "card", "icon", "title", "kind", "description", "status", "error"];
+/** Parts a kind picker exposes. */
+export declare const KIND_PICKER_PARTS: readonly ["choices", "group-heading", "choice", "choice-icon", "choice-label", "choice-description"];
+export declare class FlowCard extends BaseElement {
+    static readonly tagName = "box-flow-card";
+    node: FlowNodeBase;
+    catalog: readonly FlowKind[];
+    model: FlowModel<FlowNodeBase>;
+    selected: boolean;
+    invalid: boolean;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    refresh(): void;
+    focus(options?: FocusOptions): void;
+    protected update(): void;
+}
+export declare class InsertPoint extends BaseElement {
+    static readonly tagName = "box-insert-point";
+    detail: FlowInsertDetail;
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    focus(options?: FocusOptions): void;
+    protected update(): void;
+}
+export declare class KindPicker extends BaseElement {
+    static readonly tagName = "box-kind-picker";
+    catalog: readonly FlowKind[];
+    variant: "inline" | "menu";
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    refresh(): void;
+    focus(options?: FocusOptions): void;
+    protected update(): void;
+}
+export declare class FlowSpine extends BaseElement {
+    static readonly tagName = "box-flow-spine";
+    nodes: FlowNodeBase[];
+    catalog: readonly FlowKind[];
+    model: FlowModel<FlowNodeBase>;
+    selected: FlowNodeBase | null;
+    invalid: FlowNodeBase | null;
+    startLabel: string;
+    endLabel: string;
+    private cards;
+    protected renderTemplate(): void;
+    refresh(): void;
+    /** Re-render one card after its fields change, without rebuilding the spine. */
+    refreshNode(node: FlowNodeBase): void;
+    focusNode(node: FlowNodeBase): void;
+    select(node: FlowNodeBase | null, invalid?: FlowNodeBase | null): void;
+    protected update(): void;
+}