@sylwellsoftware/fray 0.1.0-alpha.1

package/EXPERIMENTAL.md

@@ -0,0 +1,75 @@
+# Fray experimental data APIs
+
+Everything imported from `@sylwellsoftware/fray/experimental` is outside Fray's stable
+alpha compatibility surface. It may change in any `0.x` release without a
+deprecation window. The stable package root does not export these symbols.
+
+`TreeView` is a controlled, single-select ARIA tree. Stable node keys reconcile
+selection and expansion across data replacement. Arrow keys navigate and
+expand/collapse, Home/End jump, Enter/Space select, and printable keys perform
+type-ahead. `TreeItem` supplies an optional declarative node form. The initial
+contract does not include virtualization, multi-selection, editing, or drag
+reordering.
+
+`Dialog` wraps the native modal element with a controlled boolean emitter,
+label/description relationships, cancel handling, initial focus, focus
+restoration, and deterministic cleanup. Applications provide actions and own
+all async work; the dialog does not infer promise or confirmation policy.
+
+## Current behavior
+
+`ListView` and `DataTable` use stable item/row keys and expose their selected
+items through writable emitters. Single selection replaces the prior item.
+Multi-selection supports Control/Command toggles, Shift ranges, primary-button
+drag ranges, arrow/Home/End focus movement, and Space/Enter selection. A data
+refresh reconciles selected keys to the new row objects.
+
+`DataTable` requires an explicit `mode`:
+
+- `local` accepts an array or emitter, and performs sorting/filtering in the
+  browser;
+- `remote` accepts a query emitter/handler or REST configuration, and sends
+  sort/filter arguments through the documented table serializer.
+
+Filter state lives in the table's `filtersEmitter`, so opening a panel,
+changing a filter, rerendering, and refreshing data do not reset it. Remote
+tables distinguish these states:
+
+- initial/loading with no rows: status plus placeholder rows;
+- loading with retained rows: busy status plus the partial/previous rows;
+- ready with no rows: the configured empty message;
+- error with retained rows: an alert plus those rows;
+- error with no rows: an alert without a misleading empty message;
+- retryable query: a native Retry button that calls `query.retry()`.
+
+Pagination is not built in. A remote query may implement pagination arguments,
+but Fray does not currently supply pagination controls or a page model.
+
+## Measured alpha boundary
+
+The alpha regression boundary is **1,000 rows with four to six simple columns
+on a modern desktop browser**. Larger datasets, expensive custom cell
+renderers, and mobile devices are not covered; paginate or filter them before
+rendering.
+
+The browser fixture measures a 1,000-row/four-column local table using stable
+keys. It times initial DOM creation, a full data refresh, numeric sorting, a
+filter that retains 500 rows, and one selection update. On the 2026-09-01 local
+arm64 macOS verification host with Playwright 1.62.1, the results were:
+
+| Engine | Initial | Rerender | Sort | Filter | Selection |
+| --- | ---: | ---: | ---: | ---: | ---: |
+| Chromium | 19.0 ms | 9.3 ms | 9.2 ms | 6.0 ms | 20.9 ms |
+| Firefox | 62.0 ms | 16.0 ms | 14.0 ms | 11.0 ms | 32.0 ms |
+| WebKit | 18.0 ms | 12.0 ms | 22.0 ms | 6.0 ms | 4.0 ms |
+
+These are synchronous headless-browser regression measurements, not a promise
+of end-to-end frame or device performance. The automated budget allows two
+seconds for initial creation and one second for each subsequent operation to
+remain robust on slower verification hosts while still catching a material
+regression.
+
+Virtualization is deliberately deferred: the measured boundary does not
+justify its lifecycle, focus, and accessibility complexity. Revisit it only
+with a demonstrated consumer above 1,000 rows and browser measurements showing
+that server-side pagination/filtering is insufficient.

package/LICENSE

@@ -0,0 +1,55 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS

package/NOTICE

@@ -0,0 +1,2 @@
+Fray
+Copyright 2026 Sylwell Software

package/README.md

@@ -0,0 +1,521 @@
+# Fray
+
+Fray is an experimental, browser-only component and DOM runtime built around
+Glue emitters. It targets modern evergreen browsers. Its `0.x` API may change
+with documented migration notes.
+
+After publication, install Fray together with its Glue peer:
+
+```bash
+pnpm add @sylwellsoftware/glue @sylwellsoftware/fray
+```
+
+Fray is ESM-only and targets the current and previous major versions of
+Chromium, Firefox, and Safari at candidate time. Its reproducible test matrix
+uses Playwright's pinned Chromium, Firefox, and WebKit builds. Repository
+tooling requires Node 22+ and pnpm 10; Fray's runtime itself is browser-only.
+
+## Set up a browser application
+
+Fray ships ESM, TypeScript declarations, automatic/classic JSX runtimes, and
+two supported CSS theme subpaths. Glue is a peer dependency.
+
+```ts
+import {Emitter} from '@sylwellsoftware/glue'
+import {
+    Button,
+    Component,
+    Panel,
+    Sidebar,
+    Textbox,
+    Toolbar,
+    createFrayRuntime,
+    h,
+} from '@sylwellsoftware/fray'
+import '@sylwellsoftware/fray/themes/light.css'
+
+const name = new Emitter('Ada')
+
+class App extends Component {
+    static dependencies = [Button, Panel, Textbox, Toolbar]
+
+    render() {
+        return h(Panel, {header: 'Profile'},
+            h(Textbox, {label: 'Name', valueEmitter: name}),
+            h(Toolbar, {label: 'Profile actions'},
+                h(Button, {label: 'Save', onClick: () => save(name.get())})))
+    }
+}
+
+const runtime = createFrayRuntime()
+runtime.registerStyles(App).injectStyles(document)
+runtime.mount(runtime.create(App), document.querySelector('#app')!)
+
+function save(value: string) {
+    console.log(value)
+}
+```
+
+Register the root component's dependencies before injecting styles. Injection
+is idempotent within a runtime, so another application root may register
+additional component styles and inject again safely.
+
+For automatic JSX, configure TypeScript with `"jsx": "react-jsx"` and
+`"jsxImportSource": "@sylwellsoftware/fray"`. Classic JSX uses `h` as `jsxFactory` and
+`Fragment` as `jsxFragmentFactory`. JSX and `h()` produce the same vnodes.
+
+The same root can be written with automatic JSX:
+
+```tsx
+class App extends Component {
+    render() {
+        return <Panel header="Profile">
+            <Textbox label="Name" valueEmitter={name} />
+            <Button label="Save" onClick={() => save(name.get())} />
+        </Panel>
+    }
+
+    static dependencies = [Button, Panel, Textbox]
+}
+```
+
+## Component host elements
+
+Fray components with a wrapper render a standards-valid custom host element,
+not a framework identity class. The default application runtime therefore
+produces DOM such as:
+
+```html
+<fray-panel data-fray-component="panel">
+    <fray-textbox data-fray-component="textbox">
+        <input type="text">
+    </fray-textbox>
+    <button data-fray-component="button">Save</button>
+</fray-panel>
+```
+
+Native semantics remain native: `Button` renders `button`, `Toggle` renders
+`fieldset`, `Sidebar` renders `aside`, and table header components render
+`thead`/`th`. `Tab` is a declarative child consumed by `TabPanel` and has no
+independent root. The
+`data-fray-component` attribute keeps diagnostics unambiguous without taking
+ownership of the consumer's `class`/`className`.
+
+Element naming is an immutable application-runtime setting:
+
+```ts
+const defaultNames = createFrayRuntime()
+// <fray-panel>, <fray-list-view>, ...
+
+const productNames = createFrayRuntime({
+    elementNames: {prefix: 'acme'},
+})
+// <acme-panel>, <acme-list-view>, ...
+
+const prefixlessNames = createFrayRuntime({
+    elementNames: {prefix: null},
+})
+// <layout-panel>, <list-view>, <text-box>, ...
+
+const selectedOverrides = createFrayRuntime({
+    elementNames: {
+        prefix: null,
+        overrides: {'panel': 'change-panel'},
+    },
+})
+// <change-panel>, with standalone names for the other components
+```
+
+HTML custom-element names must contain a hyphen, so prefixless mode uses each
+component's standards-valid standalone name rather than invalid names such as
+`<panel>` or `<listview>`. Prefixes and overrides must be lowercase kebab-case;
+an exact override must itself be a non-reserved custom-element name.
+
+Each runtime owns its element-name mapping and structural-style registry.
+Create the runtime once at application startup, then create and mount the root
+through that runtime. Nested components inherit it automatically. A separate
+compiled Fray build is unnecessary. Two runtimes with different mappings can
+coexist in one document without their component-host selectors colliding.
+Styles still live in the document's global cascade because these hosts are
+deliberately unregistered light-DOM elements, not Web Components or Shadow DOM
+boundaries.
+
+## Reactive templates
+
+TypeScript TSX is Fray's supported template syntax. Classic JSX and direct
+`h()` calls are equivalent frontends: both lower to the same vnode tree and
+use the same renderer. A future template-file syntax can target this vnode
+contract without changing Glue binding semantics.
+
+Fray's own stable and experimental built-ins are authored in TSX. Direct
+`h()` remains supported for consumers that do not use JSX and as the renderer's
+canonical vnode operation, but it is not the built-in component authoring
+format. The workspace lint gate rejects new `h()` templates under
+`packages/fray/src/Components`.
+
+Configured custom hosts are also available inside a TSX component through its
+protected `Host` template component:
+
+```tsx
+interface BadgeProps extends ComponentProps {
+    tone?: 'neutral' | 'positive'
+}
+
+class Badge extends Component<BadgeProps> {
+    render() {
+        const Host = this.Host
+        return <Host data-tone={this.props.tone ?? 'neutral'}>
+            {this.props.children}
+        </Host>
+    }
+
+    static override hostName = 'badge'
+    static override standaloneHostName = 'ui-badge'
+}
+```
+
+At runtime that template produces `<fray-badge>` by default,
+`<acme-badge>` under an `acme` prefix, or `<ui-badge>` in prefixless mode.
+Native-root components such as `Button` use their native tag directly in TSX
+instead of `Host`.
+
+Glue values have explicit behavior at each template boundary:
+
+| Template form | Meaning |
+| --- | --- |
+| `{emitter}` | Render the current value and patch only that child range on emission. |
+| `<Child source={emitter} />` | Pass the emitter object unchanged; the child owns how it consumes it. |
+| `prop={live(emitter)}` | Subscribe a scalar DOM or component prop one way to the emitter's current value. |
+| `<input bind:value={emitter} />` | Bind a writable string emitter and native `value` two ways. |
+| `<input bind:checked={emitter} />` | Bind a writable boolean emitter and native `checked` two ways. |
+| `this.read(emitter)` | Read during `render()` and rerender the component while that dependency is used. |
+| `this.snapshot(emitter)` | Track and read `{value, fetchState, error}` for stateful rendering. |
+
+Direct child and `live()` subscriptions are renderer-owned and are released
+when their nodes disappear. Render-time `read()`/`snapshot()` dependencies are
+reconciled after every render, so conditional dependencies are also released.
+The component still owns and disposes emitters it creates. Direct rendering
+uses only an emitter's value; use `snapshot()` when loading and error state
+must affect the markup.
+
+This complete example uses mutable and derived emitters, direct emitter
+children, raw emitter props, native two-way bindings, a one-way live property,
+conditional tracked state, and a `LiveQuery` passed to a child:
+
+```tsx
+import {
+    DerivedEmitter,
+    Emitter,
+    FetchState,
+    LiveQuery,
+    QueryHandler,
+} from '@sylwellsoftware/glue'
+import type {ReadableEmitter} from '@sylwellsoftware/glue'
+import {
+    Button,
+    Component,
+    Panel,
+    Textbox,
+    createFrayRuntime,
+    live,
+} from '@sylwellsoftware/fray'
+import type {ComponentProps, WritableEmitter} from '@sylwellsoftware/fray'
+
+interface Change {
+    id: number
+    title: string
+}
+
+const fixtures: readonly Change[] = [
+    {id: 101, title: 'Add release attestations'},
+    {id: 102, title: 'Migrate the demo to TypeScript'},
+]
+
+class ChangeQueryHandler extends QueryHandler<{filter: string}, readonly Change[]> {
+    override fetch({filter}: {filter: string}): readonly Change[] {
+        const needle = filter.trim().toLocaleLowerCase()
+        return needle === ''
+            ? fixtures
+            : fixtures.filter(({title}) =>
+                title.toLocaleLowerCase().includes(needle))
+    }
+}
+
+interface PreviewProps extends ComponentProps {
+    heading: ReadableEmitter<string, unknown>
+    approved: WritableEmitter<boolean>
+}
+
+class Preview extends Component<PreviewProps> {
+    render() {
+        return <section aria-label="Live change preview">
+            <h3>{this.props.heading}</h3>
+            <label>
+                <input type="checkbox" bind:checked={this.props.approved} />
+                Approved
+            </label>
+        </section>
+    }
+}
+
+interface ResultsProps extends ComponentProps {
+    results: ReadableEmitter<readonly Change[] | undefined, unknown>
+}
+
+class Results extends Component<ResultsProps> {
+    render() {
+        const {value, fetchState, error} = this.snapshot(this.props.results)
+        if (fetchState === FetchState.Error) {
+            return <p role="alert">{String(error)}</p>
+        }
+        return <ul aria-busy={fetchState === FetchState.Loading}>
+            {(value ?? []).map(({id, title}) => <li key={id}>{title}</li>)}
+        </ul>
+    }
+}
+
+class ChangeApp extends Component {
+    readonly title = new Emitter('Add native Glue template bindings')
+    readonly approved = new Emitter(false)
+    readonly filter = new Emitter('')
+    readonly showPreview = new Emitter(true)
+    readonly heading = new DerivedEmitter(
+        [this.title, this.approved] as const,
+        ([title, approved]) => `${title} — ${approved ? 'approved' : 'draft'}`,
+    )
+    readonly results = new LiveQuery({
+        handler: new ChangeQueryHandler(),
+        args: {filter: this.filter},
+    })
+
+    render() {
+        return <Panel header={this.heading}>
+            <Textbox label="Title" valueEmitter={this.title} />
+            <label>Search <input bind:value={this.filter} /></label>
+
+            <output title={live(this.heading)}>Current title: {this.title}</output>
+
+            <label>
+                <input type="checkbox" bind:checked={this.showPreview} />
+                Show preview
+            </label>
+            {this.read(this.showPreview)
+                ? <Preview heading={this.heading} approved={this.approved} />
+                : null}
+
+            <Results results={this.results} />
+            <Button
+                label="Refresh results"
+                onClick={() => void this.results.refresh()}
+            />
+        </Panel>
+    }
+
+    onDestroy(): void {
+        this.results.dispose()
+        this.heading.dispose()
+        this.showPreview.dispose()
+        this.filter.dispose()
+        this.approved.dispose()
+        this.title.dispose()
+    }
+
+    static dependencies = [Button, Panel, Preview, Results, Textbox]
+}
+
+const runtime = createFrayRuntime({elementNames: {prefix: 'acme'}})
+runtime.registerStyles(ChangeApp).injectStyles(document)
+runtime.mount(runtime.create(ChangeApp), document.querySelector('#app')!)
+```
+
+Emitter props are raw by default on purpose: automatically unwrapping every
+prop would make it impossible for controls such as `Textbox` and application
+components such as `Preview` to receive a stable emitter. Use `live()` only
+when the receiver expects a scalar prop and one-way updates are desired.
+
+## State convention
+
+Every stateful control follows one ownership rule:
+
+- pass a writable `valueEmitter` to share and externally update state;
+- otherwise pass `defaultValue` to initialize the control's owned emitter;
+- read the active emitter from the component instance's `valueEmitter`
+  property;
+- use `onInput` or `onChange` to observe user actions. The callback runs after
+  the emitter changes and does not replace the emitter contract.
+
+`value` remains an initial-value alias for imported `0.x` call-site
+compatibility; it is not a prop-driven controlled mode. Prefer `valueEmitter`
+or `defaultValue` in new code.
+
+## Stable component reference
+
+All components also accept `children`, `className` (`class` is an alias), and a
+sibling-local `key` through the common component props.
+
+| Component | Important props | User callback | State/emitter behavior |
+| --- | --- | --- | --- |
+| `Button` | `label`, `type`, `disabled`, `pressed`, `busy`, `busyLabel`, `ariaLabel`, native `id`/`name`/`value`/`title` | `onClick(event)` | Stateless native button; busy state disables activation and is presentation only. |
+| `Toolbar` | `label`, `orientation`, `id`, `children` | None | Stateless named toolbar; orientation is horizontal or vertical. |
+| `Textbox` | `label` or `ariaLabel`, value props, `disabled`, `required`, `readOnly`, `error`, native text constraints, `inputRef` | `onInput(value, event)`, `onChange(value, event)` | String `valueEmitter`; external emitter changes patch the native input without replacing it. |
+| `Dropdown<T>` | `options`, `label` or `ariaLabel`, value props, `disabled`, `required`, `error`, `placeholder`, `name` | `onChange(value, event)` | Typed string/number `valueEmitter`; `options` may be an array or readable emitter. |
+| `Toggle<T>` | `options`, `label` or `ariaLabel`, value props, `disabled`, `required` | `onChange(value, event)` | One selected value; arrow keys, Home, and End move and select within the radio group. |
+| `Checkbox<T>` | `symbols`, `label`, value props, `disabled`, `required`, `name` | `onChange(value, event)` | Two-state semantic value by default; click/Space advances and arrow keys move in either direction. |
+| `TriCheckbox` | Checkbox props except `symbols` | `onChange(value, event)` | Cycles deny → neutral → prefer using `FilterMode`. |
+| `QuadCheckbox` | Checkbox props except `symbols` | `onChange(value, event)` | Cycles deny → neutral → prefer → require using `FilterMode`. |
+| `Panel` | `header`, `toolbar`, `orientation`, `disabled`, `id`, `children` | None | Stateless labelled section when a header exists; `disabled` describes the region but does not mutate descendant controls. |
+| `Sidebar` | `header`, `toolbar`, `ariaLabel`, `id`, `children` | None | Native complementary region with fixed header/toolbar parts and independently scrolling content. |
+| `SplitView` | `primary`, `secondary`, `direction`, `primarySize`, pane labels | None | Stateless, non-resizable two-pane layout with explicit overflow ownership. |
+| `DescriptionList` / `DescriptionItem` | list `label`; item `term`, `value` or children | None | Native `dl`/`dt`/`dd` record summary with responsive term/value wrapping. |
+| `ProgressBar` | `label`, `value` or `valueEmitter`, `max`, `valueText` | None | Labelled native progress; a null value is indeterminate. |
+| `Tab` | `id`, `label`, `disabled`, `children` | None | Declarative content marker consumed by `TabPanel`; not rendered as a tab by itself. |
+| `TabLine` | `tabs`, `label`, `baseId`, value props | `onChange(id, event)` | Active-tab `valueEmitter`; arrow keys skip disabled tabs, with Home/End support. |
+| `TabPanel` | `tabs` or `Tab` children, `label`, `id`, value props | `onChange(id, event)` | Owns or consumes the active-tab emitter and wires the selected tab to its tabpanel. |
+
+Invalid option arrays, duplicate tab IDs, unsupported orientations, malformed
+emitters, and non-function callbacks fail with descriptive errors.
+
+## Component examples
+
+### Actions and toolbar
+
+```ts
+h(Toolbar, {label: 'Editor actions'},
+    h(Button, {label: 'Save', onClick: save}),
+    h(Button, {label: 'Delete', disabled: true}))
+```
+
+### Textbox
+
+```ts
+const query = new Emitter('')
+
+h(Textbox, {
+    label: 'Search',
+    valueEmitter: query,
+    required: true,
+    error: query.get() === '' ? 'Enter a search term' : null,
+    onInput: (value) => console.log('search changed', value),
+})
+```
+
+### Dropdown
+
+```ts
+const role = new Emitter<'author' | 'reviewer'>('author')
+
+h(Dropdown, {
+    label: 'Role',
+    valueEmitter: role,
+    options: [
+        {value: 'author', label: 'Author'},
+        {value: 'reviewer', label: 'Reviewer'},
+    ],
+    onChange: (value) => console.log(value),
+})
+```
+
+### Toggle
+
+```ts
+h(Toggle, {
+    label: 'View',
+    defaultValue: 'list',
+    options: [['list', 'List'], ['grid', 'Grid']],
+    onChange: (value) => console.log(value),
+})
+```
+
+### Checkbox variants
+
+```ts
+h(Checkbox, {label: 'Include archived'})
+h(TriCheckbox, {label: 'Match policy', defaultValue: FilterMode.Neutral})
+h(QuadCheckbox, {label: 'Required tags', defaultValue: FilterMode.Require})
+```
+
+`FilterMode` values are `Deny`, `Neutral`, `Prefer`, and `Require`. The basic
+checkbox uses neutral/prefer, while the variants expose the additional states.
+
+### Panel
+
+```ts
+h(Panel, {
+    header: 'Account',
+    orientation: 'vertical',
+    toolbar: h(Toolbar, {label: 'Account actions'},
+        h(Button, {label: 'Edit'})),
+}, h('p', null, 'Account details'))
+```
+
+### Sidebar
+
+```ts
+h(Sidebar, {
+    id: 'project-navigation',
+    header: 'Projects',
+    toolbar: h(Toolbar, {label: 'Project filters'},
+        h(Textbox, {label: 'Search projects'})),
+}, h('ul', null, h('li', null, 'Release automation')))
+```
+
+The surrounding grid or flex layout must bound the Sidebar's height. Its
+header and toolbar remain fixed while the dedicated content part owns vertical
+scrolling and is keyboard-focusable. Supply `ariaLabel` when there is no visible
+`header`.
+
+### Declarative tabs
+
+```ts
+h(TabPanel, {id: 'profile', label: 'Profile sections'},
+    h(Tab, {id: 'summary', label: 'Summary'}, 'Summary content'),
+    h(Tab, {id: 'details', label: 'Details'}, 'Details content'))
+```
+
+### Standalone tab line
+
+```ts
+h(TabLine, {
+    baseId: 'settings',
+    label: 'Settings sections',
+    defaultValue: 'general',
+    tabs: [
+        {id: 'general', label: 'General'},
+        {id: 'advanced', label: 'Advanced'},
+    ],
+    onChange: (id) => console.log('active tab', id),
+})
+```
+
+Use `TabPanel` when Fray should render content and ARIA relationships. Use a
+standalone `TabLine` only when the consumer owns the corresponding tabpanel
+content and IDs.
+
+## Styling and accessibility
+
+Structural styles use semantic custom properties and leave colors to the
+supported light/dark bundles. See [`themes/README.md`](themes/README.md) for the
+public variable contract and consumer overrides.
+
+Stable examples are tested with axe in Chromium, Firefox, and WebKit and have
+no serious or critical automated violations. Browser tests also cover keyboard
+operation, labelled roles, reduced motion, 200% configured text sizing, and
+forced-colors focus visibility. A formal manual screen-reader pass is still a
+release-candidate requirement; automated checks are not a substitute for it.
+
+## Experimental data components
+
+`ListView`, `DataTable`, `TreeView`, `TreeItem`, `Dialog`, filters, selection
+handlers, and `Placeholder` are available only from
+`@sylwellsoftware/fray/experimental`. They are outside the stable alpha
+compatibility surface and may change without a migration bridge. Their state
+model, keyboard behavior, measured data boundary, and current limitations are
+documented in [EXPERIMENTAL.md](EXPERIMENTAL.md).
+
+Fray is not a replacement for an SSR/hydration framework, Web Components,
+React/Vue adapters, a broad design system, a virtualized production data grid,
+legacy-browser support, or a stable `1.0` API. See the [workspace
+overview](../../README.md), [alpha API surface](../../docs/API_SURFACE.md),
+[architecture overview](../../docs/architecture.md),
+[changelog](../../CHANGELOG.md), [contribution guide](../../CONTRIBUTING.md),
+and [security policy](../../SECURITY.md).

package/dist/Components/Placeholder.d.ts

@@ -0,0 +1,14 @@
+import { Component } from './component.js';
+import type { ComponentProps } from './component.js';
+export interface PlaceholderProps extends ComponentProps {
+    width?: number | string;
+}
+/** Deterministic loading placeholder for experimental data components. */
+export declare class Placeholder extends Component<PlaceholderProps> {
+    render(): import("@sylwellsoftware/fray/jsx-runtime").JSX.Element;
+    static hostName: string;
+    static standaloneHostName: string;
+    static baseStyles: (string | string[])[][];
+    static css: string;
+}
+//# sourceMappingURL=Placeholder.d.ts.map

package/dist/Components/Placeholder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Placeholder.d.ts","sourceRoot":"","sources":["../../src/Components/Placeholder.tsx"],"names":[],"mappings":"AAAA,OAAO,EAAC,SAAS,EAAM,MAAM,gBAAgB,CAAA;AAC7C,OAAO,KAAK,EAAC,cAAc,EAAC,MAAM,gBAAgB,CAAA;AAElD,MAAM,WAAW,gBAAiB,SAAQ,cAAc;IACpD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;CAC1B;AAED,0EAA0E;AAC1E,qBAAa,WAAY,SAAQ,SAAS,CAAC,gBAAgB,CAAC;IACxD,MAAM;IAMN,OAAgB,QAAQ,SAAgB;IACxC,OAAgB,kBAAkB,SAAwB;IAE1D,MAAM,CAAC,UAAU,0BAEhB;IAED,MAAM,CAAC,GAAG,SAgBT;CACJ"}