@unofficialbox/box-open-elements 0.1.0

package/dist/components/layout/app-shell.js

@@ -0,0 +1,258 @@
+import { BaseElement } from "../../core/index.js";
+import { boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-app-shell";
+const appShellStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+  }
+
+  [part="shell"] {
+    display: grid;
+    grid-template-rows: auto 1fr auto;
+    min-height: 100%;
+    border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 82%, transparent);
+    border-radius: ${boeRadius.large};
+    background: var(--boe-token-surface-surface, #ffffff);
+    color: var(--boe-token-text-text, #222222);
+    overflow: hidden;
+    container-type: inline-size;
+    container-name: boe-app-shell;
+  }
+
+  [part="header"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    justify-content: space-between;
+    gap: 0.6rem;
+    padding: 0.65rem 0.75rem;
+    border-bottom: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 68%, transparent);
+    background: color-mix(in srgb, var(--boe-token-surface-surface-secondary, #fbfbfb) 94%, var(--boe-token-surface-surface, #ffffff) 6%);
+  }
+
+  [part="header-main"] {
+    display: grid;
+    gap: 0.2rem;
+  }
+
+  [part="header-main"] ::slotted([slot="eyebrow"]) {
+    font-size: 0.8rem;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+
+  [part="title"] {
+    margin: 0;
+    font: inherit;
+    font-size: 1.1rem;
+    font-weight: 700;
+    line-height: 1.2;
+  }
+
+  [part="header-actions"] {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 0.55rem;
+  }
+
+  [part="frame"] {
+    display: grid;
+    grid-template-columns: minmax(11rem, auto) 1fr minmax(11rem, auto);
+    align-items: stretch;
+    min-height: 0;
+  }
+
+  [part="nav"] {
+    padding: 0.65rem;
+    border-right: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 68%, transparent);
+    background: color-mix(in srgb, var(--boe-token-surface-surface-secondary, #fbfbfb) 94%, var(--boe-token-surface-surface, #ffffff) 6%);
+  }
+
+  [part="main"] {
+    min-width: 0;
+    padding: 0.7rem;
+    background: var(--boe-token-surface-surface, #ffffff);
+  }
+
+  [part="aside"] {
+    padding: 0.65rem;
+    border-left: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 68%, transparent);
+    background: color-mix(in srgb, var(--boe-token-surface-surface-secondary, #fbfbfb) 94%, var(--boe-token-surface-surface, #ffffff) 6%);
+  }
+
+  [part="nav"][hidden],
+  [part="aside"][hidden],
+  [part="footer"][hidden] {
+    display: none;
+  }
+
+  [part="frame"]:not(:has([part="nav"]:not([hidden]))):not(:has([part="aside"]:not([hidden]))) {
+    grid-template-columns: 1fr;
+  }
+
+  [part="frame"]:has([part="nav"]:not([hidden])):not(:has([part="aside"]:not([hidden]))) {
+    grid-template-columns: minmax(11rem, auto) 1fr;
+  }
+
+  [part="frame"]:not(:has([part="nav"]:not([hidden]))):has([part="aside"]:not([hidden])) {
+    grid-template-columns: 1fr minmax(11rem, auto);
+  }
+
+  [part="footer"] {
+    padding: 0.55rem 0.75rem;
+    border-top: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 68%, transparent);
+    background: color-mix(in srgb, var(--boe-token-surface-surface-secondary, #fbfbfb) 94%, var(--boe-token-surface-surface, #ffffff) 6%);
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    font-size: 0.86rem;
+  }
+
+  /* Narrow shells stack nav → main → aside instead of a three-column frame. */
+  @container boe-app-shell (max-width: 48rem) {
+    [part="frame"] {
+      grid-template-columns: 1fr;
+    }
+
+    [part="frame"]:has([part="nav"]:not([hidden])):not(:has([part="aside"]:not([hidden]))),
+    [part="frame"]:not(:has([part="nav"]:not([hidden]))):has([part="aside"]:not([hidden])),
+    [part="frame"]:has([part="nav"]:not([hidden])):has([part="aside"]:not([hidden])) {
+      grid-template-columns: 1fr;
+    }
+
+    [part="nav"] {
+      border-right: 0;
+      border-bottom: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 68%, transparent);
+    }
+
+    [part="aside"] {
+      border-left: 0;
+      border-top: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 68%, transparent);
+    }
+  }
+`;
+export class BoxAppShellElement extends BaseElement {
+    static get observedAttributes() {
+        return ["heading", "nav-label", "aside-label"];
+    }
+    shellEl;
+    titleEl;
+    navEl;
+    asideEl;
+    footerEl;
+    navSlot;
+    asideSlot;
+    footerSlot;
+    slotObserver = null;
+    get heading() {
+        return this.getAttribute("heading") ?? "App Shell";
+    }
+    set heading(value) {
+        this.setAttribute("heading", value);
+    }
+    get navLabel() {
+        return this.getAttribute("nav-label") ?? "Primary";
+    }
+    set navLabel(value) {
+        this.setAttribute("nav-label", value);
+    }
+    get asideLabel() {
+        return this.getAttribute("aside-label") ?? "Context";
+    }
+    set asideLabel(value) {
+        this.setAttribute("aside-label", value);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${appShellStyles}</style>
+      <section part="shell">
+        <header part="header">
+          <div part="header-main">
+            <slot name="eyebrow"></slot>
+            <h2 part="title"></h2>
+          </div>
+          <div part="header-actions">
+            <slot name="header-actions"></slot>
+          </div>
+        </header>
+        <div part="frame">
+          <nav part="nav" aria-label="Primary">
+            <slot name="nav"></slot>
+          </nav>
+          <main part="main">
+            <slot></slot>
+          </main>
+          <aside part="aside" aria-label="Context">
+            <slot name="aside"></slot>
+          </aside>
+        </div>
+        <footer part="footer">
+          <slot name="footer"></slot>
+        </footer>
+      </section>
+    `;
+        this.shellEl = this.shadowRoot.querySelector('[part="shell"]');
+        this.titleEl = this.shadowRoot.querySelector('[part="title"]');
+        this.navEl = this.shadowRoot.querySelector('[part="nav"]');
+        this.asideEl = this.shadowRoot.querySelector('[part="aside"]');
+        this.footerEl = this.shadowRoot.querySelector('[part="footer"]');
+        this.navSlot = this.shadowRoot.querySelector('slot[name="nav"]');
+        this.asideSlot = this.shadowRoot.querySelector('slot[name="aside"]');
+        this.footerSlot = this.shadowRoot.querySelector('slot[name="footer"]');
+    }
+    setupListeners() {
+        this.navSlot.addEventListener("slotchange", () => this.syncLandmarkVisibility());
+        this.asideSlot.addEventListener("slotchange", () => this.syncLandmarkVisibility());
+        this.footerSlot.addEventListener("slotchange", () => this.syncLandmarkVisibility());
+        // Cover hosts (incl. jsdom) that do not emit slotchange for light-DOM appends.
+        this.slotObserver = new MutationObserver(() => this.syncLandmarkVisibility());
+        this.slotObserver.observe(this, {
+            childList: true,
+        });
+    }
+    disconnectedCallback() {
+        this.slotObserver?.disconnect();
+        this.slotObserver = null;
+    }
+    hasNamedSlotContent(name, slot) {
+        // Prefer direct light-DOM children — jsdom often leaves slot.assignedNodes() empty
+        // even when slotted children are present.
+        if (Array.from(this.children).some(el => el.getAttribute("slot") === name)) {
+            return true;
+        }
+        return slot.assignedNodes({ flatten: true }).length > 0;
+    }
+    syncLandmarkVisibility() {
+        if (!this.navEl || !this.asideEl || !this.footerEl) {
+            return;
+        }
+        this.navEl.hidden = !this.hasNamedSlotContent("nav", this.navSlot);
+        this.asideEl.hidden = !this.hasNamedSlotContent("aside", this.asideSlot);
+        this.footerEl.hidden = !this.hasNamedSlotContent("footer", this.footerSlot);
+    }
+    update() {
+        if (!this.shellEl || !this.titleEl || !this.navEl || !this.asideEl) {
+            return;
+        }
+        const heading = this.heading;
+        this.shellEl.setAttribute("aria-label", heading);
+        this.titleEl.textContent = heading;
+        this.navEl.setAttribute("aria-label", this.navLabel);
+        this.asideEl.setAttribute("aria-label", this.asideLabel);
+        this.syncLandmarkVisibility();
+    }
+}
+export const defineBoxAppShellElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxAppShellElement);
+    return BoxAppShellElement;
+};

package/dist/components/layout/divider.d.ts

@@ -0,0 +1,12 @@
+import { BaseElement } from "../../core/index.js";
+export declare class BoxDividerElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private dividerEl;
+    get label(): string;
+    set label(value: string);
+    get orientation(): string;
+    set orientation(value: string);
+    protected renderTemplate(): void;
+    protected update(): void;
+}
+export declare const defineBoxDividerElement: (tagName?: string) => typeof BoxDividerElement;

package/dist/components/layout/divider.js

@@ -0,0 +1,119 @@
+import { BaseElement } from "../../core/index.js";
+const DEFAULT_TAG_NAME = "box-divider";
+const escapeHtml = (value) => value
+    .replaceAll("&", "&")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+const dividerStyles = `
+  :host {
+    display: block;
+    /* A horizontal divider spans its container even when placed as a flex item. */
+    inline-size: 100%;
+    color: inherit;
+    font: inherit;
+  }
+
+  :host([orientation="vertical"]) {
+    display: inline-block;
+    inline-size: auto;
+    block-size: 100%;
+    vertical-align: middle;
+  }
+
+  [part="divider"] {
+    display: flex;
+    align-items: center;
+    gap: 0.55rem;
+    inline-size: 100%;
+  }
+
+  :host([orientation="vertical"]) [part="divider"] {
+    flex-direction: column;
+    inline-size: auto;
+    block-size: 100%;
+    min-block-size: 1rem;
+  }
+
+  [part~="line"] {
+    flex: 1 1 0%;
+    block-size: 1px;
+    border: 0;
+    background: var(--boe-token-stroke-stroke, #e8e8e8);
+  }
+
+  :host([orientation="vertical"]) [part~="line"] {
+    inline-size: 1px;
+    block-size: auto;
+    align-self: stretch;
+  }
+
+  [part="label"] {
+    flex: 0 0 auto;
+    font-size: 0.72rem;
+    font-weight: 700;
+    letter-spacing: 0.08em;
+    text-transform: uppercase;
+    white-space: nowrap;
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+  }
+`;
+export class BoxDividerElement extends BaseElement {
+    static get observedAttributes() {
+        return ["label", "orientation"];
+    }
+    dividerEl;
+    get label() {
+        return this.getAttribute("label") ?? "";
+    }
+    set label(value) {
+        this.setAttribute("label", value);
+    }
+    get orientation() {
+        return this.getAttribute("orientation") === "vertical" ? "vertical" : "horizontal";
+    }
+    set orientation(value) {
+        this.setAttribute("orientation", value);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${dividerStyles}</style>
+      <div part="divider" role="separator"></div>
+    `;
+        this.dividerEl = this.shadowRoot.querySelector('[part="divider"]');
+    }
+    update() {
+        if (!this.dividerEl) {
+            return;
+        }
+        const orientation = this.orientation;
+        const label = this.label;
+        // A vertical divider never carries a label; only horizontal section dividers do.
+        const hasLabel = orientation === "horizontal" && label.length > 0;
+        this.dividerEl.setAttribute("aria-orientation", orientation);
+        if (hasLabel) {
+            this.dividerEl.setAttribute("aria-label", label);
+            this.dividerEl.innerHTML = `
+        <span part="line line-start"></span>
+        <span part="label">${escapeHtml(label)}</span>
+        <span part="line line-end"></span>
+      `;
+        }
+        else {
+            this.dividerEl.removeAttribute("aria-label");
+            this.dividerEl.innerHTML = `<span part="line"></span>`;
+        }
+    }
+}
+export const defineBoxDividerElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxDividerElement);
+    return BoxDividerElement;
+};

package/dist/components/layout/nav-sidebar.d.ts

@@ -0,0 +1,23 @@
+import { BaseElement } from "../../core/index.js";
+/**
+ * A collapsible navigation rail for the explorer/workspace shell. It owns no
+ * transport and no routing: it is structure (a labelled `<nav>` with header,
+ * body, and footer slots) plus a reflected `collapsed` state that narrows the
+ * rail to its icon strip. Pair it with `box-sidebar-toggle-button`, wiring the
+ * button's `toggle` event to this element's `collapsed` property.
+ *
+ * Collapsed icon contract: slot `a`/`button` rows with an icon and a
+ * `[data-nav-label]` span. Host exposes `--boe-nav-label-display` (`none` when
+ * collapsed) so light-DOM CSS can hide labels without piercing the shadow tree.
+ */
+export declare class BoxNavSidebarElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private sidebarEl;
+    get collapsed(): boolean;
+    set collapsed(value: boolean);
+    get label(): string;
+    set label(value: string);
+    protected renderTemplate(): void;
+    protected update(): void;
+}
+export declare const defineBoxNavSidebarElement: (tagName?: string) => typeof BoxNavSidebarElement;

package/dist/components/layout/nav-sidebar.js

@@ -0,0 +1,167 @@
+import { BaseElement } from "../../core/index.js";
+import { boeMotionDuration, boeMotionEasing } from "../../foundations/motion/index.js";
+import { boeRadius } from "../../foundations/geometry/index.js";
+const DEFAULT_TAG_NAME = "box-nav-sidebar";
+const navSidebarStyles = `
+  :host {
+    display: block;
+    color: inherit;
+    font: inherit;
+    /* Consumers hide label spans with: [data-nav-label] { display: var(--boe-nav-label-display, inline); } */
+    --boe-nav-label-display: inline;
+  }
+
+  :host([collapsed]) {
+    --boe-nav-label-display: none;
+  }
+
+  [part="sidebar"] {
+    display: flex;
+    flex-direction: column;
+    gap: 0.55rem;
+    block-size: 100%;
+    inline-size: 14rem;
+    padding: 0.65rem 0.6rem;
+    box-sizing: border-box;
+    border: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 82%, transparent);
+    border-radius: ${boeRadius.large};
+    background: color-mix(in srgb, var(--boe-token-surface-surface-secondary, #fbfbfb) 94%, var(--boe-token-surface-surface, #ffffff) 6%);
+    color: var(--boe-token-text-text, #222222);
+    overflow: hidden;
+    transition: inline-size ${boeMotionDuration.medium} ${boeMotionEasing.standard};
+  }
+
+  /* Collapsed: shrink to an icon strip. The header and footer usually hold
+     branding and labels, so they hide; the body (icon nav) stays. */
+  [part="sidebar"][data-collapsed="true"] {
+    inline-size: 3.75rem;
+    padding-inline: 0.55rem;
+  }
+
+  [part="header"],
+  [part="footer"] {
+    display: block;
+    min-block-size: 0;
+  }
+
+  [part="sidebar"][data-collapsed="true"] [part="header"],
+  [part="sidebar"][data-collapsed="true"] [part="footer"] {
+    display: none;
+  }
+
+  [part="body"] {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    flex: 1 1 auto;
+    min-block-size: 0;
+    overflow-y: auto;
+  }
+
+  /* Icon-strip contract: slotted anchors/buttons lay out as nav rows. Pair with
+     [data-nav-icon] / [data-nav-label] in light DOM (see docs example). */
+  [part="body"] ::slotted(a),
+  [part="body"] ::slotted(button) {
+    display: flex;
+    align-items: center;
+    gap: 0.55rem;
+    min-block-size: 1.9rem;
+    padding: 0.3rem 0.45rem;
+    border-radius: ${boeRadius.nav};
+    color: inherit;
+    text-decoration: none;
+    font: inherit;
+    box-sizing: border-box;
+  }
+
+  [part="body"] ::slotted(button) {
+    appearance: none;
+    border: 0;
+    background: transparent;
+    cursor: pointer;
+    text-align: start;
+    width: 100%;
+  }
+
+  [part="body"] ::slotted(a:hover),
+  [part="body"] ::slotted(button:hover) {
+    background: color-mix(in srgb, var(--boe-token-surface-surface-brand, #0061d5) 8%, var(--boe-token-surface-surface, #ffffff) 92%);
+  }
+
+  [part="sidebar"][data-collapsed="true"] ::slotted(a),
+  [part="sidebar"][data-collapsed="true"] ::slotted(button) {
+    justify-content: center;
+    padding-inline: 0.25rem;
+  }
+
+  [part="footer"] {
+    padding-block-start: 0.75rem;
+    border-top: 1px solid color-mix(in srgb, var(--boe-token-stroke-stroke, #e8e8e8) 68%, transparent);
+    color: var(--boe-token-text-text-secondary, #6f6f6f);
+    font-size: 0.86rem;
+  }
+`;
+/**
+ * A collapsible navigation rail for the explorer/workspace shell. It owns no
+ * transport and no routing: it is structure (a labelled `<nav>` with header,
+ * body, and footer slots) plus a reflected `collapsed` state that narrows the
+ * rail to its icon strip. Pair it with `box-sidebar-toggle-button`, wiring the
+ * button's `toggle` event to this element's `collapsed` property.
+ *
+ * Collapsed icon contract: slot `a`/`button` rows with an icon and a
+ * `[data-nav-label]` span. Host exposes `--boe-nav-label-display` (`none` when
+ * collapsed) so light-DOM CSS can hide labels without piercing the shadow tree.
+ */
+export class BoxNavSidebarElement extends BaseElement {
+    static get observedAttributes() {
+        return ["collapsed", "label"];
+    }
+    sidebarEl;
+    get collapsed() {
+        return this.hasAttribute("collapsed");
+    }
+    set collapsed(value) {
+        this.toggleAttribute("collapsed", value);
+    }
+    get label() {
+        return this.getAttribute("label") ?? "Sidebar";
+    }
+    set label(value) {
+        this.setAttribute("label", value);
+    }
+    renderTemplate() {
+        if (!this.shadowRoot) {
+            return;
+        }
+        this.shadowRoot.innerHTML = `
+      <style>${navSidebarStyles}</style>
+      <nav part="sidebar">
+        <div part="header">
+          <slot name="header"></slot>
+        </div>
+        <div part="body">
+          <slot></slot>
+        </div>
+        <div part="footer">
+          <slot name="footer"></slot>
+        </div>
+      </nav>
+    `;
+        this.sidebarEl = this.shadowRoot.querySelector('[part="sidebar"]');
+    }
+    update() {
+        if (!this.sidebarEl) {
+            return;
+        }
+        this.sidebarEl.dataset.collapsed = this.collapsed ? "true" : "false";
+        this.sidebarEl.setAttribute("aria-label", this.label);
+    }
+}
+export const defineBoxNavSidebarElement = (tagName = DEFAULT_TAG_NAME) => {
+    const existingElement = customElements.get(tagName);
+    if (existingElement) {
+        return existingElement;
+    }
+    customElements.define(tagName, BoxNavSidebarElement);
+    return BoxNavSidebarElement;
+};

package/dist/components/layout/section.d.ts

@@ -0,0 +1,20 @@
+import { BaseElement } from "../../core/index.js";
+/**
+ * A titled content region: an optional eyebrow, a heading, an optional
+ * description, an `actions` slot for header controls, and a default slot for
+ * content. The `<section>` is labelled by its heading via `aria-labelledby` so
+ * it is announced as a named region. Layout-only — it owns no behavior.
+ */
+export declare class BoxSectionElement extends BaseElement {
+    static get observedAttributes(): string[];
+    private headerMainEl;
+    get heading(): string;
+    set heading(value: string);
+    get eyebrow(): string;
+    set eyebrow(value: string);
+    get description(): string;
+    set description(value: string);
+    protected renderTemplate(): void;
+    protected update(): void;
+}
+export declare const defineBoxSectionElement: (tagName?: string) => typeof BoxSectionElement;