@motifx-community/ui 0.1.0-beta.1 → 0.1.0-beta.3

package/docs/stepper.md

@@ -0,0 +1,238 @@
+# Stepper
+
+> Navigation · @motifx-community/ui 0.1.0-beta.3
+
+The steps of a longer task and where the user stands in them: an indicator and a text per step, a line between them, the steps before the current one completed. The [Wizard](wizard.md) adds a page and the buttons to each step.
+
+## Import
+
+```tsx
+import { Stepper } from '@motifx-community/ui';
+```
+
+## Declarative and programmatic
+
+The current step is `value`: a step’s `key`, else its index; `x-model` binds it two-way. Programmatically, `next()`, `previous()` and `goTo()` move it and `onStepChanged` tells.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack, Stepper } from '@motifx-community/ui';
+
+/** A stepper bound with x-model, and one made programmatically and moved with its own methods. */
+export default function Programmatic() {
+    const s = reactive({ step: 0 as string | number | null, at: 0, told: '' });
+    const coded = new Stepper({
+        label: 'Order',
+        items: ['Cart', 'Address', 'Payment', 'Done'],
+        linear: false,
+        onStepChanged: e => {
+            s.at = e.index;
+            s.told = `Step ${e.index + 1}${e.byUser ? ', pressed' : ''}`;
+        }
+    });
+
+    return (
+        <Stack gap="lg" style="inline-size: 100%">
+            <Stepper label="Sign up" items={['Account', 'Profile', 'Review']} x-model={() => s.step} />
+            <output class="st-value">{() => `value: ${JSON.stringify(s.step)}`}</output>
+            <span onConfig={c => c.controls.add(coded)} />
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Back" variant="outline" enabled={() => s.at > 0} onclick={() => void coded.previous()} />
+                <Button text="Next" variant="outline" enabled={() => s.at < 3} onclick={() => void coded.next()} />
+                <output class="st-told">{() => s.told}</output>
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Statuses
+
+The steps before the current one are completed by themselves. An item may say `status: 'done'` or `'error'` whatever the current step is, be `optional`, be disabled, or carry an `icon` in place of its number; its fields may be functions of your state.
+
+| Status | How |
+| --- | --- |
+| `pending` | A step to come: its number in the indicator. |
+| `current` | The step in hand: `aria-current="step"`. |
+| `done` | The steps before the current one, and any step whose item says `status: 'done'`: a check in the indicator, the line before it filled. |
+| `error` | A step whose item says `status: 'error'`: a mark in the indicator, the text in the danger colour; read out as “Needs attention”. |
+| `optional` | Says “Optional” under the text; in linear order it may be skipped. |
+| `disabled` | An item with `enabled: false`, or a step linear order does not reach yet: `aria-disabled`, out of the Tab order. |
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack, Stepper } from '@motifx-community/ui';
+
+const pencil = () => {
+    const svg = document.createElementNS('http://www.w3.org/2000/svg', 'svg');
+    svg.setAttribute('viewBox', '0 0 16 16');
+    svg.setAttribute('aria-hidden', 'true');
+    svg.innerHTML = '<path d="M11.5 2.5l2 2L5 13H3v-2z" fill="none" stroke="currentColor" stroke-width="1.5" stroke-linejoin="round"/>';
+    return svg;
+};
+
+/** Completed and failed steps told by the items, an optional step, a disabled one, an icon in place of the number. */
+export default function Statuses() {
+    const s = reactive({ paid: false });
+    const items = [
+        { text: 'Cart', status: 'done' as const },
+        { text: 'Address', description: 'Checked', status: 'done' as const },
+        { text: 'Payment', description: () => (s.paid ? 'Paid' : 'Card declined'), status: () => (s.paid ? 'done' : 'error') },
+        { text: 'Gift note', optional: true, icon: pencil() },
+        { text: 'Pick-up', enabled: false },
+        { text: 'Done' }
+    ];
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Stepper label="Statuses" items={items} value={5} linear={false} />
+            <Button text={() => (s.paid ? 'Decline the card' : 'Take the payment')} variant="outline" onclick={() => (s.paid = !s.paid)} />
+        </Stack>
+    );
+}
+```
+
+## In order, or free
+
+`linear` (the default) lets a press reach only the completed steps and the next one; `linear={false}` lets it reach any. Either way `onStepChanging` is asked first: `cancel` keeps the step, a `promise` waits for a check or a server.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { CheckBox, Stack, Stepper } from '@motifx-community/ui';
+
+/** In linear order a step is reached only after the ones before it; `onStepChanging` refuses a step while the box is unchecked. */
+export default function Linear() {
+    const s = reactive({ step: 0 as string | number | null, agreed: false, note: '' });
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Stepper
+                label="In order"
+                items={['Terms', 'Details', 'Confirm']}
+                x-model={() => s.step}
+                onStepChanging={e => {
+                    if (e.to > 0 && !s.agreed) {
+                        e.cancel = true;
+                        s.note = 'Accept the terms first.';
+                    } else {
+                        s.note = '';
+                    }
+                }}
+            />
+            <CheckBox label="I accept the terms" x-model={() => s.agreed} />
+            <output class="st-note">{() => s.note}</output>
+        </Stack>
+    );
+}
+```
+
+## Orientations
+
+```tsx
+import { Stack, Stepper } from '@motifx-community/ui';
+
+const STEPS = [
+    { text: 'Details', description: 'Name and e-mail' },
+    { text: 'Address', description: 'Where to send it' },
+    { text: 'Payment', description: 'Card or transfer' },
+    { text: 'Review' }
+];
+
+/** Horizontal with the texts under or after the indicators, and vertical. */
+export default function Orientations() {
+    return (
+        <Stack gap="lg" style="inline-size: 100%">
+            <Stepper label="Texts under" items={STEPS} value={1} linear={false} />
+            <Stepper label="Texts after" items={STEPS.slice(0, 3)} value={1} labelPosition="end" linear={false} />
+            <div style="inline-size: 18rem">
+                <Stepper label="Standing" items={STEPS} value={1} orientation="vertical" linear={false} />
+            </div>
+        </Stack>
+    );
+}
+```
+
+## Sizes
+
+```tsx
+import { Stack, Stepper } from '@motifx-community/ui';
+
+const STEPS = ['Plan', 'Build', 'Ship'];
+
+/** Three sizes, and a stepper without numbers. */
+export default function Sizes() {
+    return (
+        <Stack gap="lg" style="inline-size: 100%">
+            <Stepper label="Small" items={STEPS} value={1} size="sm" linear={false} />
+            <Stepper label="Medium" items={STEPS} value={1} linear={false} />
+            <Stepper label="Large" items={STEPS} value={1} size="lg" linear={false} />
+            <Stepper label="Dots" items={STEPS} value={1} showNumbers={false} size="sm" labelPosition="end" linear={false} />
+        </Stack>
+    );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Tab` | One stop: the step focused last, else the current one, else the first that can be reached. |
+| `Arrow keys` | Left and Right (Up and Down standing) move between the steps that can be reached, around the ends; Home and End go to the first and the last. |
+| `Enter, Space` | Choose the focused step; `onStepChanging` may refuse. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Landmark` | A `nav` named “Steps” in the kit language, holding an ordered list; several on one page: give each its own `label`. |
+| `A step` | A button whose name reads “Step 2 of 4, Address, Where to send it, Completed”: the position, the texts and the status are all in it. |
+| `Not clickable` | Plain elements: nothing to press, the current one still `aria-current`. |
+| `Lines and marks` | Decorative, hidden from readers. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-stepper` | The stepper. `data-orientation`, `data-labels`, `data-size`. |
+| `.mx-stepper__list, .mx-stepper__item` | The list and each step with its line. `data-status` on the item. |
+| `.mx-stepper__step` | The step: a button or a div. `data-status`, `aria-current`, `aria-disabled`. |
+| `.mx-stepper__indicator, .mx-stepper__number, .mx-stepper__mark, .mx-stepper__icon` | The circle, the number in it, the check or error mark, an icon of your own. |
+| `.mx-stepper__label, .mx-stepper__description, .mx-stepper__note` | The texts. |
+| `.mx-stepper__line` | The line to the next step. `data-status="done"` up to the current one. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `stepper.step, .indicator, .mark, .label, .description, .note, .line` | Units: the step (`hover`, `pressed`, `focus`, `disabled`, `current`, `done`, `error`), its indicator, the mark (`icon` per state), the texts, the line (`done`); the line turns a quarter in a vertical stepper. |
+| `stepper.size.*, .font-size.*, .padding.*` | The indicator, the text and the space around a step, per size. |
+| `stepper.description-font-size, .gap, .line-gap, .line-min-length` | The second line, the space between indicator and texts, and the line’s margins and least length. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `Bind<readonly (StepperItem \| string)[]>` | `[]` | The steps in order: `StepperItem`s (`text`, `description`, `key`, `icon`, `status`, `optional`, `enabled`, `data`) or plain texts. |
+| `value` | `Bind<string \| number \| null>` | `0` | The current step: its `key`, else its index; `null` for none. `x-model` binds it two-way. |
+| `linear` | `Bind<boolean>` | `true` | A press reaches a completed step, or the one right after the last completed; optional steps may be skipped. |
+| `orientation` | `Bind<StepperOrientation>` | `'horizontal'` | `horizontal` or `vertical`. |
+| `labelPosition` | `Bind<StepperLabelPosition>` | `'bottom'` | Horizontal only: the texts under the indicator (`bottom`) or after it (`end`). |
+| `size` | `Bind<ControlSize>` | `'md'` | `sm`, `md`, `lg`. |
+| `clickable` | `Bind<boolean>` | `true` | `false` shows the way only: no buttons, no Tab stop. |
+| `showNumbers` | `Bind<boolean>` | `true` | The indicator of a step to come shows its number. |
+| `label` | `Bind<string>` | the kit’s “Steps” | What screen readers call it. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onStepChanging` | event | The current step is about to change (`from`, `to`, `fromItem`, `toItem`, `byUser`). `cancel = true` keeps it; `promise` set to a `Promise<boolean>` waits, and the step changes when it resolves to `true`. |
+| `onStepChanged` | event | The current step changed (`index`, `item`, `previous`, `byUser`). |
+| `selectedIndex` | read-only | The index of the current step; -1 when there is none. |
+| `count` | read-only | How many steps there are. |
+| `canGoNext, canGoPrevious` | read-only | There is an enabled step after, or before, the current one. |
+| `next(), previous()` | `Promise<boolean>` | Goes to the next or the previous enabled step; `false` when there is none or the change was refused. |
+| `goTo(step)` | `Promise<boolean>` | Goes to a step by index or key, whatever the order; `onStepChanging` is asked first. |
+| `statusOf(index)` | `StepperStatus` | `pending`, `current`, `done` or `error`, as drawn. |
+| `canReach(index)` | `boolean` | Whether a press may reach the step. |
+| `refresh()` | `void` | Reads the items again after they were changed in place. |

package/docs/switch.md

@@ -1,6 +1,6 @@
 # Switch
 
-> Choice · @motifx-community/ui 0.1.0-beta.1
+> Choice · @motifx-community/ui 0.1.0-beta.3
 
 An on / off switch with its caption: a track with a thumb that slides, an optional on / off text inside or next to it, read-only and required. A native checkbox with the switch role underneath.
 
@@ -10,21 +10,21 @@ An on / off switch with its caption: a track with a thumb that slides, an option
 import { Switch } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-Every prop takes a value or a function; `x-model` binds the value two-way. Created with `new`, the same properties are set from code.
+Every prop takes a value or a function; `x-model` binds the value two-way. Created with `new`, the same properties are set programmatically.
 
 ```tsx
 import { reactive } from '@motifx/core';
 import { Button, Stack, Switch } from '@motifx-community/ui';
 
-/** A switch bound to state with x-model, and switches created with `new` and added from code. */
-export default function FromCode() {
+/** A switch bound to state with x-model, and switches created with `new` and added programmatically. */
+export default function Programmatic() {
   const s = reactive({ wifi: true, result: '' });
   let added = 0;
   let host: Stack | null = null;
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const sw = new Switch({ label: `Feature ${++added}`, onText: 'On', offText: 'Off' });
     sw.onValueChanged((e) => (s.result = `${sw.label}: ${e.value ? 'on' : 'off'}`));
     host?.controls.add(sw);
@@ -35,7 +35,7 @@ export default function FromCode() {
     <>
       <Switch label="&Wi-Fi" x-model={() => s.wifi} helpText={() => (s.wifi ? 'Connected to Home.' : 'Not connected.')} />
       <Stack orientation="horizontal" wrap align="center">
-        <Button text="Add a switch from code" variant="outline" onclick={addFromCode} />
+        <Button text="Add a switch programmatically" variant="outline" onclick={addProgrammatic} />
         <output class="sw-result">{() => s.result}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />

package/docs/tabdocs-dock.md

@@ -1,6 +1,6 @@
 # TabDocumentManager: Dock and floating windows
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 Documents and whole groups float in windows of their own in the page and dock again into the documents' groups or into dock areas around them, which fold to the manager's edge. The mouse, the keys and the code do the same, through the same events.
 
@@ -568,14 +568,14 @@ export function fileDocument(path: string, extra: TabDocumentOptions = {}): TabD
 }
 ```
 
-`FloatFromCode.tsx`
+`FloatProgrammatically.tsx`
 
 ```tsx
 import { Button, Stack, TabDocumentManager } from '@motifx-community/ui';
 import { FILES, fileDocument } from './files';
 
 /** Floating windows by code: float a document, move, resize and maximize its window, dock it back or to a side, close it. */
-export default function FloatFromCode() {
+export default function FloatProgrammatically() {
   const docs = new TabDocumentManager({ label: 'Files to float' });
   docs.element.style.cssText = 'block-size: 28rem; inline-size: 100%';
   for (const file of FILES.slice(0, 5)) docs.open(fileDocument(file.path), { index: 99 });

package/docs/tabdocs-drag.md

@@ -1,6 +1,6 @@
 # TabDocumentManager: Drag and drop
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 Tabs and whole groups dragged as in a code editor: along a strip, to another group, beside a group or along an edge of the layout, between two managers, and the same moves from the keyboard. Every drop goes through the methods and events of what it does.
 

package/docs/tabdocs-menus.md

@@ -1,6 +1,6 @@
 # TabDocumentManager: Menus and keys
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 The commands around the tabs: context menus on tabs and on the empty strip, a searchable list of a group's documents, the app's own toolbar buttons, the recently used list, back and forward, reopening what was closed, locked groups, and the keys for all of them.
 

package/docs/tabdocs-mobile.md

@@ -1,6 +1,6 @@
 # TabDocumentManager: Tablet and phone
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 On a tablet and a phone a layout of groups, splits and dock areas does not fit as it is. The manager keeps the layout and shows it another way: the same documents, groups and areas, the same saved JSON, the content moved and never made again. It goes by its own width, not by the device; on a touch screen its tabs and buttons get larger.
 

package/docs/tabdocs-tabs.md

@@ -1,6 +1,6 @@
 # TabDocumentManager: Tabs
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 What a tab does in a code editor: preview tabs that the next preview replaces, pinned tabs that stay at the start, tabs that shrink, wrap or scroll, counts and colours, and the same document open in two groups.
 

package/docs/tabdocs-windows.md

@@ -1,6 +1,6 @@
 # TabDocumentManager: New windows
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 A document, a group or a floating window moves into a browser window of its own, and back. Its content moves with it, nothing is made again, and the new window is a part of the same manager: its tabs, menus, keys and drag work as they do here.
 

package/docs/tabdocs-workspace.md

@@ -1,6 +1,6 @@
 # TabDocumentManager: A whole workspace
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 A whole screen made of the kit's parts: a menu bar, the manager, a DataGrid with everything turned on, forms and a tool docked at the bottom. Each part is the same component it is on its own page; the manager only holds them.
 

package/docs/tabdocs.md

@@ -1,6 +1,6 @@
 # TabDocumentManager
 
-> TabDocumentManager · @motifx-community/ui 0.1.0-beta.1
+> TabDocumentManager · @motifx-community/ui 0.1.0-beta.3
 
 A document manager in the way code editors arrange files: documents in tabs, tabs in groups, groups split side by side and one under the other. A document's content is any component, a form, a grid or plain text, and it is moved, never made again, when its tab goes to another group. Everything the user does is a method too, asks first and reports after; the whole layout saves to JSON and comes back. Preview and pinned tabs, sizes and copies are on [Tabs](tabdocs-tabs.md); context menus, lists and keys on [Menus and keys](tabdocs-menus.md).
 
@@ -131,7 +131,7 @@ export function customerCard(customer: Customer): ComponentBase {
 }
 ```
 
-## From code, and the events
+## Programmatic use, and the events
 
 Each thing the user does is also a method (`open`, `close`, `activate`, `split`, `move`, `closeGroup`, `focusGroup`, `maximizeGroup`, `restoreGroups`, `evenSizes`, `resizeGroup`), asks first through a cancelable `on…ing` event and reports through `on…ed`, with `byUser` telling the two apart.
 
@@ -731,7 +731,7 @@ export default function Options() {
 }
 ```
 
-`FromCode.tsx`
+`Programmatic.tsx`
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -739,14 +739,14 @@ import { Button, Stack, TabDocumentManager, type SplitDirection } from '@motifx-
 import { notes } from './contents';
 
 /** Everything the user does is a method too; the events report each change, by the user or by code. */
-export default function FromCode() {
+export default function Programmatic() {
   const log = reactive({ lines: [] as { id: number; text: string }[], next: 0, opened: 0 });
   const write = (text: string) => {
     log.lines.unshift({ id: log.next++, text });
     if (log.lines.length > 6) log.lines.pop();
   };
 
-  const docs = new TabDocumentManager({ label: 'Driven from code' });
+  const docs = new TabDocumentManager({ label: 'Driven programmatically' });
   docs.element.style.cssText = 'block-size: 28rem; inline-size: 100%';
   docs.onOpened((e) => write(`opened ${e.document.title} in group ${e.group.index + 1}`));
   docs.onClosed((e) => write(`closed ${e.document.title}${e.byUser ? ' (user)' : ''}`));

package/docs/tabs.md

@@ -1,8 +1,8 @@
 # Tabs
 
-> Navigation · @motifx-community/ui 0.1.0-beta.1
+> Navigation · @motifx-community/ui 0.1.0-beta.3
 
-Tabs show one panel at a time under a strip of tabs: from JSX or from code, closable, with icons and badges, scroll buttons when the tabs do not fit, four placements and panels built when they are first shown.
+Tabs show one panel at a time under a strip of tabs: from JSX or programmatically, closable, with icons and badges, scroll buttons when the tabs do not fit, four placements and panels built when they are first shown.
 
 ## Import
 
@@ -10,22 +10,22 @@ Tabs show one panel at a time under a strip of tabs: from JSX or from code, clos
 import { Tabs, Tab } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-A `<Tab>`'s children are its panel. `value` is the selected tab's `key` (else its index) and `x-model` binds it two-way. Created with `new`, tabs are added, inserted and removed from code.
+A `<Tab>`'s children are its panel. `value` is the selected tab's `key` (else its index) and `x-model` binds it two-way. Created with `new`, tabs are added, inserted and removed programmatically.
 
 ```tsx
 import { reactive } from '@motifx/core';
 import { Button, Stack, Tab, Tabs, TextBox } from '@motifx-community/ui';
 
-/** Tabs from JSX bound with x-model, and tabs created with `new` and added from code. */
-export default function FromCode() {
+/** Tabs from JSX bound with x-model, and tabs created with `new` and added programmatically. */
+export default function Programmatic() {
   const s = reactive({ page: 'general' as string | number, name: '', log: '' });
   let added = 0;
 
   const reports = new Tabs({ label: 'Reports', closable: true });
   reports.add(new Tab({ title: 'Summary', content: () => <p>The summary, built when it was first shown.</p> }));
-  reports.onSelectionChanged((e) => (s.log = e.tab ? `Selected “${e.tab.title}”${e.byUser ? ' by the user' : ' from code'}.` : 'No tab left.'));
+  reports.onSelectionChanged((e) => (s.log = e.tab ? `Selected “${e.tab.title}”${e.byUser ? ' by the user' : ' programmatically'}.` : 'No tab left.'));
 
   const addReport = () => {
     const n = ++added;
@@ -48,7 +48,7 @@ export default function FromCode() {
       </Tabs>
       <output class="tabs-page">{() => `value: "${s.page}"`}</output>
       <Stack orientation="horizontal" wrap align="center">
-        <Button text="Add a report from code" variant="outline" onclick={addReport} />
+        <Button text="Add a report programmatically" variant="outline" onclick={addReport} />
         <output class="tabs-log">{() => s.log}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center" class="tabs-coded" style="inline-size: 100%" onBuilt={(c) => c.controls.add(reports)} />
@@ -346,7 +346,7 @@ Tabs write one text: the close button's tooltip, `uiLocale.strings.close`. Every
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, uiLocale } from '@motifx-community/ui';
 import { kitTexts } from '../../../shared/kit-texts';
 
 /** Switches the texts of every component on the page, the tabs' close button included. */
@@ -354,7 +354,7 @@ export default function Localization() {
   const s = reactive({ lang: 'en' });
   const toggle = () => {
     s.lang = s.lang === 'en' ? 'tr' : 'en';
-    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+    void uiLocale.use(s.lang);
   };
   return (
     <>
@@ -442,7 +442,7 @@ export default function Localization() {
 | `add(tab)` | `Tab` | Adds a tab at the end. A tab of another `Tabs` moves here. |
 | `insert(index, tab)` | `Tab` | Adds a tab at an index. |
 | `remove(tab)` | `boolean` | Removes the tab and disposes it; no `onClose`. The selection and focus move to a neighbour. |
-| `select(tab \| index)` | `boolean` | Selects a tab from code; `false` when it is hidden or not there. |
+| `select(tab \| index)` | `boolean` | Selects a tab programmatically; `false` when it is hidden or not there. |
 | `close(tab)` | `boolean` | Closes a tab as its close button does: `onClose` can cancel it. |
 | `focus()` | `boolean` | Focuses the selected tab. |
 | `Tab.select(), Tab.close(), Tab.focus()` | `boolean` | The same, from the tab. |

package/docs/tagbox.md

@@ -1,6 +1,6 @@
 # TagBox
 
-> Data · @motifx-community/ui 0.1.0-beta.1
+> Data · @motifx-community/ui 0.1.0-beta.3
 
 Picks several items. The chosen ones are tags in the field, followed by a text input that searches the list; items come from memory or from a data source, and typed text can become a tag of its own.
 
@@ -11,9 +11,9 @@ import { TagBox } from '@motifx-community/ui';
 import { data } from '@motifx-community/data';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-`x-model` binds an array; every change writes a new one. Created with `new`, the same properties are set from code.
+`x-model` binds an array; every change writes a new one. Created with `new`, the same properties are set programmatically.
 
 ```tsx
 /** The skills the tag boxes of the examples pick from. */
@@ -265,20 +265,20 @@ export const skills = ['CSS', 'Go', 'HTML', 'Java', 'JavaScript', 'Kotlin', 'Pyt
 
 ## Example files
 
-`FromCode.tsx`
+`Programmatic.tsx`
 
 ```tsx
 import { reactive } from '@motifx/core';
 import { Button, Stack, TagBox } from '@motifx-community/ui';
 import { skills } from './skills';
 
-/** A tag box bound to an array with x-model, and tag boxes created with `new` and added from code. */
-export default function FromCode() {
+/** A tag box bound to an array with x-model, and tag boxes created with `new` and added programmatically. */
+export default function Programmatic() {
   const form = reactive({ skills: ['TypeScript', 'CSS'] as string[], result: '' });
   let added = 0;
   let host: Stack | null = null;
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const tags = new TagBox<string, string>({ label: `Skills ${++added}`, items: skills, placeholder: 'Pick some' });
     tags.onValueChanged((e) => (form.result = `${tags.label}: ${e.value.join(', ')}`));
     host?.controls.add(tags);
@@ -290,7 +290,7 @@ export default function FromCode() {
       <TagBox label="&Skills" items={skills} x-model={() => form.skills} stretch />
       <Stack orientation="horizontal" wrap align="center">
         <output class="tg-skills">{() => `skills: ${JSON.stringify(form.skills)}`}</output>
-        <Button text="Add a tag box from code" variant="outline" onclick={addFromCode} />
+        <Button text="Add a tag box programmatically" variant="outline" onclick={addProgrammatic} />
         <output class="tg-made">{() => form.result}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />
@@ -341,7 +341,7 @@ export default function Validation() {
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, TagBox, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, TagBox, uiLocale } from '@motifx-community/ui';
 import { skills } from './skills';
 
 /** Switches the texts of every tag box on the page: remove buttons, “+3”, “Select all”. */
@@ -349,7 +349,7 @@ export default function Localization() {
   const s = reactive({ lang: 'en' });
   const toggle = () => {
     s.lang = s.lang === 'en' ? 'tr' : 'en';
-    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+    void uiLocale.use(s.lang);
   };
   return (
     <>

package/docs/textarea.md

@@ -1,6 +1,6 @@
 # TextArea
 
-> Editors · @motifx-community/ui 0.1.0-beta.1
+> Editors · @motifx-community/ui 0.1.0-beta.3
 
 A text field of several lines: a box that grows with the text or that the user drags bigger, a character counter, a clear button, Ctrl+Enter to send, and the label, help text and validation every field has.
 
@@ -10,21 +10,21 @@ A text field of several lines: a box that grows with the text or that the user d
 import { TextArea, type TextAreaProps } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-Every prop takes a value or a function; `x-model` binds the text two-way. Created with `new`, the same properties are set from code.
+Every prop takes a value or a function; `x-model` binds the text two-way. Created with `new`, the same properties are set programmatically.
 
 ```tsx
 import { reactive } from '@motifx/core';
 import { Button, Stack, TextArea } from '@motifx-community/ui';
 
-/** A textarea bound with x-model, and notes created with `new` and added from code. */
-export default function FromCode() {
+/** A textarea bound with x-model, and notes created with `new` and added programmatically. */
+export default function Programmatic() {
   const s = reactive({ comment: 'MotifJS keeps the DOM it builds.', log: '' });
   let added = 0;
   let host: Stack | null = null;
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const note = new TextArea({ label: `Note ${++added}`, rows: 2, autoGrow: true, maxRows: 5, clearButton: true });
     note.onValueChanged((e) => (s.log = `${note.label}: ${e.value.split('\n').length} line(s)`));
     host?.controls.add(note);
@@ -35,7 +35,7 @@ export default function FromCode() {
     <>
       <TextArea label="&Comment" x-model={() => s.comment} helpText={() => `${s.comment.length} characters`} stretch />
       <Stack orientation="horizontal" wrap align="center">
-        <Button text="Add a note from code" variant="outline" onclick={addFromCode} />
+        <Button text="Add a note programmatically" variant="outline" onclick={addProgrammatic} />
         <output class="ta-log">{() => s.log}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />
@@ -217,7 +217,7 @@ The name of the clear button and the validation messages come from `uiLocale.str
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, uiLocale } from '@motifx-community/ui';
 import { kitTexts } from '../../../shared/kit-texts';
 
 /** Switches the texts of every field on the page, the clear button's name included. */
@@ -225,7 +225,7 @@ export default function Localization() {
   const s = reactive({ lang: 'en' });
   const toggle = () => {
     s.lang = s.lang === 'en' ? 'tr' : 'en';
-    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+    void uiLocale.use(s.lang);
   };
   return (
     <>