@motifx-community/ui 0.0.0-stage → 0.1.0-beta.0

package/docs/colorbox.md

@@ -0,0 +1,153 @@
+# ColorBox and ColorPicker
+
+> Editors · @motifx-community/ui 0.1.0-beta.0
+
+A colour as a field, with a picker in a popup; or the picker on its own. The picker has an area of saturation and brightness, a hue strip, an opacity strip, inputs for the channels and preset colours.
+
+## Import
+
+```tsx
+import { ColorBox, ColorPicker } from '@motifx-community/ui';
+```
+
+## A colour field
+
+Type a hex or any `rgb(…)` form, or open the picker; the value is kept as hex. Every prop takes a value or a function.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { ColorBox, Stack } from '@motifx-community/ui';
+
+const PALETTE = ['#3b5bdb', '#1971c2', '#0c8599', '#2b8a3e', '#f08c00', '#e8590c', '#e03131', '#c2255c', '#862e9c', '#495057'];
+
+/** A colour field bound with `x-model`: type a hex, or open the picker (Alt+Down); one made with `new` from code. */
+export default function FromCode() {
+  const s = reactive({ accent: '#3b5bdb' as string | null });
+  const coded = new ColorBox({ label: 'Made in code', value: '#2b8a3e', clearButton: true });
+
+  return (
+    <Stack gap="lg" style="inline-size: 18rem; max-inline-size: 100%">
+      <ColorBox label="&Accent" palette={PALETTE} x-model={() => s.accent} helpText={() => `Value: ${s.accent ?? 'none'}`} />
+      <span onConfig={(c) => c.controls.add(coded)} />
+    </Stack>
+  );
+}
+```
+
+## The picker on its own
+
+```tsx
+import { reactive } from '@motifx/core';
+import { ColorPicker, Stack } from '@motifx-community/ui';
+
+const PALETTE = ['#ffffff', '#ced4da', '#495057', '#000000', '#e03131', '#f08c00', '#2b8a3e', '#1971c2', '#862e9c', '#3b5bdb80'];
+
+/** The picker on its own, in the page: with opacity (`alpha`) and preset colours. */
+export default function Picker() {
+  const s = reactive({ color: '#1971c2cc' as string | null });
+
+  return (
+    <Stack gap="lg">
+      <ColorPicker alpha palette={PALETTE} x-model={() => s.color} />
+      <span>{() => `Value: ${s.color}`}</span>
+    </Stack>
+  );
+}
+```
+
+## OK and Cancel
+
+```tsx
+import { reactive } from '@motifx/core';
+import { ColorBox, Stack } from '@motifx-community/ui';
+
+/** Applied with buttons: the value changes on OK, Cancel leaves it; with opacity it keeps `#rrggbbaa`. */
+export default function Buttons() {
+  const s = reactive({ overlay: '#00000080' as string | null });
+
+  return (
+    <Stack gap="lg" style="inline-size: 18rem; max-inline-size: 100%">
+      <ColorBox label="Overlay" alpha apply="useButtons" x-model={() => s.overlay} />
+      <span>{() => `Value: ${s.overlay ?? 'none'}`}</span>
+    </Stack>
+  );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Arrow keys` | On the area: saturation (left, right) and brightness (up, down); on a strip: hue or opacity. Shift moves by 10. |
+| `Home, End` | A strip’s ends. |
+| `Alt+Down` | In the colour box: opens the picker. |
+| `Enter` | In the colour box: takes the hex typed. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Handles` | Sliders named “Saturation and brightness”, “Hue”, “Opacity”, saying where they stand, in the kit language. |
+| `Inputs` | Kit text and number boxes, each with its label (Hex, Red, Green, Blue, Opacity). |
+| `Presets` | Buttons named by their colour; the chosen one is pressed (`aria-pressed`). |
+| `Popup` | A dialog named “Choose color”; focus goes to the area and comes back to the box. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-color-picker` | The picker. `data-alpha`. |
+| `.mx-color-picker__area, __strip, __hue, __alpha, __thumb` | The area, the strips and their handles. |
+| `.mx-color-picker__preview, __inputs, __hex, __channel, __swatches, __swatch, __pick` | The rest of the picker. |
+| `.mx-color-box, .mx-color-box__swatch, .mx-color-box__toggle, .mx-color-box__popup` | The colour box and its parts. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `color-picker.area, .strip, .thumb, .preview, .swatch` | Units: their corners, the handle’s ring and focus, a preset’s hover, chosen and focus looks. |
+| `color-picker.width, .gap, .area-height, .strip-height, .thumb-size, .preview-size, .swatch-size, .swatch-gap` | The picker’s sizes and spaces. |
+| `color-picker.checker-*, color-box.checker-*` | The checker under a see-through colour. |
+| `color-box.swatch, color-box.swatch-size, color-box.popup-gap` | The swatch in the box, and the space in the popup. |
+
+## API reference
+
+### ColorBox props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<string \| null>` | `null` | The colour, kept as `#rrggbb` (`#rrggbbaa` with `alpha`); any `#…` or `rgb(…)` form is read. Two-way with `x-model`. |
+| `alpha` | `Bind<boolean>` | `false` | An opacity strip and input; the value keeps its opacity. |
+| `palette` | `Bind<readonly string[] \| null>` | `null` | Preset colours in the popup. |
+| `apply` | `Bind<ColorBoxApply>` | `'instantly'` | `instantly`: the value follows every move in the popup; `useButtons`: it changes on OK, Cancel leaves it. |
+| `clearButton` | `Bind<boolean>` | `false` | A button that empties it. |
+| `placeholder` | `Bind<string>` | `''` | Shown while it is empty. |
+| `label, helpText, readOnly, required, rules, size…` | see Field |  | Everything a field has. Text that is not a colour is reported as not valid. |
+
+### ColorBox properties, methods and events
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `open(), close()` | methods | Opens or closes the picker (Alt+Down opens it too). |
+| `opened` | read-only | Whether the picker is open. |
+| `onOpened, onClosed` | events | The picker opened, or closed (with the reason). |
+| `picker` | read-only | The `ColorPicker` in the popup, once it was opened. |
+| `clear()` | method | Empties it. |
+
+### ColorPicker props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<string \| null>` | `null` | The colour; it follows every move. Two-way with `x-model`. |
+| `alpha` | `Bind<boolean>` | `false` | An opacity strip and input. |
+| `palette` | `Bind<readonly string[] \| null>` | `null` | Preset colours to choose with one press. |
+| `showInputs` | `Bind<boolean>` | `true` | The hex and red, green, blue inputs. |
+| `eyeDropper` | `Bind<boolean>` | `true` | A button that picks a colour from the screen, where the browser can (EyeDropper). |
+| `onValueChanged` | `ColorChangedEventArgs` |  | The colour changed (`value`), by the user or by code (`byUser`). |
+
+### Functions
+
+| Function | Returns | Description |
+| --- | --- | --- |
+| `parseColor(text)` | `ColorRgba \| null` | Reads `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `rgb(…)`, `rgba(…)`. |
+| `formatColor(rgba)` | `string` | `#rrggbb`, or `#rrggbbaa` when it is not opaque. |

package/docs/combobox.md

@@ -0,0 +1,214 @@
+# ComboBox and Autocomplete
+
+> Choice · @motifx-community/ui 0.1.0-beta.0
+
+A text field with a list that follows what is typed. The items come from memory or from a data source of the data layer, searched on the server. `Autocomplete` is the free-text kind: the value is the text.
+
+## Import
+
+```tsx
+import { ComboBox, Autocomplete } from '@motifx-community/ui';
+import { data } from '@motifx-community/data';
+```
+
+## From JSX and from code
+
+```tsx
+/** The cities the combo boxes of the examples suggest. */
+export const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'Diyarbakır', 'Erzurum', 'Eskişehir', 'Gaziantep', 'İstanbul', 'İzmir', 'Kayseri', 'Konya', 'Mersin', 'Samsun', 'Trabzon'];
+```
+
+## From a data source
+
+With `dataSource` the search goes to the data source (its `searchFields`), after `searchDelay`. In `'blocks'` mode only the rows in view load; a value on no loaded page is found by key, so the field shows its text at once. This one holds 10,000 products and answers after 300 ms.
+
+```tsx
+import { data } from '@motifx-community/data';
+
+/** Rows in memory that answer a little later, the way a server does; for the examples. */
+export class SlowAdapter<T extends object, K> extends data.ArrayAdapter<T, K> {
+  constructor(
+    options: data.ArrayAdapterOptions<T>,
+    private readonly delayMs = 300,
+  ) {
+    super(options);
+  }
+
+  override async load(options: data.LoadOptions = {}): Promise<data.LoadResult<T>> {
+    await new Promise((done) => setTimeout(done, this.delayMs));
+    return super.load(options);
+  }
+}
+```
+
+## Custom values and Autocomplete
+
+```tsx
+/** The cities the combo boxes of the examples suggest. */
+export const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'Diyarbakır', 'Erzurum', 'Eskişehir', 'Gaziantep', 'İstanbul', 'İzmir', 'Kayseri', 'Konya', 'Mersin', 'Samsun', 'Trabzon'];
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Typing` | Searches and opens the list; the first match is highlighted. |
+| `Down / Up, Alt + Down` | Open the list with every item; move in it. |
+| `Enter` | Take the highlighted item (or the text, see `acceptCustomValue`) and close. |
+| `Tab, leaving` | An item whose text is the text is taken; otherwise the custom value or the chosen item again. |
+| `Escape` | Close the list; closed, undo the typing; then, with `clearButton`, empty it. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Pattern` | The APG combobox with list autocomplete: the input is `role="combobox"`, `aria-autocomplete="list"`, `aria-expanded`, `aria-controls`. |
+| `Highlight` | `aria-activedescendant` names the highlighted option; focus stays in the input. |
+| `Loading` | Rows not loaded yet are options with `aria-busy`, reading "Loading…" from `uiLocale`. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<V \| null>` | `null` | The value of the chosen item; `x-model` binds it. |
+| `items / dataSource` | `Bind<readonly T[]>` / `Bind<DataSource \| null>` | — | Items in memory, searched here, or a data source of `@motifx-community/data`, searched where it lives. |
+| `textField, valueField, iconField, groupField, enabledField` | `Bind<ItemField<T>>` | — | As for DropDown; groups for items in memory. |
+| `searchMode` | `Bind<'contains' \| 'startswith'>` | `'contains'` | How items in memory match. |
+| `minSearchLength` | `Bind<number>` | `0` | Characters to type before the list opens. |
+| `searchDelay` | `Bind<number>` | `0` / `250` | Milliseconds after the last key before searching (in memory / a data source). |
+| `acceptCustomValue` | `Bind<boolean>` | `false` | Text that matches no item becomes the value; otherwise the field goes back to the chosen item. |
+| `autoHighlight` | `Bind<boolean>` | `true` | The first match is highlighted, so Enter takes it. |
+| `showDropDownButton, clearButton` | `Bind<boolean>` | `true`, `false` | The arrow that opens every item; the button that empties it. |
+| `itemTemplate, matchWidth, placeholder` |  |  | As for DropDown. |
+
+### Properties, methods, events
+
+| Member | Description |
+| --- | --- |
+| `selectedItem` | The item of the value, when known. |
+| `listItems` | The `DataItems` the list shows (what the last search matched). |
+| `opened, open(), close(), clear()` | The list and the value. |
+| `refresh()` | Your items may be plain or reactive; the box reads them as they are. After changing them in place, call `refresh()`. The open list and the text of the value follow. Autocomplete has it too. |
+| `onValueChanged, onOpened, onClosed, onValidated` | As for DropDown. |
+
+The items part is shared: `DataItems` feeds any list control from an array or a data source.
+
+## Example files
+
+`FromCode.tsx`
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, ComboBox, Stack } from '@motifx-community/ui';
+import { cities } from './cities';
+
+/** A combo box bound with x-model, and combo boxes created with `new` and added from code. */
+export default function FromCode() {
+  const form = reactive({ city: 'İzmir' as string | null, result: '' });
+  let added = 0;
+  let host: Stack | null = null;
+
+  const addFromCode = () => {
+    const town = new ComboBox<string, string>({ label: `Town ${++added}`, items: cities, minSearchLength: 2 });
+    town.onValueChanged((e) => (form.result = `${town.label}: ${e.value ?? '—'}`));
+    host?.controls.add(town);
+    town.focus();
+  };
+
+  return (
+    <>
+      <ComboBox label="&City" items={cities} x-model={() => form.city} clearButton />
+      <output class="cb-city">{() => `city: ${form.city ?? '—'}`}</output>
+      <Button text="Add a combo box from code" variant="outline" onclick={addFromCode} />
+      <output class="cb-made">{() => form.result}</output>
+      <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />
+    </>
+  );
+}
+```
+
+`cities.ts`
+
+```tsx
+/** The cities the combo boxes of the examples suggest. */
+export const cities = ['Adana', 'Ankara', 'Antalya', 'Bursa', 'Diyarbakır', 'Erzurum', 'Eskişehir', 'Gaziantep', 'İstanbul', 'İzmir', 'Kayseri', 'Konya', 'Mersin', 'Samsun', 'Trabzon'];
+```
+
+`Products.tsx`
+
+```tsx
+import { reactive } from '@motifx/core';
+import { data } from '@motifx-community/data';
+import { ComboBox } from '@motifx-community/ui';
+import { SlowAdapter } from '../../../shared/slow-adapter';
+
+interface Product {
+  id: number;
+  name: string;
+  category: string;
+}
+
+const categories = ['Beverages', 'Condiments', 'Dairy', 'Grains', 'Produce', 'Seafood'];
+const rows: Product[] = Array.from({ length: 10000 }, (_, i) => ({ id: i + 1, name: `${categories[i % 6]} item ${i + 1}`, category: categories[i % 6] }));
+
+/** 10,000 products behind a server that answers after 300 ms: the search goes to the data source, the value's text is found by key. */
+export default function Products() {
+  const line = reactive({ product: 2500 as number | null });
+  const products = new data.DataSource<Product, number>({
+    adapter: new SlowAdapter<Product, number>({ data: rows, key: 'id' }, 300),
+    loadMode: 'blocks',
+    pageSize: 50,
+    searchFields: ['name'],
+  });
+
+  return (
+    <>
+      <ComboBox label="Product" dataSource={products} textField="name" valueField="id" x-model={() => line.product} stretch />
+      <output class="cb-product">{() => `product: ${line.product ?? '—'}`}</output>
+    </>
+  );
+}
+```
+
+`slow-adapter.ts`
+
+```tsx
+import { data } from '@motifx-community/data';
+
+/** Rows in memory that answer a little later, the way a server does; for the examples. */
+export class SlowAdapter<T extends object, K> extends data.ArrayAdapter<T, K> {
+  constructor(
+    options: data.ArrayAdapterOptions<T>,
+    private readonly delayMs = 300,
+  ) {
+    super(options);
+  }
+
+  override async load(options: data.LoadOptions = {}): Promise<data.LoadResult<T>> {
+    await new Promise((done) => setTimeout(done, this.delayMs));
+    return super.load(options);
+  }
+}
+```
+
+`CustomValues.tsx`
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Autocomplete, ComboBox } from '@motifx-community/ui';
+import { cities } from './cities';
+
+/** A combo box that takes text matching no item, and an Autocomplete whose value is the text itself. */
+export default function CustomValues() {
+  const form = reactive({ tag: '', query: '' });
+  return (
+    <>
+      <ComboBox label="Tag" items={['bug', 'feature', 'docs']} acceptCustomValue x-model={() => form.tag} />
+      <Autocomplete label="Search" items={cities} x-model={() => form.query} />
+      <output class="cb-query">{() => `query: "${form.query}"`}</output>
+    </>
+  );
+}
+```

package/docs/control.md

@@ -0,0 +1,232 @@
+# Control
+
+> Foundations · @motifx-community/ui 0.1.0-beta.0
+
+The base of every control in the package. It gives each one the same `text`, `enabled`, `visible` and `tabStop`, and the same focus methods, whether the control is written in JSX and bound to state or created with `new` and changed from code.
+
+## Import
+
+```tsx
+import { Control, type ControlProps } from '@motifx-community/ui';
+```
+
+Every component of the package ([Button](button.md), …) extends it; extend it for your own controls.
+
+## From JSX and from code
+
+Both ways are complete; the developer using the control decides.
+
+```tsx
+// JSX, bound to state
+<Badge text="Unread" enabled={() => !this.state.busy} />
+
+// code: create, add anywhere, change later
+const unread = new Badge({ text: 'Unread' });
+this.toolbar.controls.add(unread);
+unread.enabled = false;
+unread.text = 'Unread mail';
+unread.text = () => `Unread (${this.mail.count})`; // a function is followed
+```
+
+`Badge` is the control written in [Writing a control](#own).
+
+```tsx
+import { Button, Stack } from '@motifx-community/ui';
+
+/** Buttons created with `new`, added to a container, and their text changed from code on a click. */
+export default function AddFromCode() {
+  let added = 0;
+  let target: Stack | null = null;
+
+  const addFromCode = () => {
+    const b = new Button({ text: `Button ${++added}` });
+    b.motif.on('click', () => (b.text = `${b.text} ✓`));
+    target?.controls.add(b);
+  };
+
+  return (
+    <>
+      <Button text="Add a button from code" onclick={addFromCode} />
+      <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (target = c)} />
+    </>
+  );
+}
+```
+
+## How a property gets its value
+
+- A prop is a value or a function. A function of a reactive object (`enabled={() => !state.busy}`) keeps the property in step with it; this is how MotifJS keeps a prop live.
+
+- Your data is used as you give it: the control never makes it reactive, never copies or changes it. Over plain data the function is read again when you call `reState()` on the control or on anything it sits in; you choose which kind of data to give.
+
+- With `x-model` the model always shows the control's state: a change by the user, by your code (`ctrl.value = …`, `select()`, `show()`) or by a rule you gave (`decimals`, a mask, `min` / `max`) is written back to it.
+
+- A property set from code takes the same: a function (`ctrl.enabled = () => !state.busy`) is bound in place of what was there and followed; a value (`ctrl.enabled = false`) drops what was bound, and from then on the code owns it.
+
+- Every property is reactive to read: `{() => ctrl.text}` in JSX or a `bindings.watch` follows it, whichever way it changed.
+
+- `x-wait` and `x-display` stay one-way: they show and hide from state, and nothing is written back. If the state must change when the control goes away, do it in `onDisposed`.
+
+## Enabled
+
+Disabling a control disables everything inside it — other controls and plain elements alike, as a disabled `<fieldset>` does for form fields — and enabling it puts every element back exactly as it was. An element that was disabled on its own stays disabled; content added while the control is disabled is disabled too; a change the app makes in the meantime (a bound `disabled`) is what gets restored. Disabled containers nest: an element stays disabled while any of them, or its own value, says so.
+
+| What | What happens |
+| --- | --- |
+| `Native controls` | `button`, `input`, `select`, `textarea`, `fieldset`, `optgroup`, `option` get `disabled`: the browser blocks them and announces the state. |
+| `Other focusable elements` | Links, `[tabindex]`, `contenteditable`, `summary`, `iframe` get `tabindex="-1"` and `aria-disabled="true"`. |
+| `Pointer input` | `pointerdown`, `mousedown`, `click`, `dblclick`, `auxclick` and `contextmenu` are swallowed inside the disabled control, before any handler. |
+| `The control itself` | Gets `data-disabled` for styling. |
+| `Windows inside` | A `<dialog>` window opened inside a disabled control is not disabled: owned windows stay usable. |
+
+If focus was inside, it moves to the next usable element in the same window (or the one before it) instead of falling to `<body>`.
+
+```tsx
+import { Button, Panel, Stack } from '@motifx-community/ui';
+
+/** A panel disabled and enabled from code: everything inside follows, and the inner button keeps its own `enabled`. */
+export default function EnabledPanel() {
+  let panel: Panel | null = null;
+  let inner: Button | null = null;
+
+  return (
+    <>
+      <Button text="Toggle panel enabled" onclick={() => (panel!.enabled = !panel!.enabled)} />
+      <Panel variant="outline" padding="md" class="ctl-panel" ref={(p: Panel) => (panel = p)}>
+        <Stack orientation="horizontal" wrap align="center">
+          <label>
+            Name <input name="panel-name" />
+          </label>
+          <Button text="Inner button" ref={(b: Button) => (inner = b)} />
+          <a href="#enabled">A link</a>
+        </Stack>
+      </Panel>
+      <output>{() => (inner ? `Inner button: enabled ${inner.enabled}, isEnabled ${inner.isEnabled}` : '')}</output>
+    </>
+  );
+}
+```
+
+## Visible and TabStop
+
+`visible` uses core `hide()` / `show()`: a hidden control leaves the page and comes back in place, with its state. If focus was inside, it moves on first. `tabStop = false` only skips the control on Tab.
+
+## Focus
+
+```tsx
+if (!nameBox.focus()) saveButton.focus();
+nameBox.canFocus;      // enabled, on the page, focusable
+panel.focusWithin;   // focus is somewhere inside
+```
+
+Focus never falls to `<body>` because of a control: disabling, hiding, removing or disposing the focused part moves focus to the next usable element. Focus rings show only for keyboard use (`:focus-visible`). Tab order, access keys and shortcuts: [Keyboard and focus](keyboard.md).
+
+## FocusContainer
+
+A control that remembers which control inside it is active and is a scope for Tab; the package's windows, tab pages and document views will be ones. The outermost container of a page or window also runs the `tabIndex` order (see [Keyboard and focus](keyboard.md)).
+
+```tsx
+class CustomerEditor extends FocusContainer<HTMLDivElement> { … }
+
+editor.activeControl;           // the control holding focus inside, reactive
+editor.activeControl = nameBox; // focuses it
+editor.restoreFocus();          // back to where focus was when it was last active
+```
+
+| Member | Type | Kind | Description |
+| --- | --- | --- | --- |
+| `activeControl` | `Control \| null` | read/write, reactive | The control inside that has (or last had) focus, as `document.activeElement` is for the page; a nested container counts as one. Setting it focuses that control. |
+| `restoreFocus()` | `boolean` | method | Focus back to where it was the last time the container was active, else its active control, else the first in Tab order. |
+| `cyclesTab` | `boolean` | protected getter | `true` keeps Tab inside the container. `false` by default; a modal window returns `true`. |
+
+## Writing a control
+
+Extend `Control`, set the root element, and render `text` (and your own properties) with `observeProperty`: no effect is created, the callback runs on every change.
+
+```tsx
+interface BadgeProps extends ControlProps {
+  count?: Bind<number>;
+}
+
+class Badge extends Control<HTMLSpanElement, BadgeProps> {
+  static override elementTag = 'span';
+
+  constructor(props?: IBaseProp<BadgeProps>) {
+    super(props);
+    if (this.props.count !== undefined) this.bindProperty('count', this.props.count);
+  }
+
+  get count(): number { return this.getProperty<number>('count') ?? 0; }
+  set count(value: number) { this.setProperty('count', value); }
+
+  override onConfigured() {
+    this.class.add('my-badge');
+    this.observeProperty<string>('text', (t) => this.element.setAttribute('aria-label', t));
+    this.observeProperty<number>('count', (n) => (this.element.textContent = String(n ?? 0)));
+  }
+}
+```
+
+| Member | What it is |
+| --- | --- |
+| `static elementTag` | The root element. `div` unless the subclass sets another (`button` for a button). |
+| `focusElement` | Getter: the element that takes focus; the root by default. Composite controls override it. It runs from the constructor, so derive it from `this.element`. |
+| `observeProperty(name, apply)` | Renders a property without an effect: `apply` runs now and on every change, from a getter prop or from code. |
+| `getProperty(name) / setProperty(name, value)` | The storage behind the shared properties, for your own: tracked read, and set-from-code (which replaces a bound getter). |
+| `bindProperty(name, prop)` | Binds one of your own props: a getter is read now and followed by a binding of the control (so `reState()` reads it again), a value is stored once. Call it from your constructor. |
+| `applyProperty(name, value) / peekProperty(name)` | Render your own properties without an effect: override `applyProperty` (call `super`); read the current value untracked with `peekProperty`. Can run from the constructor: touch only `this.element`. |
+| `setAccessKey(key)` | Declares the access key parsed from `&Text` (`parseAccessKey`): written to `aria-keyshortcuts` as `Alt+K`, which is how Alt+K finds the control. |
+
+## Performance
+
+The base adds no listeners per control and pays only for what is used.
+
+| Case | Cost |
+| --- | --- |
+| `A property nobody set, bound or read` | Nothing: no storage, no DOM write, no binding. |
+| `A plain value (`enabled={false}`, `new Badge({ text })`)` | Stored and written to the DOM once. |
+| `A getter (`enabled={() => !state.busy}`)` | One binding for that property, stopped when the control is disposed or another value or function is set. |
+| `Reading a property` | A small change counter, created the first time someone reads it. |
+| `Setting from code` | A direct DOM write; readers are notified through the counter. |
+| ``enabled = false`` | One pass over the control's subtree, plus one shared observer while anything is disabled (it disappears when nothing is). |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `text` | `Bind<string>` | `''` | The control's text. Where it shows is up to the control: a button's caption, a form's title. |
+| `enabled` | `Bind<boolean>` | `true` | `false` disables the control and everything inside it. See "Enabled". |
+| `disabled` | `Bind<boolean>` | `false` | The HTML-style inverse of `enabled`, for habit: `disabled={() => state.busy}`. Ignored when `enabled` is given. |
+| `visible` | `Bind<boolean>` | `true` | `false` hides the control with core `hide()`; `true` shows it again with `show()`. |
+| `tabStop` | `Bind<boolean>` | `true` | `false` takes the control out of the Tab order; a click or `focus()` still focuses it. |
+| `tabIndex` | `Bind<number>` | `0` | Order among the controls of the same container: Tab visits them in ascending order, ties in document order. Leave it unset where you can: document order is also the reading order of screen readers. See Keyboard and focus. |
+
+### Properties
+
+| Property | Type | Access | Description |
+| --- | --- | --- | --- |
+| `text` | `string` | read/write, reactive | Set from code with a value or a function, like the prop (see "How a property gets its value"). |
+| `enabled` | `boolean` | read/write, reactive | This control's own value, as set or bound (like the HTML `disabled` attribute). |
+| `isEnabled` | `boolean` | read-only, reactive | Whether it can be used now: enabled itself and in every control it sits in (like CSS `:enabled`). Windows shown inside do not inherit it. |
+| `visible` | `boolean` | read/write, reactive | This control's own value; a hidden parent does not change it. |
+| `disabled` | `boolean` | read/write, reactive | `!enabled`. |
+| `tabIndex` | `number` | read/write, reactive | Position in the Tab order of its container. |
+| `tabStop` | `boolean` | read/write, reactive | Writes `tabindex="-1"` on the focus element while `false`, and puts back the element's own `tabindex` afterwards. |
+| `parentControl` | `Control \| null` | read-only | The nearest ancestor that is a `Control`, not crossing a window. |
+| `canFocus` | `boolean` | read-only | Enabled, on the page and focusable right now. |
+| `focused` | `boolean` | read-only | Its focus element has focus. A DOM query, not reactive. |
+| `focusWithin` | `boolean` | read-only | Focus is on it or anything inside it. A DOM query, not reactive. |
+
+### Methods
+
+| Method | Returns | Description |
+| --- | --- | --- |
+| `focus()` | `boolean` | Focuses the control; `false` when it cannot take focus (`canFocus`). |
+| `onAccessKey()` | `boolean` | What its access key (`&Save` → Alt+S, Control+Option+S on Apple platforms) does: focus; a button also clicks. Override it in your control. |
+| `addShortcut(chord, handler, options?)` | `() => void` | A shortcut active while focus is inside this control, removed when it is disposed. See Keyboard and focus. |
+
+## Not yet
+
+- Arrow keys inside composite controls (one Tab stop, arrows inside): with the first composite control.