@aiquants/auth-react-router 0.15.1 → 0.17.0

package/README.md

@@ -81,15 +81,88 @@ 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.11.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 | 項目がありません |
+  | `searching` | select-box catalog (message of the open list while nothing matches yet and more rows may still come) | Searching... | 検索中... |
+  | `guess` | select-box catalog (accessible description of a suggested row, one the picker lists as a guess rather than a match) | suggestion | 推測 |
+  | `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
@@ -180,11 +253,32 @@ 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
+That is the components-only build. Follow select-box's own README ("CSS Setup") for the rest of your build: a Tailwind v4
+host imports it (and the `@aiquants/virtualscroll` peer build) in `layer(components)` and points `@source` at
+`node_modules/@aiquants/select-box/dist` (the published package ships no `src`); a host without Tailwind imports
+`@aiquants/select-box/styles/select-box.standalone.css` instead.
+
+The option rows of both pickers are drawn by this package: each row shows the group name and address, a note (the local
+group already linked to it, which makes the row unpickable, or else its member count when known), and the part of the
+label the typed query matched. The match paint is
+the picker's own (`RenderOptionContext.highlight`: the query compiled once under the picker's normalization and bound to
+the row's match category), so a row the picker lists as a guess is never painted as an exact match; the runs carry
+`data-aqar-match="exact"` or `"fuzzy"` and are paint-only (background and text colour, no bold), so a label keeps its
+width while you type.
+
+`@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` and its 0.11 render and typing contract (`RenderOptionContext.highlight`, and `value` /
+`onChange` typed by the option type), plus the locale resolution of `@aiquants/virtualscroll` 3.7.0, so select-box 0.11.0
+and virtualscroll 3.7.0 are the peer floors (the published manifest carries `^0.11.0`, which a 0.10 install does not
+satisfy).
+
+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

package/dist/admin.d.mts

@@ -1,9 +1,12 @@
+import { VirtualScrollLocale } from "@aiquants/virtualscroll";
 import * as react_router from "react-router";
 import { AuthUser, AuthGroup, AuthGroupMember, AuthAllowlistEntry, AuthDirectoryMembershipMode, AuthDirectoryStatus, AuthDirectoryCatalogSnapshot, AuthDirectoryCatalogGroup } from "@aiquants/auth-core";
 import React__default from "react";
+type UserAdminLocale = VirtualScrollLocale;
 type UserAdminLabels = {
     title: string;
-    locale: string;
+    locale: UserAdminLocale;
+    formatLocale: string;
     timeZone: string;
     common: {
         create: string;
@@ -211,7 +214,8 @@ declare const defaultUserAdminLabels: UserAdminLabels;
 declare const jaUserAdminLabels: UserAdminLabels;
 type PartialUserAdminLabels = {
     title?: string;
-    locale?: string;
+    locale?: UserAdminLocale;
+    formatLocale?: string;
     timeZone?: string;
     common?: Partial<UserAdminLabels["common"]>;
     errors?: Partial<UserAdminLabels["errors"]>;
@@ -382,9 +386,10 @@ type UserAdminShellProps = {
         title: string;
         annotation: React__default.ReactNode;
     }) => React__default.ReactNode;
+    basePath: string;
     pendingSyncPolling?: PendingSyncPolling;
 };
-declare function UserAdminShell({ children, renderHeader, pendingSyncPolling }: UserAdminShellProps): React__default.JSX.Element;
+declare function UserAdminShell({ children, renderHeader, pendingSyncPolling, basePath }: UserAdminShellProps): React__default.JSX.Element;
 type UserAdminLoaderData = {
     segment: string;
     users: AuthUser[];
@@ -401,5 +406,5 @@ declare function GroupMembersView(): React__default.JSX.Element;
 declare function AllowlistView(): React__default.JSX.Element;
 declare function DirectoryView(): React__default.JSX.Element;
 type AuthUserAdminAppViewProps = UserAdminShellProps;
-declare function AuthUserAdminAppView({ renderHeader, pendingSyncPolling }?: AuthUserAdminAppViewProps): React__default.JSX.Element;
-export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };
+declare function AuthUserAdminAppView({ renderHeader, pendingSyncPolling, basePath }: AuthUserAdminAppViewProps): React__default.JSX.Element;
+export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, type UserAdminLocale, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };

package/dist/admin.d.ts

@@ -1,9 +1,12 @@
+import { VirtualScrollLocale } from "@aiquants/virtualscroll";
 import * as react_router from "react-router";
 import { AuthUser, AuthGroup, AuthGroupMember, AuthAllowlistEntry, AuthDirectoryMembershipMode, AuthDirectoryStatus, AuthDirectoryCatalogSnapshot, AuthDirectoryCatalogGroup } from "@aiquants/auth-core";
 import React__default from "react";
+type UserAdminLocale = VirtualScrollLocale;
 type UserAdminLabels = {
     title: string;
-    locale: string;
+    locale: UserAdminLocale;
+    formatLocale: string;
     timeZone: string;
     common: {
         create: string;
@@ -211,7 +214,8 @@ declare const defaultUserAdminLabels: UserAdminLabels;
 declare const jaUserAdminLabels: UserAdminLabels;
 type PartialUserAdminLabels = {
     title?: string;
-    locale?: string;
+    locale?: UserAdminLocale;
+    formatLocale?: string;
     timeZone?: string;
     common?: Partial<UserAdminLabels["common"]>;
     errors?: Partial<UserAdminLabels["errors"]>;
@@ -382,9 +386,10 @@ type UserAdminShellProps = {
         title: string;
         annotation: React__default.ReactNode;
     }) => React__default.ReactNode;
+    basePath: string;
     pendingSyncPolling?: PendingSyncPolling;
 };
-declare function UserAdminShell({ children, renderHeader, pendingSyncPolling }: UserAdminShellProps): React__default.JSX.Element;
+declare function UserAdminShell({ children, renderHeader, pendingSyncPolling, basePath }: UserAdminShellProps): React__default.JSX.Element;
 type UserAdminLoaderData = {
     segment: string;
     users: AuthUser[];
@@ -401,5 +406,5 @@ declare function GroupMembersView(): React__default.JSX.Element;
 declare function AllowlistView(): React__default.JSX.Element;
 declare function DirectoryView(): React__default.JSX.Element;
 type AuthUserAdminAppViewProps = UserAdminShellProps;
-declare function AuthUserAdminAppView({ renderHeader, pendingSyncPolling }?: AuthUserAdminAppViewProps): React__default.JSX.Element;
-export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };
+declare function AuthUserAdminAppView({ renderHeader, pendingSyncPolling, basePath }: AuthUserAdminAppViewProps): React__default.JSX.Element;
+export { AllowlistView, AuthUserAdminAppView, type AuthUserAdminAppViewProps, DEFAULT_PENDING_SYNC_POLLING, DirectoryView, GroupMembersView, GroupsView, type PartialUserAdminLabels, type PendingSyncPolling, type UserAdminAccess, type UserAdminAppConfig, type UserAdminCatalog, type UserAdminCatalogFailure, type UserAdminCatalogGroup, type UserAdminCatalogSnapshot, type UserAdminGuards, UserAdminInputError, type UserAdminLabels, type UserAdminLinkSyncOutcome, type UserAdminLoaderData, type UserAdminLocale, UserAdminOperatorError, type UserAdminPermission, UserAdminShell, type UserAdminShellProps, type UserAdminStore, type UserAdminSyncRequestOutcome, UsersView, createInMemoryUserAdminStore, createUserAdminApp, defaultUserAdminLabels, jaUserAdminLabels, normalizeUpstreamKey, resolveUserAdminLabels, userAdminAccessFor, userAdminIntents };