@unofficialbox/box-open-elements 0.3.0 → 0.5.0

package/README.md

@@ -1,7 +1,15 @@
+<p align="center">
+  <a href="https://unofficialbox.github.io/box-open-elements">
+    <img src="https://raw.githubusercontent.com/unofficialbox/box-open-elements/main/assets/banner.svg" alt="Box Open Elements — framework-agnostic Web Components that track Box's design language" width="100%">
+  </a>
+</p>
+
 # box-open-elements
 
 `box-open-elements` is an open, framework-agnostic design system and web component library for Box-style experiences.
 
+> **Community project — not affiliated with, authorized, or endorsed by Box, Inc.** “Box” is a trademark of Box, Inc. This library tracks Box’s public design language for interoperability; it ships no Box code.
+
 It is a ground-up rebuild of [`box-open-web-components`](https://github.com/unofficialbox/box-open-web-components), carrying forward that repo's validated architecture, docs, and research — without its accumulated baggage — under a new industry-standard taxonomy:
 
 - **Foundations** — design decisions as data: tokens, color, typography, iconography, accessibility, theming
@@ -18,6 +26,16 @@ The guiding idea is unchanged: predictable, extensible building blocks that are
 - accessibility semantics and keyboard support as part of the component contract
 - injected transport contracts instead of SDK coupling
 
+## Preview
+
+[![The box-open-elements documentation site](https://raw.githubusercontent.com/unofficialbox/box-open-elements/main/docs/screenshots/docs-site/home.png)](https://unofficialbox.github.io/box-open-elements)
+
+The **[live docs site](https://unofficialbox.github.io/box-open-elements)** browses the full catalog with live previews, an events/properties inspector, per-framework code snippets (React / Angular / Vue / Svelte / HTML), and the foundations pages.
+
+Components track Box’s design language out of the box — tokens-driven, light and dark, keyboard-accessible:
+
+![A selection of form components — text field, search, select, checkboxes, radios, and a pill-selector dropdown](https://raw.githubusercontent.com/unofficialbox/box-open-elements/main/docs/screenshots/gallery/forms.png)
+
 ## Setup
 
 This package uses Bun as its package manager and task runner.
@@ -48,13 +66,14 @@ Full catalog parity with the reference repo, plus every scoped gap the research
 - `src/core` — typed event emitter, controller base class, `BaseElement` (in-place shadow DOM render contract), and `FormAssociatedElement` (native form participation + invalid state)
 - `src/foundations/tokens` — the design-system registry (tokens, icons, illustrations), the Box default bundle, and the Box dark bundle, retoned to Box's modernized Blueprint palette with an Inter typography baseline; shared interaction helpers (`interaction.ts`) for focus/hover/active/disabled
 - `src/foundations/motion` — shared duration/easing vocabulary and reduced-motion CSS helper
+- `src/foundations/profiles` — typed runtime profiles for density, geometry, typography, elevation, and motion
 - `src/foundations/icons` — the generated Box iconography manifest and alias layer
 - `tools/style-bridge` — CSS/SCSS → BOE token/selector bridge (`bun run style-bridge`; BUE explorer: `bun run style-bridge:bue-explorer`)
-- `src/components` — 72 components across all ten categories, including the Phase 5 gap fills (`box-chip`, `box-divider`, `box-calendar`, `box-tag-input`, `box-nav-sidebar`, `box-sidebar-toggle-button`, `box-grid-view`, `box-fieldset`, `box-section`, `box-error-mask`, `box-draggable-list`, `box-nudge`, `box-pill-cloud`, `box-pill-selector-dropdown`, `box-datalist-item`, `box-contact-datalist-item`, `box-category-selector`)
+- `src/components` — 78 components across all ten categories, including the Phase 5 gap fills (`box-chip`, `box-divider`, `box-calendar`, `box-tag-input`, `box-nav-sidebar`, `box-sidebar-toggle-button`, `box-grid-view`, `box-fieldset`, `box-section`, `box-error-mask`, `box-draggable-list`, `box-nudge`, `box-pill-cloud`, `box-pill-selector-dropdown`, `box-datalist-item`, `box-contact-datalist-item`, `box-category-selector`)
 - `src/patterns/content-explorer` — the full headless explorer stack (collection, navigation, selection, actions, facade controller, data-source contracts, Box transport, wire schemas) plus the `box-explorer-*` presentation adapters and the composed `box-content-explorer` surface
 - `src/patterns/{search,item,metadata,share,preview,file-request,task,governance,insights}` — all nine composition/workflow areas, including contracts and wire schemas for metadata and share, the provider-neutral preview adapter stack, the pluggable `box-preview-element`, and the share workflows (`box-presence`, `box-invite-collaborators-modal`, `box-unified-share-modal`, `box-access-stats`, `box-collaborator-avatars`)
 - `packages/box-server` — a dependency-free server-side adapter: CCG auth + REST client, Box-backed explorer/share/metadata data sources, DTO mappers, and framework-neutral route handlers (see [docs/integration/box-server.md](./docs/integration/box-server.md))
-- `packages/react` — optional React wrappers (`@box-open-elements/react`); the validated surface ships `BoxButton`, `BoxTextField`, and `BoxSelect`. React, Angular, Vue, and Svelte progress is tracked in [docs/integration/framework-adapters.md](./docs/integration/framework-adapters.md).
+- `packages/react` — optional React wrappers (`@box-open-elements/react`); the validated surface ships `Button`, `TextField`, and `Select`. React, Angular, Vue, and Svelte progress is tracked in [docs/integration/framework-adapters.md](./docs/integration/framework-adapters.md).
 - `storybook/` — a Bun-native workshop: typed stories → identity-guarded extracted JSON → a self-contained, separately-deployable static site, with no Storybook/Vite runtime or consumer dependency (see [storybook/README.md](./storybook/README.md))
 - Docs site + CI — live GitHub Pages deploy, Storybook-backed variant dropdown, and a strict pixel-diff visual-regression gate in CI
 
@@ -66,14 +85,12 @@ Everything in the [components catalog](./docs/components/catalog.md) and [patter
 
 ```ts
 import {
-  applyDesignTokens,
-  registerBoxDefaultDesignSystem,
-} from "@unofficialbox/box-open-elements/foundations/tokens";
-import { defineBoxButtonElement } from "@unofficialbox/box-open-elements/components/actions/button";
-
-registerBoxDefaultDesignSystem({ setActive: true });
-applyDesignTokens(document.documentElement, "box-default");
-defineBoxButtonElement();
+  createThemeController,
+} from "@unofficialbox/box-open-elements/foundations/theming";
+import { Button } from "@unofficialbox/box-open-elements";
+
+const theme = createThemeController();
+theme.start();
 ```
 
 ```html
@@ -104,10 +121,18 @@ Workflow patterns begin as headless behavior and gain presentation adapters, so
 - root exports: `@unofficialbox/box-open-elements`
 - shared runtime: `@unofficialbox/box-open-elements/core`
 - foundations: `@unofficialbox/box-open-elements/foundations/<module>`
-- components: `@unofficialbox/box-open-elements/components/<category>/<name>`
+- optimized component entrypoints: `@unofficialbox/box-open-elements/<name>`
 - patterns: `@unofficialbox/box-open-elements/patterns/<area>` and `@unofficialbox/box-open-elements/patterns/<area>/<module>`
 
-New exports follow the wildcard contract by default instead of adding explicit `package.json` entries. See [docs/api-guidelines.md](./docs/api-guidelines.md).
+The root entrypoint is the concise convenience API and registers the full
+catalog. Flat component entrypoints register only the imported component:
+
+```ts
+import { Accordion, Avatar, Button, Switch } from "@unofficialbox/box-open-elements";
+import { TextField } from "@unofficialbox/box-open-elements/text-field";
+```
+
+See [docs/api-guidelines.md](./docs/api-guidelines.md).
 
 ## Documentation
 

package/dist/components/actions/button-group.d.ts

@@ -3,7 +3,8 @@ export interface ButtonGroupOption {
     label: string;
     value: string;
 }
-export declare class BoxButtonGroupElement extends BaseElement {
+export declare class ButtonGroup extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     private groupEl;
@@ -19,4 +20,3 @@ export declare class BoxButtonGroupElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxButtonGroupElement: (tagName?: string) => typeof BoxButtonGroupElement;

package/dist/components/actions/button-group.js

@@ -91,7 +91,8 @@ const buttonGroupStyles = `
     opacity: 0.55;
   }
 `;
-export class BoxButtonGroupElement extends BaseElement {
+export class ButtonGroup extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["label", "layout", "options", "value"];
     }
@@ -245,11 +246,4 @@ export class BoxButtonGroupElement extends BaseElement {
         });
     }
 }
-export const defineBoxButtonGroupElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxButtonGroupElement);
-    return BoxButtonGroupElement;
-};
+ButtonGroup.register();

package/dist/components/actions/button.d.ts

@@ -1,6 +1,7 @@
 import { BaseElement } from "../../core/index.js";
 export type ButtonType = "button" | "submit" | "reset";
-export declare class BoxButtonElement extends BaseElement {
+export declare class Button extends BaseElement {
+    static readonly tagName: string;
     static formAssociated: boolean;
     static get observedAttributes(): string[];
     private buttonEl;
@@ -28,4 +29,3 @@ export declare class BoxButtonElement extends BaseElement {
     private syncIconVisibility;
     protected update(): void;
 }
-export declare const defineBoxButtonElement: (tagName?: string) => typeof BoxButtonElement;

package/dist/components/actions/button.js

@@ -163,7 +163,8 @@ const buttonStyles = `
     [part="spinner"] { animation-duration: 1.6s; }
   }
 `;
-export class BoxButtonElement extends BaseElement {
+export class Button extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static formAssociated = true;
     static get observedAttributes() {
         return ["disabled", "label", "size", "tone", "is-loading", "type"];
@@ -284,11 +285,4 @@ export class BoxButtonElement extends BaseElement {
         this.syncIconVisibility();
     }
 }
-export const defineBoxButtonElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxButtonElement);
-    return BoxButtonElement;
-};
+Button.register();

package/dist/components/actions/icon-button.d.ts

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxIconButtonElement extends BaseElement {
+export declare class IconButton extends BaseElement {
+    static readonly tagName: string;
     private readonly handleDesignSystemChange;
     static get observedAttributes(): string[];
     private buttonEl;
@@ -17,4 +18,3 @@ export declare class BoxIconButtonElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxIconButtonElement: (tagName?: string) => typeof BoxIconButtonElement;

package/dist/components/actions/icon-button.js

@@ -98,7 +98,8 @@ const iconButtonStyles = `
     fill: currentColor;
   }
 `;
-export class BoxIconButtonElement extends BaseElement {
+export class IconButton extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     handleDesignSystemChange = () => {
         if (this.isRendered) {
             this.update();
@@ -177,11 +178,4 @@ export class BoxIconButtonElement extends BaseElement {
         this.iconEl.innerHTML = iconMarkup;
     }
 }
-export const defineBoxIconButtonElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxIconButtonElement);
-    return BoxIconButtonElement;
-};
+IconButton.register();

package/dist/components/actions/link-button.d.ts

@@ -1,7 +1,16 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxLinkButtonElement extends BaseElement {
+export declare class LinkButton extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private linkEl;
+    private labelEl;
+    private contentSlot;
+    /** Anchor target (e.g. `_blank`). Opening a new tab auto-adds a safe rel. */
+    get target(): string;
+    set target(value: string);
+    /** Explicit rel; defaults to `noopener noreferrer` when target is `_blank`. */
+    get rel(): string;
+    set rel(value: string);
     get href(): string;
     set href(value: string);
     get label(): string;
@@ -9,6 +18,6 @@ export declare class BoxLinkButtonElement extends BaseElement {
     get tone(): string;
     set tone(value: string);
     protected renderTemplate(): void;
+    protected setupListeners(): void;
     protected update(): void;
 }
-export declare const defineBoxLinkButtonElement: (tagName?: string) => typeof BoxLinkButtonElement;

package/dist/components/actions/link-button.js

@@ -84,11 +84,28 @@ const linkButtonStyles = `
     color: var(--boe-token-surface-status-surface-error, #ed3757);
   }
 `;
-export class BoxLinkButtonElement extends BaseElement {
+export class LinkButton extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
-        return ["href", "label", "tone"];
+        return ["href", "label", "tone", "target", "rel"];
     }
     linkEl;
+    labelEl;
+    contentSlot;
+    /** Anchor target (e.g. `_blank`). Opening a new tab auto-adds a safe rel. */
+    get target() {
+        return this.getAttribute("target") ?? "";
+    }
+    set target(value) {
+        this.setAttribute("target", value);
+    }
+    /** Explicit rel; defaults to `noopener noreferrer` when target is `_blank`. */
+    get rel() {
+        return this.getAttribute("rel") ?? "";
+    }
+    set rel(value) {
+        this.setAttribute("rel", value);
+    }
     get href() {
         return this.getAttribute("href") ?? "#";
     }
@@ -113,9 +130,18 @@ export class BoxLinkButtonElement extends BaseElement {
         }
         this.shadowRoot.innerHTML = `
       <style>${linkButtonStyles}</style>
-      <a part="link"></a>
+      <a part="link"><slot><span part="label"></span></slot></a>
     `;
         this.linkEl = this.shadowRoot.querySelector('[part="link"]');
+        this.contentSlot = this.shadowRoot.querySelector("slot");
+        this.labelEl = this.shadowRoot.querySelector('[part="label"]');
+    }
+    setupListeners() {
+        this.contentSlot.addEventListener("slotchange", () => {
+            if (this.isRendered) {
+                this.update();
+            }
+        });
     }
     update() {
         if (!this.linkEl) {
@@ -123,15 +149,34 @@ export class BoxLinkButtonElement extends BaseElement {
         }
         this.linkEl.dataset.tone = this.tone;
         this.linkEl.setAttribute("href", escapeHtml(safeHref(this.href)));
-        this.linkEl.setAttribute("aria-label", this.label);
-        this.linkEl.textContent = this.label;
+        // Rich children (slotted) replace the `label` text; keep the fallback in
+        // sync. Detect real host content only — assignedNodes() without flatten
+        // excludes the fallback span; ignore whitespace-only text nodes.
+        const hasSlotted = this.contentSlot
+            .assignedNodes()
+            .some(node => node.nodeType === Node.ELEMENT_NODE || (node.textContent ?? "").trim() !== "");
+        this.labelEl.textContent = this.label;
+        if (hasSlotted) {
+            this.linkEl.removeAttribute("aria-label");
+        }
+        else {
+            this.linkEl.setAttribute("aria-label", this.label);
+        }
+        const target = this.target;
+        if (target) {
+            this.linkEl.setAttribute("target", target);
+        }
+        else {
+            this.linkEl.removeAttribute("target");
+        }
+        // Explicit rel wins; opening a new tab defaults to a safe rel.
+        const rel = this.rel || (target === "_blank" ? "noopener noreferrer" : "");
+        if (rel) {
+            this.linkEl.setAttribute("rel", rel);
+        }
+        else {
+            this.linkEl.removeAttribute("rel");
+        }
     }
 }
-export const defineBoxLinkButtonElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxLinkButtonElement);
-    return BoxLinkButtonElement;
-};
+LinkButton.register();

package/dist/components/actions/menu-item.d.ts

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxMenuItemElement extends BaseElement {
+export declare class MenuItem extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private itemEl;
     get disabled(): boolean;
@@ -14,4 +15,3 @@ export declare class BoxMenuItemElement extends BaseElement {
     protected setupListeners(): void;
     protected update(): void;
 }
-export declare const defineBoxMenuItemElement: (tagName?: string) => typeof BoxMenuItemElement;

package/dist/components/actions/menu-item.js

@@ -55,7 +55,8 @@ const menuItemStyles = `
     opacity: ${boeControl.disabledOpacity};
   }
 `;
-export class BoxMenuItemElement extends BaseElement {
+export class MenuItem extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["disabled", "label", "selected", "value"];
     }
@@ -127,11 +128,4 @@ export class BoxMenuItemElement extends BaseElement {
         this.itemEl.textContent = this.label;
     }
 }
-export const defineBoxMenuItemElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxMenuItemElement);
-    return BoxMenuItemElement;
-};
+MenuItem.register();

package/dist/components/actions/menu.d.ts

@@ -12,7 +12,8 @@ type BoxMenuItem = {
     /** Checkable item — renders menuitemcheckbox with aria-checked. */
     checked?: boolean;
 };
-export declare class BoxMenuElement extends BaseElement {
+export declare class Menu extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private menuEl;
     get disabled(): boolean;
@@ -28,5 +29,4 @@ export declare class BoxMenuElement extends BaseElement {
     private enabledMenuItems;
     protected update(): void;
 }
-export declare const defineBoxMenuElement: (tagName?: string) => typeof BoxMenuElement;
 export {};

package/dist/components/actions/menu.js

@@ -98,7 +98,8 @@ const menuStyles = `
     content: "✓";
   }
 `;
-export class BoxMenuElement extends BaseElement {
+export class Menu extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["disabled", "items", "label"];
     }
@@ -225,11 +226,4 @@ export class BoxMenuElement extends BaseElement {
         applyRovingTabindex(buttons, 0);
     }
 }
-export const defineBoxMenuElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxMenuElement);
-    return BoxMenuElement;
-};
+Menu.register();

package/dist/components/actions/segmented-control.d.ts

@@ -4,7 +4,8 @@ export interface SegmentedControlOption {
     value: string;
     disabled?: boolean;
 }
-export declare class BoxSegmentedControlElement extends BaseElement {
+export declare class SegmentedControl extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     private controlEl;
@@ -24,4 +25,3 @@ export declare class BoxSegmentedControlElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxSegmentedControlElement: (tagName?: string) => typeof BoxSegmentedControlElement;

package/dist/components/actions/segmented-control.js

@@ -71,7 +71,8 @@ const segmentedControlStyles = `
     opacity: 0.55;
   }
 `;
-export class BoxSegmentedControlElement extends BaseElement {
+export class SegmentedControl extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["disabled", "label", "layout", "options", "value"];
     }
@@ -263,11 +264,4 @@ export class BoxSegmentedControlElement extends BaseElement {
         });
     }
 }
-export const defineBoxSegmentedControlElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxSegmentedControlElement);
-    return BoxSegmentedControlElement;
-};
+SegmentedControl.register();

package/dist/components/collections/card.d.ts

@@ -1,5 +1,6 @@
 import { BaseElement } from "../../core/index.js";
-export declare class BoxCardElement extends BaseElement {
+export declare class Card extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private eyebrowEl;
     private titleEl;
@@ -10,4 +11,3 @@ export declare class BoxCardElement extends BaseElement {
     protected renderTemplate(): void;
     protected update(): void;
 }
-export declare const defineBoxCardElement: (tagName?: string) => typeof BoxCardElement;

package/dist/components/collections/card.js

@@ -51,7 +51,8 @@ const cardStyles = `
     display: none;
   }
 `;
-export class BoxCardElement extends BaseElement {
+export class Card extends BaseElement {
+    static tagName = DEFAULT_TAG_NAME;
     static get observedAttributes() {
         return ["eyebrow", "heading"];
     }
@@ -100,11 +101,4 @@ export class BoxCardElement extends BaseElement {
         this.titleEl.hidden = !heading;
     }
 }
-export const defineBoxCardElement = (tagName = DEFAULT_TAG_NAME) => {
-    const existingElement = customElements.get(tagName);
-    if (existingElement) {
-        return existingElement;
-    }
-    customElements.define(tagName, BoxCardElement);
-    return BoxCardElement;
-};
+Card.register();

package/dist/components/collections/carousel.d.ts

@@ -5,13 +5,17 @@ type CarouselItem = {
     description?: string;
     imageSrc?: string;
 };
-export declare class BoxCarouselElement extends BaseElement {
+export declare class Carousel extends BaseElement {
+    static readonly tagName: string;
     static get observedAttributes(): string[];
     private valueInternal;
     private lastItemsJson;
     private carouselEl;
     private labelEl;
     private stageEl;
+    private viewportEl;
+    private slottedStageEl;
+    private slideSlot;
     private mediaEl;
     private eyebrowEl;
     private titleEl;
@@ -28,6 +32,10 @@ export declare class BoxCarouselElement extends BaseElement {
     get value(): number;
     set value(value: number);
     attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+    /** Slotted slides (elements assigned to the `slide` slot). */
+    private slottedSlides;
+    /** Active slide count — slotted slides when present, else JSON items. */
+    private slideCount;
     private normalizeIndex;
     private emitValueChanged;
     private setIndex;
@@ -36,5 +44,4 @@ export declare class BoxCarouselElement extends BaseElement {
     protected setupListeners(): void;
     protected update(): void;
 }
-export declare const defineBoxCarouselElement: (tagName?: string) => typeof BoxCarouselElement;
 export {};