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

package/docs/layout.md

@@ -1,6 +1,6 @@
 # Layout
 
-> Navigation · @motifx-community/ui 0.1.0-beta.1
+> Navigation · @motifx-community/ui 0.1.0-beta.3
 
 Containers that place controls: `Stack` (a row or a column), `Grid` (rows and columns), `Panel` (a plain box that can scroll), `GroupBox` (a titled frame), `DockPanel` (children stuck to its edges) and `SplitContainer` (two panes and a splitter). All of them are controls: they disable and hide what is inside, and lay out children added at any time.
 
@@ -10,7 +10,7 @@ Containers that place controls: `Stack` (a row or a column), `Grid` (rows and co
 import { Stack, Grid, Panel, GroupBox, DockPanel, SplitContainer, type LayoutSpace } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
 Children come as JSX or are added later with `controls.add`; either way the container picks them up. A child says where it goes in its own props (`grow`, `row`, `dock`…), whatever kind of component it is.
 
@@ -19,13 +19,13 @@ import type { Component } from '@motifx/core';
 import { Button, Grid, Stack, TextBox } from '@motifx-community/ui';
 
 /** Buttons added to a Stack with `controls.add`, and a Grid built with `new`. */
-export default function FromCode() {
+export default function Programmatic() {
   let added = 0;
   let bar: Stack | null = null;
 
   const addButton = () => bar?.controls.add(new Button({ text: `Button ${++added}`, variant: 'outline', grow: added % 3 === 0 }));
 
-  const buildFromCode = (host: Component<HTMLDivElement>) => {
+  const buildProgrammatic = (host: Component<HTMLDivElement>) => {
     const grid = new Grid({ columns: '* *', gap: 'xs' });
     grid.element.classList.add('layout-coded');
     grid.controls.add(
@@ -41,7 +41,7 @@ export default function FromCode() {
       <Stack ref={(c: Stack) => (bar = c)} orientation="horizontal" gap="sm" wrap align="center" style="inline-size: 100%">
         <Button text="Add a button" tone="accent" onclick={addButton} />
       </Stack>
-      <div style="inline-size: 100%" ref={(c: Component<HTMLDivElement>) => buildFromCode(c)} />
+      <div style="inline-size: 100%" ref={(c: Component<HTMLDivElement>) => buildProgrammatic(c)} />
     </>
   );
 }
@@ -287,7 +287,7 @@ const FRAME = 'border: var(--mx-border-width-1) solid var(--mx-color-stroke-card
 const BAR = 'background: var(--mx-color-bg-bar);';
 const LAYER = 'background: var(--mx-color-bg-layer);';
 
-/** A mail app laid out with DockPanel: a header, a sidebar that changes sides, a status bar, a float button and a panel added from code. */
+/** A mail app laid out with DockPanel: a header, a sidebar that changes sides, a status bar, a float button and a panel added programmatically. */
 export default function AppShell() {
   const s = reactive({ side: 'start' as Dock, messages: 3 });
   let shell: DockPanel | null = null;
@@ -302,7 +302,7 @@ export default function AppShell() {
     notes = new Panel({ dock: 'end', padding: 'sm' });
     notes.element.setAttribute('style', `inline-size: 9rem; ${LAYER}`);
     notes.element.classList.add('layout-notes');
-    notes.controls.add(<span>Notes, added from code.</span>);
+    notes.controls.add(<span>Notes, added programmatically.</span>);
     shell?.controls.add(notes);
   };
 
@@ -310,7 +310,7 @@ export default function AppShell() {
     <>
       <Stack orientation="horizontal" wrap align="center">
         <Button text={() => `Sidebar: ${s.side}`} size="sm" variant="outline" onclick={() => (s.side = s.side === 'start' ? 'end' : 'start')} />
-        <Button text="Notes panel from code" size="sm" variant="outline" onclick={toggleNotes} />
+        <Button text="Notes panel programmatically" size="sm" variant="outline" onclick={toggleNotes} />
       </Stack>
       <DockPanel class="layout-shell" ref={(c: DockPanel) => (shell = c)} style={`block-size: 22rem; inline-size: 100%; overflow: hidden; ${FRAME}`}>
         <Stack dock="top" orientation="horizontal" align="center" gap="sm" padding="xs sm" style={BAR}>
@@ -332,7 +332,7 @@ export default function AppShell() {
         <Panel class="layout-content" text="Message" scrollable padding="md">
           <h3 style="margin-block-start: 0">Welcome</h3>
           <p>The header, the folders and the status bar are docked; this panel fills the rest and scrolls on its own.</p>
-          <p>Switch the sidebar to the other side, or add a panel from code: the layout follows at once.</p>
+          <p>Switch the sidebar to the other side, or add a panel programmatically: the layout follows at once.</p>
         </Panel>
         <Button class="layout-help" dock="float" right={16} bottom={48} text="Help" variant="outline" />
       </DockPanel>
@@ -353,7 +353,7 @@ const FOLDERS = ['Inbox', 'Drafts', 'Sent', 'Archive', 'Spam', 'Trash'];
 const FRAME = 'border: var(--mx-border-width-1) solid var(--mx-color-stroke-card); border-radius: var(--mx-radius-lg);';
 const LAYER = 'background: var(--mx-color-bg-layer);';
 
-/** A split container inside another: a position bound with x-model, minimum sizes, a fixed pane, and hiding a pane from code. */
+/** A split container inside another: a position bound with x-model, minimum sizes, a fixed pane, and hiding a pane programmatically. */
 export default function NestedSplit() {
   const s = reactive({ tree: 180 as SplitPosition, fixed: 'first' as SplitPanel, log: '' });
   let outer: SplitContainer | null = null;
@@ -426,7 +426,7 @@ The only text the containers write is the splitter's name, `uiLocale.strings.res
 
 ```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 the kit; the splitters on the page take the new name at once. */
@@ -434,7 +434,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 (
     <>
@@ -567,9 +567,9 @@ Every container also has the shared properties of `Control`: `enabled` / `disabl
 
 | Method | Returns | Description |
 | --- | --- | --- |
-| `Stack.setGrow(child, grow), growOf(child)` | `void`, value | A child's `grow` from code (a value or a function). |
-| `Grid.setCell(child, cell), cellOf(child)` | `void`, `GridCell` | A child's `row`, `column`, `rowSpan`, `columnSpan` from code. |
-| `DockPanel.setDock(child, dock), dockOf(child)` | `void`, `Dock` | A child's `dock` from code. |
+| `Stack.setGrow(child, grow), growOf(child)` | `void`, value | A child's `grow` programmatically (a value or a function). |
+| `Grid.setCell(child, cell), cellOf(child)` | `void`, `GridCell` | A child's `row`, `column`, `rowSpan`, `columnSpan` programmatically. |
+| `DockPanel.setDock(child, dock), dockOf(child)` | `void`, `Dock` | A child's `dock` programmatically. |
 | `DockPanel.setAnchors(child, anchors)` | `void` | The `left` / `top` / `right` / `bottom` of a `float` child. |
 | `SplitContainer.collapse(pane?), restore()` | `void` | Hides a pane (the first by default) / shows both again. |
 | `GroupBox.focus()` | `boolean` | Focuses the first control inside, opening a collapsed box. |

package/docs/listbox.md

@@ -1,6 +1,6 @@
 # ListBox
 
-> Data · @motifx-community/ui 0.1.0-beta.1
+> Data · @motifx-community/ui 0.1.0-beta.3
 
 A list that stays on the page. One item or several are chosen with the keys or the pointer; items come from memory or from a data source, can be searched and grouped, and long lists draw only the rows in view.
 
@@ -11,9 +11,9 @@ import { ListBox } from '@motifx-community/ui';
 import { data } from '@motifx-community/data';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-`items` can be plain values; `x-model` binds the value. Created with `new`, the same properties are set from code.
+`items` can be plain values; `x-model` binds the value. Created with `new`, the same properties are set programmatically.
 
 ```tsx
 /** The cities the lists of the examples show. */
@@ -164,14 +164,14 @@ export const cities = ['Ankara', 'Antalya', 'Bursa', 'İstanbul', 'İzmir', 'Kon
 
 ```tsx
 import { reactive } from '@motifx/core';
-import { Button, ListBox, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, ListBox, uiLocale } from '@motifx-community/ui';
 
 /** Switches the texts of every list on the page: “Select all”, the search box, “No items”. */
 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 (
     <>
@@ -255,20 +255,20 @@ A prop whose value is a function of its own (`textField`, a template) takes the
 
 ## Example files
 
-`FromCode.tsx`
+`Programmatic.tsx`
 
 ```tsx
 import { reactive } from '@motifx/core';
 import { Button, ListBox, Stack } from '@motifx-community/ui';
 import { cities } from './cities';
 
-/** A list bound with x-model, and lists created with `new` and added from code. */
-export default function FromCode() {
+/** A list bound with x-model, and lists created with `new` and added programmatically. */
+export default function Programmatic() {
   const form = reactive({ city: 'İzmir' as string | null, result: '' });
   let added = 0;
   let host: Stack | null = null;
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const list = new ListBox<string, string>({ label: `Size ${++added}`, items: ['S', 'M', 'L', 'XL'], height: 4 });
     list.onValueChanged((e) => (form.result = `${list.label}: ${e.value}`));
     host?.controls.add(list);
@@ -280,7 +280,7 @@ export default function FromCode() {
       <ListBox label="&City" items={cities} x-model={() => form.city} />
       <Stack orientation="horizontal" wrap align="center">
         <output class="lb-city">{() => `city: ${form.city ?? '—'}`}</output>
-        <Button text="Add a list from code" variant="outline" onclick={addFromCode} />
+        <Button text="Add a list programmatically" variant="outline" onclick={addProgrammatic} />
         <output class="lb-made">{() => form.result}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />

package/docs/loadpanel.md

@@ -0,0 +1,184 @@
+# LoadPanel
+
+> Feedback · @motifx-community/ui 0.1.0-beta.3
+
+A “loading” layer over a container or the whole page: a shade, a pane with the kit’s spinner and a message, a Cancel button when the work can be stopped. Nothing under it can be used meanwhile, and focus comes back afterwards.
+
+## Import
+
+```tsx
+import { LoadPanel } from '@motifx-community/ui';
+```
+
+## Over a container
+
+`target` names the component or element it covers; `value` (or `x-model`) shows and hides it, `show()` and `hide()` programmatically. `delay` keeps quick work from flashing it.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, LoadPanel, Panel, Stack, TextBox } from '@motifx-community/ui';
+
+/** A load panel over a panel while its orders load: bound with x-model, shown after a short delay. */
+export default function Container() {
+    const s = reactive({ loading: false, result: '' });
+    let panel!: Panel;
+
+    // Stands in for a call to the server.
+    const load = () => {
+        s.loading = true;
+        s.result = '';
+        setTimeout(() => {
+            s.loading = false;
+            s.result = 'Orders loaded.';
+        }, 1800);
+    };
+
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Panel class="lp-panel" variant="outline" padding="md" style="min-block-size: 10rem" ref={(c: Panel) => (panel = c)}>
+                <Stack orientation="horizontal" wrap align="center">
+                    <TextBox label="Customer" value="Ada" />
+                    <Button text="Load orders" tone="accent" onclick={load} />
+                </Stack>
+            </Panel>
+            <LoadPanel target={() => panel} message="Loading orders" delay={200} x-model={() => s.loading} />
+            <output class="lp-result">{() => s.result}</output>
+        </Stack>
+    );
+}
+```
+
+## Over the page, with Cancel
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, LoadPanel, Stack } from '@motifx-community/ui';
+
+/** Over the whole page, with a Cancel button: the work stops when it is pressed (or on Escape). */
+export default function Page() {
+    const s = reactive({ told: '' });
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    const panel = new LoadPanel({
+        message: 'Building the report…',
+        cancelable: true,
+        onCancel: () => {
+            if (timer) clearTimeout(timer);
+            timer = null;
+            s.told = 'Cancelled.';
+        }
+    });
+    const start = () => {
+        s.told = '';
+        panel.show();
+        timer = setTimeout(() => {
+            timer = null;
+            panel.hide();
+            s.told = 'The report is ready.';
+        }, 4000);
+    };
+    return (
+        <Stack orientation="horizontal" wrap align="center">
+            <Button text="Build the report" variant="outline" onclick={start} />
+            <span onConfig={c => c.controls.add(panel)} />
+            <output class="lp-told">{() => s.told}</output>
+        </Stack>
+    );
+}
+```
+
+## Shade, pane and indicator
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, LoadPanel, Panel, Stack } from '@motifx-community/ui';
+
+/** Without the shade, without the pane, without the indicator; a press on the shade may hide it. */
+export default function Options() {
+    const s = reactive({ clear: false, bare: false, words: false });
+    let clear!: Panel;
+    let bare!: Panel;
+    let words!: Panel;
+    const flash = (key: 'clear' | 'bare' | 'words') => {
+        s[key] = true;
+        setTimeout(() => (s[key] = false), 2500);
+    };
+    return (
+        <Stack orientation="horizontal" wrap align="center" style="inline-size: 100%">
+            <Panel variant="outline" padding="md" style="min-inline-size: 16rem; min-block-size: 9rem" ref={(c: Panel) => (clear = c)}>
+                <Button text="No shade" variant="outline" onclick={() => flash('clear')} />
+            </Panel>
+            <LoadPanel target={() => clear} shade={false} x-model={() => s.clear} closeOnOutside />
+            <Panel variant="outline" padding="md" style="min-inline-size: 16rem; min-block-size: 9rem" ref={(c: Panel) => (bare = c)}>
+                <Button text="No pane" variant="outline" onclick={() => flash('bare')} />
+            </Panel>
+            <LoadPanel target={() => bare} showPane={false} x-model={() => s.bare} />
+            <Panel variant="outline" padding="md" style="min-inline-size: 16rem; min-block-size: 9rem" ref={(c: Panel) => (words = c)}>
+                <Button text="Words only" variant="outline" onclick={() => flash('words')} />
+            </Panel>
+            <LoadPanel target={() => words} showIndicator={false} message="Please wait" x-model={() => s.words} />
+        </Stack>
+    );
+}
+```
+
+## Behaviour
+
+| Topic | How |
+| --- | --- |
+| `Over a container` | It goes inside the container, over everything in it; the container is `aria-busy` and what is under the panel is inert: nothing there can be pressed or focused. |
+| `Over the page` | Without a `target`, it covers the viewport and the rest of the page is inert. |
+| `Focus` | Focus that was under it waits on the panel (on the Cancel button when there is one) and goes back where it was when the panel hides. |
+| `Delay` | Quick work shows nothing: it comes after `delay`, and a hide before that cancels it. |
+| `Spinner.cover` | The kit’s spinner covers a container programmatically in one call (`Spinner.cover`); the load panel is the component with the pane, the message, the delay and the button. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Pane` | A `status` region: the message is read when the panel appears, and again when it changes. |
+| `Indicator` | Decorative; the message says what is going on. |
+| `Under it` | `inert` and `aria-busy`, so readers skip it and nothing there takes a press or focus. |
+| `Cancel` | The kit’s button, named in the kit language; Escape presses it. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-load-panel` | The layer. `data-shade`, `data-pane`, `data-page`. |
+| `.mx-load-panel__pane` | The pane. |
+| `.mx-load-panel__indicator, .mx-load-panel__message, .mx-load-panel__cancel` | The spinner, the message and the button. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `load-panel.shade, .pane, .message` | Units: the layer (`shaded`), the pane (`shown`), the message. |
+| `load-panel.cancel` | Place: the Cancel button’s look (`variant`). |
+| `load-panel.padding, .gap` | The least space to the edge of what it covers; the space between the indicator, the message and the button. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `target` | `Bind<ComponentBase \| HTMLElement \| null>` | `null` | What it covers: a component or an element; `null` covers the whole page. |
+| `message` | `Bind<string>` | the kit’s “Loading…” | The message under the indicator. The same property as `text`. |
+| `value` | `Bind<boolean>` | `false` | Shown or not; `x-model` binds it two-way. |
+| `delay` | `Bind<number>` | `0` | Milliseconds before it shows; a hide before that shows nothing. |
+| `shade` | `Bind<boolean>` | `true` | Dims what it covers. |
+| `showPane` | `Bind<boolean>` | `true` | The box behind the indicator and the message. |
+| `showIndicator` | `Bind<boolean>` | `true` | The turning indicator (the kit’s spinner). |
+| `cancelable` | `Bind<boolean>` | `false` | A Cancel button in the pane; Escape presses it too. |
+| `cancelText` | `Bind<string>` | the kit’s “Cancel” | The button’s text. |
+| `closeOnOutside` | `Bind<boolean>` | `false` | A press on the shade hides it. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onShown, onHidden` | event | It came on the screen (after its delay); it went. |
+| `onCancel` | event | The Cancel button was pressed, or Escape; the panel hides after. |
+| `show(), hide(), cancel()` | `boolean` / `void` | Programmatically; `show()` is `false` while it is shown or waiting for its delay. |
+| `isShown` | read-only | Whether it is on the screen now. |
+| `spinner, cancelButton` | read-only | The kit’s spinner and button in the pane. |

package/docs/lookup.md

@@ -1,6 +1,6 @@
 # Lookup
 
-> Choice · @motifx-community/ui 0.1.0-beta.1
+> Choice · @motifx-community/ui 0.1.0-beta.3
 
 Picks one row of a table-like list, typically from a data source searched on the server: a customer by its company, contact and city. The field shows the chosen row's text; everything else works as in DropDown.
 

package/docs/menus.md

@@ -1,6 +1,6 @@
 # MenuBar and ContextMenu
 
-> Buttons · @motifx-community/ui 0.1.0-beta.1
+> Buttons · @motifx-community/ui 0.1.0-beta.3
 
 A menu bar of an app (File, Edit, View) and the menu that opens on a right-click. Both show the same menu items: submenus, check and radio items, shortcuts, access keys.
 
@@ -298,7 +298,7 @@ Menus write no text of their own: every label, shortcut and name comes from your
 | --- | --- | --- |
 | `MenuBar.open(item \| index)` | `boolean` | Opens a top item’s menu with focus on its first item. |
 | `MenuBar.close()` | `void` | Closes the open menu. |
-| `ContextMenu.open(at, target?)` | `boolean` | Opens it from code, at `{ x, y }` or at an element. |
+| `ContextMenu.open(at, target?)` | `boolean` | Opens it programmatically, at `{ x, y }` or at an element. |
 | `ContextMenu.close()` | `void` | Closes it. |
 | `MenuBar.refresh(), ContextMenu.refresh()` | `void` | Your items may be plain or reactive; the menu reads them as they are. After changing them in place, call `refresh()`. The bar, the open menu and its submenus follow. |
 | `attachContextMenu(target, items)` | `() => void` | Gives an element or component a menu; `items` can be a function of the opening (`e.target`). Returns the remover. |

package/docs/multiview.md

@@ -0,0 +1,202 @@
+# MultiView
+
+> Navigation · @motifx-community/ui 0.1.0-beta.3
+
+Pages side by side, one in sight: a swipe or a drag brings the next one, and so do `next()`, `previous()` and `goTo()`, or a [Tabs](tabs.md), a [Stepper](stepper.md) or buttons bound to the same value. The panels of a tab strip without the strip.
+
+## Import
+
+```tsx
+import { MultiView, View } from '@motifx-community/ui';
+```
+
+## Pages driven by a stepper
+
+The `View` children are the pages; the one in sight is `value` (a view’s `key`, else its index), `x-model` binds it two-way. Here a `Stepper` shares the value: a press on a step and a swipe on a page move both. A page is built when first in sight (`lazy`).
+
+```tsx
+import { reactive } from '@motifx/core';
+import { CheckBox, MultiView, Stack, Stepper, TextBox, View } from '@motifx-community/ui';
+
+/** A stepper and a multi-view bound to the same value: a press on a step or a swipe on a page moves both. */
+export default function Pages() {
+    const s = reactive({ page: 0 as string | number | null });
+    return (
+        <Stack gap="md" style="inline-size: 100%">
+            <Stepper class="mv-steps" label="Order" linear={false} items={['Address', 'Delivery', 'Payment']} x-model={() => s.page} />
+            <MultiView class="mv-order" label="Order" x-model={() => s.page}>
+                <View title="Address">
+                    <Stack gap="sm">
+                        <TextBox label="Street" />
+                        <TextBox label="Town" />
+                    </Stack>
+                </View>
+                <View title="Delivery">
+                    <Stack gap="sm">
+                        <CheckBox text="Leave it at the door" />
+                        <CheckBox text="Send a message before" />
+                    </Stack>
+                </View>
+                <View title="Payment">
+                    <Stack gap="sm">
+                        <TextBox label="Card number" />
+                        <TextBox label="Name on the card" />
+                    </Stack>
+                </View>
+            </MultiView>
+            <output class="mv-order-page">{() => `page: ${s.page}`}</output>
+        </Stack>
+    );
+}
+```
+
+## Built when first in sight, kept or not
+
+`lazy` (the default) builds a view when it first comes into sight and keeps it; `keepAlive={false}` disposes what a view’s `content` made while it is out of sight, and makes it again the next time. The JSX children stay either way, as in `Tabs`.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, MultiView, Stack, View } from '@motifx-community/ui';
+
+/** Each page is made when first in sight; with `keepAlive` off, what `content` made is dropped out of sight and made again. */
+export default function Lazy() {
+    const s = reactive({ made: 0, keep: true });
+    let views!: MultiView;
+    const report = (name: string) => () => {
+        s.made++;
+        return <p class="mv-lazy-page">{`${name}, made as number ${s.made}`}</p>;
+    };
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Previous" variant="outline" onclick={() => void views.previous()} />
+                <Button text="Next" variant="outline" onclick={() => void views.next()} />
+                <Button text="Keep alive" variant="outline" toggle x-model={() => s.keep} />
+                <output class="mv-lazy-made">{() => `made ${s.made} times`}</output>
+            </Stack>
+            <MultiView ref={(m: MultiView) => (views = m)} class="mv-lazy" label="Reports" keepAlive={() => s.keep}>
+                <View title="Sales" content={report('Sales')} />
+                <View title="Stock" content={report('Stock')} />
+                <View title="Staff" content={report('Staff')} />
+            </MultiView>
+        </Stack>
+    );
+}
+```
+
+## Programmatic use
+
+Made with `new`, views added with `add()` and `insert()`, removed with `remove()`; `loop` goes around the ends, `animated={false}` shows the next view at once.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, MultiView, Stack, View } from '@motifx-community/ui';
+
+/** A multi-view made programmatically around the ends: views added, inserted and removed, the sight moved with its methods. */
+export default function Programmatic() {
+    const s = reactive({ told: '', count: 0 });
+    let number = 0;
+    const page = () => {
+        number++;
+        const n = number;
+        return new View({ title: `Note ${n}`, content: () => <p class="mv-coded-note">{`Note ${n}`}</p> });
+    };
+    const coded = new MultiView({
+        label: 'Notes',
+        loop: true,
+        onSelectionChanged: e => (s.told = `in sight: ${e.view?.title ?? 'none'}${e.byUser ? ', by a swipe' : ''}`)
+    });
+    const count = () => (s.count = coded.count);
+    coded.add(page());
+    coded.add(page());
+    count();
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Previous" variant="outline" onclick={() => void coded.previous()} />
+                <Button text="Next" variant="outline" onclick={() => void coded.next()} />
+                <Button
+                    text="Add a note"
+                    variant="outline"
+                    onclick={() => {
+                        void coded.goTo(coded.add(page()));
+                        count();
+                    }}
+                />
+                <Button
+                    text="Remove this note"
+                    variant="outline"
+                    enabled={() => s.count > 1}
+                    onclick={() => {
+                        if (coded.selectedView) coded.remove(coded.selectedView);
+                        count();
+                    }}
+                />
+                <output class="mv-coded-told">{() => `${s.count} notes${s.told ? `, ${s.told}` : ''}`}</output>
+            </Stack>
+            <span class="mv-coded" onConfig={c => c.controls.add(coded)} />
+        </Stack>
+    );
+}
+```
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Group` | A `group` named “Pages” in the kit language; several on one page: give each its own `label`. |
+| `A view` | A `group` named by its `title`, else “Page 2 of 3”; the views out of sight are hidden from readers and from the keys (`inert`), so Tab moves only inside the view in sight. |
+| `Moving` | A swipe needs a finger or a mouse: give the keys a way too, a `Tabs`, a `Stepper` or buttons bound to the same `value`, as the examples do. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-multi-view` | The multi-view. `data-swipe` when a drag moves it, `data-dragging` while one does, `data-still` with `animated` off. |
+| `.mx-multi-view__viewport, .mx-multi-view__track` | The frame that clips the views and the track that slides in it (`data-dragging`, `data-no-motion`). |
+| `.mx-multi-view__view` | A view (`aria-hidden`, `inert` out of sight). |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `multi-view.frame, .view` | Units: the frame (`swipeable`, `dragging`) and a view. |
+| `multi-view.gap` | Between the views, seen while a finger drags them. |
+
+## API reference
+
+### MultiView props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `value` | `Bind<string \| number \| null>` | `0` | The view in sight: its `key`, else its index. `x-model` binds it two-way. |
+| `loop` | `Bind<boolean>` | `false` | After the last view comes the first; the move goes around the ends, not back across the views between. |
+| `swipeEnabled` | `Bind<boolean>` | `true` | A finger or a pointer drags the views; a drag far or fast enough lands on the next one. |
+| `animated` | `Bind<boolean>` | `true` | The views slide into sight. `false` shows the next one at once. |
+| `lazy` | `Bind<boolean>` | `true` | A view is built when first in sight, then kept (a view’s own `lazy` wins). |
+| `keepAlive` | `Bind<boolean>` | `true` | `false` disposes what a view’s `content` made while the view is out of sight (a view’s own `keepAlive` wins). |
+| `label` | `Bind<string>` | the kit’s “Pages” | What screen readers call it. |
+
+### View props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `title` | `Bind<string>` | “Page 2 of 3” | What screen readers call the view. |
+| `key` | `Bind<string>` | `''` | Names the view in `value`; the JSX `key` is read too. |
+| `content` | `() => ComponentBase \| ComponentBase[]` | — | Content made when the view is first in sight, besides the JSX children. |
+| `lazy, keepAlive` | `Bind<boolean \| undefined>` | `undefined` | The view’s own settings; `undefined` follows the multi-view. |
+| `visible, enabled` | `Bind<boolean>` | `true` | A hidden view takes no room and is skipped; a disabled one is skipped by `next()` and `previous()` and refused by `goTo()`. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onSelecting` | event | The view in sight is about to change (`from`, `to`, `fromView`, `toView`, `byUser`); `cancel = true` keeps the one there. |
+| `onSelectionChanged` | event | The view in sight changed (`index`, `view`, `previous`, `byUser`: by a swipe, else programmatically). |
+| `views` | read-only | The views in order, hidden ones too. |
+| `selectedView, selectedIndex` | read-only | The view in sight and its index; `null` and -1 when there is none. |
+| `count` | read-only | How many views there are. |
+| `next(), previous()` | `Promise<boolean>` | Goes to the next or the previous view that is shown and enabled; `false` at an end without `loop`, or when refused. |
+| `goTo(view)` | `Promise<boolean>` | Goes to a view, by index, key or the `View` itself; `onSelecting` is asked first. A view’s own `select()` does the same. |
+| `add(view), insert(index, view)` | `View` | Adds a view at the end or at an index; one from another multi-view moves here. |
+| `remove(view)` | `boolean` | Removes a view and disposes it; the sight moves to a neighbour. |

package/docs/numberbox.md

@@ -1,6 +1,6 @@
 # NumberBox
 
-> Editors · @motifx-community/ui 0.1.0-beta.1
+> Editors · @motifx-community/ui 0.1.0-beta.3
 
 A number field: arrow keys, PageUp / PageDown and spin buttons that repeat while held, bounds, a step without float noise, a format for display (currency, percent) and typing in the locale’s own way.
 
@@ -10,9 +10,9 @@ A number field: arrow keys, PageUp / PageDown and spin buttons that repeat while
 import { NumberBox, type NumberBoxProps } from '@motifx-community/ui';
 ```
 
-## From JSX and from code
+## Declarative and programmatic
 
-`x-model` binds a number (`null` when empty). Created with `new`, the same properties are set from code.
+`x-model` binds a number (`null` when empty). Created with `new`, the same properties are set programmatically.
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -20,13 +20,13 @@ import { Button, NumberBox, Stack } from '@motifx-community/ui';
 
 const show = (value: number | null) => (value === null ? 'null' : String(value));
 
-/** A field bound to a number with x-model, and fields created with `new` and stepped from code. */
-export default function FromCode() {
+/** A field bound to a number with x-model, and fields created with `new` and stepped programmatically. */
+export default function Programmatic() {
   const s = reactive({ quantity: 3 as number | null, log: '' });
   let added = 0;
   let host: Stack | null = null;
 
-  const addFromCode = () => {
+  const addProgrammatic = () => {
     const box = new NumberBox({ label: `Count ${++added}`, min: 0, max: 10, value: 5, locale: 'en' });
     box.onValueChanged((e) => (s.log = `${box.label}: ${show(e.value)}`));
     host?.controls.add(box);
@@ -41,7 +41,7 @@ export default function FromCode() {
         <output class="nb-quantity">{() => `value: ${show(s.quantity)}`}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center">
-        <Button text="Add a field from code" variant="outline" onclick={addFromCode} />
+        <Button text="Add a field programmatically" variant="outline" onclick={addProgrammatic} />
         <output class="nb-log">{() => s.log}</output>
       </Stack>
       <Stack orientation="horizontal" wrap align="center" ref={(c: Stack) => (host = c)} />
@@ -212,7 +212,7 @@ The names of the spin buttons and the range messages come from `uiLocale.strings
 
 ```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 names of the spin buttons and the range messages. */
@@ -221,7 +221,7 @@ export default function Localization() {
 
   const toggle = () => {
     s.lang = s.lang === 'en' ? 'tr' : 'en';
-    uiLocale.strings = s.lang === 'en' ? enStrings : trStrings;
+    void uiLocale.use(s.lang);
   };
 
   return (