@unofficialbox/box-open-elements 0.4.0 → 0.6.0

package/dist/components/feedback/progress-bar.js

@@ -52,7 +52,8 @@ const progressBarStyles = `
     transition: width ${boeMotionDuration.interactive} ${boeMotionEasing.standard};
   }
 `;
-export class BoxProgressBarElement extends BaseElement {
+export class ProgressBar extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["label", "max", "value"];
     }
@@ -118,11 +119,4 @@ export class BoxProgressBarElement extends BaseElement {
         this.indicatorEl.style.width = `${percentage}%`;
     }
 }
-export const defineBoxProgressBarElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxProgressBarElement);
-    return BoxProgressBarElement;
-};
+ProgressBar.register();

package/dist/components/feedback/progress-ring.d.ts

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxProgressRingElement extends BaseElement {
+export declare class ProgressRing extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private ringEl;
     private svgEl;
@@ -18,4 +19,3 @@ export declare class BoxProgressRingElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxProgressRingElement: (tagName?: string) => typeof BoxProgressRingElement;

package/dist/components/feedback/progress-ring.js

@@ -53,7 +53,8 @@ const progressRingStyles = `
     color: var(--boe-token-text-text-secondary, #6f6f6f);
   }
 `;
-export class BoxProgressRingElement extends BaseElement {
+export class ProgressRing extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["label", "max", "size", "value"];
     }
@@ -145,11 +146,4 @@ export class BoxProgressRingElement extends BaseElement {
         this.labelEl.textContent = this.label;
     }
 }
-export const defineBoxProgressRingElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxProgressRingElement);
-    return BoxProgressRingElement;
-};
+ProgressRing.register();

package/dist/components/feedback/progress-steps.d.ts

@@ -1,25 +1,71 @@
 import { BaseElement } from "../../core/index.js";
-type BoxProgressStep = {
+/**
+ * Explicit per-step status. Absent means the step derives complete / current /
+ * upcoming from its position relative to `value` — the behaviour existing
+ * hosts rely on. An explicit status wins over the positional derivation:
+ * `complete` marks out-of-order completion, `blocked` and `disabled` make the
+ * step non-interactive, `failed` stays interactive because a failed step is
+ * usually exactly where the user needs to go.
+ */
+export type ProgressStepStatus = "complete" | "blocked" | "failed" | "disabled";
+export interface ProgressStepItem {
     description?: string;
     label: string;
     value: string;
-};
-export declare class BoxProgressStepsElement extends BaseElement {
+    status?: ProgressStepStatus;
+    /** Short visible note under the label explaining the status ("Waiting on legal review"). */
+    statusNote?: string;
+}
+export type ProgressStepState = "current" | "upcoming" | ProgressStepStatus;
+export interface ResolvedProgressStep {
+    item: ProgressStepItem;
+    state: ProgressStepState;
+    /**
+     * True on the step `value` points at, whatever its status — currency is
+     * position, status is condition, and the two are stated separately so a
+     * failed step can still be the one the user is on.
+     */
+    isCurrent: boolean;
+    /** Blocked and disabled steps take no clicks and no focus. */
+    interactive: boolean;
+}
+/** Attribute payloads are author input — validate every record. */
+export declare const isProgressStepRecord: (value: unknown) => value is ProgressStepItem;
+/**
+ * The state rules, pure and DOM-free, so a host can drive its own surface
+ * (or decide whether "Continue" is enabled) from the same function the
+ * component renders from. An unknown `value` falls back to the first step,
+ * matching the component's long-standing behaviour.
+ */
+export declare const resolveStepStates: (items: readonly ProgressStepItem[], value: string) => ResolvedProgressStep[];
+/** Every state in words — colour never carries the meaning alone. */
+export declare const STEP_STATE_LABEL: Record<ProgressStepState, string>;
+export declare class ProgressSteps extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     private stepsEl;
+    private liveEl;
     private itemsSignature;
     get label(): string;
     set label(value: string);
-    get items(): BoxProgressStep[];
-    set items(value: BoxProgressStep[]);
+    get items(): ProgressStepItem[];
+    set items(value: ProgressStepItem[]);
+    /** The resolved states — same objects the render uses. */
+    get resolvedSteps(): ResolvedProgressStep[];
     get value(): string;
     set value(nextValue: string);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
     protected renderTemplate(): void;
     protected setupListeners(): void;
     private selectValue;
+    /** A polite announcement on user-driven step changes, never on render. */
+    private announceStep;
+    /**
+     * The tab stop lives on the current step — unless that step is blocked or
+     * disabled (a host can point `value` anywhere), in which case the first
+     * interactive step takes it so the group stays reachable.
+     */
+    private tabbableIndex;
     protected update(): void;
 }
-export declare const defineBoxProgressStepsElement: (tagName?: string) => typeof BoxProgressStepsElement;
-export {};

package/dist/components/feedback/progress-steps.js

@@ -8,6 +8,50 @@ const escapeHtml = (value) => value
     .replaceAll(">", ">")
     .replaceAll('"', """)
     .replaceAll("'", "'");
+const STEP_STATUSES = new Set(["complete", "blocked", "failed", "disabled"]);
+/** Attribute payloads are author input — validate every record. */
+export const isProgressStepRecord = (value) => {
+    if (typeof value !== "object" || value === null) {
+        return false;
+    }
+    const step = value;
+    return (typeof step.value === "string" &&
+        step.value.length > 0 &&
+        typeof step.label === "string" &&
+        step.label.length > 0 &&
+        (step.status === undefined || STEP_STATUSES.has(step.status)) &&
+        // Non-string text fields would reach escapeHtml and throw mid-render.
+        (step.description === undefined || typeof step.description === "string") &&
+        (step.statusNote === undefined || typeof step.statusNote === "string"));
+};
+/**
+ * The state rules, pure and DOM-free, so a host can drive its own surface
+ * (or decide whether "Continue" is enabled) from the same function the
+ * component renders from. An unknown `value` falls back to the first step,
+ * matching the component's long-standing behaviour.
+ */
+export const resolveStepStates = (items, value) => {
+    const currentIndex = Math.max(0, items.findIndex(item => item.value === value));
+    return items.map((item, index) => {
+        const positional = index < currentIndex ? "complete" : index === currentIndex ? "current" : "upcoming";
+        const state = item.status ?? positional;
+        return {
+            item,
+            state,
+            isCurrent: index === currentIndex,
+            interactive: state !== "blocked" && state !== "disabled",
+        };
+    });
+};
+/** Every state in words — colour never carries the meaning alone. */
+export const STEP_STATE_LABEL = {
+    complete: "Complete",
+    current: "Current step",
+    upcoming: "Not started",
+    blocked: "Blocked",
+    failed: "Failed",
+    disabled: "Unavailable",
+};
 const progressStepsStyles = `
   :host {
     display: block;
@@ -100,13 +144,75 @@ const progressStepsStyles = `
     color: var(--boe-token-text-text-secondary, #6f6f6f);
     line-height: 1.45;
   }
+
+  [part="step"]:disabled {
+    cursor: not-allowed;
+    background: var(--boe-token-surface-surface, #ffffff);
+  }
+
+  [part="step"][data-state="blocked"] [part="step-label"],
+  [part="step"][data-state="disabled"] [part="step-label"] {
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part="step"][data-state="blocked"] [part="marker"] {
+    background: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 18%, var(--boe-token-surface-surface, #ffffff) 82%);
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 52%, var(--boe-token-text-text, #222222));
+  }
+
+  [part="step"][data-state="failed"] {
+    border-color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 34%, transparent);
+  }
+
+  [part="step"][data-state="failed"] [part="marker"] {
+    border-color: transparent;
+    background: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 16%, var(--boe-token-surface-surface, #ffffff) 84%);
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 72%, black 28%);
+  }
+
+  [part="step"][data-state="disabled"] {
+    opacity: 0.62;
+  }
+
+  /* The status, in words: visible for the conditions a user must not miss. */
+  [part="step-status"] {
+    font-size: 0.8rem;
+    font-weight: 700;
+  }
+
+  [part="step"][data-state="blocked"] [part="step-status"] {
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-warning, #f5b31b) 48%, var(--boe-token-text-text, #222222));
+  }
+
+  [part="step"][data-state="failed"] [part="step-status"] {
+    color: color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 76%, black 24%);
+  }
+
+  [part="step-status-note"] {
+    font-size: 0.82rem;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  .boe-sr-only {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    margin: -1px;
+    padding: 0;
+    border: 0;
+    clip: rect(0, 0, 0, 0);
+    overflow: hidden;
+    white-space: nowrap;
+  }
 `;
-export class BoxProgressStepsElement extends BaseElement {
+export class ProgressSteps extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["items", "label", "value"];
     }
     valueInternal = "";
     stepsEl;
+    liveEl;
     itemsSignature = "";
     get label() {
         return this.getAttribute("label") ?? "Progress Steps";
@@ -121,7 +227,9 @@ export class BoxProgressStepsElement extends BaseElement {
         }
         try {
             const parsed = JSON.parse(raw);
-            return Array.isArray(parsed) ? parsed : [];
+            return Array.isArray(parsed) && parsed.every(isProgressStepRecord)
+                ? parsed
+                : [];
         }
         catch {
             return [];
@@ -130,6 +238,10 @@ export class BoxProgressStepsElement extends BaseElement {
     set items(value) {
         this.setAttribute("items", JSON.stringify(value));
     }
+    /** The resolved states — same objects the render uses. */
+    get resolvedSteps() {
+        return resolveStepStates(this.items, this.valueInternal);
+    }
     get value() {
         return this.valueInternal;
     }
@@ -153,8 +265,10 @@ export class BoxProgressStepsElement extends BaseElement {
         this.shadowRoot.innerHTML = `
       <style>${progressStepsStyles}</style>
       <div part="steps" role="group"></div>
+      <div part="live" class="boe-sr-only" aria-live="polite"></div>
     `;
         this.stepsEl = this.shadowRoot.querySelector('[part="steps"]');
+        this.liveEl = this.shadowRoot.querySelector('[part="live"]');
     }
     setupListeners() {
         this.stepsEl.addEventListener("click", event => {
@@ -174,34 +288,51 @@ export class BoxProgressStepsElement extends BaseElement {
             if (!step || !this.stepsEl.contains(step)) {
                 return;
             }
-            const items = this.items;
+            const resolved = this.resolvedSteps;
             const index = Array.from(this.stepsEl.querySelectorAll('[part="step"]')).indexOf(step);
-            if (index < 0) {
+            if (index < 0 || resolved.length === 0) {
                 return;
             }
-            const lastIndex = items.length - 1;
-            let nextIndex = index;
+            // Arrows walk to the next *interactive* step — blocked and disabled
+            // steps are skipped, not landed on and bounced off.
+            const isInteractive = (candidate) => resolved[candidate]?.interactive ?? false;
+            const walk = (direction) => {
+                for (let offset = 1; offset <= resolved.length; offset += 1) {
+                    const candidate = (((index + direction * offset) % resolved.length) + resolved.length) % resolved.length;
+                    if (isInteractive(candidate)) {
+                        return candidate;
+                    }
+                }
+                return -1;
+            };
+            let nextIndex;
             if (keyboardEvent.key === "ArrowRight" || keyboardEvent.key === "ArrowDown") {
-                nextIndex = index >= lastIndex ? 0 : index + 1;
+                nextIndex = walk(1);
             }
             else if (keyboardEvent.key === "ArrowLeft" || keyboardEvent.key === "ArrowUp") {
-                nextIndex = index <= 0 ? lastIndex : index - 1;
+                nextIndex = walk(-1);
             }
             else if (keyboardEvent.key === "Home") {
-                nextIndex = 0;
+                nextIndex = resolved.findIndex(entry => entry.interactive);
             }
             else if (keyboardEvent.key === "End") {
-                nextIndex = lastIndex;
+                nextIndex = -1;
+                for (let candidate = resolved.length - 1; candidate >= 0; candidate -= 1) {
+                    if (isInteractive(candidate)) {
+                        nextIndex = candidate;
+                        break;
+                    }
+                }
             }
             else {
                 return;
             }
             keyboardEvent.preventDefault();
-            const nextStep = items[nextIndex];
-            if (!nextStep) {
+            const nextStep = resolved[nextIndex];
+            if (nextIndex < 0 || !nextStep) {
                 return;
             }
-            this.selectValue(nextStep.value);
+            this.selectValue(nextStep.item.value);
             queueMicrotask(() => {
                 const nextButton = this.stepsEl.querySelectorAll('[part="step"]')[nextIndex];
                 nextButton?.focus();
@@ -209,6 +340,13 @@ export class BoxProgressStepsElement extends BaseElement {
         });
     }
     selectValue(nextValue) {
+        // Disabled buttons never emit clicks and the keyboard path skips them,
+        // but the invariant should not depend on every caller knowing that.
+        const resolved = resolveStepStates(this.items, this.valueInternal);
+        const target = resolved.find(entry => entry.item.value === nextValue);
+        if (!target || !target.interactive) {
+            return;
+        }
         this.valueInternal = nextValue;
         this.setAttribute("value", nextValue);
         this.dispatchEvent(new CustomEvent("value-changed", {
@@ -217,6 +355,28 @@ export class BoxProgressStepsElement extends BaseElement {
             detail: { value: nextValue },
         }));
         this.update();
+        this.announceStep(target);
+    }
+    /** A polite announcement on user-driven step changes, never on render. */
+    announceStep(target) {
+        if (!this.liveEl) {
+            return;
+        }
+        const items = this.items;
+        const position = items.findIndex(item => item.value === target.item.value) + 1;
+        this.liveEl.textContent = `${target.item.label}, step ${String(position)} of ${String(items.length)}`;
+    }
+    /**
+     * The tab stop lives on the current step — unless that step is blocked or
+     * disabled (a host can point `value` anywhere), in which case the first
+     * interactive step takes it so the group stays reachable.
+     */
+    tabbableIndex(resolved) {
+        const currentIndex = resolved.findIndex(entry => entry.isCurrent);
+        if (resolved[currentIndex]?.interactive) {
+            return currentIndex;
+        }
+        return resolved.findIndex(entry => entry.interactive);
     }
     update() {
         if (!this.stepsEl) {
@@ -230,24 +390,35 @@ export class BoxProgressStepsElement extends BaseElement {
             this.setAttribute("value", selectedValue);
         }
         this.stepsEl.setAttribute("aria-label", this.label);
+        const resolved = resolveStepStates(items, this.valueInternal);
+        const tabbable = this.tabbableIndex(resolved);
         const signature = JSON.stringify(items);
         if (signature !== this.itemsSignature) {
             this.itemsSignature = signature;
-            this.stepsEl.innerHTML = items
-                .map((item, index) => {
-                const state = index < activeIndex ? "complete" : index === activeIndex ? "current" : "upcoming";
+            this.stepsEl.innerHTML = resolved
+                .map((entry, index) => {
+                const { item, state, isCurrent, interactive } = entry;
+                // Blocked / failed / disabled are said out loud on the surface; the
+                // positional states get a screen-reader word so colour and a number
+                // are never the only carriers of the state.
+                const explicitStatus = item.status
+                    ? `<span part="step-status">${STEP_STATE_LABEL[state]}</span>
+               ${item.statusNote ? `<span part="step-status-note">${escapeHtml(item.statusNote)}</span>` : ""}`
+                    : `<span part="step-state" class="boe-sr-only">${STEP_STATE_LABEL[state]}</span>`;
                 return `
             <button
               type="button"
               part="step"
               data-state="${state}"
               data-value="${escapeHtml(item.value)}"
-              aria-current="${state === "current" ? "step" : "false"}"
-              tabindex="${index === activeIndex ? "0" : "-1"}"
+              aria-current="${isCurrent ? "step" : "false"}"
+              tabindex="${index === tabbable ? "0" : "-1"}"
+              ${interactive ? "" : "disabled"}
             >
               <span part="marker">${index + 1}</span>
               <span part="content">
                 <strong part="step-label">${escapeHtml(item.label)}</strong>
+                ${explicitStatus}
                 ${item.description ? `<span part="step-description">${escapeHtml(item.description)}</span>` : ""}
               </span>
             </button>
@@ -257,20 +428,21 @@ export class BoxProgressStepsElement extends BaseElement {
             return;
         }
         this.stepsEl.querySelectorAll('[part="step"]').forEach((step, index) => {
-            const state = index < activeIndex ? "complete" : index === activeIndex ? "current" : "upcoming";
+            const entry = resolved[index];
+            if (!entry) {
+                return;
+            }
             const button = step;
-            button.dataset.state = state;
-            button.setAttribute("aria-current", state === "current" ? "step" : "false");
-            button.setAttribute("aria-selected", String(index === activeIndex));
-            button.tabIndex = index === activeIndex ? 0 : -1;
+            button.dataset.state = entry.state;
+            button.setAttribute("aria-current", entry.isCurrent ? "step" : "false");
+            button.tabIndex = index === tabbable ? 0 : -1;
+            button.disabled = !entry.interactive;
+            // Positional states move with `value`; keep the spoken word in step.
+            const stateWord = button.querySelector('[part="step-state"]');
+            if (stateWord) {
+                stateWord.textContent = STEP_STATE_LABEL[entry.state];
+            }
         });
     }
 }
-export const defineBoxProgressStepsElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxProgressStepsElement);
-    return BoxProgressStepsElement;
-};
+ProgressSteps.register();

package/dist/components/feedback/skeleton.d.ts

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxSkeletonElement extends BaseElement {
+export declare class Skeleton extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private skeletonEl;
     private appliedWidth;
@@ -11,4 +12,3 @@ export declare class BoxSkeletonElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxSkeletonElement: (tagName?: string) => typeof BoxSkeletonElement;

package/dist/components/feedback/skeleton.js

@@ -34,7 +34,8 @@ const skeletonStyles = `
 
   ${boeReducedMotionStyles('[part="skeleton"]', "animation: none;")}
 `;
-export class BoxSkeletonElement extends BaseElement {
+export class Skeleton extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["height", "width"];
     }
@@ -85,11 +86,4 @@ export class BoxSkeletonElement extends BaseElement {
         }
     }
 }
-export const defineBoxSkeletonElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxSkeletonElement);
-    return BoxSkeletonElement;
-};
+Skeleton.register();

package/dist/components/feedback/spinner.d.ts

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxSpinnerElement extends BaseElement {
+export declare class Spinner extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private labelEl;
     private indicatorEl;
@@ -11,4 +12,3 @@ export declare class BoxSpinnerElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxSpinnerElement: (tagName?: string) => typeof BoxSpinnerElement;

package/dist/components/feedback/spinner.js

@@ -51,7 +51,8 @@ const spinnerStyles = `
     color: var(--boe-token-text-text-secondary, #6f6f6f);
   }
 `;
-export class BoxSpinnerElement extends BaseElement {
+export class Spinner extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["label", "size"];
     }
@@ -98,11 +99,4 @@ export class BoxSpinnerElement extends BaseElement {
         }
     }
 }
-export const defineBoxSpinnerElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxSpinnerElement);
-    return BoxSpinnerElement;
-};
+Spinner.register();

package/dist/components/feedback/stage-path.d.ts

@@ -0,0 +1,44 @@
+import { BaseElement } from "../../core/index.js";
+/** One point in a record's lifecycle. */
+export interface StagePathStage {
+    id: string;
+    label: string;
+    /** Optional detail shown under the label on the current stage. */
+    description?: string;
+}
+export type StageState = "complete" | "current" | "upcoming";
+/** Attribute payloads are author input — validate every record. */
+export declare const isStagePathStageRecord: (value: unknown) => value is StagePathStage;
+/** State of each stage relative to the current one. */
+export declare const resolveStageStates: (stages: readonly StagePathStage[], currentId: string) => StageState[];
+/**
+ * Horizontal chevron lifecycle tracker for record headers — Draft → In
+ * Review → Approved → Executed.
+ *
+ * Distinct from `box-progress-steps`, which is a vertical setup rail for a
+ * task the reader is working through: this states where a *record* sits in
+ * its lifecycle, is read-only, and belongs in a header rather than a form.
+ *
+ * Rendered as an ordered list with the current stage marked `aria-current`,
+ * so the sequence and the position are both available without relying on the
+ * chevron geometry — which is decoration, and collapses on narrow viewports.
+ */
+export declare class StagePath extends BaseElement {
+    static readonly tagName: string;
+    static get observedAttributes(): string[];
+    private pathEl;
+    private stagesRaw;
+    private stagesCache;
+    get label(): string;
+    set label(value: string);
+    /** Id of the stage the record is at. An unknown id leaves every stage upcoming. */
+    get current(): string;
+    set current(value: string);
+    get stages(): StagePathStage[];
+    set stages(value: StagePathStage[]);
+    /** State of each stage, in order. */
+    get states(): StageState[];
+    protected renderTemplate(): void;
+    protected setupListeners(): void;
+    protected update(): void;
+}