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

package/docs/language.md

@@ -0,0 +1,229 @@
+# Language
+
+> Foundations · @motifx-community/ui 0.1.0-beta.2
+
+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. |

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.2
 
 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.
 
@@ -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 (
     <>

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.2
 
 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.
 
@@ -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 (
     <>

package/docs/loadpanel.md

@@ -0,0 +1,184 @@
+# LoadPanel
+
+> Feedback · @motifx-community/ui 0.1.0-beta.2
+
+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()` from code. `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 from code 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` | From code; `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.2
 
 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.2
 
 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.
 

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.2
 
 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.
 
@@ -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 (

package/docs/pagination.md

@@ -1,6 +1,6 @@
 # Pagination
 
-> Navigation · @motifx-community/ui 0.1.0-beta.1
+> Navigation · @motifx-community/ui 0.1.0-beta.2
 
 Moving through pages of items: the sizes to choose from, where the page stands, the steps and a button per page around the current one. It turns compact when it does not fit. It looks and works as the grid’s pager.