@aiquants/auth-react-router 0.15.0 → 0.16.0

package/README.md

@@ -81,15 +81,86 @@ export const userAdminApp = createUserAdminApp({
 import { AuthUserAdminAppView } from "@aiquants/auth-react-router/admin"
 export const loader = userAdminApp.loader
 export const action = userAdminApp.action
-export default () => <AuthUserAdminAppView />
+// mounted as the splat route "/users/*"
+export default () => <AuthUserAdminAppView basePath="/users" />
 ```
 
+- **`basePath` is required** (`AuthUserAdminAppView` / `UserAdminShell`): the absolute path the console is mounted at,
+  without a trailing slash (`"/users"` for a `/users/*` route). The five tabs and the per-row "members" links of the
+  groups tab are built from it. There is no default: the host decides where the console lives, and a built-in default
+  would keep drawing links to that default after the mount moves — the routes still resolve and the build still
+  passes, only the links point at a place that is not served.
+
 - **`guards` is mandatory** — this surface lists every user and mutates group membership, so an unguarded mount is an account-enumeration and privilege-escalation path. Allow by returning, deny by throwing (`Response` / `redirect` / `Error`); the return value is `void` by contract, so a predicate-style guard that returns `false` cannot silently fail open.
 - **Per-operation authorization**: the guard receives the CRUD verb each intent actually performs (`read` / `create` / `update` / `delete`), so a principal holding only `update` cannot delete. Membership add/remove map to `create`/`delete` because they add and remove rows.
 - Unknown intents reach neither the guard nor the store (the intent table is a `Map`, so prototype keys such as `constructor` do not resolve).
 - Store errors (e.g. "cannot remove the last administrator") are returned as `{ ok: false, error }` and rendered by the views; guard rejections propagate untouched.
 - Labels default to **English** (`defaultUserAdminLabels`); inject `jaUserAdminLabels` or a partial override via `resolveUserAdminLabels`.
 
+### Localization (`labels.locale` vs `labels.formatLocale`)
+
+Every string this package draws lives in `UserAdminLabels`, and a host picks the language by injecting a whole catalog
+(`defaultUserAdminLabels` for English, the package default, or `jaUserAdminLabels`) or a partial override. Two keys
+carry language, and they are **different axes**:
+
+| Key | Type | `defaultUserAdminLabels` | `jaUserAdminLabels` | Drives |
+| --- | --- | --- | --- | --- |
+| `locale` | `UserAdminLocale` (`"en"` \| `"ja"`) | `"en"` | `"ja"` | UI chrome language of both upstream-group pickers (`SelectBox` `locale`) |
+| `formatLocale` | BCP 47 `string` | `"en-US"` | `"ja-JP"` | `Intl.DateTimeFormat` (with `timeZone`) and the user-list `Intl.Collator` |
+
+- **`locale`** is forwarded to both `@aiquants/select-box` pickers (the create-group dialog and the directory link
+  form). The picker strings this package owns (`directoryView.pickerNoOptions` / `pickerClear` / `pickerToggle` /
+  `pickerSelected` / `pickerAvailable`) are passed as the picker's `labels`, the placeholder is the per-instance
+  `placeholder` prop, and every other key comes from the select-box catalog of `locale` (the values below are those of
+  `defaultUserAdminLabels` / `jaUserAdminLabels` and of select-box 0.10.0):
+
+  | select-box key | Source | `"en"` | `"ja"` |
+  | --- | --- | --- | --- |
+  | `noOptions` | `directoryView.pickerNoOptions` | No matching group | 一致するグループがありません |
+  | `clear` | `directoryView.pickerClear` | Clear the selection | 選択を解除 |
+  | `toggle` | `directoryView.pickerToggle` | Show the group list | グループ一覧を開く |
+  | `selection` | `directoryView.pickerSelected` (`{value}` = the picked option's label) | Selected: {value} | 選択中: {value} |
+  | `status` | `directoryView.pickerAvailable` (`{count}` = options shown) | {count} groups available | 候補 {count} 件 |
+  | `placeholder` | `placeholder` prop: `groupsView.pickUpstreamPlaceholder` (dialog) / `directoryView.pickUpstreamPlaceholder` (link form) | Search by name or address... | 名前かアドレスで検索... |
+  | `scrollUp` | select-box catalog | Scroll up | 上へスクロール |
+  | `scrollDown` | select-box catalog | Scroll down | 下へスクロール |
+  | `scrollLeft` | select-box catalog | Scroll left | 左へスクロール |
+  | `scrollRight` | select-box catalog | Scroll right | 右へスクロール |
+  | `scrollToTop` | select-box catalog | Top | 先頭へ |
+  | `scrollToBottom` | select-box catalog | Bottom | 末尾へ |
+  | `noItems` | select-box catalog | No items | 項目がありません |
+  | `removeTag` | select-box catalog (multi-select chips; both pickers are single-select) | Remove {label} | 「{label}」を削除 |
+  | `resizeHandle` | select-box catalog (tooltip of the option list's resize handle) | Resize handle | サイズ変更ハンドル |
+
+  To change a catalog-sourced string, there is no per-key override here: pick the `locale` whose catalog you want.
+
+- `resolveUserAdminLabels` (run once when `createUserAdminApp` is built) **validates `locale`**: an omitted value keeps
+  the English default `"en"`; `"en"` / `"ja"` pass; anything else (`"ja-JP"`, `"EN"`, `""`, `null`, ...) throws
+  `RangeError` naming `labels.formatLocale`, so a mistake stops the app at startup instead of crashing the picker on
+  first render. There is no language negotiation — map `navigator.language` or a user setting to `"en"` / `"ja"`
+  yourself.
+- **`formatLocale` is not validated**: an unreadable tag degrades (dates fall back to the raw ISO string, sorting to the
+  runtime collator) instead of throwing, because formatting must never take the screen down.
+
+#### Migrating from 0.15.x (breaking changes in 0.16.0)
+
+1. **`basePath` is now required** on `AuthUserAdminAppView` / `UserAdminShell` (see above). Pass the absolute mount
+   path, without a trailing slash: `<AuthUserAdminAppView basePath="/users" />`. Omitting it fails type-checking
+   (TS2741); an untyped caller would draw links such as `undefined/groups`.
+2. **`labels.locale` changed meaning**: the old `labels.locale` (a BCP 47 tag for dates and sorting) is now
+   `labels.formatLocale` — no alias. The new `labels.locale` (type `UserAdminLocale` = `"en"` | `"ja"`) is the UI
+   language of the pickers, validated at startup.
+   - Hosts that inject `jaUserAdminLabels` whole, or spread it (`{ ...jaUserAdminLabels, heading: "" }`), need no
+     change: it carries `locale: "ja"` and `formatLocale: "ja-JP"`.
+   - A host that overrode `locale: "ja-JP"` must write `formatLocale: "ja-JP"`, and add `locale: "ja"` if it relies
+     on Japanese picker chrome (without it the pickers' catalog-sourced strings, such as the scroll-arrow names, are
+     English).
+   - A host that builds a full `UserAdminLabels` literal must add both keys.
+3. **`@aiquants/select-box` `texts` is gone**: the pickers take select-box 0.10.0 `locale` / `labels`
+   (`SelectBoxLabelOverrides`) instead of `texts` / `SelectBoxTexts`. This is internal to the views — hosts that only
+   render `AuthUserAdminAppView` do nothing — but a host must install `@aiquants/select-box` >= 0.10.0 and
+   `@aiquants/virtualscroll` >= 3.7.0 (the new peer floors).
+
 ### Upstream group catalog (optional port)
 
 The groups and directory tabs let the operator **pick** an upstream group instead of spelling its address. Wire the optional
@@ -146,6 +217,22 @@ domain with no groups.
 - `createLinkedGroup` creates the group and links it in **one** intent, and therefore requires the union of the verbs both
   halves need (`create` + `update` + `delete`). Splitting it in two would leave a state where only one half succeeded.
 
+### Sync requests: queued on link, followed through on screen
+
+The console never reaches the upstream itself. "Sync now" — and, since 0.15.0, **every link creation** — queues a request
+for the synchronization job (`store.requestDirectorySync(groupId, actor)`), and the job writes the result back to the
+database a few seconds later.
+
+- Both link intents return `{ ok: true, syncRequest }` with `"queued"`, `"already-pending"`, or `"not-queued"`. The last
+  one means **the link succeeded but the request could not be queued**; it is reported as such (and logged) rather than
+  thrown, because throwing would report a failure for a link that now exists. The request is scoped to the group, not the
+  tenant, so linking one group does not re-sweep every link.
+- While `directoryStatus.pendingRequestCount > 0`, the shell re-validates the route data every `intervalMs` and stops
+  after `maxMs` if the count never changes (a deployment with no job consuming the queue must not be polled forever from
+  every open tab). Configure it with the optional `pendingSyncPolling` prop of `AuthUserAdminAppView` / `UserAdminShell`;
+  the default is `DEFAULT_PENDING_SYNC_POLLING` (3 s, up to 5 min). Nothing here adds an upstream call: the
+  re-validation reads the rows the job wrote.
+
 Styling: this package has **no hand-written component CSS** (the `GoogleForm` classes are plain Tailwind utilities), so it ships **no components-only artifact** — only a standalone build. Two consumption modes, never mixed:
 
 - **Tailwind v4 host** — add `@source "../node_modules/@aiquants/auth-react-router/src/**/*.{ts,tsx}";` (monorepo: `../../../../packages/auth-react-router/src/**/*.{ts,tsx}`) so the `GoogleForm` classes are generated in the host's own canonical build; `src` ships in the published package.
@@ -164,11 +251,17 @@ the host, or the group picker's dropdown renders unstyled:
 @import "@aiquants/select-box/styles/select-box.css";
 ```
 
-Its transitive peers (`@aiquants/fuzzy-search`, `@aiquants/virtualscroll`) are declared here as well, so a host that
-installs this package is told what the picker needs rather than discovering it as a runtime resolution failure.
-
-All three are **required** peers, not optional. `src/admin/views.tsx` imports `@aiquants/select-box` at the top level and
-`./admin` re-exports it, so the specifier survives into `dist/admin.mjs`: a host without it does not get a degraded
+`@aiquants/fuzzy-search` is a transitive peer (the picker's search index, reached only through select-box) and is
+declared here as well, so a host that installs this package is told what the picker needs rather than discovering it
+as a runtime resolution failure. `@aiquants/virtualscroll` is both: select-box renders its option list with it, and
+this package imports it **directly** — `src/admin/labels.ts` resolves the UI language with
+`resolveVirtualScrollLocale`, so `dist/admin.mjs` carries its specifier. The pickers use the `locale` / `labels` props
+of `@aiquants/select-box` 0.10.0 and the locale resolution of `@aiquants/virtualscroll` 3.7.0, so those are the peer
+floors.
+
+All three are **required** peers, not optional. `src/admin/views.tsx` imports `@aiquants/select-box` and
+`src/admin/labels.ts` imports `@aiquants/virtualscroll` at the top level, and `./admin` re-exports both modules, so the
+specifiers survive into `dist/admin.mjs`: a host without them does not get a degraded
 picker, it gets `ERR_MODULE_NOT_FOUND` for the whole admin surface — including the groups and allowlist tabs, which have
 nothing to do with the picker. Marking them optional would suppress the install warning that is the only thing standing
 between a consumer and that failure. Note also that `@aiquants/select-box` pins React 19, which is stricter than this
@@ -189,7 +282,7 @@ package's own `react: ">=18"`; a host that mounts `/admin` must satisfy the stri
 | Port | App A | App B |
 | --- | --- | --- |
 | `google.scopes` | default | + `directory.readonly` etc. |
-| `mockUser` | `mock_user_id` cookie parse + name map | fixed id |
+| `mockUser` | cookie parse + name map | fixed id |
 | `warmup` | 2 pools | 1 pool |
 | `backendAuth` | primary-api | secondary-api |
 | `isUserActive` | DB lookup + allowlist re-check | omitted (always active) |