@leef-l/macos-ui-kit 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,216 @@
-# Temporary Holding Version
+# @leef-l/macos-ui-kit
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+macOS-style UI components in dependency-free TypeScript. No React, no Vue, no
+virtual DOM — just `document.createElement` wrappers over two-layer design
+tokens, so one import gives you the whole design system.
+
+- **30 components** — 17 controls, 6 layout, 6 overlays, 1 mobile shell
+- **Zero runtime dependencies**
+- **Light DOM only** — no Shadow DOM, so native window dragging and screen
+  readers both work
+- **Runtime theming** — four built-in themes plus custom token overrides
+- **Density scaling** — one `--mac-scale` factor resizes the whole interface
+
+## Scope: frontend only
+
+This package is **UI components and nothing else**. It contains no backend, no
+server, no data layer and no build-time code generation.
+
+- **No Go, no Wails runtime.** `package.json` declares no `dependencies` and no
+  `peerDependencies`; the built bundle has no imports at all. Nothing in `src/`
+  reads a `_wails` global, an IPC bridge, or a native API.
+- **No framework.** Just DOM APIs. It runs in any browser, in an Electron or
+  Tauri webview, in a Wails window, or in a plain HTML page opened from disk.
+- **No network calls.** Components never fetch anything. What you render is what
+  you pass in.
+
+Wails v3 is a *target*, not a requirement: the drag regions and the mobile shell
+were tuned for a frameless desktop window, and that is where the kit looks best.
+In a normal browser those behaviours simply do nothing instead of failing.
+
+Where the kit does touch host behaviour, it is through standard web APIs only:
+
+| Behaviour | How it works | Outside a desktop shell |
+|---|---|---|
+| Window dragging | `--wails-draggable` is a CSS custom property on the title bar | Ignored; nothing to drag |
+| Double-click to zoom | Listens for `dblclick` | Does nothing |
+| Mobile detection | `matchMedia("(pointer: coarse)")` + a width query | Works everywhere |
+| Sidebar / overlays | Plain DOM + CSS | Works everywhere |
+
+The Go application in this repository is a separate thing: a demo host that
+happens to use these components. You do not need it, and nothing in this package
+imports from it.
+
+---
+
+## Install
+
+### From npm (after the first publish)
+
+```sh
+npm install @leef-l/macos-ui-kit
+```
+
+### Straight from a GitHub release — no npm account, no publish needed
+
+```sh
+npm install https://github.com/leef-l/macos-ui-kit/releases/download/v0.1.0/leef-l-macos-ui-kit-0.1.0.tgz
+```
+
+This is a normal npm install: it lands in `node_modules` with the same files,
+the same types and the same exports. Use it while the package is not on the
+registry yet, or to pin an exact build.
+
+### From a clone
+
+```sh
+git clone https://github.com/leef-l/macos-ui-kit
+cd macos-ui-kit/packages/macos-ui-kit
+npm install
+npm run build
+
+# in your project
+npm install /absolute/path/to/packages/macos-ui-kit
+```
+
+### No build tooling at all
+
+Download `dist/macos-ui-kit.iife.js` and `dist/macos-ui-kit.css` from a release
+(or open the files in `packages/macos-ui-kit/dist/` after building) and use the
+global `MacUI`:
+
+```html
+<link rel="stylesheet" href="./macos-ui-kit.css" />
+<script src="./macos-ui-kit.iife.js"></script>
+<script>
+    const button = new MacUI.Button({label: "Hello", variant: "primary"});
+    document.body.appendChild(button.element);
+</script>
+```
+
+The IIFE build needs the `assets/` folder next to the stylesheet, because the
+stylesheet references the Inter font by relative path.
+
+---
+
+## Use
+
+```ts
+import {Button, TextField, showToast} from "@leef-l/macos-ui-kit";
+// The stylesheet is separate: the JS bundle contains no CSS.
+import "@leef-l/macos-ui-kit/style.css";
+
+const field = new TextField({placeholder: "Your name"});
+document.body.appendChild(field.element);
+
+const button = new Button({
+    label: "Greet",
+    variant: "primary",
+    onClick: () => showToast(`Hello ${field.value}`),
+});
+document.body.appendChild(button.element);
+```
+
+Every component exposes `element`, which is the node you mount. Construct it,
+append `element`, and keep the instance for the methods.
+
+### Whole kit or a single component
+
+Both are the same import — take only what you use:
+
+```ts
+// Whole kit, when you want everything
+import * as ui from "@leef-l/macos-ui-kit";
+
+// One component, when you want one
+import {Button} from "@leef-l/macos-ui-kit";
+```
+
+There is one entry point, and the ESM build is tree-shakeable: a bundler drops
+every component you do not reference, provided the package's `sideEffects` field
+is respected (Vite, Rollup, webpack and esbuild all do).
+
+**Honest caveat:** the JavaScript is tree-shaken, the **stylesheet is not**. CSS
+ships as a single 63 KB file and every component's rules are in it. Splitting it
+per component is not worth the extra requests for a desktop window, but if you
+are shipping to a slow network and use three components, know that you still
+download the rules for thirty.
+
+### Theming
+
+```ts
+import {themeManager, setDensity} from "@leef-l/macos-ui-kit";
+
+themeManager.apply("macos-dark");   // macos-dark | macos-light | hc-dark | hc-light
+setDensity("compact");              // compact | comfortable | touch
+```
+
+Or override tokens in your own stylesheet — components read semantic tokens
+only, so one declaration restyles every component:
+
+```css
+:root {
+    --mac-accent: #7c5cff;
+    --mac-radius-m: 10px;
+}
+```
+
+---
+
+## API convention
+
+Three rules, applied to all 30 components, so a control you have never used
+behaves the way you would guess:
+
+| Concern | Rule | Examples |
+|---|---|---|
+| **Read state** | property getter | `field.value`, `toggle.checked`, `sheet.isOpen` |
+| **Write state** | `setX()`, always silent | `setValue()`, `setChecked()`, `setSelected()` |
+| **Dismissible overlays** | `open(anchor?)` / `close()` / `isOpen` | `dialog.open()`, `popover.open(btn)` |
+
+`setX()` never fires the change callback — only a user interaction does. That
+makes programmatic writes safe to call from a render path.
+
+`Toast` is the one exception: it is a notification, not an overlay, so it uses
+`show()` / `hide()`.
+
+---
+
+## Components
+
+| Group | Components |
+|---|---|
+| Controls | `Button` `TextField` `TextArea` `NumberField` `Slider` `Progress` `Spinner` `Badge` `Switch` `Checkbox` `SegmentedControl` `Select` `ComboBox` `DatePicker` `Disclosure` `Table` `SplitView` |
+| Layout | `TitleBar` `TrafficLights` `Sidebar` `StatusBar` `Toolbar` `TabView` |
+| Overlays | `Menu` `Tooltip` `Dialog` `Popover` `Sheet` `Toast` |
+| Mobile | `MobileShell` |
+
+Every component also exposes `element`, `destroy()` (releases listeners and any
+observer), and `focus()` where focusing makes sense.
+
+---
+
+## Files
+
+```
+dist/index.js               ESM bundle            (import in a bundler)
+dist/macos-ui-kit.iife.js   IIFE, global MacUI    (<script> tag)
+dist/macos-ui-kit.css       one stylesheet
+dist/index.d.ts             type declarations
+dist/assets/                Inter font + its OFL licence
+```
+
+## Fonts
+
+Apple's SF Pro cannot be redistributed, so the kit ships **Inter** (SIL Open
+Font License 1.1, included in `dist/assets`) as an SF-alike fallback. The font
+stack puts the real system font first on macOS, so Apple users see SF Pro and
+everyone else sees near-identical glyphs.
+
+The stylesheet references the font as `./assets/Inter-Medium.ttf`. If your
+bundler relocates CSS assets, copy `dist/assets/` alongside the stylesheet — or
+drop the `@font-face` block and provide your own.
+
+## Licence
+
+MIT. Bundled Inter typeface: SIL Open Font License 1.1.

package/dist/assets/Inter Font License.txt

@@ -0,0 +1,93 @@
+Copyright 2020 The Inter Project Authors (https://github.com/rsms/inter)
+
+This Font Software is licensed under the SIL Open Font License, Version 1.1.
+This license is copied below, and is also available with a FAQ at:
+http://scripts.sil.org/OFL
+
+
+-----------------------------------------------------------
+SIL OPEN FONT LICENSE Version 1.1 - 26 February 2007
+-----------------------------------------------------------
+
+PREAMBLE
+The goals of the Open Font License (OFL) are to stimulate worldwide
+development of collaborative font projects, to support the font creation
+efforts of academic and linguistic communities, and to provide a free and
+open framework in which fonts may be shared and improved in partnership
+with others.
+
+The OFL allows the licensed fonts to be used, studied, modified and
+redistributed freely as long as they are not sold by themselves. The
+fonts, including any derivative works, can be bundled, embedded, 
+redistributed and/or sold with any software provided that any reserved
+names are not used by derivative works. The fonts and derivatives,
+however, cannot be released under any other type of license. The
+requirement for fonts to remain under this license does not apply
+to any document created using the fonts or their derivatives.
+
+DEFINITIONS
+"Font Software" refers to the set of files released by the Copyright
+Holder(s) under this license and clearly marked as such. This may
+include source files, build scripts and documentation.
+
+"Reserved Font Name" refers to any names specified as such after the
+copyright statement(s).
+
+"Original Version" refers to the collection of Font Software components as
+distributed by the Copyright Holder(s).
+
+"Modified Version" refers to any derivative made by adding to, deleting,
+or substituting -- in part or in whole -- any of the components of the
+Original Version, by changing formats or by porting the Font Software to a
+new environment.
+
+"Author" refers to any designer, engineer, programmer, technical
+writer or other person who contributed to the Font Software.
+
+PERMISSION & CONDITIONS
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of the Font Software, to use, study, copy, merge, embed, modify,
+redistribute, and sell modified and unmodified copies of the Font
+Software, subject to the following conditions:
+
+1) Neither the Font Software nor any of its individual components,
+in Original or Modified Versions, may be sold by itself.
+
+2) Original or Modified Versions of the Font Software may be bundled,
+redistributed and/or sold with any software, provided that each copy
+contains the above copyright notice and this license. These can be
+included either as stand-alone text files, human-readable headers or
+in the appropriate machine-readable metadata fields within text or
+binary files as long as those fields can be easily viewed by the user.
+
+3) No Modified Version of the Font Software may use the Reserved Font
+Name(s) unless explicit written permission is granted by the corresponding
+Copyright Holder. This restriction only applies to the primary font name as
+presented to the users.
+
+4) The name(s) of the Copyright Holder(s) or the Author(s) of the Font
+Software shall not be used to promote, endorse or advertise any
+Modified Version, except to acknowledge the contribution(s) of the
+Copyright Holder(s) and the Author(s) or with their explicit written
+permission.
+
+5) The Font Software, modified or unmodified, in part or in whole,
+must be distributed entirely under this license, and must not be
+distributed under any other license. The requirement for fonts to
+remain under this license does not apply to any document created
+using the Font Software.
+
+TERMINATION
+This license becomes null and void if any of the above conditions are
+not met.
+
+DISCLAIMER
+THE FONT SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT
+OF COPYRIGHT, PATENT, TRADEMARK, OR OTHER RIGHT. IN NO EVENT SHALL THE
+COPYRIGHT HOLDER BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+INCLUDING ANY GENERAL, SPECIAL, INDIRECT, INCIDENTAL, OR CONSEQUENTIAL
+DAMAGES, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF THE USE OR INABILITY TO USE THE FONT SOFTWARE OR FROM
+OTHER DEALINGS IN THE FONT SOFTWARE.

package/dist/component.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Base class for every macOS UI Kit component.
+ *
+ * It owns two things that raw DOM code gets wrong most often:
+ *
+ * 1. **Listener lifetime.** Vanilla UI leaks because listeners outlive the
+ *    elements they touch. `listen` records every binding so `destroy()` can
+ *    remove all of them in one pass.
+ * 2. **A stable root element.** Subclasses build their markup in the
+ *    constructor; callers only ever see `element`, which keeps the internal DOM
+ *    structure free to change.
+ *
+ * Deliberately light DOM: shadow roots would retarget `event.target`, and
+ * Wails' window-drag detection reads exactly that property
+ * (`internal/runtime/.../drag.ts` uses `event.target`, never `composedPath`).
+ */
+export declare abstract class Component<T extends HTMLElement = HTMLElement> {
+    /** The root element. Subclasses fill this in before the constructor returns. */
+    protected abstract readonly root: T;
+    private readonly cleanups;
+    private destroyed;
+    /** The component's root element, for mounting into the page. */
+    get element(): T;
+    /** True once `destroy()` has run. */
+    get isDestroyed(): boolean;
+    /**
+     * Add an event listener whose removal `destroy()` handles.
+     *
+     * Prefer this over `addEventListener` everywhere: a component that is torn
+     * down mid-session (a closed dialog, a re-rendered list) must not leave
+     * handlers pointing at detached nodes.
+     */
+    protected listen<K extends keyof HTMLElementEventMap>(target: T | HTMLElement | Document | Window, type: K, handler: (event: HTMLElementEventMap[K]) => void, options?: AddEventListenerOptions): void;
+    protected listen(target: T | HTMLElement | Document | Window, type: string, handler: EventListenerOrEventListenerObject, options?: AddEventListenerOptions): void;
+    /** Register an arbitrary teardown step (timers, observers, subscriptions). */
+    protected onDestroy(cleanup: () => void): void;
+    /** Reflect a boolean state as a class on the root, skipping no-op writes. */
+    protected toggleClass(name: string, on: boolean): void;
+    /** Set an attribute only when its value actually changes. */
+    protected setAttr(name: string, value: string): void;
+    /** Mount the component into a parent, replacing that parent's content. */
+    mount(parent?: Element): this;
+    /** Remove the component from the document and release everything it holds. */
+    remove(): void;
+    /** Tear down listeners and timers. Safe to call more than once. */
+    destroy(): void;
+}

package/dist/controls/badge.d.ts

@@ -0,0 +1,27 @@
+import { Component } from "../component";
+import "./badge.css";
+export type BadgeVariant = "default" | "accent" | "success" | "warning" | "danger";
+export interface BadgeOptions {
+    /** Badge text. */
+    text: string;
+    /** Colour treatment. Default `default` (neutral grey). */
+    variant?: BadgeVariant;
+}
+/**
+ * A small pill used to tag rows, counts and states.
+ *
+ * Renders inline, so a badge dropped inside a sidebar row or a paragraph sits
+ * on the text baseline rather than breaking that row's layout. The text is
+ * written with `textContent` only — a badge is the component most likely to
+ * receive a server-supplied string, so it never goes anywhere near HTML.
+ */
+export declare class Badge extends Component<HTMLElement> {
+    protected readonly root: HTMLElement;
+    private text;
+    private variant;
+    constructor(options: BadgeOptions);
+    /** Replace the badge text. */
+    setText(text: string): void;
+    /** Swap the colour treatment. */
+    setVariant(variant: BadgeVariant): void;
+}

package/dist/controls/button.d.ts

@@ -0,0 +1,41 @@
+import { Component } from "../component";
+import { type Child } from "../dom";
+import "./button.css";
+export type ButtonVariant = "default" | "primary" | "destructive" | "plain";
+export type ButtonSize = "small" | "default" | "large";
+export interface ButtonOptions {
+    /** Visible label. Omit for an icon-only button (then set `ariaLabel`). */
+    label?: Child;
+    /** Leading SVG path data, drawn at the control's icon size. */
+    icon?: string;
+    variant?: ButtonVariant;
+    size?: ButtonSize;
+    /** Accessible name; required when there is no visible label. */
+    ariaLabel?: string;
+    /** Stretch to the container's width. */
+    block?: boolean;
+    disabled?: boolean;
+    /** Native `type`, so a button inside a form does not submit by accident. */
+    type?: "button" | "submit" | "reset";
+    /** Fires on activation (click, Enter, Space — the browser handles the rest). */
+    onClick?: (event: MouseEvent) => void;
+}
+/**
+ * A native `<button>` with macOS styling.
+ *
+ * Built on the real element rather than a `div[role=button]` so keyboard
+ * activation, disabled handling and focus order come from the browser.
+ */
+export declare class Button extends Component<HTMLButtonElement> {
+    protected readonly root: HTMLButtonElement;
+    private readonly labelNode;
+    constructor(options?: ButtonOptions);
+    /** Replace the visible label text. */
+    setLabel(text: string): void;
+    /** Enable or disable the button. */
+    setDisabled(disabled: boolean): void;
+    /** Toggle the primary (blue) treatment at runtime. */
+    setPrimary(primary: boolean): void;
+    /** Give the caller a way to move focus programmatically. */
+    focus(): void;
+}

package/dist/controls/checkbox.d.ts

@@ -0,0 +1,40 @@
+import { Component } from "../component";
+import { type Child } from "../dom";
+import "./checkbox.css";
+export interface CheckboxOptions {
+    /** Initial ticked state. Default false. */
+    checked?: boolean;
+    /** Show the dash instead of the tick; it takes precedence over `checked`. */
+    indeterminate?: boolean;
+    disabled?: boolean;
+    /** Text rendered next to the box; it also names the control for assistive tech. */
+    label?: Child;
+    /** Fires with the new state after a user toggle; setters stay silent. */
+    onChange?: (checked: boolean) => void;
+}
+/**
+ * A styled checkbox built around a real `<input type="checkbox">`.
+ *
+ * The input stays in the document — clipped to a pixel, not `display: none` —
+ * so it keeps its place in the tab order, its focus ring and its click target.
+ * The drawn box is pure decoration: `:checked` and `:indeterminate` in CSS
+ * follow the input, and one native `change` listener mirrors the result to the
+ * caller. Space, screen readers and form submission therefore stay native;
+ * nothing in this component toggles state behind the browser's back.
+ */
+export declare class Checkbox extends Component<HTMLElement> {
+    protected readonly root: HTMLLabelElement;
+    private readonly input;
+    private readonly onChange?;
+    constructor(options?: CheckboxOptions);
+    /** The current ticked state. */
+    get checked(): boolean;
+    /** Set the ticked state; a write that changes nothing is skipped, and `onChange` stays silent. */
+    setChecked(checked: boolean): void;
+    /** Show the mixed state (a dash instead of the tick). */
+    setIndeterminate(indeterminate: boolean): void;
+    /** Enable or disable the checkbox, using the native attribute. */
+    setDisabled(disabled: boolean): void;
+    /** Move keyboard focus onto the native input. */
+    focus(): void;
+}

package/dist/controls/combobox.d.ts

@@ -0,0 +1,105 @@
+import { Component } from "../component";
+import "./combobox.css";
+/** One suggestion in the list. */
+export interface ComboBoxOption {
+    label: string;
+    value: string;
+}
+export interface ComboBoxOptions {
+    /** Full suggestion list; typing filters it. */
+    options: ComboBoxOption[];
+    /** Initially selected value; its label fills the field. */
+    value?: string;
+    placeholder?: string;
+    /**
+     * Custom rendering for a suggestion row. Returning a `Node` lets the list
+     * hold live UI; returning a string renders as text. The list keeps its own
+     * ARIA wiring around whatever is returned.
+     */
+    renderOption?: (option: ComboBoxOption) => Node | string;
+    /** Fires when a suggestion is committed (click, Enter or Tab). */
+    onChange?: (value: string) => void;
+    /** Fires on every keystroke with the raw text. */
+    onInput?: (text: string) => void;
+}
+/**
+ * A macOS combo box: a text field with an editable suggestion list.
+ *
+ * The list is absolutely positioned inside the component's own box rather than
+ * appended to `document.body` like the overlay components. A combo box's
+ * suggestions are conceptually part of the field, so staying in the container
+ * avoids portal teardown, scroll re-positioning and a `z-index` war with the
+ * dialogs above it. The trade-off is that an ancestor with `overflow: hidden`
+ * clips the list — acceptable for a control that rarely sits at the edge of a
+ * clipped card.
+ *
+ * Implements the ARIA combobox pattern: the input owns `role="combobox"`,
+ * `aria-expanded` and `aria-activedescendant`; the list is a `role="listbox"`
+ * of `role="option"` rows. Focus never leaves the input, so typing continues
+ * while the arrow keys move the highlight.
+ */
+export declare class ComboBox extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly input;
+    private readonly list;
+    private readonly onChange?;
+    private readonly onInput?;
+    private readonly renderOption?;
+    private readonly listId;
+    private options;
+    /** Options currently drawn, i.e. after filtering. */
+    private filtered;
+    /** Option rows, index-aligned with `filtered`. */
+    private rows;
+    /** Highlighted row index; -1 means nothing is highlighted. */
+    private active;
+    /**
+     * Value of the committed option, or null once the text is free-form.
+     * Kept separately from `input.value`, because the field shows a label while
+     * the caller may have handed us a machine value (an id, a slug).
+     */
+    private selectedValue;
+    constructor(options: ComboBoxOptions);
+    /**
+     * Show every option.
+     *
+     * Opening from a click or a focus must not filter by whatever text is
+     * already in the field: a field showing "张三" would otherwise open to a
+     * single row, which reads as a broken control. Typing is the only thing that
+     * narrows the list, and that path filters explicitly.
+     */
+    private openWithFullList;
+    /**
+     * The committed value.
+     *
+     * The highlight wins (an arrowed-onto row is what the user means), then the
+     * value behind the current label, and only then the raw text. Going through
+     * `selectedValue` is what keeps a field showing "Apricot" answering with its
+     * machine value "b".
+     */
+    get value(): string;
+    /**
+     * Set the text and value programmatically.
+     *
+     * A value that matches an option shows that option's label, so the field
+     * never displays a bare id where a name belongs. Silent, like every setter.
+     */
+    setValue(value: string): void;
+    /** Replace the suggestion list; the current text is kept and re-filtered. */
+    setOptions(options: ComboBoxOption[]): void;
+    /** Move keyboard focus into the field and show the full list. */
+    focus(): void;
+    private optionFor;
+    /** Rebuild the visible rows for the given text. */
+    private filter;
+    private open;
+    private close;
+    /** Move the highlight by `step` rows, wrapping at both ends. */
+    private move;
+    /** Mirror `active` into the DOM and the input's ARIA wiring. */
+    private syncActive;
+    private onKeyDown;
+    private onListClick;
+    /** Accept an option: fill the field, close the list, report the value. */
+    private commit;
+}

package/dist/controls/datepicker.d.ts

@@ -0,0 +1,42 @@
+import { Component } from "../component";
+import "./datepicker.css";
+export interface DatePickerOptions {
+    /** Initial date as `YYYY-MM-DD`. */
+    value?: string;
+    /** Earliest selectable date, inclusive, as `YYYY-MM-DD`. */
+    min?: string;
+    /** Latest selectable date, inclusive, as `YYYY-MM-DD`. */
+    max?: string;
+    disabled?: boolean;
+    /** Optional label rendered above the control and linked through `for`/`id`. */
+    label?: string;
+    /** Fires with `YYYY-MM-DD` (or "" when cleared) once the value is committed. */
+    onChange?: (value: string) => void;
+}
+/**
+ * A macOS date picker wrapping a native `<input type="date">`.
+ *
+ * The native control is kept, not reimplemented: it brings the platform
+ * calendar popup, keyboard editing of each date segment, locale-correct
+ * formatting, `min`/`max` enforcement and the iOS wheel picker. A hand-built
+ * calendar would have to re-earn all of that and would still not match the OS.
+ *
+ * What this component adds is purely visual — the macOS field chrome and a
+ * trailing calendar icon that is `pointer-events: none`, so the click falls
+ * through to the native picker indicator underneath.
+ */
+export declare class DatePicker extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly input;
+    private readonly labelNode;
+    private readonly onChange?;
+    constructor(options?: DatePickerOptions);
+    /** The current date as `YYYY-MM-DD`, or "" when empty. */
+    get value(): string;
+    /** Set the date; an empty string clears it. Silent, like every setter. */
+    setValue(value: string): void;
+    /** Enable or disable the field, using the native attribute. */
+    setDisabled(disabled: boolean): void;
+    /** Move keyboard focus into the field. */
+    focus(): void;
+}

package/dist/controls/disclosure.d.ts

@@ -0,0 +1,40 @@
+import { Component } from "../component";
+import { type Child } from "../dom";
+import "./disclosure.css";
+export interface DisclosureOptions {
+    /** Section title shown in the header. */
+    title: string;
+    /** Collapsible content. */
+    content?: Child;
+    /** Start expanded. Defaults to false, the macOS convention. */
+    open?: boolean;
+    /** Optional trailing summary, visible whether open or closed. */
+    meta?: string;
+    disabled?: boolean;
+    onToggle?: (open: boolean) => void;
+}
+/**
+ * A collapsible section.
+ *
+ * Uses `aria-expanded` on the header button and `hidden` on the region, which is
+ * the pattern screen readers understand for a disclosure widget: the button
+ * announces whether the section is open, and the content is genuinely removed
+ * from the accessibility tree when closed rather than merely scrolled away.
+ */
+export declare class Disclosure extends Component<HTMLDivElement> {
+    protected readonly root: HTMLDivElement;
+    private readonly header;
+    private readonly content;
+    private readonly metaNode;
+    private readonly onToggle?;
+    private open;
+    constructor(options: DisclosureOptions);
+    /** Expand or collapse the section. */
+    setOpen(open: boolean, notify?: boolean): void;
+    /** Whether the section is currently expanded. */
+    get isOpen(): boolean;
+    /** Update the trailing summary text. */
+    setMeta(meta: string): void;
+    /** The region content is appended to after construction. */
+    get contentElement(): HTMLDivElement;
+}