@unofficialbox/box-open-elements 0.5.0 → 0.6.0

package/dist/patterns/preview/preview-element.js

@@ -1,3 +1,4 @@
+import { resolvePreviewStatus, } from "./provider-adapter.js";
 import { BaseElement } from "../../core/index.js";
 import { boePanel } from "../../foundations/geometry/index.js";
 const DEFAULT_TAG_NAME = "box-preview-element";
@@ -19,6 +20,7 @@ const elementStyles = `
           --_obp-text-muted: var(--boe-token-text-text-secondary, #6f6f6f);
           --_obp-brand: var(--boe-token-surface-surface-brand, #0061d5);
           --_obp-brand-soft: color-mix(in srgb, var(--_obp-brand) 12%, var(--boe-token-surface-surface, #ffffff) 88%);
+          --_obp-error: var(--boe-token-surface-status-surface-error, #ed3757);
         }
 
         [part="shell"] {
@@ -58,6 +60,20 @@ const elementStyles = `
           text-transform: uppercase;
         }
 
+        [part="status"][data-status="error"] {
+          background: color-mix(in srgb, var(--_obp-error) 14%, var(--_obp-surface) 86%);
+          color: var(--_obp-error);
+        }
+
+        [part="error"] {
+          margin: 0;
+          padding: 0.5rem 0.7rem;
+          border: 1px solid color-mix(in srgb, var(--_obp-error) 50%, #fff);
+          border-radius: 8px;
+          background: color-mix(in srgb, var(--_obp-error) 10%, #fff);
+          color: inherit;
+        }
+
         [part="adapter-meta"],
         [part="capabilities"] {
           display: flex;
@@ -105,7 +121,8 @@ const elementStyles = `
           gap: 0.5rem;
         }
 
-        [part="action"] {
+        [part="action"],
+        [part="control"] {
           appearance: none;
           min-height: 2rem;
           padding: 0.4rem 0.7rem;
@@ -123,6 +140,24 @@ const elementStyles = `
           color: var(--boe-token-text-text-on-brand, #ffffff);
         }
 
+        [part="control"]:disabled {
+          opacity: 0.5;
+          cursor: not-allowed;
+        }
+
+        [part="controls"] {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: center;
+          gap: 0.45rem;
+        }
+
+        [part="control-readout"] {
+          color: var(--_obp-text-muted);
+          font-size: 0.85rem;
+          font-variant-numeric: tabular-nums;
+        }
+
         [part="toolbar"] {
           display: block;
         }
@@ -134,6 +169,10 @@ const elementStyles = `
           align-items: start;
         }
 
+        [part="workspace"][data-sidebar="empty"] {
+          grid-template-columns: minmax(0, 1fr);
+        }
+
         [part="stage"] {
           min-block-size: 13rem;
           border: 1px solid var(--_obp-border-subtle);
@@ -142,11 +181,28 @@ const elementStyles = `
           overflow: hidden;
         }
 
+        [part="stage"][aria-busy="true"] {
+          opacity: 0.7;
+        }
+
+        [part="stage-mount"] {
+          width: 100%;
+          height: 100%;
+        }
+
+        [part="stage-mount"][hidden] {
+          display: none;
+        }
+
         [part="sidebar"] {
           display: grid;
           gap: 0.6rem;
         }
 
+        [part="workspace"][data-sidebar="empty"] [part="sidebar"] {
+          display: none;
+        }
+
         ::slotted([slot="toolbar"]) {
           display: block;
         }
@@ -171,6 +227,7 @@ export class Preview extends BaseElement {
     static tagName = DEFAULT_TAG_NAME;
     providerAdapterValue = null;
     providerAdapterUnsubscribe = null;
+    adapterMounted = false;
     static get observedAttributes() {
         return ["actions", "adapter-state", "item-label", "message", "provider", "provider-label", "status", "heading"];
     }
@@ -252,12 +309,8 @@ export class Preview extends BaseElement {
     set providerAdapter(value) {
         this.teardownProviderAdapter();
         this.providerAdapterValue = value;
-        if (value?.subscribe) {
-            this.providerAdapterUnsubscribe = value.subscribe(() => {
-                if (this.isRendered) {
-                    this.update();
-                }
-            });
+        if (this.isConnected) {
+            this.attachProviderAdapter();
         }
         if (this.isRendered) {
             this.update();
@@ -265,13 +318,16 @@ export class Preview extends BaseElement {
     }
     connectedCallback() {
         super.connectedCallback();
+        // Re-attach after a detach: disconnectedCallback tears the subscription and
+        // mount down, so a reconnect must restore both or the element goes stale.
+        this.attachProviderAdapter();
+        if (this.isRendered) {
+            this.update();
+        }
     }
     disconnectedCallback() {
         this.teardownProviderAdapter();
     }
-    attributeChangedCallback(name, oldValue, newValue) {
-        super.attributeChangedCallback(name, oldValue, newValue);
-    }
     parseJsonAttribute(name, fallback) {
         const raw = this.getAttribute(name);
         if (!raw) {
@@ -284,9 +340,36 @@ export class Preview extends BaseElement {
             return fallback;
         }
     }
+    attachProviderAdapter() {
+        const adapter = this.providerAdapterValue;
+        if (!adapter) {
+            return;
+        }
+        if (adapter.subscribe && !this.providerAdapterUnsubscribe) {
+            this.providerAdapterUnsubscribe = adapter.subscribe(() => {
+                if (this.isRendered) {
+                    this.update();
+                }
+            });
+        }
+        const mountNode = this.shadowRoot?.querySelector('[part="stage-mount"]');
+        if (adapter.mount && mountNode && !this.adapterMounted) {
+            mountNode.hidden = false;
+            adapter.mount(mountNode);
+            this.adapterMounted = true;
+        }
+    }
     teardownProviderAdapter() {
         this.providerAdapterUnsubscribe?.();
         this.providerAdapterUnsubscribe = null;
+        if (this.adapterMounted) {
+            this.providerAdapterValue?.unmount?.();
+            this.adapterMounted = false;
+            const mountNode = this.shadowRoot?.querySelector('[part="stage-mount"]');
+            if (mountNode) {
+                mountNode.hidden = true;
+            }
+        }
     }
     getActiveProvider() {
         return this.providerAdapterValue?.getProvider() ?? this.provider;
@@ -303,13 +386,39 @@ export class Preview extends BaseElement {
             provider,
             providerId: provider?.id ?? null,
         };
-        void this.providerAdapterValue?.performAction?.(detail);
+        Promise.resolve(this.providerAdapterValue?.performAction?.(detail)).catch((error) => {
+            this.dispatchEvent(new CustomEvent("action-error", {
+                bubbles: true,
+                composed: true,
+                detail: {
+                    action: actionId,
+                    message: error instanceof Error ? error.message : "Preview action failed",
+                },
+            }));
+        });
         this.dispatchEvent(new CustomEvent("action", {
             bubbles: true,
             composed: true,
             detail,
         }));
-        this.dispatchEvent(new CustomEvent("provider-action", {
+    }
+    emitCommand(command) {
+        const provider = this.getActiveProvider();
+        const detail = {
+            command,
+            providerId: provider?.id ?? null,
+        };
+        Promise.resolve(this.providerAdapterValue?.sendCommand?.(command)).catch((error) => {
+            this.dispatchEvent(new CustomEvent("action-error", {
+                bubbles: true,
+                composed: true,
+                detail: {
+                    action: command.command,
+                    message: error instanceof Error ? error.message : "Preview command failed",
+                },
+            }));
+        });
+        this.dispatchEvent(new CustomEvent("command", {
             bubbles: true,
             composed: true,
             detail,
@@ -319,11 +428,58 @@ export class Preview extends BaseElement {
         if (!this.shadowRoot) {
             return;
         }
+        // Stable skeleton: the chrome host is re-rendered per update, while the
+        // workspace (adapter mount node + slots) keeps node identity so mounted
+        // preview engines and slotted content survive chrome updates.
         this.shadowRoot.innerHTML = `
       <style>${elementStyles}</style>
-      <div part="content-host"></div>
+      <article part="shell">
+        <div part="content-host"></div>
+        <div part="toolbar">
+          <slot name="toolbar"></slot>
+        </div>
+        <div part="workspace" data-sidebar="empty">
+          <div part="stage">
+            <div part="stage-mount" hidden></div>
+            <slot name="stage"></slot>
+          </div>
+          <aside part="sidebar">
+            <slot name="sidebar"></slot>
+          </aside>
+        </div>
+      </article>
     `;
     }
+    setupListeners() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        // Delegated once — chrome re-renders never re-bind listeners.
+        this.shadowRoot.querySelector('[part="content-host"]')?.addEventListener("click", event => {
+            const target = event.target.closest("[data-action-id], [data-command]");
+            if (!target || target.disabled) {
+                return;
+            }
+            const actionId = target.getAttribute("data-action-id");
+            if (actionId) {
+                this.emitAction(actionId);
+                return;
+            }
+            const command = target.getAttribute("data-command");
+            if (command) {
+                this.emitCommand({ command });
+            }
+        });
+        const sidebarSlot = this.shadowRoot.querySelector('slot[name="sidebar"]');
+        const workspace = this.shadowRoot.querySelector('[part="workspace"]');
+        const syncSidebar = () => {
+            const hasContent = (sidebarSlot?.assignedNodes({ flatten: true }) ?? []).some(node => node.nodeType === Node.ELEMENT_NODE || (node.textContent ?? "").trim() !== "");
+            workspace?.setAttribute("data-sidebar", hasContent ? "filled" : "empty");
+        };
+        sidebarSlot?.addEventListener("slotchange", syncSidebar);
+        syncSidebar();
+        this.attachProviderAdapter();
+    }
     update() {
         if (!this.shadowRoot) {
             return;
@@ -331,8 +487,15 @@ export class Preview extends BaseElement {
         const provider = this.getActiveProvider();
         const adapterState = this.getActiveAdapterState();
         const providerLabel = provider?.label ?? this.providerLabel;
-        const providerStatus = provider?.status ?? this.status;
-        const statusMarkup = providerStatus ? `<span part="status">${escapeHtml(providerStatus)}</span>` : "";
+        const lifecycle = resolvePreviewStatus(adapterState);
+        const statusLabel = provider?.status ?? this.status ?? "";
+        const statusText = statusLabel || (adapterState ? lifecycle : "");
+        const statusMarkup = statusText
+            ? `<span part="status" role="status" data-status="${escapeHtml(lifecycle)}">${escapeHtml(statusText)}</span>`
+            : "";
+        const errorMarkup = lifecycle === "error"
+            ? `<p part="error" role="alert">${escapeHtml(adapterState?.errorMessage ?? "Preview failed to load.")}</p>`
+            : "";
         const messageMarkup = this.message ? `<div part="message">${escapeHtml(this.message)}</div>` : "";
         const providerMarkup = providerLabel ? `<span part="provider">${escapeHtml(providerLabel)}</span>` : "";
         const itemMarkup = this.itemLabel ? `<div part="item-label">${escapeHtml(this.itemLabel)}</div>` : "";
@@ -346,9 +509,6 @@ export class Preview extends BaseElement {
             ${adapterState.currentAnnotationId
                 ? `<span part="adapter-chip">${escapeHtml(`Annotation ${adapterState.currentAnnotationId}`)}</span>`
                 : ""}
-            ${typeof adapterState.ready === "boolean"
-                ? `<span part="adapter-chip">${adapterState.ready ? "Ready" : "Connecting"}</span>`
-                : ""}
           </div>
         `
             : "";
@@ -359,6 +519,7 @@ export class Preview extends BaseElement {
           </div>
         `
             : "";
+        const controlsMarkup = this.renderControls(adapterState);
         const actionsMarkup = this.actions.length
             ? `
           <div part="actions">
@@ -382,42 +543,52 @@ export class Preview extends BaseElement {
             return;
         }
         host.innerHTML = `
-      <article part="shell">
-        <div part="topline">
-          <div part="topline-meta">
-            ${providerMarkup}
-            ${statusMarkup}
-          </div>
-          ${actionsMarkup}
-        </div>
-        <header part="header">
-          <h2 part="title">${escapeHtml(this.heading)}</h2>
-          ${itemMarkup}
-          ${messageMarkup}
-          ${adapterMarkup}
-          ${capabilityMarkup}
-        </header>
-        <div part="toolbar">
-          <slot name="toolbar"></slot>
+      <div part="topline">
+        <div part="topline-meta">
+          ${providerMarkup}
+          ${statusMarkup}
         </div>
-        <div part="workspace">
-          <div part="stage">
-            <slot name="stage"></slot>
-          </div>
-          <aside part="sidebar">
-            <slot name="sidebar"></slot>
-          </aside>
-        </div>
-      </article>
+        ${actionsMarkup}
+      </div>
+      <header part="header">
+        <h2 part="title">${escapeHtml(this.heading)}</h2>
+        ${itemMarkup}
+        ${messageMarkup}
+        ${errorMarkup}
+        ${adapterMarkup}
+        ${capabilityMarkup}
+        ${controlsMarkup}
+      </header>
     `;
-        this.shadowRoot.querySelectorAll('[part="action"]').forEach(button => {
-            button.addEventListener("click", () => {
-                const actionId = button.getAttribute("data-action-id");
-                if (actionId) {
-                    this.emitAction(actionId);
-                }
-            });
-        });
+        const stage = this.shadowRoot.querySelector('[part="stage"]');
+        stage?.setAttribute("aria-busy", lifecycle === "loading" ? "true" : "false");
+    }
+    /**
+     * Paging/zoom controls render only when the adapter accepts commands and the
+     * state carries the numeric fields to drive them.
+     */
+    renderControls(adapterState) {
+        if (!this.providerAdapterValue?.sendCommand || !adapterState) {
+            return "";
+        }
+        const segments = [];
+        if (typeof adapterState.page === "number" && typeof adapterState.pageCount === "number") {
+            const atFirst = adapterState.page <= 1;
+            const atLast = adapterState.page >= adapterState.pageCount;
+            segments.push(`
+        <button type="button" part="control" data-command="previous-page" aria-label="Previous page" ${atFirst ? "disabled" : ""}>&#8249;</button>
+        <span part="control-readout">Page ${adapterState.page} of ${adapterState.pageCount}</span>
+        <button type="button" part="control" data-command="next-page" aria-label="Next page" ${atLast ? "disabled" : ""}>&#8250;</button>
+      `);
+        }
+        if (typeof adapterState.zoomPercent === "number") {
+            segments.push(`
+        <button type="button" part="control" data-command="zoom-out" aria-label="Zoom out">&#8722;</button>
+        <span part="control-readout">${Math.round(adapterState.zoomPercent)}%</span>
+        <button type="button" part="control" data-command="zoom-in" aria-label="Zoom in">&#43;</button>
+      `);
+        }
+        return segments.length ? `<div part="controls" aria-label="Preview controls">${segments.join("")}</div>` : "";
     }
 }
 Preview.register();

package/dist/patterns/preview/provider-adapter.d.ts

@@ -5,13 +5,49 @@ export type PreviewProvider = {
     label: string;
     status?: string;
 };
+/** Lifecycle of the previewed content, from nothing loaded to failure. */
+export type PreviewStatus = "idle" | "loading" | "ready" | "error";
 export type PreviewAdapterState = {
     currentAnnotationId?: string;
     mode?: string;
+    /** Display-only label; prefer the numeric `page`/`pageCount` when driving UI. */
     pageLabel?: string;
+    /** Legacy readiness flag; prefer `status`. Kept for adapter compatibility. */
     ready?: boolean;
     selectionLabel?: string;
+    /** Display-only label; prefer the numeric `zoomPercent` when driving UI. */
     zoomLabel?: string;
+    /** Content lifecycle. When absent, derived from `ready` (see resolvePreviewStatus). */
+    status?: PreviewStatus;
+    /** Human-readable failure description; render when `status` is "error". */
+    errorMessage?: string;
+    /** 1-based current page for paged content. */
+    page?: number;
+    pageCount?: number;
+    /** Zoom level as a percentage (100 = actual size). */
+    zoomPercent?: number;
+};
+/**
+ * Effective lifecycle for a state object: an explicit `status` wins; otherwise
+ * the legacy `ready` flag maps true→ready / false→loading; no state → idle.
+ */
+export declare const resolvePreviewStatus: (state: PreviewAdapterState | null | undefined) => PreviewStatus;
+/**
+ * A typed command the host UI sends INTO the preview engine. Known commands
+ * carry their payload shape; the string fallback keeps the channel open for
+ * engine-specific extensions.
+ */
+export type PreviewCommand = {
+    command: "next-page" | "previous-page" | "zoom-in" | "zoom-out" | "toggle-fullscreen" | "download" | "print";
+} | {
+    command: "go-to-page";
+    value: number;
+} | {
+    command: "set-zoom";
+    value: number;
+} | {
+    command: string;
+    value?: unknown;
 };
 export type PreviewProviderActionDetail = {
     action: string;
@@ -24,6 +60,16 @@ export type PreviewProviderAdapter = {
     getState: () => PreviewAdapterState | null;
     performAction?: (detail: PreviewProviderActionDetail) => void | Promise<void>;
     subscribe?: (listener: () => void) => () => void;
+    /**
+     * Hand the adapter a stable container to render the preview engine into.
+     * `box-preview-element` calls this with its stage node when present; the
+     * node survives shell re-renders, so mounted DOM is never destroyed by
+     * chrome updates.
+     */
+    mount?: (container: HTMLElement) => void;
+    unmount?: () => void;
+    /** Drive the engine (paging, zoom, download, …) with a typed command. */
+    sendCommand?: (command: PreviewCommand) => void | Promise<void>;
 };
 export type StaticPreviewProviderAdapter = PreviewProviderAdapter & {
     setProvider: (provider: PreviewProvider | null) => void;
@@ -31,6 +77,7 @@ export type StaticPreviewProviderAdapter = PreviewProviderAdapter & {
 };
 export declare const createStaticPreviewProviderAdapter: (config: {
     onAction?: (detail: PreviewProviderActionDetail) => void | Promise<void>;
+    onCommand?: (command: PreviewCommand) => void | Promise<void>;
     provider?: PreviewProvider | null;
     state?: PreviewAdapterState | null;
 }) => StaticPreviewProviderAdapter;

package/dist/patterns/preview/provider-adapter.js

@@ -1,3 +1,19 @@
+/**
+ * Effective lifecycle for a state object: an explicit `status` wins; otherwise
+ * the legacy `ready` flag maps true→ready / false→loading; no state → idle.
+ */
+export const resolvePreviewStatus = (state) => {
+    if (!state) {
+        return "idle";
+    }
+    if (state.status) {
+        return state.status;
+    }
+    if (typeof state.ready === "boolean") {
+        return state.ready ? "ready" : "loading";
+    }
+    return "idle";
+};
 export const createStaticPreviewProviderAdapter = (config) => {
     let provider = config.provider ?? null;
     let state = config.state ?? null;
@@ -11,6 +27,7 @@ export const createStaticPreviewProviderAdapter = (config) => {
         getProvider: () => provider,
         getState: () => state,
         performAction: config.onAction,
+        ...(config.onCommand ? { sendCommand: config.onCommand } : {}),
         setProvider(nextProvider) {
             provider = nextProvider;
             notify();

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

@@ -0,0 +1,2 @@
+export * from "./types.js";
+export * from "./run-trace.js";

package/dist/patterns/run/index.js

@@ -0,0 +1,4 @@
+// Run model, rules, and validation
+export * from "./types.js";
+// Machine execution trace surface
+export * from "./run-trace.js";

package/dist/patterns/run/run-trace.d.ts

@@ -0,0 +1,40 @@
+import type { RunResolution, RunStep, RunStepStatus } from "./types.js";
+import { BaseElement } from "../../core/index.js";
+/** Every status in words — colour never carries the meaning alone. */
+export declare const RUN_STEP_STATUS_LABEL: Record<RunStepStatus, string>;
+/**
+ * Machine execution trace: a job, pipeline, or agent run, top-down. The
+ * rules live in `resolveRunSteps` (pure), the same way `resolveCeremony`
+ * backs the signature card: an explicit status wins, a failure shadows the
+ * queue behind it as skipped, timestamps derive running/succeeded, and the
+ * host can drive its notifications from the identical function.
+ *
+ * Deliberately not `box-timeline` (the human activity feed): a run reads
+ * forward, has one step in flight, and takes no comments.
+ *
+ * The summary chip doubles as a polite status region, so a run driven by
+ * attribute updates announces "Running Deploy — step 3 of 5" → "Completed"
+ * without extra wiring. Per-step detail expands in place: `description`
+ * plus a `detail-<id>` slot for rich host content, plus child tasks with
+ * live `box-progress-bar` rows.
+ */
+export declare class RunTrace extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private hostEl;
+    private stepsRaw;
+    private stepsCache;
+    private readonly expandedIds;
+    get heading(): string;
+    set heading(value: string);
+    get steps(): RunStep[];
+    set steps(value: RunStep[]);
+    /** The resolved run — same object the render uses. */
+    get resolution(): RunResolution;
+    /** Ids of the steps whose detail is expanded (host-readable). */
+    get expandedSteps(): string[];
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    private childrenMarkup;
+    protected update(): void;
+}