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

package/docs/filterbuilder.md

@@ -1,6 +1,6 @@
 # FilterBuilder
 
-> Data · @motifx-community/ui 0.1.0-beta.1
+> Data · @motifx-community/ui 0.1.0-beta.3
 
 A filter builder lets people put a filter together by hand: groups joined by And, Or, Not And or Not Or, and conditions of a field, an operation and a value. Its value is the data layer's filter expression, so it goes to rows in memory and to every adapter as it is. The DataGrid opens it from its filter panel; on its own it serves a report screen or a saved search.
 
@@ -57,7 +57,7 @@ export const saleFields: FilterBuilderField[] = [
 ];
 ```
 
-## From code, and the events
+## Programmatic use, and the events
 
 Every change the user makes is also a method (`addCondition`, `addGroup`, `removeItem`, `setField`, `setOperation`, `setConditionValue`, `setGroupOperation`, `clear`), and every change asks first: `onItemAdding`, `onItemRemoving` and `onItemChanging` can change it or cancel it, the `…ed` events and `onValueChanged` follow. Here the last condition of the root cannot be taken out.
 
@@ -372,7 +372,7 @@ export const saleFields: FilterBuilderField[] = [
 | `setField(condition, dataField), setOperation(condition, op), setConditionValue(condition, value)` | `boolean` | An operation or value that no longer fits the new field is reset. |
 | `setGroupOperation(group, op)` | `boolean` |  |
 | `clear()` | `void` | Empties the tree. |
-| `openEditor(condition), closeEditor(keep?)` | `boolean`, `void` | The value editor, from code. |
+| `openEditor(condition), closeEditor(keep?)` | `boolean`, `void` | The value editor, programmatically. |
 | `focusItem(item, part?), focus()` | `boolean` | A row's button (`'remove'`, `'group'`, `'add'`, `'field'`, `'operation'`, `'value'`); the tree's Tab stop. |
 | `getFilterExpression()` | `data.FilterExpression \| null` | The value. |
 | `refresh()` | `void` | Your fields and value may be plain or reactive; the builder reads them as they are. After changing them in place, call `refresh()`. The rows are drawn again; a value changed in place is read into the tree. |
@@ -460,7 +460,7 @@ export const saleFields: FilterBuilderField[] = [
 ];
 ```
 
-`FromCode.tsx`
+`Programmatic.tsx`
 
 ```tsx
 import { reactive } from '@motifx/core';
@@ -468,14 +468,14 @@ import { data } from '@motifx-community/data';
 import { Button, FilterBuilder, Stack } from '@motifx-community/ui';
 import { saleFields } from './sales';
 
-/** Made with `new` and driven from code; every change asks first, and a handler may cancel it. */
-export default function FromCode() {
+/** Made with `new` and driven programmatically; every change asks first, and a handler may cancel it. */
+export default function Programmatic() {
   const log = reactive({ lines: [] as { id: number; text: string }[], next: 0 });
   const write = (text: string) => {
     log.lines.unshift({ id: log.next++, text });
     if (log.lines.length > 6) log.lines.pop();
   };
-  const builder = new FilterBuilder({ fields: saleFields, locale: 'en', label: 'Built from code' });
+  const builder = new FilterBuilder({ fields: saleFields, locale: 'en', label: 'Built programmatically' });
   builder.element.classList.add('fb-code');
   builder.onItemAdding((e) => write(`adding a ${e.item.kind}${e.byUser ? ' (user)' : ''}`));
   builder.onItemRemoving((e) => {
@@ -574,7 +574,7 @@ export default function CustomOperations() {
 ```tsx
 import { reactive } from '@motifx/core';
 import { data } from '@motifx-community/data';
-import { Button, FilterBuilder, enStrings, trStrings, uiLocale } from '@motifx-community/ui';
+import { Button, FilterBuilder, uiLocale } from '@motifx-community/ui';
 import { saleFields } from './sales';
 
 /** The builder's texts come from `uiLocale`; `texts` changes some for one builder only. */
@@ -582,7 +582,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/formlayout.md

@@ -1,6 +1,6 @@
 # FormLayout
 
-> Navigation · @motifx-community/ui 0.1.0-beta.1
+> Navigation · @motifx-community/ui 0.1.0-beta.3
 
 Lays out the fields of a data object on a grid. Each field gets an editor — by name, or by the type of its value — bound to the object both ways; groups, spans and buttons arrange them; sending the form checks every field first.
 

package/docs/gallery.md

@@ -0,0 +1,244 @@
+# Gallery
+
+> Display · @motifx-community/ui 0.1.0-beta.3
+
+Panes side by side, one in view or several, moved by the buttons at the sides, the dots under them, a swipe or the arrow keys; a slideshow when told. A pane is an image with a caption, or any content.
+
+## Import
+
+```tsx
+import { Gallery } from '@motifx-community/ui';
+```
+
+## Pictures with captions
+
+`items` are the panes: an address, or an item with `image`, `alt`, `text` and `description`. The pane in view is `value` (a pane’s `key`, else its index), `x-model` binds it two-way. Drag a pane with a finger or the mouse, press an arrow or a dot, or use the keys on the panes.
+
+```tsx
+import { Gallery } from '@motifx-community/ui';
+import { scene } from './scenes';
+
+/** Five pictures with captions: the buttons at the sides, the dots under them, a swipe or the arrow keys move them. */
+export default function Basic() {
+    return (
+        <Gallery
+            class="ga-trip"
+            label="A trip"
+            height={300}
+            items={[
+                { image: scene(205), alt: 'Boats in a harbour', text: 'Harbour', description: 'Early morning' },
+                { image: scene(30), alt: 'Market stalls', text: 'Market' },
+                { image: scene(120), alt: 'Hills under cloud', text: 'Hills', description: 'After the rain' },
+                { image: scene(280), alt: 'The town at night', text: 'Night' },
+                { image: scene(345), alt: 'The way home', text: 'Home', description: 'Last day' }
+            ]}
+        />
+    );
+}
+```
+
+## Loop and slideshow
+
+`loop` goes around the ends: the pane on the other side is brought next to the one leaving, so the move never runs back across the panes between. `slideInterval` makes a slideshow; it waits while the pointer rests on the gallery, while focus is inside, while the page is out of sight and under reduced motion, and the button in the bar pauses it. `stretchImages` fills the panes.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Gallery, Stack } from '@motifx-community/ui';
+import { scene } from './scenes';
+
+/** A slideshow around the ends: it moves on every 2.5 s, waits while the pointer or focus is on it, and its button pauses it. */
+export default function Slideshow() {
+    const s = reactive({ shown: 0 as string | number | null, told: '' });
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <Gallery
+                class="ga-show"
+                label="Slideshow"
+                height={240}
+                loop
+                stretchImages
+                slideInterval={2500}
+                x-model={() => s.shown}
+                onSlideChanged={e => (s.told = e.byUser ? 'moved by you' : 'moved by the slideshow')}
+                items={[
+                    { image: scene(190), alt: 'Dawn over the sea', text: 'Dawn' },
+                    { image: scene(50), alt: 'Noon in the square', text: 'Noon' },
+                    { image: scene(260), alt: 'Dusk on the hill', text: 'Dusk' }
+                ]}
+            />
+            <output class="ga-show-told">{() => `in view: ${s.shown}${s.told ? `, ${s.told}` : ''}`}</output>
+        </Stack>
+    );
+}
+```
+
+## Several panes side by side
+
+`itemsPerPage` puts that many panes in the width, the `gap` token between them. The buttons and the keys move one pane at a time and stop when the last pane is in view; the pane in view is the first of them.
+
+```tsx
+import { Gallery } from '@motifx-community/ui';
+import { scene } from './scenes';
+
+/** Three panes share the width; next and previous move one pane at a time and stop when the last is in view. */
+export default function PerPage() {
+    const places = ['Pier', 'Lane', 'Roof', 'Park', 'Bridge', 'Shore', 'Tower'];
+    return (
+        <Gallery
+            class="ga-wide"
+            label="Places"
+            height={150}
+            itemsPerPage={3}
+            stretchImages
+            items={places.map((place, i) => ({ image: scene(i * 48), alt: `The ${i + 1}. picture of the walk`, text: place }))}
+        />
+    );
+}
+```
+
+## Any content
+
+An item’s `content` makes the pane’s content when the pane is made; what is in it works as anywhere else. `onItemClick` tells a press on the pane that was not a drag.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Gallery, Stack } from '@motifx-community/ui';
+
+const PLANS = [
+    { name: 'Starter', price: '€9', line: 'One project, two people' },
+    { name: 'Team', price: '€29', line: 'Ten projects, your whole team' },
+    { name: 'Company', price: '€79', line: 'No limits, a person to call' }
+];
+
+/** Any content in a pane: a plan each, with its own button; a press on the pane itself is told too. */
+export default function Content() {
+    const s = reactive({ told: '' });
+    const plan = (p: (typeof PLANS)[number]) => (
+        <Stack class="ga-plan" gap="xs" align="center" justify="center" style="block-size: 100%">
+            <strong>{p.name}</strong>
+            <span class="ga-plan-price">{p.price} a month</span>
+            <span>{p.line}</span>
+            <Button text="Choose" variant="outline" onclick={() => (s.told = `${p.name} chosen`)} />
+        </Stack>
+    );
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <Gallery class="ga-plans" label="Plans" height={200} swipeEnabled={false} items={PLANS.map(p => ({ key: p.name, content: () => plan(p) }))} onItemClick={e => (s.told = `pane ${e.index + 1} pressed`)} />
+            <output class="ga-plans-told">{() => s.told}</output>
+        </Stack>
+    );
+}
+```
+
+## Programmatic use
+
+Made with `new`, moved with `next()`, `previous()` and `goTo()`; `showNavButtons` and `showIndicator` off leave the moving to your own buttons, `onSlideChanged` tells where it stands.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Gallery, Stack } from '@motifx-community/ui';
+import { scene } from './scenes';
+
+/** A gallery made programmatically without its own buttons or dots: yours move it, and `onSlideChanged` tells where it is. */
+export default function Programmatic() {
+    const s = reactive({ at: 0, told: '' });
+    const coded = new Gallery({
+        label: 'Rooms',
+        height: 200,
+        showNavButtons: false,
+        showIndicator: false,
+        swipeEnabled: false,
+        items: [
+            { key: 'hall', image: scene(20), alt: 'The hall', text: 'Hall' },
+            { key: 'study', image: scene(200), alt: 'The study', text: 'Study' },
+            { key: 'garden', image: scene(110), alt: 'The garden', text: 'Garden' }
+        ],
+        onSlideChanged: e => {
+            s.at = e.index;
+            s.told = `slide ${e.index + 1} of ${coded.count}`;
+        }
+    });
+    return (
+        <Stack gap="sm" style="inline-size: 100%">
+            <span class="ga-rooms" onConfig={c => c.controls.add(coded)} />
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Previous" variant="outline" enabled={() => s.at > 0} onclick={() => void coded.previous()} />
+                <Button text="Next" variant="outline" enabled={() => s.at < 2} onclick={() => void coded.next()} />
+                <Button text="Garden" variant="outline" onclick={() => void coded.goTo('garden')} />
+                <output class="ga-rooms-told">{() => s.told}</output>
+            </Stack>
+        </Stack>
+    );
+}
+```
+
+## Keyboard
+
+| Key | What it does |
+| --- | --- |
+| `Tab` | The slideshow button, the dots (one stop: the dot of the pane in view), the previous button, the panes, the next button; what is in the pane in view after it. |
+| `Arrow keys` | On the panes or the dots: Left and Right (the other way round in a right-to-left page) move to the previous and the next pane, Home and End to the first and the last. |
+| `Enter, Space` | On a button or a dot: press it. |
+
+## Accessibility
+
+| Topic | How |
+| --- | --- |
+| `Landmark` | A `region` with `aria-roledescription="carousel"`, named “Gallery” in the kit language; several on one page: give each its own `label`. |
+| `A pane` | A `group` with `aria-roledescription="slide"` named “Slide 2 of 5”; the panes out of view are hidden from readers and from the keys (`inert`). |
+| `Images` | Give each an `alt`; an empty one is a decorative image. The caption is read as the pane’s content. |
+| `Slideshow` | The panes are a live region while it is stopped (`polite`), silent while it runs (`off`), as the carousel pattern asks; the button to stop it comes first in the Tab order. |
+| `Dots and arrows` | Buttons named “Slide 2 of 5”, “Previous slide” and “Next slide”; the dot of the pane in view is `aria-current`; an arrow at an end is `aria-disabled`. |
+
+## Styling
+
+| Hook | What it is |
+| --- | --- |
+| `.mx-gallery` | The gallery. `data-swipe` when a drag moves it, `data-dragging` while one does, `data-playing` while the slideshow is on, `data-stretch`. |
+| `.mx-gallery__viewport, .mx-gallery__track` | The frame that clips the panes and the track that slides in it (`data-dragging`, `data-no-motion`). |
+| `.mx-gallery__item, .mx-gallery__figure, .mx-gallery__image` | A pane (`data-current`, `aria-hidden`), what it shows, the image. |
+| `.mx-gallery__caption, .mx-gallery__title, .mx-gallery__description` | The band over the bottom of a pane and its two lines. |
+| `.mx-gallery__nav, .mx-gallery__arrow` | The previous and next buttons (`data-direction`, `aria-disabled`) and the glyph in them. |
+| `.mx-gallery__bar, .mx-gallery__indicator, .mx-gallery__dot, .mx-gallery__play, .mx-gallery__play-glyph` | The bar over the bottom, the dots (`aria-current`), the slideshow button and its glyph. |
+
+### Component tokens
+
+| Token | What it sets |
+| --- | --- |
+| `gallery.frame, .item, .caption, .title, .description` | Units: the frame (`focus`, `swipeable`, `dragging`), a pane (`current`), the caption and its texts. |
+| `gallery.nav, .arrow, .dot, .play, .play-glyph, .bar` | Units: the side buttons (`hover`, `pressed`, `focus`, `disabled`), their glyph (`icon` per direction), the dots (`current`, `hover`, `pressed`, `focus`), the slideshow button and its glyph (`icon` while `playing`), the bar. |
+| `gallery.gap, .nav-inset, .bar-inset, .indicator-gap, .caption-padding` | Between panes side by side, from the sides and the bottom to what lies over them, between the dots, inside a caption. |
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `items` | `Bind<readonly (GalleryItem \| string)[]>` | `[]` | The panes in order: `GalleryItem`s (`image`, `alt`, `text`, `description`, `key`, `content`, `data`) or image addresses. |
+| `value` | `Bind<string \| number \| null>` | `0` | The pane in view: its `key`, else its index. `x-model` binds it two-way. |
+| `loop` | `Bind<boolean>` | `false` | After the last pane comes the first; the move goes around the ends, not back across the panes between. |
+| `showNavButtons` | `Bind<boolean>` | `true` | The previous and next buttons over the sides. |
+| `showIndicator` | `Bind<boolean>` | `true` | The dots under the panes, one per pane. |
+| `slideInterval` | `Bind<number>` | `0` | Milliseconds a pane stays in a slideshow; `0` for none. It pauses under the pointer, while focus is inside, out of sight and under reduced motion. |
+| `pauseOnHover` | `Bind<boolean>` | `true` | The slideshow waits while the pointer rests on the gallery. |
+| `swipeEnabled` | `Bind<boolean>` | `true` | A finger or a pointer drags the panes; a drag far or fast enough lands on the next one. |
+| `itemsPerPage` | `Bind<number>` | `1` | Panes side by side in the width, with the `gap` token between them. |
+| `stretchImages` | `Bind<boolean>` | `false` | An image fills its pane, cut at the edges, instead of fitting inside it whole. |
+| `height` | `Bind<string \| number \| null>` | `null` | A CSS length or pixels. Without one the gallery is as tall as its tallest pane. |
+| `label` | `Bind<string>` | the kit’s “Gallery” | What screen readers call it. |
+
+### Events, properties and methods
+
+| Member | Kind | Description |
+| --- | --- | --- |
+| `onSlideChanging` | event | The pane in view is about to change (`from`, `to`, `fromItem`, `toItem`, `byUser`); `cancel = true` keeps the one there. |
+| `onSlideChanged` | event | The pane in view changed (`index`, `item`, `previous`, `byUser`: by a press, a swipe or a key, else programmatically or the slideshow). |
+| `onItemClick` | event | A press on a pane that was not a drag (`index`, `item`, `event`). |
+| `selectedIndex` | read-only | The index of the pane in view; -1 when there is none. |
+| `count` | read-only | How many panes there are. |
+| `isPlaying` | read-only | The slideshow runs now: not paused, and nothing holds it. |
+| `next(), previous()` | `Promise<boolean>` | Goes to the next or the previous pane; `false` at an end without `loop`, or when the change was refused. |
+| `goTo(pane)` | `Promise<boolean>` | Goes to a pane by index or key; `onSlideChanging` is asked first. |
+| `play(), pause()` | `void` | Starts the slideshow again, or stops it until `play()`; the button in the bar does the same. |
+| `refresh()` | `void` | Reads the items again after they were changed in place. |

package/docs/home.md

@@ -1,6 +1,6 @@
 # @motifx-community/ui
 
-> Get started · @motifx-community/ui 0.1.0-beta.1
+> Get started · @motifx-community/ui 0.1.0-beta.3
 
 Components for MotifJS that work the way desktop UI does — created when needed, shown anywhere, closed and disposed like windows — drawn from the MotifJS design system's tokens.
 
@@ -22,14 +22,18 @@ import { Button, Control, FocusContainer, addShortcut } from '@motifx-community/
 
 ## What ships today
 
-The components are being written one at a time; Button is the first. Under them is the base they all build on: focus and the keyboard, and the shared parts a menu or a drop-down opens on.
+More than fifty components, every one an object with the same base: focus and the keyboard, the right roles and names for a screen reader, texts in English and Turkish that switch while the app runs, right to left, and a look in each of the design system's five languages (Tactile, Lounge, Material, Fluent, Lilac) painted from component tokens. Each has a page with live examples and its API.
 
-| Part | What it is |
+| Group | Components |
 | --- | --- |
-| [`Button`](button.md) | Solid, outline and ghost in three tones and sizes, pressable; icon, `&` access key, toggle, busy; a menu or any content, from the whole button or with `split` from an arrow next to it. |
-| `Popup`, `MenuList` | The shared parts: a surface above the page that follows its anchor and closes on Escape or a press outside, and a keyboard-driven list of commands. |
-| [`Control`](control.md) | The base of every control: `text`, `enabled`, `visible`, `tabStop` and focus, the same from JSX and from code. |
-| [`FocusContainer`, `addShortcut`](keyboard.md) | Tab order, the active control of a container, `&` access keys, shortcuts, and focus that never falls to the page when a control goes away. |
+| Buttons and commands | [`Button`](button.md) (menu, split, toggle, busy), [`ButtonGroup`](buttongroup.md), [`Toolbar`](toolbar.md), [`MenuBar` and `ContextMenu`](menus.md) |
+| Editors | [`TextBox`](textbox.md) (mask, validation), [`TextArea`](textarea.md), [`NumberBox`](numberbox.md), [`DateBox`](datebox.md), [`DateRangeBox`](daterangebox.md), [`Calendar`](calendar.md), [`ColorBox` and `ColorPicker`](colorbox.md), [`Slider`](slider.md), [`Rating`](rating.md), [`FileUploader`](fileuploader.md) |
+| Choice | [`CheckBox`](checkbox.md), [`Switch`](switch.md), [`RadioGroup`](radiogroup.md), [`DropDown`](dropdown.md), [`ComboBox` and `Autocomplete`](combobox.md), [`Lookup`](lookup.md), [`TagBox`](tagbox.md), [`ListBox`](listbox.md) |
+| Display and feedback | [`Badge`](badge.md), [`Avatar` and `AvatarGroup`](avatar.md), [`Chip` and `ChipGroup`](chip.md), [`Card`](card.md), [`Skeleton`](skeleton.md), [`ProgressBar` and `Spinner`](progress.md), [`LoadPanel`](loadpanel.md), [`Tooltip`](tooltip.md), [`Popover`](popover.md), [`Toast`](toast.md) |
+| Navigation and layers | [`Tabs`](tabs.md), [`Accordion`](accordion.md), [`Breadcrumb`](breadcrumb.md), [`Pagination`](pagination.md), [`Stepper`](stepper.md), [`Wizard`](wizard.md), [`Window` and dialog](window.md), [`BottomSheet`](bottomsheet.md), [`Drawer`](drawer.md), [`ActionSheet`](actionsheet.md) |
+| Layout | [`Stack`, `Grid`, `DockPanel`, `Panel`, `GroupBox`, `SplitContainer`](layout.md), [`FormLayout`](formlayout.md), [`ScrollView`](scrollview.md) (pull to refresh, load more), [`Sortable`](sortable.md) |
+| Data | [`DataGrid`](datagrid.md) (virtual or paged, editing, filters, grouping, master-detail, export), [`TreeView`](treeview.md), [`FilterBuilder`](filterbuilder.md), [`Scheduler`](scheduler.md) (day to timeline, recurrence, resources, iCalendar), [`TabDocumentManager`](tabdocs.md) (tabs, split, dock, new windows); lists and grids read `@motifx-community/data` sources |
+| Base | [`Control`](control.md), [`FocusContainer` and `addShortcut`](keyboard.md), [`uiLocale`](language.md), [the component tokens](tokens.md); `Popup` and `MenuList`, the shared parts a menu or a drop-down opens on |
 
 ## Design system
 

package/docs/keyboard.md

@@ -1,6 +1,6 @@
 # Keyboard and focus
 
-> Foundations · @motifx-community/ui 0.1.0-beta.1
+> Foundations · @motifx-community/ui 0.1.0-beta.3
 
 The rules every control follows: Tab order, the active control of a container, focus that never falls to `<body>`, `&File` access keys and app-wide shortcuts.
 

package/docs/language.md

@@ -0,0 +1,229 @@
+# Language
+
+> Foundations · @motifx-community/ui 0.1.0-beta.3
+
+The texts the controls write, the locale their dates and numbers follow, and the direction: one `uiLocale` for the kit, with a pack per language loaded as it is asked for.
+
+## Import
+
+```tsx
+import { uiLocale, connectI18n } from '@motifx-community/ui';
+```
+
+## Switching the language
+
+`uiLocale.use('tr')` loads the Turkish pack the first time, then every control on the page draws its texts and formats again. The Language menu in the header of these docs does the same.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, DateBox, NumberBox, Pagination, Stack, uiLocale } from '@motifx-community/ui';
+import { kitTexts } from '../../../shared/kit-texts';
+
+/** The kit's language switched live: the pack is loaded first, then every control draws its texts and formats again. */
+export default function Switch() {
+    const s = reactive({ price: 1234.5, when: new Date(2026, 2, 18) as Date | null });
+    return (
+        <Stack gap="md">
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="English" variant="outline" onclick={() => void uiLocale.use('en')} />
+                <Button text="Türkçe" variant="outline" onclick={() => void uiLocale.use('tr')} />
+                <span>
+                    In use: <output class="lang-locale">{() => kitTexts.locale}</output>
+                </span>
+            </Stack>
+            <Stack orientation="horizontal" wrap align="center">
+                <NumberBox label="Price" x-model={() => s.price} format={{ style: 'currency', currency: 'EUR' }} />
+                <DateBox label="When" x-model={() => s.when} clearButton />
+            </Stack>
+            <Pagination total={95} pageSizes={[10, 20, 50]} label="Orders" />
+        </Stack>
+    );
+}
+```
+
+## The rules
+
+| Rule | How |
+| --- | --- |
+| `Start` | The page’s `<html lang>`, else the browser’s language. Set `lang` before the first control is made; `uiLocale.ready` settles once that language is in. |
+| `Texts` | Every text a control writes itself (a button’s name, a message, “No items”) comes from the pack of the language in use; English fills what the pack leaves out. |
+| `Formats` | Dates, numbers, the first day of the week and 12 or 24 hours follow `uiLocale.locale`; a control’s own `locale` prop wins for that control. |
+| `Direction` | `uiLocale.dir` is `rtl` for Arabic, Hebrew, Persian, Urdu…; the controls lay themselves out from `<html dir>`, which `@motifx-community/i18n` keeps in step. |
+| `Nothing follows` | A change is one event, `onChanged`: the controls draw again on it, and so can your own texts. No binding reads `uiLocale`. |
+| `Plurals` | A text with a count is an ICU message, `{count, plural, one {# record} other {# records}}`; a pack writes it the way its language counts. |
+
+## Packs
+
+| Pack | Where it comes from |
+| --- | --- |
+| `English` | Built in. What a pack leaves out is shown in English. |
+| `Turkish` | `uiLocale.use('tr')` loads it the first time, as a chunk of the package. |
+| `@motifx-community/ui/locales/<language>.json` | The same packs as files, for an app that bundles or serves them its own way: `uiLocale.add('tr', pack)`. |
+| `uiLocale.loader` | Where the kit asks for a pack it does not have: `(language) => fetch(`/i18n/ui/${language}.json`).then((r) => r.json())`. A language without a pack keeps the English texts. |
+
+A pack of your own is a plain object of the kit’s texts: `uiLocale.add` gives a language its texts, `use` switches to it. A few texts are enough to start; the rest stay English until the pack has them.
+
+```tsx
+import { Button, DropDown, Stack, uiLocale } from '@motifx-community/ui';
+
+// A few German texts; what is left out stays English.
+uiLocale.add('de', {
+    close: 'Schließen',
+    clear: 'Leeren',
+    search: 'Suchen',
+    noItems: 'Keine Einträge',
+    loading: 'Wird geladen…',
+    ok: 'OK',
+    cancel: 'Abbrechen',
+});
+
+/** A pack of your own: `uiLocale.add` gives a language its texts, `use` switches to it. */
+export default function OwnPack() {
+    return (
+        <Stack gap="md">
+            <Stack orientation="horizontal" wrap align="center">
+                <Button text="Deutsch" variant="outline" onclick={() => void uiLocale.use('de')} />
+                <Button text="English" variant="outline" onclick={() => void uiLocale.use('en')} />
+            </Stack>
+            <DropDown label="Empty list" items={[]} placeholder="Open me" />
+        </Stack>
+    );
+}
+```
+
+## With your app’s translations
+
+An app translated with `@motifx-community/i18n` has one locale already. `connectI18n(i18n)` makes the kit follow it: when the app switches, the kit loads its own pack and switches too. The link is undone by what it returns.
+
+```tsx
+import { Component } from '@motifx/core';
+import { createI18n } from '@motifx-community/i18n';
+import { Button, connectI18n, Stack, TextBox } from '@motifx-community/ui';
+
+// The app's own translations; the kit follows their locale.
+const i18n = createI18n({
+    locale: 'en',
+    messages: {
+        en: { greeting: 'Hello {name}', hint: 'The clear button is named by the kit' },
+        tr: { greeting: 'Merhaba {name}', hint: 'Temizle düğmesini kit adlandırır' },
+    },
+    dom: false,
+});
+
+/** One locale for the app and the kit: `connectI18n` switches the kit whenever the app's translations switch. */
+export default class Connect extends Component<HTMLDivElement> {
+    override onBuilt(): void {
+        this.motif.setDisposable(connectI18n(i18n));
+    }
+
+    override view() {
+        return (
+            <Stack gap="md">
+                <Stack orientation="horizontal" wrap align="center">
+                    <Button text="English" variant="outline" onclick={() => void i18n.setLocale('en')} />
+                    <Button text="Türkçe" variant="outline" onclick={() => void i18n.setLocale('tr')} />
+                </Stack>
+                <p class="lang-greeting">{() => i18n.t('greeting', { name: 'Ada' })}</p>
+                <TextBox label={() => i18n.t('hint')} value="Clear me" clearButton />
+            </Stack>
+        );
+    }
+}
+```
+
+## Your own texts that follow
+
+The kit follows nothing: a change of language is told once, through `uiLocale.onChanged`. Keep your own texts with it, and fill the kit’s own texts with `uiLocale.text`, plurals included.
+
+```tsx
+import { Component, reactive } from '@motifx/core';
+import { Button, NumberBox, Stack, uiLocale } from '@motifx-community/ui';
+
+const OWN = {
+    en: { title: 'Orders', hint: 'Written by the app, kept with the kit’s language' },
+    tr: { title: 'Siparişler', hint: 'Uygulama yazar, kitin diliyle birlikte değişir' },
+};
+
+/** Your own texts drawn again on `uiLocale.onChanged`, and the kit's plural texts filled with `uiLocale.text`. */
+export default class OwnTexts extends Component<HTMLDivElement> {
+    s = reactive({ count: 3, title: '', hint: '', records: '' });
+
+    override onBuilt(): void {
+        this.motif.register(uiLocale.onChanged(() => this.draw()));
+        this.draw();
+    }
+
+    draw(): void {
+        const own = uiLocale.locale.startsWith('tr') ? OWN.tr : OWN.en;
+        this.s.title = own.title;
+        this.s.hint = own.hint;
+        this.s.records = uiLocale.text('gridRecords', { count: this.s.count });
+    }
+
+    override view() {
+        return (
+            <Stack gap="md">
+                <Stack orientation="horizontal" wrap align="center">
+                    <Button text="English" variant="outline" onclick={() => void uiLocale.use('en')} />
+                    <Button text="Türkçe" variant="outline" onclick={() => void uiLocale.use('tr')} />
+                </Stack>
+                <p>
+                    <strong class="lang-own-title">{this.s.title}</strong>
+                </p>
+                <p>{this.s.hint}</p>
+                <Stack orientation="horizontal" wrap align="center">
+                    <NumberBox label="Count" min={0} max={99} x-model={() => this.s.count} onValueChanged={() => this.draw()} />
+                    <output class="lang-records">{this.s.records}</output>
+                </Stack>
+            </Stack>
+        );
+    }
+}
+```
+
+## Formats of one control
+
+Dates and numbers follow the kit’s locale. A control given a `locale` of its own writes that one, whatever the kit’s language is.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { DateBox, NumberBox, Stack } from '@motifx-community/ui';
+
+/** A control's own `locale` wins over the kit's: these write German and Japanese whatever the kit's language is. */
+export default function Formats() {
+    const s = reactive({ amount: 98765.43, day: new Date(2026, 2, 18) as Date | null });
+    return (
+        <Stack orientation="horizontal" wrap align="center">
+            <NumberBox label="Betrag" locale="de-DE" format={{ style: 'currency', currency: 'EUR' }} x-model={() => s.amount} />
+            <DateBox label="日付" locale="ja-JP" x-model={() => s.day} />
+            <NumberBox label="The kit's locale" format={{ style: 'currency', currency: 'EUR' }} x-model={() => s.amount} />
+        </Stack>
+    );
+}
+```
+
+## Checking a pack
+
+In the repository, `npm run locales` checks every pack the kit ships, and `npm run locales -- path/to/de.json` one of your own. The texts themselves are in `src/locales/en.json`; a pack is the same keys in another language.
+
+| Check | What it means |
+| --- | --- |
+| `Every text` | A pack names every text of `en.json`; one it leaves out is shown in English, and the check says which. |
+| `Only the kit’s texts` | A key `en.json` does not have is a typo. |
+| `The same arguments` | A text fills the same `{values}` as the English one, in ICU; the plural forms are the language’s own. |
+| `The interface` | `UiStrings` and `en.json` name the same keys. |
+
+## API reference
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `uiLocale.use(locale)` | `Promise<void>` | Switches to `locale` (`tr`, `tr-TR`): its pack is loaded first when it is not there, then every control draws again. A later call wins over one still loading. |
+| `uiLocale.locale` | `string` | The locale in use. |
+| `uiLocale.dir` | `'ltr' \| 'rtl'` | The direction of the locale in use. |
+| `uiLocale.strings` | `UiStrings` | The texts in use. Assigning a set changes the texts and keeps the locale: `uiLocale.strings = { ...uiLocale.strings, close: 'Shut' }`. |
+| `uiLocale.text(key, values)` | `string` | A text of the kit with its values filled in: `uiLocale.text('gridRecords', { count: 3 })`. |
+| `uiLocale.add(language, pack)` | `void` | Adds the pack of a language, or more texts to it; a language in use shows them at once. |
+| `uiLocale.loader` | `(language) => Promise<UiPackModule>` | Where packs come from; the package by default. |
+| `uiLocale.ready` | `Promise<void>` | Settles once the starting language is in. |
+| `uiLocale.onChanged` | event | Raised once the language changed, with `locale` and `previous`. |
+| `connectI18n(i18n)` | `() => void` | Keeps the kit’s language with your app’s translations (`@motifx-community/i18n`, or anything with `locale` and `onLocaleChanged`); returns what stops it. |