@mdbase-dev/ui 0.1.0-beta.126 → 0.1.0-beta.148

package/README.md

@@ -36,6 +36,174 @@ applyThemePreference(loadThemePreference());
   collection in another app. Lab and local builds pass their own URLs to
   `withAppUrls`.
 
+## Languages
+
+The `/i18n` entry exports `uiCatalogues: CatalogueSource` with synchronous
+English and lazy local-deployment JSON for `fr de es ja ko pt ru zh`.
+Compose it once with the app's catalogue using `@mdbase-dev/i18n`:
+
+```tsx
+import { i18n, uiCatalogues } from "@mdbase-dev/ui/i18n";
+const runtime = createI18nRuntime({ i18n, english: appEnglish, loadLocale, libraries: [uiCatalogues] });
+// Wrap the app once in LocaleProvider with this runtime.
+```
+
+Core-macro presentation helpers use the shared Lingui singleton; do not compose
+into an unrelated isolated instance. Keep React and Lingui deduplicated in app
+bundlers. No form is remounted on a locale switch. Build output includes all
+ten catalogues and transformed macros; consumers do not compile library source.
+PO files are the only authoring format. Builds use the kit CLI to prune obsolete PO
+entries before compilation, including English fallback; `prepack` runs strict catalogue
+checks and rebuilds so stale compiled messages cannot enter a fresh tarball.
+Run strict `i18n:check` before release: a fallback-capable development build does
+not prove a language is complete.
+Reviewed identical terms are Esc/ID, the literal example email, and French
+Collection/Collections (allowlisted per generated ID).
+
+## Command palette
+
+`CommandPalette` from `@mdbase-dev/ui/command-palette` accepts an optional
+`groupLabel(groupId: string): string` callback for localized group headings.
+For example, pass `groupLabel={readerCommandGroupLabel}`. Without it, the heading
+remains the command's `group` string. This is presentation only: keep `Command.group`
+and `showAll` values as stable IDs. Group order, browsing limits and search matching
+still use those IDs; translated headings do not change matching or merge groups.
+Re-render with the current locale's callback to update the presentation.
+
+## Collections
+
+Import `@mdbase-dev/ui/collections` and `@mdbase-dev/ui/collections.css`.
+`tokens.css` is optional: without it every value falls back to a built-in one.
+Every component takes the SDK front door from `createMdbase` (an optional peer
+dependency) and `app: { name, mark? }`.
+
+```tsx
+import { CollectionGate, CollectionSwitcher } from "@mdbase-dev/ui/collections";
+import "@mdbase-dev/ui/collections.css";
+
+<CollectionGate mdbase={mdbase} app={{ name: "Reader" }} extraActions={<TrySample />}>
+  {(connection) => <Shell header={<CollectionSwitcher mdbase={mdbase} app={app} />} />}
+</CollectionGate>;
+```
+
+- `CollectionGate` covers sign-in, choosing, approval, setup review and
+  problems, and renders its children once the phase is `ready`. A live problem
+  then shows as a banner above them. `layout="panel"` fits inside a shell or a
+  dialog.
+- The gate calls `mdbase.start()` itself while the front door hasn't started
+  (`autoStart`, default `true`). It makes one call however many gates render,
+  and none once the app has started it, so apps can drop their own `start()`.
+  Pass `autoStart={false}` to start it yourself. `CollectionPanel` does the same.
+- `extraActions` holds the app's own actions. On the signed-out screen they sit
+  beside Sign in. On every other gate screen they lead the footer, never under
+  a problem. Pass a function `(view) => node` to vary them by `view.kind`, or
+  return `null` to hide them.
+- `CollectionSwitcher` (`variant` `full`, `compact` or `icon`) is the header
+  switcher: a popover, and a bottom sheet below 640px. `icon` puts the app's
+  icon before the name, or `icon="mark"` the open collection's initials. In
+  the `icon` variant it replaces the folder glyph.
+- Pass `open` and `onOpenChange` to control the switcher; `onOpenChange` is
+  called for every open and close it makes itself, controlled or not.
+  `variant="none"` renders no trigger, for an app that opens the switcher from
+  its own control, such as an item in an overflow menu. It requires
+  `anchorRef`, an element that stays mounted while the switcher is open (the
+  menu's button, say): the popover is placed against it, and focus returns to
+  it when the switcher or a row dialog opened from it closes. Close your menu
+  without moving focus back to that button; the switcher takes focus as it
+  opens.
+- `rowDetail(row)` adds a second line to each collection row, such as where it
+  lives or which account it belongs to. `row.entry` is the SDK's entry.
+- `sections` lists collections the app knows about and the SDK doesn't (local
+  or private ones). Each section is `{ id, title, items, onSelect, onClose?,
+  empty? }`, and each item is `{ id, name, detail?, current?, disabled? }`.
+  Sections appear after "Your collections" on the gate's choosing and
+  signed-out screens and in the switcher. Selecting an item asks
+  `onBeforeLeave("switch")` when something is open, closes any other open
+  item, then calls `onSelect` from the click. Mark the open item `current`.
+  The gate then renders `renderAppCollection(item, { section, chooseAnother })`
+  instead of its screens, and `chooseAnother()` (or "Choose a different
+  collection" in the switcher) calls `onClose` to return to the list. Choosing
+  an SDK collection also calls `onClose` first.
+- A section item's `actions` fill its row menu, the same "…" menu SDK
+  collections have: `{ id, label, onSelect(item, context), danger?, disabled? }`.
+  `danger` actions show in the danger colour; confirm before acting.
+  `context.confirmDelete(onClose?)` opens `DeleteCollectionDialog` for the
+  item (the person types its name; the SDK deletes it by the item's `id`), and
+  `onClose(outcome)` reports how it ended:
+
+  ```tsx
+  actions: isOwner ? [{ id: "delete", label: "Delete collection…", danger: true,
+    onSelect: (_item, { confirmDelete }) => confirmDelete((outcome) => { if (outcome === "deleted") reload(); }) }] : []
+  ```
+- `CollectionPanel` combines the gate screens with the switcher list, for
+  settings dialogs. `CollectionProblem` shows one problem with its fix, either
+  the current one or an error the app passes in.
+- `onBeforeLeave(intent)` lets the app confirm before a switch, an add, choosing
+  another collection or signing out. Return `true` or a promise. The Connect
+  window opens straight after it, with no other await in between.
+- `allowDelete` enables "Delete collection…" for owners. `copy` overrides
+  strings from `defaultCollectionCopy`. `DeleteCollectionDialog`'s
+  `onClose(outcome)` reports `"deleted"`, `"cancelled"` (closed without trying)
+  or `"failed"` (closed after a refused delete).
+- `collectionView(snapshot)` is the headless model behind the components:
+  heading, rows and a notice with its control.
+- Hosts that don't use React call
+  `mountCollectionUi(element, { part: "panel" | "switcher" | "problem", ...options })`,
+  which returns `{ update, unmount }`. React and react-dom must be installed.
+
+### Testing
+
+The focus and popover code reads the global `window` and `document`, not the
+rendered element's document. Test files that use a jsdom environment
+(`// @vitest-environment jsdom`) already have them. A Node test that creates
+its own window has to make it global before rendering:
+
+```ts
+import { shareTestDocument } from "@mdbase-dev/ui/collections/testing";
+import { JSDOM } from "jsdom";
+
+const restore = shareTestDocument(new JSDOM("<!doctype html><body></body>").window);
+afterAll(restore);
+```
+
+### Restyling
+
+Map these properties anywhere up the tree (`:root` is fine) instead of
+overriding internals. Each one falls back to the app-ui token, then to the
+built-in value.
+
+| Property (`--mdbase-collections-…`) | Used for | app-ui token | Built-in |
+| --- | --- | --- | --- |
+| `accent` | filled actions, focus, the current row | `--color-accent` | blue |
+| `on-accent` | text on the accent | `--color-on-accent` | near white |
+| `surface` | popovers, sheets, dialogs, rows | `--color-surface` | near white |
+| `canvas` | the gate page background | `--color-canvas` | near white |
+| `text` | primary text | `--color-text` | near black |
+| `text-soft` | secondary text | `--color-text-soft` | grey |
+| `border` | hairlines | `--color-border-strong` | light grey |
+| `danger` | errors and destructive actions | `--color-danger` | red |
+| `warning` | warning text | `--color-warning-text` | amber |
+| `warning-edge` | the warning notice's edge | `--color-warning` | amber |
+| `scrim` | behind dialogs and sheets | `--color-scrim` | `rgb(0 0 0 / 0.3)` |
+| `current-bg` | the open collection's row | (none) | accent 9% into surface, mixed in oklab |
+| `font` | font family | `--sans` | `system-ui, sans-serif` |
+| `font-size` | body text | `--font-size-ui` | `0.8125rem` |
+| `font-size-caption` | row details, chips, labels | `--font-size-caption` | `0.75rem` |
+| `font-size-section` | leads, panel headings | `--font-size-section` | `0.9375rem` |
+| `font-size-heading` | the gate heading | `--font-size-heading` | `1.5rem` |
+| `font-weight-strong` | names, headings, buttons | `--font-weight-semibold` | `600` |
+| `radius-sm` | rows, buttons, fields | `--radius-sm` | `4px` |
+| `radius` | lists and cards | `--radius-md` | `8px` |
+| `radius-lg` | popovers, dialogs, sheets | `--radius-lg` | `12px` |
+| `elevation-low` | menus | `--elevation-low` | soft shadow |
+| `elevation-high` | popovers and dialogs | `--elevation-high` | deeper shadow |
+| `control-height` | button and row height | (none) | `36px`, `44px` on touch |
+
+Motion reads `--ease-standard`, `--motion-quick` and `--motion-spin`
+(`150ms` and `700ms` built in), and reduced motion slows the spinner. The
+built-in colours are light-theme values: an app with a dark theme and no
+`tokens.css` maps the colour properties.
+
 ## Shared feedback
 
 Import `@mdbase-dev/ui/feedback` and `@mdbase-dev/ui/feedback.css`, alongside