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

package/docs/formlayout.md

@@ -0,0 +1,118 @@
+# FormLayout
+
+> Navigation · @motifx-community/ui 0.1.0-beta.0
+
+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.
+
+## Import
+
+```tsx
+import { FormLayout, type FormItem } from '@motifx-community/ui';
+```
+
+## A form over an object
+
+```tsx
+import { reactive } from '@motifx/core';
+import { FormLayout, type FormItem } from '@motifx-community/ui';
+
+const countries = [
+  { value: 'TR', text: 'Türkiye' },
+  { value: 'DE', text: 'Germany' },
+  { value: 'FR', text: 'France' },
+];
+
+/** The fields of a customer on two columns: editors by name or by value, a group, a field shown on a condition, a Save button that checks first. */
+export default function CustomerForm() {
+  const customer = reactive({
+    name: 'Ada Lovelace',
+    email: '',
+    phone: '',
+    birthday: null as Date | null,
+    country: 'TR' as string | null,
+    city: 'İstanbul',
+    vip: false,
+    credit: 1000,
+    note: '',
+  });
+  const s = reactive({ result: '' });
+
+  const items: FormItem[] = [
+    { field: 'name', label: '&Name', required: true },
+    { field: 'email', label: 'Email', editor: 'email', required: true },
+    { field: 'phone', label: 'Phone', editorProps: { mask: '(000) 000 00 00', type: 'tel' } },
+    { field: 'birthday', label: 'Birthday', editor: 'date', editorProps: { max: new Date() } },
+    {
+      group: 'Address',
+      columns: 2,
+      items: [
+        { field: 'country', label: 'Country', editor: 'dropdown', editorProps: { items: countries } },
+        { field: 'city', label: 'City' },
+      ],
+    },
+    { field: 'vip', label: 'VIP customer', editor: 'switch' },
+    { field: 'credit', label: 'Credit limit', editorProps: { format: { style: 'currency', currency: 'TRY' }, min: 0 }, visible: () => customer.vip },
+    { field: 'note', label: 'Note', editor: 'textarea', colSpan: 'all' },
+    { button: { text: 'Save', tone: 'accent', submit: true } },
+  ];
+
+  return (
+    <>
+      <FormLayout
+        data={customer}
+        columns={2}
+        items={items}
+        onValidSubmit={() => (s.result = `Saved ${customer.name}.`)}
+        onInvalidSubmit={(e) => (s.result = `${e.invalid.length} field(s) to fix.`)}
+      />
+      <output class="fl-result">{() => s.result}</output>
+      <output class="fl-data">{() => `${customer.name} · ${customer.email || '—'} · ${customer.city} · vip: ${customer.vip}`}</output>
+    </>
+  );
+}
+```
+
+## Editors
+
+By name: `text`, `password`, `email`, `textarea`, `number`, `date`, `datetime`, `time`, `checkbox`, `switch`, `dropdown`, `combobox`, `lookup`, `radio`, `slider`. Left out, the value picks it: a number gets a NumberBox, a boolean a CheckBox, a Date a DateBox, anything else a TextBox. `editorProps` go to the editor. Your own editors are registered once:
+
+```tsx
+FormLayout.editors.set('color', (props) => new ColorPicker(props));
+{ field: 'tint', label: 'Tint', editor: 'color' }
+```
+
+## API reference
+
+### Props
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `data` | `Bind<T \| null>` | — | The object the editors show and change. |
+| `items` | `Bind<readonly FormItem[]>` | `[]` | The places of the form; a function is followed. |
+| `columns` | `Bind<number>` | `1` | Columns of the grid. |
+| `minColumnWidth` | `Bind<string>` | — | As many columns as fit, each at least this wide. |
+| `labelMode` | `Bind<FieldLabelMode>` | `'top'` | Passed to every editor. |
+| `readOnly` | `Bind<boolean>` | `false` | Every editor read-only. |
+| `onValidSubmit(e) / onInvalidSubmit(e)` |  |  | Sent and passed (`{ data, event }`) / sent and failed (`{ valid, invalid }`). |
+
+### FormItem
+
+| Field | Description |
+| --- | --- |
+| `field, label, editor, editorProps` | The property, its caption, its editor and the editor’s props. |
+| `required, rules, helpText, enabled, readOnly, visible` | Passed to the editor (each a value or a function); `visible` hides the place. |
+| `colSpan` | Columns it spans; `'all'` for the whole row. |
+| `group, items, columns` | A captioned group with its own columns. |
+| `button` | Button props; `submit: true` sends the form. |
+| `template` | Any component made for the place. |
+
+### Members
+
+| Member | Description |
+| --- | --- |
+| `validate(), resetValidation(), submit()` | Check every field, hide the outcome, send the form. |
+| `editorOf(field)` | The editor of a field. |
+| `refresh()` | Your data object and items may be plain or reactive; the form reads them as they are. After changing them in place, call `refresh()`. Every editor reads its value again, the items their texts and states; items added or removed draw the form again. |
+| `refreshField(field)` | Reads one field of the data object again, after it was changed in place. |
+| `validationGroup, isValid` | The group the fields are checked in. |
+| `FormLayout.editors` | The editors known by name. |

package/docs/getting-started.md

@@ -0,0 +1,105 @@
+# Getting started
+
+> `@motifx-community/ui` is a **preview** (`beta`): it is complete enough to build with, and its API may still change
+> before 1.0. Install it with the `beta` tag; `@motifx/core` and its compiler with `next`.
+
+## Install
+
+```sh
+npm i @motifx/core@next @motifx-community/ui@beta @motifx-community/design-system@beta @motifx-community/data@beta @motifx-community/i18n@beta
+npm i -D @motifx/compiler@next vite typescript
+```
+
+`exceljs` (the grid's Excel export, `@motifx-community/ui/excel`) and `jspdf` (`@motifx-community/ui/pdf`) are optional: install
+them only when you import those entries.
+
+## Set up Vite and TypeScript
+
+```ts
+// vite.config.ts
+import compiler from '@motifx/compiler';
+import { defineConfig } from 'vite';
+
+export default defineConfig({
+  plugins: [compiler()],
+  resolve: { extensions: ['.tsx', '.ts', '.jsx', '.js'], dedupe: ['@motifx/core'] },
+  // The kit's styles use :dir(), :has() and relative colours: build CSS for the browsers it supports.
+  build: { cssTarget: ['chrome120', 'edge120', 'firefox128', 'safari18'] },
+});
+```
+
+```jsonc
+// tsconfig.json (the keys that matter)
+{ "compilerOptions": { "jsx": "preserve", "target": "ES2021", "module": "esnext", "moduleResolution": "bundler", "useDefineForClassFields": true, "strict": true } }
+```
+
+## Styles, design languages, themes
+
+```ts
+// main.tsx
+import '@motifx-community/ui/styles.css'; // the design system first, then the kit
+import { Application } from '@motifx/core';
+import { App } from './App';
+
+Application.CreateBuilder().build().run('#app', new App());
+```
+
+The look comes from the design system. Choose a design language and a theme on `<html>` (or on any element, for that
+part of the page):
+
+```html
+<html data-identity="material" data-theme="dark" data-density="compact">
+```
+
+- `data-identity`: `tactile` (the default, without the attribute), `lounge`, `material`, `fluent`, `lilac`.
+- `data-theme`: `light`, `dark`, `high-contrast`; without it the system's preference.
+- `data-density`: `compact`; without it the regular one.
+
+Restyle by overriding design-system tokens (`--mx-*`) after the kit's stylesheet, e.g. `:root { --mx-color-accent-solid: #8764b8; }`.
+
+## The kit's language
+
+The texts the components write themselves (buttons, messages, screen-reader names) and their numbers and dates follow
+`uiLocale`. English and Turkish ship with the kit; `uiLocale.use('tr')` loads the Turkish pack and every component
+draws again, live.
+
+```ts
+import { uiLocale } from '@motifx-community/ui';
+await uiLocale.use('tr');
+uiLocale.add('de', { ok: 'OK', cancel: 'Abbrechen' /* … */ });
+```
+
+With `@motifx-community/i18n` for the app's own texts, `connectI18n(i18n)` keeps the kit on the app's language.
+
+## How the components work
+
+- A component is an object: write it in JSX (`<Button text="Save" />`) or make it with `new Button({ text: 'Save' })`, add it
+  anywhere (`this.controls.add(button)`), change it later (`button.text = 'Saved'`).
+- Every prop and property takes a value or a function (`Bind<T>`): `disabled={() => this.model.busy}` follows the state.
+- `x-model` binds a value two-way: `<TextBox label="Name" x-model={() => this.form.name} />`.
+- Events are `onX` props or properties that take a listener: `onValueChanged={(e) => …}`, `grid.onRowClick((e) => …)`;
+  `e.byUser` tells a user's change from one made by code.
+- A component added to another is its child and goes with it when it is disposed; add components with `controls.add`,
+  never by putting their element into the page yourself.
+- Your data is used as given: items, rows and values are not wrapped or copied.
+
+```tsx
+import { Component, reactive } from '@motifx/core';
+import { Button, Stack, TextBox } from '@motifx-community/ui';
+
+export class App extends Component<HTMLDivElement> {
+  state = reactive({ name: '', saved: false });
+
+  view() {
+    return (
+      <Stack gap="md">
+        <TextBox label="&Name" x-model={() => this.state.name} required />
+        <Button text="&Save" tone="accent" disabled={() => !this.state.name} onclick={() => (this.state.saved = true)} />
+      </Stack>
+    );
+  }
+}
+```
+
+Each component's page in `docs/` lists its props, properties, methods, events, keyboard, accessibility and design
+tokens, with examples.

package/docs/home.md

@@ -0,0 +1,54 @@
+# @motifx-community/ui
+
+> Get started · @motifx-community/ui 0.1.0-beta.0
+
+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.
+
+## Install
+
+```tsx
+npm i @motifx/core @motifx-community/ui
+
+import { Button, Control, FocusContainer, addShortcut } from '@motifx-community/ui';
+```
+
+## How the components work
+
+- Every component is an object. Write it in JSX and bind it to state, or create it with `new` and add it wherever and whenever you need it — the developer using it decides, both ways are complete.
+
+- Lifetime follows ownership: a component dies with the one it belongs to.
+
+- Keyboard, focus and ARIA are part of every component, not extras.
+
+## 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.
+
+| Part | What it is |
+| --- | --- |
+| [`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. |
+
+## Design system
+
+The look comes from `@motifx-community/design-system`: its tokens, three themes, density, fonts and user-preference overrides. `styles.css` imports it first, then this kit's own layer (`mx.components`) adds the [component tokens](tokens.md) and the components. Nothing here is a color or a size of its own.
+
+- Themes: light, dark and high contrast, switched with `data-theme`; the OS preference is the default. Every text/background pair is checked in the design system's build: WCAG AA, AAA in high contrast.
+
+- Density: `data-density="compact"` shrinks every control, bar and title bar.
+
+- RTL through logical properties.
+
+```tsx
+<html data-theme="dark" data-density="compact">
+
+/* your accent, after styles.css: a design-system override restyles every component */
+:root {
+  --mx-color-accent-solid: #8764b8;
+  --mx-color-accent-solid-hover: #9373c0;
+  --mx-color-accent-solid-pressed: #7e5aaf;
+  --mx-color-accent-fg: #5c2e91;
+}
+```

package/docs/keyboard.md

@@ -0,0 +1,188 @@
+# Keyboard and focus
+
+> Foundations · @motifx-community/ui 0.1.0-beta.0
+
+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.
+
+## The rules
+
+| Rule | How |
+| --- | --- |
+| `Tab navigation` | Every control is a Tab stop unless `tabStop = false`; `tabIndex` orders the controls of a container. |
+| `Active control` | Containers (`FocusContainer`) track `activeControl` and put focus back with `restoreFocus()` when they become active again. |
+| `Composite controls` | One Tab stop, arrow keys inside (roving tabindex or `aria-activedescendant`): with the first composite control. |
+| `Focus never on <body>` | Disabling, hiding, removing or disposing the focused part of a control moves focus to the next usable element. |
+| `Focus ring` | Only for keyboard use (`:focus-visible`), the design system's double ring. |
+| `Access keys` | `&Save` in a control text: Alt+S. Underlined while Alt is held. |
+| `Shortcuts` | `addShortcut('Ctrl+S', …)` app-wide, or scoped to a control. |
+
+## Tab order
+
+Give controls a `tabIndex` and the outermost container of the page or window visits them in ascending order at each level of the control tree; equal indexes (and plain elements, index 0) go in document order. Until a control inside sets a `tabIndex`, Tab is left to the browser. A modal window keeps Tab inside itself; one radio button per group is a stop, as in browsers.
+
+```tsx
+import { Button, FocusContainer, Panel, Stack } from '@motifx-community/ui';
+
+/** A container of your own: it runs the Tab order of its controls and remembers the active one. */
+class CustomerEditor extends FocusContainer<HTMLDivElement> {}
+
+/** Tab visits the buttons by `tabIndex`; the container reports its `activeControl` and puts focus back with `restoreFocus()`. */
+export default function TabOrder() {
+  let editor: CustomerEditor | null = null;
+  return (
+    <>
+      <CustomerEditor ref={(c: CustomerEditor) => (editor = c)}>
+        <Panel variant="outline" padding="md">
+          <Stack orientation="horizontal" wrap align="center">
+            <Button text="Third" tabIndex={3} />
+            <Button text="First" tabIndex={1} />
+            <Button text="Second" tabIndex={2} />
+          </Stack>
+        </Panel>
+      </CustomerEditor>
+      <span>
+        activeControl: <output class="active-name">{() => editor?.activeControl?.text ?? '—'}</output>
+      </span>
+      <Button text="restoreFocus()" onclick={() => editor?.restoreFocus()} />
+    </>
+  );
+}
+```
+
+## Active control
+
+A `FocusContainer` knows which control inside holds focus (`activeControl`, reactive) and puts focus back there with `restoreFocus()`: a window coming to the front, a tab page coming back.
+
+## Access keys
+
+```tsx
+<Button text="&Save" onclick={save} />    // Alt+S
+<Button text="Save &as…" onclick={saveAs} /> // Alt+A
+<Button text="Tom && Jerry" />             // a literal &
+<input aria-keyshortcuts="Alt+N" />        // plain elements too
+```
+
+| Topic | Behaviour |
+| --- | --- |
+| `Marker` | `&` before a letter: `&Save`, `Save &as…`. `&&` is a literal ampersand. Only the first marker counts. |
+| `Keys` | Alt + the key; on Apple platforms Control + Option + the key, because Option alone types characters there (browsers use the same keys for HTML `accesskey`). |
+| `What it does` | The key activates the control: a button is focused and clicked (as HTML `accesskey` does), another control is focused (`onAccessKey()`). |
+| `Several with the same key` | Each press moves focus to the next one, activating none. |
+| `Where` | The modal window while one is open, else the window holding focus, else the page outside windows. Disabled and hidden controls are skipped. |
+| `AltGr` | Ignored: AltGr (Ctrl+Alt on Windows) types characters such as `@` on a Turkish keyboard. |
+| `Underline` | Shown while Alt is held (Control + Option on Apple platforms). Tapping Alt (press and release) keeps it shown until Alt is tapped again, another key is pressed or the pointer is used; while the page has access keys, that tap is kept from the browser, which would otherwise move keyboard focus to its menu bar. `data-mx-access-keys="always"` on `<html>` shows it all the time. |
+| `Accessibility` | The accessible name is the plain text; the control gets `aria-keyshortcuts="Alt+S"` (`"Control+Alt+S"` on Apple platforms). |
+| `Plain elements` | Any element with `aria-keyshortcuts="Alt+N"` takes part: a button-like one is clicked, an input focused, a `<label>` focuses its field. |
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button } from '@motifx-community/ui';
+
+/** `&` in a button text: Alt+S saves, Alt+O opens, Alt+P exports. */
+export default function AccessKeys() {
+  const s = reactive({ saves: 0, opens: 0, exports: 0 });
+  return (
+    <>
+      <Button text="&Save" onclick={() => s.saves++} />
+      <Button text="&Open" onclick={() => s.opens++} />
+      <Button text="Ex&port" onclick={() => s.exports++} />
+      <span>
+        Saved <output class="saves">{() => s.saves}</output> · opened <output class="opens">{() => s.opens}</output> · exported{' '}
+        <output>{() => s.exports}</output>
+      </span>
+    </>
+  );
+}
+```
+
+Browsers keep a few Alt combinations for their own menus, and they differ per browser and language; test the keys you choose.
+
+## Shortcuts
+
+```tsx
+import { addShortcut } from '@motifx-community/ui';
+
+const remove = addShortcut('Mod+S', () => model.save()); // app-wide
+grid.addShortcut('Delete', () => grid.deleteSelected()); // while focus is in the grid
+addShortcut('F2', () => rename(), { scope: tree });
+```
+
+### Chords
+
+| Part | Meaning |
+| --- | --- |
+| `Ctrl / Control` | The Ctrl key. |
+| `Alt / Option` | The Alt key (Option on a Mac). |
+| `Shift` | The Shift key. |
+| `Meta / Cmd / Win` | The Windows key, Cmd on a Mac. |
+| `Mod` | Cmd on Apple platforms, Ctrl elsewhere: `Mod+S` saves everywhere. |
+| `keys` | A character (`S`, `1`, `/`), or a `KeyboardEvent.key` name: `Enter`, `Escape` (`Esc`), `Delete` (`Del`), `F2`, `ArrowUp` (`Up`), `Space`, `Plus`… Case does not matter; `Ctrl++` is Ctrl and plus. |
+
+### Which shortcut runs
+
+| Rule | Behaviour |
+| --- | --- |
+| `Most specific first` | Shortcuts scoped to the controls holding focus run first, the innermost one first; app-wide ones last. A handler that returns `false` passes the key on. |
+| `Modal windows` | While a modal window is open, only shortcuts scoped inside it run; app-wide ones are silent. |
+| `Windows` | App-wide shortcuts without Ctrl, Alt or Meta (Delete, Escape, a letter) do not run while focus is in a window: those keys belong to the window. Chords with a modifier and F-keys still do. |
+| `Text fields` | A chord without Ctrl, Alt or Meta leaves text fields alone (Delete deletes text) unless `inEditable: true`. F-keys and chords with a modifier work everywhere. |
+| `Disabled scope` | A shortcut scoped to a disabled control does not run. |
+| `Handled` | The key gets `preventDefault()` and stops there. Shortcuts run before access keys: an explicit chord wins over an implicit key. |
+
+```tsx
+import { Component, reactive } from '@motifx/core';
+import { addShortcut } from '@motifx-community/ui';
+
+/** An app-wide shortcut, Mod+K, registered for as long as this component lives. */
+export default class Shortcut extends Component {
+  private readonly s = reactive({ palette: 0 });
+
+  override onConfigured(): void {
+    this.motif.setDisposable(addShortcut('Mod+K', () => void this.s.palette++));
+  }
+
+  override view() {
+    return (
+      <span>
+        This page registers <kbd>Mod+K</kbd> (Ctrl+K, Cmd+K on a Mac). Pressed <output class="palette">{() => this.s.palette}</output> times.
+      </span>
+    );
+  }
+}
+```
+
+## Focus never on &lt;body&gt;
+
+When the focused part of a control is disabled, hidden, removed (a list row, a branch) or disposed, focus moves to the next usable element from that spot in the same window, else the one before it. A click on an empty spot still clears focus as usual, and route changes are left to the router.
+
+```tsx
+import { reactive } from '@motifx/core';
+import { Button, Stack } from '@motifx-community/ui';
+
+/** Removing the row that holds focus moves focus to the next row, not to `<body>`. */
+export default function FocusGuard() {
+  const s = reactive({ items: [{ id: 1 }, { id: 2 }, { id: 3 }, { id: 4 }] });
+  return (
+    <>
+      {s.items.map((item) => (
+        <Stack key={item.id} orientation="horizontal" wrap align="center">
+          <span>Row {item.id}</span>
+          <Button text={`Remove row ${item.id}`} onclick={() => s.items.splice(s.items.indexOf(item), 1)} />
+        </Stack>
+      ))}
+    </>
+  );
+}
+```
+
+## API reference
+
+| Member | Returns / kind | Description |
+| --- | --- | --- |
+| `addShortcut(chord, handler, options?)` | `() => void` | Registers a shortcut; returns the remover. `options.scope`: a component; `options.inEditable`: also in text fields. |
+| `control.addShortcut(chord, handler, options?)` | `() => void` | The same, scoped to the control and removed when it is disposed. |
+| `parseAccessKey(text)` | `{ text, key, index }` | Parses `&Text` for your own controls; render with the `mx-access-key` class and call `setAccessKey(key)`. |
+| `tabIndex` | prop / property | Order inside the container; default 0. |
+| `activeControl / restoreFocus()` | FocusContainer | See the Control page. |
+
+Controls: see `Control` for `tabStop`, `tabIndex`, `focus()`, `onAccessKey()` and `FocusContainer`.