@unofficialbox/box-open-elements 0.5.0 → 0.7.0

package/README.md

@@ -10,96 +10,49 @@
 
 > **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:
+Browse the full catalog on the **[live docs site](https://unofficialbox.github.io/box-open-elements)** — live previews, an events/properties inspector, per-framework code snippets (React / Angular / Vue / Svelte / HTML), and the foundations pages.
+
+The library is organized around three layers (see [docs/taxonomy.md](./docs/taxonomy.md) for the canonical model):
 
 - **Foundations** — design decisions as data: tokens, color, typography, iconography, accessibility, theming
 - **Components** — accessible Web Components for single controls, organized by category
 - **Patterns** — combinations of components that address user objectives with sequences and flows: headless controllers, transport contracts, and composed workflow surfaces, grouped by Box noun
 
-See [docs/taxonomy.md](./docs/taxonomy.md) for the canonical model.
-
-The guiding idea is unchanged: predictable, extensible building blocks that are easy for both human developers and AI coding assistants to compose.
+Core implementation principles:
 
-- plain TypeScript modules, no React requirement in the core package
+- plain TypeScript modules, no React requirement in the core package — zero runtime dependencies
 - state and business logic separate from rendering: controllers and stores, not framework components
 - standard DOM events where a UI layer needs them
 - 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.
+## Install
 
 ```bash
-bun install
+npm install @unofficialbox/box-open-elements
 ```
 
-## Common commands
+Importing the root registers the full `box-*` catalog; flat entrypoints register only the imported component:
 
-```bash
-bun run typecheck
-bun run test
-bun run test:coverage
-bun run build
-bun run verify
-bun run docs
+```ts
+import { Accordion, Avatar, Button, Switch } from "@unofficialbox/box-open-elements";
+import { TextField } from "@unofficialbox/box-open-elements/text-field";
 ```
 
-`bun run docs` builds the library and serves the component-documentation site at `http://localhost:4600` — browse the full catalog with live previews, events/properties inspectors, and foundations pages.
-
-`bun run verify` is the main safety check and runs typecheck, **coverage-gated** tests (`test:coverage`), and build in sequence.
-
-## Current state
-
-Full catalog parity with the reference repo, plus every scoped gap the research surfaced:
-
-- `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` — 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 `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
-
-**Fidelity program**: complete — Batches 0–7, the medium/low audit nits, and the design-heavy leftovers have shipped.
-
-Everything in the [components catalog](./docs/components/catalog.md) and [patterns catalog](./docs/patterns/catalog.md) that carries a **built** marker is implemented here with dedicated tests. Remaining catalog entries are intentional generic-component gaps whose current implementations are explorer-bound; future additions are gap-driven rather than phase-gated ports.
+```html
+<box-button label="Save" tone="primary"></box-button>
+```
 
-## Example: foundations + components
+Components consume foundation tokens (`--boe-token-*`) with safe fallbacks, so they render sensibly with no design system registered and restyle automatically when one is active:
 
 ```ts
-import {
-  createThemeController,
-} from "@unofficialbox/box-open-elements/foundations/theming";
-import { Button } from "@unofficialbox/box-open-elements";
+import { createThemeController } from "@unofficialbox/box-open-elements/foundations/theming";
 
 const theme = createThemeController();
 theme.start();
 ```
 
-```html
-<box-button label="Save" tone="primary"></box-button>
-```
-
-Components consume foundation tokens (`--boe-token-*`) with safe fallbacks, so they render sensibly with no design system registered and restyle automatically when one is active.
-
-## Example: headless patterns
+Workflow patterns begin as headless behavior and gain presentation adapters, so custom React components, Angular templates, Vue SFCs, Svelte components, Web Components, and plain DOM can all consume the same state:
 
 ```ts
 import { ExplorerSelectionController } from "@unofficialbox/box-open-elements/patterns/content-explorer/selection";
@@ -114,8 +67,6 @@ selection.setItems([{ id: "1" }, { id: "2" }]);
 selection.toggleSelection("1");
 ```
 
-Workflow patterns begin as headless behavior and gain presentation adapters, so custom React components, Angular templates, Vue SFCs, Svelte components, Web Components, and plain DOM can all consume the same state.
-
 ## Import contract
 
 - root exports: `@unofficialbox/box-open-elements`
@@ -124,15 +75,17 @@ Workflow patterns begin as headless behavior and gain presentation adapters, so
 - optimized component entrypoints: `@unofficialbox/box-open-elements/<name>`
 - patterns: `@unofficialbox/box-open-elements/patterns/<area>` and `@unofficialbox/box-open-elements/patterns/<area>/<module>`
 
-The root entrypoint is the concise convenience API and registers the full
-catalog. Flat component entrypoints register only the imported component:
+See [docs/api-guidelines.md](./docs/api-guidelines.md).
 
-```ts
-import { Accordion, Avatar, Button, Switch } from "@unofficialbox/box-open-elements";
-import { TextField } from "@unofficialbox/box-open-elements/text-field";
-```
+## Developing
 
-See [docs/api-guidelines.md](./docs/api-guidelines.md).
+This repo uses Bun as its package manager and task runner.
+
+```bash
+bun install
+bun run verify   # the main safety gate: typecheck, coverage-gated tests, build
+bun run docs     # build + serve the docs site at http://localhost:4600
+```
 
 ## Documentation
 
@@ -141,6 +94,7 @@ The docs index is at [docs/README.md](./docs/README.md). The most important entr
 - [Taxonomy](./docs/taxonomy.md)
 - [Architecture](./docs/architecture.md)
 - [API Guidelines](./docs/api-guidelines.md)
+- [Components catalog](./docs/components/catalog.md) and [patterns catalog](./docs/patterns/catalog.md)
 - [Using with React, Angular, Vue, and Svelte](./docs/integration/frameworks.md)
 - [Design Tokens](./docs/foundations/tokens.md)
 - [Content Explorer](./docs/patterns/content-explorer.md)

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

@@ -1,4 +1,5 @@
 import { BaseElement } from "../../core/index.js";
+import type { RowWindow } from "../../core/index.js";
 export interface TableColumn {
     key: string;
     label: string;
@@ -7,12 +8,47 @@ export interface TableColumn {
     /** Mark the column sortable — clicking its header emits `sort`. */
     sortable?: boolean;
 }
+export type TableCellTone = "neutral" | "brand" | "success" | "warning" | "error";
+/**
+ * Declarative cell content beyond plain text. Deliberately a descriptor the
+ * table renders itself, never an HTML string or a render callback: cell data
+ * is server-supplied and stays escaped — a string renderer would reopen the
+ * injection hole the escaping exists to close.
+ */
+export interface TableCellDescriptor {
+    kind: "text" | "badge" | "link";
+    text: string;
+    /** Badge colour; the text still carries the meaning. */
+    tone?: TableCellTone;
+    /** Link target; non-http(s) schemes render as plain text. */
+    href?: string;
+}
+export type TableCellValue = string | TableCellDescriptor;
 export interface TableRow {
     id: string;
-    /** Cell text keyed by column key, or positional strings matching `columns`. */
-    cells: Record<string, string> | string[];
+    /** Cell values keyed by column key, or positional, matching `columns`. */
+    cells: Record<string, TableCellValue> | TableCellValue[];
+    /**
+     * Expandable detail. Renders a per-row toggle and a full-width detail row
+     * holding this text plus a `detail-<id>` slot for rich host content.
+     */
+    detail?: string;
 }
 export type TableSelectionMode = "none" | "single" | "multiple";
+/** Detail of the `sort` event, for typed listeners. */
+export interface TableSortDetail {
+    key: string;
+    direction: "ascending" | "descending";
+}
+/** Detail of the `selection-changed` event, for typed listeners. */
+export interface TableSelectionChangedDetail {
+    selectedIds: string[];
+}
+/** Detail of the `row-toggled` event, for typed listeners. */
+export interface TableRowToggledDetail {
+    rowId: string;
+    expanded: boolean;
+}
 /**
  * A semantic, selectable data table — box-ui-elements `Table` + `makeSelectable`.
  * Rows and columns come from JSON. Selection supports single / Ctrl-click toggle
@@ -25,8 +61,68 @@ export declare class Table extends BaseElement {
     static get observedAttributes(): string[];
     private bodyEl;
     private headEl;
+    private shellEl;
     private selected;
     private anchorIndex;
+    private readonly expandedIds;
+    private lastWindow;
+    /**
+     * Whether the last render actually windowed. Not the same as `virtualize`:
+     * the flag is suppressed for a collection the fixed-height window cannot
+     * describe (see `update`). Cached at render time so the scroll handler does
+     * not re-parse `rows` on every frame to answer the question.
+     */
+    private windowing;
+    private scrollFrame;
+    private measuredRowHeight;
+    private measureFrame;
+    /** True while rows are being fetched: the body states "Loading rows…". */
+    get loading(): boolean;
+    set loading(value: boolean);
+    /** What the body says when there are no rows and nothing is loading. */
+    get emptyText(): string;
+    set emptyText(value: string);
+    /** Non-empty puts the table in an error state stating this text. */
+    get errorText(): string;
+    set errorText(value: string);
+    /**
+     * Render only the rows near the viewport. Opt-in: a windowed table needs a
+     * bounded height to scroll within, and silently windowing an unbounded table
+     * would render nothing.
+     *
+     * A request, not a guarantee. The window arithmetic is fixed-height, so it is
+     * suppressed for a collection whose rows can change height — today that means
+     * any collection where a row declares `detail`. Read `renderedWindow` to see
+     * whether a render actually windowed.
+     */
+    get virtualize(): boolean;
+    set virtualize(value: boolean);
+    /**
+     * Row height in pixels for the window arithmetic — a starting estimate, not
+     * a contract. The real height depends on density, font, and zoom, and a
+     * declared value that is off by a fraction of a pixel makes the scroll range
+     * drift as you scroll (a 10k-row table measured ~55px of wobble at 37px
+     * declared). After the first paint the element measures a rendered row and
+     * uses that instead, so the estimate only has to be close enough to pick a
+     * sane first window.
+     */
+    get rowHeight(): number;
+    private get declaredRowHeight();
+    set rowHeight(value: number);
+    /**
+     * Adopt the real rendered row height, once, when it differs from the value
+     * the last window was computed with. Re-rendering with the measured height
+     * settles immediately: the next measurement matches, so this cannot loop.
+     */
+    private measureRowHeight;
+    /**
+     * The window the last render used, or null when it rendered every row — for
+     * tests and hosts. Null despite `virtualize` means the collection is one the
+     * fixed-height window cannot describe and windowing was suppressed.
+     */
+    get renderedWindow(): RowWindow | null;
+    /** Ids of the rows whose detail is expanded (host-readable). */
+    get expandedRows(): string[];
     get columns(): TableColumn[];
     set columns(value: TableColumn[]);
     get rows(): TableRow[];
@@ -38,16 +134,30 @@ export declare class Table extends BaseElement {
     get label(): string;
     set label(value: string);
     private parseJson;
-    private cellText;
+    private cellValue;
+    /**
+     * Descriptor rendering. Everything is escaped; a link with a non-http(s)
+     * href renders as plain text; a badge's tone colours a word that already
+     * carries the meaning.
+     */
+    private cellMarkup;
     protected renderTemplate(): void;
     protected setupListeners(): void;
     private rowElements;
+    private toggleRowDetail;
     private onBodyKeydown;
+    /**
+     * Focus a row by its absolute index, bringing it into the window first when
+     * virtualizing — keyboard navigation must be able to reach a row that is not
+     * currently rendered, or Home/End stop at the edge of the window.
+     */
+    private focusRowByIndex;
     private toggleSort;
     private activateRow;
     private selectRange;
     private selectAll;
     private setSelection;
     private applySelectionState;
+    private currentWindow;
     protected update(): void;
 }