@unofficialbox/box-open-elements 0.1.0

package/dist/components/visuals/illustration.js

@@ -0,0 +1,319 @@
+import { BaseElement } from "../../core/index.js";
+import { DESIGN_SYSTEM_CHANGE_EVENT, resolveDesignIllustration, } from "../../foundations/tokens/registry.js";
+const DEFAULT_TAG_NAME = "box-illustration";
+const illustrationStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+  }
+
+  [part="illustration"] {
+    display: grid;
+    gap: 0.55rem;
+    justify-items: center;
+    margin: 0;
+    text-align: center;
+  }
+
+  [part="art"] {
+    position: relative;
+    display: grid;
+    place-items: center;
+    inline-size: 100%;
+    min-block-size: 10.5rem;
+    isolation: isolate;
+  }
+
+  [part="art"]::before {
+    content: "";
+    position: absolute;
+    inset: 18% 14%;
+    border-radius: 0.75rem;
+    background:
+      radial-gradient(
+        circle at 50% 50%,
+        color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 10%, var(--boe-token-surface-surface, #ffffff) 90%) 0%,
+        color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 4%, transparent) 58%,
+        transparent 100%
+      );
+    filter: blur(10px);
+    z-index: 0;
+  }
+
+  [part="asset"] {
+    display: grid;
+    place-items: center;
+    width: min(11rem, 72%);
+    max-width: 100%;
+    aspect-ratio: 1 / 1;
+    z-index: 1;
+  }
+
+  [part="asset"] > svg {
+    display: block;
+    width: 100%;
+    height: auto;
+    max-width: 100%;
+    overflow: visible;
+    filter: drop-shadow(0 16px 28px rgba(15, 23, 42, 0.08));
+  }
+
+  [part="cloud"] {
+    position: relative;
+    inline-size: 10rem;
+    block-size: 6.75rem;
+    z-index: 1;
+    filter: drop-shadow(0 18px 30px rgba(15, 23, 42, 0.08));
+  }
+
+  [part~="orb"] {
+    position: absolute;
+    display: block;
+    border-radius: 999px;
+    background:
+      linear-gradient(
+        180deg,
+        color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 34%, var(--boe-token-surface-surface, #ffffff) 66%) 0%,
+        color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 16%, var(--boe-token-surface-surface-secondary, #fbfbfb) 84%) 100%
+      );
+    border: 1px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 22%, transparent);
+    box-shadow: 0 14px 26px rgba(15, 23, 42, 0.1);
+  }
+
+  [part~="orb-a"] {
+    inline-size: 4rem;
+    block-size: 4rem;
+    inset: 1.9rem auto auto 0.4rem;
+  }
+
+  [part~="orb-b"] {
+    inline-size: 5rem;
+    block-size: 5rem;
+    inset: 0.35rem auto auto 2.55rem;
+  }
+
+  [part~="orb-c"] {
+    inline-size: 3.85rem;
+    block-size: 3.85rem;
+    inset: 2.15rem auto auto 5.95rem;
+  }
+
+  [part="stack"] {
+    position: relative;
+    inline-size: 10rem;
+    block-size: 7rem;
+    z-index: 1;
+    filter: drop-shadow(0 18px 30px rgba(15, 23, 42, 0.08));
+  }
+
+  [part~="stack-card"] {
+    position: absolute;
+    inset: 1rem auto auto 1.7rem;
+    display: block;
+    inline-size: 6.6rem;
+    block-size: 4.8rem;
+    border-radius: 0.75rem;
+    background: var(--boe-token-surface-surface, #ffffff);
+    border: 1px solid color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 16%, transparent);
+    box-shadow: 0 14px 28px rgba(15, 23, 42, 0.1);
+  }
+
+  [part~="stack-card-one"] {
+    transform: rotate(-10deg);
+  }
+
+  [part~="stack-card-two"] {
+    transform: rotate(0deg);
+  }
+
+  [part~="stack-card-three"] {
+    transform: rotate(10deg);
+  }
+
+  [part="spark-cluster"] {
+    position: relative;
+    inline-size: 9rem;
+    block-size: 7rem;
+    z-index: 1;
+  }
+
+  [part~="spark"] {
+    position: absolute;
+    display: block;
+    inline-size: 1rem;
+    block-size: 1rem;
+    background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 52%, transparent);
+    clip-path: polygon(50% 0%, 62% 38%, 100% 50%, 62% 62%, 50% 100%, 38% 62%, 0% 50%, 38% 38%);
+    filter: drop-shadow(0 8px 12px rgba(15, 23, 42, 0.12));
+  }
+
+  [part~="spark-a"] {
+    inset: 3.2rem auto auto 1rem;
+  }
+
+  [part~="spark-b"] {
+    inline-size: 1.6rem;
+    block-size: 1.6rem;
+    inset: 0.9rem auto auto 3.8rem;
+  }
+
+  [part~="spark-c"] {
+    inset: 3.35rem auto auto 6.9rem;
+  }
+
+  [part="meta"] {
+    display: grid;
+    gap: 0.45rem;
+    justify-items: center;
+    max-inline-size: 28rem;
+  }
+
+  [part="title"] {
+    font-weight: 700;
+    font-size: 1rem;
+    line-height: 1.2;
+  }
+
+  [part="title"][hidden] {
+    display: none;
+  }
+
+  [part~="caption"] {
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    line-height: 1.5;
+  }
+
+  [part~="caption"][hidden] {
+    display: none;
+  }
+`;
+export class BoxIllustrationElement extends BaseElement {
+    handleDesignSystemChange = () => {
+        this.update();
+    };
+    static get observedAttributes() {
+        return ["asset", "caption", "message", "shape", "heading"];
+    }
+    figureEl;
+    artEl;
+    titleEl;
+    captionEl;
+    artSignature = "";
+    get caption() {
+        return this.getAttribute("caption") ?? this.message;
+    }
+    set caption(value) {
+        this.setAttribute("caption", value);
+    }
+    get asset() {
+        return this.getAttribute("asset") ?? "";
+    }
+    set asset(value) {
+        this.setAttribute("asset", value);
+    }
+    get message() {
+        return this.getAttribute("message") ?? this.getAttribute("caption") ?? "";
+    }
+    set message(value) {
+        this.setAttribute("message", value);
+    }
+    get shape() {
+        return this.getAttribute("shape") ?? "cloud";
+    }
+    set shape(value) {
+        this.setAttribute("shape", value);
+    }
+    get heading() {
+        return this.getAttribute("heading") ?? "";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    connectedCallback() {
+        globalThis.addEventListener?.(DESIGN_SYSTEM_CHANGE_EVENT, this.handleDesignSystemChange);
+        super.connectedCallback();
+    }
+    disconnectedCallback() {
+        globalThis.removeEventListener?.(DESIGN_SYSTEM_CHANGE_EVENT, this.handleDesignSystemChange);
+    }
+    renderShape() {
+        switch (this.shape) {
+            case "spark":
+                return `<div part="spark-cluster"><span part="spark spark-a"></span><span part="spark spark-b"></span><span part="spark spark-c"></span></div>`;
+            case "stack":
+                return `<div part="stack"><span part="stack-card stack-card-one"></span><span part="stack-card stack-card-two"></span><span part="stack-card stack-card-three"></span></div>`;
+            default:
+                return `<div part="cloud"><span part="orb orb-a"></span><span part="orb orb-b"></span><span part="orb orb-c"></span></div>`;
+        }
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${illustrationStyles}</style>
+      <figure part="illustration">
+        <div part="art"></div>
+        <figcaption part="meta">
+          <h2 part="title" hidden></h2>
+          <span part="message caption" hidden></span>
+        </figcaption>
+      </figure>
+    `;
+        this.figureEl = this.shadowRoot.querySelector('[part="illustration"]');
+        this.artEl = this.shadowRoot.querySelector('[part="art"]');
+        this.titleEl = this.shadowRoot.querySelector('[part="title"]');
+        this.captionEl = this.shadowRoot.querySelector('[part~="caption"]');
+    }
+    update() {
+        if (!this.figureEl) {
+            return;
+        }
+        const illustrationMarkup = this.asset ? resolveDesignIllustration(this.asset) : null;
+        const artMarkup = illustrationMarkup ? `<div part="asset">${illustrationMarkup}</div>` : this.renderShape();
+        const signature = `${this.asset}|${this.shape}|${illustrationMarkup ?? ""}`;
+        this.figureEl.dataset.shape = this.shape;
+        this.artEl.dataset.assetSource = illustrationMarkup ? "design-system" : "shape";
+        if (signature !== this.artSignature) {
+            this.artSignature = signature;
+            this.artEl.innerHTML = artMarkup;
+        }
+        if (this.heading) {
+            this.titleEl.hidden = false;
+            this.titleEl.textContent = this.heading;
+        }
+        else {
+            this.titleEl.hidden = true;
+            this.titleEl.textContent = "";
+        }
+        if (this.message) {
+            this.captionEl.hidden = false;
+            this.captionEl.textContent = this.message;
+        }
+        else {
+            this.captionEl.hidden = true;
+            this.captionEl.textContent = "";
+        }
+        // Keep image role on the art node only when there is no visible text alternative,
+        // so a heading in figcaption is not swallowed by presentational descendants.
+        if (this.heading || this.message) {
+            this.artEl.setAttribute("aria-hidden", "true");
+            this.artEl.removeAttribute("role");
+            this.artEl.removeAttribute("aria-label");
+        }
+        else {
+            this.artEl.removeAttribute("aria-hidden");
+            this.artEl.setAttribute("role", "img");
+            this.artEl.setAttribute("aria-label", "Illustration");
+        }
+    }
+}
+export const defineBoxIllustrationElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxIllustrationElement);
+    return BoxIllustrationElement;
+};

package/dist/core/controller.d.ts

@@ -0,0 +1,11 @@
+import { TypedEventEmitter, type EventMap, type Unsubscribe } from "./event-emitter.js";
+export declare abstract class Controller<TState, TEvents extends EventMap> {
+    protected readonly events: TypedEventEmitter<TEvents>;
+    protected state: TState;
+    protected constructor(initialState: TState);
+    getState(): Readonly<TState>;
+    subscribe<TKey extends keyof TEvents>(eventName: TKey, listener: (payload: TEvents[TKey]) => void): Unsubscribe;
+    protected setState(nextState: TState): void;
+    protected emit<TKey extends keyof TEvents>(eventName: TKey, payload: TEvents[TKey]): void;
+    destroy(): void;
+}

package/dist/core/controller.js

@@ -0,0 +1,23 @@
+import { TypedEventEmitter } from "./event-emitter.js";
+export class Controller {
+    events = new TypedEventEmitter();
+    state;
+    constructor(initialState) {
+        this.state = initialState;
+    }
+    getState() {
+        return this.state;
+    }
+    subscribe(eventName, listener) {
+        return this.events.on(eventName, listener);
+    }
+    setState(nextState) {
+        this.state = nextState;
+    }
+    emit(eventName, payload) {
+        this.events.emit(eventName, payload);
+    }
+    destroy() {
+        this.events.clear();
+    }
+}

package/dist/core/element.d.ts

@@ -0,0 +1,22 @@
+export declare abstract class BaseElement extends HTMLElement {
+    protected isRendered: boolean;
+    constructor();
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+    attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /**
+     * Subclasses override this to define the initial Shadow DOM structure and styles.
+     * This is only run once during the first connectedCallback.
+     */
+    protected abstract renderTemplate(): void;
+    /**
+     * Subclasses override this to register event listeners on elements within their Shadow DOM.
+     * This is only run once during the first connectedCallback.
+     */
+    protected setupListeners(): void;
+    /**
+     * Subclasses override this to perform in-place mutations (text content, classes,
+     * attributes, dataset etc.) on existing Shadow DOM nodes when state changes.
+     */
+    protected abstract update(): void;
+}

package/dist/core/element.js

@@ -0,0 +1,28 @@
+export class BaseElement extends HTMLElement {
+    isRendered = false;
+    constructor() {
+        super();
+        this.attachShadow({ mode: "open" });
+    }
+    connectedCallback() {
+        if (!this.isRendered) {
+            this.renderTemplate();
+            this.isRendered = true;
+            this.setupListeners();
+        }
+        this.update();
+    }
+    disconnectedCallback() {
+        // Optional teardown for subclasses to override
+    }
+    attributeChangedCallback(name, oldValue, newValue) {
+        if (this.isRendered && oldValue !== newValue) {
+            this.update();
+        }
+    }
+    /**
+     * Subclasses override this to register event listeners on elements within their Shadow DOM.
+     * This is only run once during the first connectedCallback.
+     */
+    setupListeners() { }
+}

package/dist/core/event-emitter.d.ts

@@ -0,0 +1,9 @@
+export type Unsubscribe = () => void;
+export type EventMap = object;
+export declare class TypedEventEmitter<TEvents extends EventMap> {
+    private listeners;
+    on<TKey extends keyof TEvents>(eventName: TKey, listener: (payload: TEvents[TKey]) => void): Unsubscribe;
+    off<TKey extends keyof TEvents>(eventName: TKey, listener: (payload: TEvents[TKey]) => void): void;
+    emit<TKey extends keyof TEvents>(eventName: TKey, payload: TEvents[TKey]): void;
+    clear(): void;
+}

package/dist/core/event-emitter.js

@@ -0,0 +1,33 @@
+export class TypedEventEmitter {
+    listeners = new Map();
+    on(eventName, listener) {
+        const eventListeners = this.listeners.get(eventName) ?? new Set();
+        eventListeners.add(listener);
+        this.listeners.set(eventName, eventListeners);
+        return () => {
+            this.off(eventName, listener);
+        };
+    }
+    off(eventName, listener) {
+        const eventListeners = this.listeners.get(eventName);
+        if (!eventListeners) {
+            return;
+        }
+        eventListeners.delete(listener);
+        if (eventListeners.size === 0) {
+            this.listeners.delete(eventName);
+        }
+    }
+    emit(eventName, payload) {
+        const eventListeners = this.listeners.get(eventName);
+        if (!eventListeners) {
+            return;
+        }
+        for (const listener of eventListeners) {
+            listener(payload);
+        }
+    }
+    clear() {
+        this.listeners.clear();
+    }
+}

package/dist/core/form-associated.d.ts

@@ -0,0 +1,63 @@
+import { BaseElement } from "./element.js";
+/**
+ * Form-associated custom element base for Batch 5.
+ *
+ * Subclasses set `static formAssociated = true` (inherited), call
+ * `syncFormAssociation()` whenever the submitted value or validity changes,
+ * and implement `getFormValue` / `restoreFormValue`.
+ *
+ * jsdom's `ElementInternals` stubs omit `setFormValue` / `setValidity`; we keep
+ * a mirror store so unit tests can assert submission values via
+ * `getMirroredFormValue`.
+ */
+export type FormValue = string | File | FormData | null;
+export declare const getMirroredFormValue: (internals: ElementInternals) => FormValue;
+/** Build a multi-entry FormData payload (empty selection → `null`). */
+export declare const formDataFromNamedValues: (name: string, values: readonly string[]) => FormData | null;
+/** Restore string[] from FormData / JSON / comma-separated / single string. */
+export declare const stringValuesFromFormValue: (value: FormValue, name: string) => string[];
+/** Range pair as FormData (`${name}-start` / `${name}-end`). */
+export declare const formDataFromRange: (name: string, start: number, end: number) => FormData;
+export declare const rangeFromFormValue: (value: FormValue, name: string, fallback: {
+    start: number;
+    end: number;
+}) => {
+    start: number;
+    end: number;
+};
+/** Shared invalid-state styles using the status-error token. */
+export declare const boeFormFieldErrorStyles = "\n  :host([invalid]) [part=\"input\"],\n  :host([invalid]) [part=\"textarea\"],\n  :host([invalid]) [part=\"select\"],\n  :host([invalid]) [part=\"control\"],\n  :host([invalid]) [part=\"editor\"] {\n    border-color: var(--boe-token-surface-status-surface-error, #ed3757);\n  }\n\n  :host([invalid]) [part=\"input\"]:focus-visible,\n  :host([invalid]) [part=\"textarea\"]:focus-visible,\n  :host([invalid]) [part=\"select\"]:focus-visible,\n  :host([invalid]) [part=\"control\"]:focus-visible {\n    border-color: var(--boe-token-surface-status-surface-error, #ed3757);\n    box-shadow: 0 0 0 3px color-mix(in srgb, var(--boe-token-surface-status-surface-error, #ed3757) 22%, transparent);\n  }\n\n  [part=\"error-message\"] {\n    margin: 0;\n    color: var(--boe-token-surface-status-surface-error, #ed3757);\n    font-size: 0.82rem;\n    line-height: 1.35;\n  }\n\n  [part=\"error-message\"][hidden] {\n    display: none;\n  }\n";
+export declare const FORM_ERROR_MESSAGE_ID = "boe-field-error";
+export declare const formErrorMessageMarkup: () => string;
+export declare abstract class FormAssociatedElement extends BaseElement {
+    static formAssociated: boolean;
+    /** Attributes every form control should observe (merge into subclass lists). */
+    static readonly formObservedAttributes: readonly ["name", "invalid", "error-message"];
+    /** ElementInternals for form association (public for tests / advanced hosts). */
+    readonly internals: ElementInternals;
+    private defaultFormValue;
+    private defaultCaptured;
+    constructor();
+    get name(): string;
+    set name(value: string);
+    get invalid(): boolean;
+    set invalid(value: boolean);
+    get errorMessage(): string;
+    set errorMessage(value: string);
+    /** Value reported to the owning form (`null` omits the control). */
+    protected abstract getFormValue(): FormValue;
+    /** Restore a value from form reset / autocomplete. */
+    protected abstract restoreFormValue(value: FormValue): void;
+    connectedCallback(): void;
+    formResetCallback(): void;
+    formStateRestoreCallback(state: string | File | FormData | null): void;
+    /** Push the current value + validity into ElementInternals. */
+    protected syncFormAssociation(): void;
+    /**
+     * Apply `aria-invalid` / `aria-errormessage` on the focusable control and
+     * update the error message region.
+     */
+    protected applyInvalidState(control: HTMLElement | null | undefined, messageEl: HTMLElement | null | undefined): void;
+    /** Apply invalid ARIA to every focusable control in a multi-option field. */
+    protected applyInvalidStateToControls(controls: Iterable<HTMLElement | null | undefined>, messageEl: HTMLElement | null | undefined): void;
+}