@nxgt/material-core 0.9.1 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,103 @@
 # @nxgt/material-core
 
+## 0.11.0
+
+### Minor Changes
+
+- [#574](https://github.com/softistx/nxgt-material/pull/574) [`c00f8c3`](https://github.com/softistx/nxgt-material/commit/c00f8c366e35b7769560bb86b964ae0705bcc60f) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Add `RepeatableGroup` and `RepeatableGroupFormField` (Storybook
+  `Form fields/RepeatableGroup`): rows of fields a user adds, removes and, with
+  `reorderable`, moves up and down. `RepeatableGroupFormField` wraps the form
+  library's `useFieldArray` (react-hook-form in React, vee-validate in Vue) and
+  renders each row from `renderRow` (React) or the `row` slot (Vue), whose
+  `path` names the row's fields. The rows are a list (`ul` / `li`) in a group
+  named by `label`; each row's buttons are named after it ("Remove period 2",
+  "Move period 2 up"), from the new `material.repeatable-group.*` keys in
+  English and French. An added row's first field takes the focus, a removed row
+  hands it to its neighbour or to Add, and a moved row keeps it on its move
+  button; each change is announced politely. `max` makes Add `aria-disabled`,
+  described by "Maximum reached (n)"; `min` disables Remove; `emptyTitle` /
+  `emptyDescription` show an `EmptyState` with no row. The array's own error
+  shows under the rows and describes the group; each row's fields show their
+  own. One column on a phone, a responsive grid wider up, no inline style.
+  
+  `@nxgt/material-core` gains `/repeatable-group`: the focus rules
+  (`focusAfterRemove`, `focusAfterMove`, `focusRowTarget`), the limits
+  (`canAddRow`, `canRemoveRow`, `rowMoveTarget`) and the `RowAnnouncement`
+  descriptor both libraries use.
+  
+  ```tsx
+  <RepeatableGroupFormField
+    control={control}
+    name="periods"
+    label="Periods"
+    rowLabel="period"
+    max={6}
+    reorderable
+    newRow={() => ({ name: '' })}
+    renderRow={({ index }) => (
+      <TextFormField control={control} name={`periods.${index}.name`} label="Name" />
+    )}
+  />
+  ```
+  
+  ```vue
+  <RepeatableGroupFormField
+    name="periods"
+    label="Periods"
+    row-label="period"
+    :max="6"
+    reorderable
+    :new-row="() => ({ name: '' })"
+  >
+    <template #row="{ path }">
+      <TextFormField :name="`${path}.name`" label="Name" />
+    </template>
+  </RepeatableGroupFormField>
+  ```
+  
+  Fixes [#516](https://github.com/softistx/nxgt-material/issues/516).
+  
+  Migration: an app with a local field-array list marked temporary for this
+  request ([#516](https://github.com/softistx/nxgt-material/issues/516)) — a `useFieldArray` whose rows are mapped by hand, with its own
+  Add and per-row Remove buttons — can delete it and render
+  `RepeatableGroupFormField` instead: the array's `name`, `newRow` for what Add
+  appends, and the row's fields moved into `renderRow` / the `row` slot. Pass no
+  `shouldFocus` to `append`: the group moves the focus itself.
+
+## 0.10.0
+
+### Minor Changes
+
+- [#535](https://github.com/softistx/nxgt-material/pull/535) [`a088c1c`](https://github.com/softistx/nxgt-material/commit/a088c1c8f08f8c4483fe0ba0e35eedfbe1b193f9) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Three form and focus helpers, the same names in both libraries (softistx/nxgt-material#500). Fixes [#500](https://github.com/softistx/nxgt-material/issues/500).
+  
+  - **`useFocusOnMount<T>(focus?)`** (`@nxgt/material/hooks`, `@nxgt/material-vue/composables`, auto-imported by the Nuxt module): the element takes focus once mounted, and again whenever `focus` turns true. Put it on the heading of what replaced the content the user acted on (a wizard's next step, "Message sent"), with `tabIndex={-1}` / `tabindex="-1"`. React returns a `RefObject`, Vue a `ShallowRef` to bind with `ref="…"`.
+  - **`useSubmitOnce(busy?)`** (same entries): one submit in flight. `const submitOnce = useSubmitOnce(); <form onSubmit={submitOnce(handleSubmit(save))}>` (Vue: `const onSubmit = submitOnce(handleSubmit(save))`) drops a double click or a second Enter until `save` ends; a dropped call's event has its default prevented. Return the request's promise, or pass its busy flag (Vue: a ref or getter): the guard then opens once the flag was true and is false again, for the submit that was on its way when it rose. Without `busy`, a handler that returns no promise (an early `return`) opens the guard at once. The framework-free `createSubmitGuard()` and `busySettler(guard)` are re-exported by both from `@nxgt/material-core/submit-guard`.
+  - **`useCodeResolver(schema, { translate, codeOf?, language? })`** (`@nxgt/material/components`, `@nxgt/material-vue/components`): a zod 4 schema's errors worded in the page's language. A refinement carrying `params.code` (`.refine(isFree, { params: { code: 'errors.taken' } })`) reads as your translator's words for that code, every other issue as `zodLocaleError`'s, with your `material.zod.*` overrides. `createCodeErrorMap`, `defaultCodeOf`, `isEmptyRequired` and the type `CodeIssue` are exported beside it. React returns a react-hook-form `Resolver` (`useForm({ resolver })`); Vue a computed vee-validate `TypedSchema` (`useForm({ validationSchema })`), so a language switch re-words the errors on screen.
+  - `@nxgt/material-core` adds `/submit-guard` (`createSubmitGuard` with `once(run, { settleSync })`, a run-scoped `settle(run)` and `pendingRun()`, and `busySettler`) and `/code-errors` (`createCodeErrorMap`, `defaultCodeOf`, `isEmptyRequired`): the error map is typed by shape, with no zod dependency.
+  
+  An app with a local copy marked `To extract to material (request [#500](https://github.com/softistx/nxgt-material/issues/500))` — `useFocusOnMount`, `createSubmitGuard` / `useSubmitOnce`, `useCodeResolver` and the code error map behind it — can delete it and import the same names from `@nxgt/material` / `@nxgt/material-vue` (`createSubmitGuard` and `createCodeErrorMap` from `@nxgt/material-core/submit-guard` and `/code-errors`). A local `useSubmitOnce(busy)` keeps its call; a local code error map becomes `useCodeResolver(schema, { translate, codeOf })`, with `codeOf: (issue) => (isEmptyRequired(issue) ? '<your required code>' : defaultCodeOf(issue))` where empty required fields had a code of their own.
+
+- [#544](https://github.com/softistx/nxgt-material/pull/544) [`e071e15`](https://github.com/softistx/nxgt-material/commit/e071e15a1d3b31c7e8fe7ad83d5a206687d18d9f) Thanks [@SteveGT96](https://github.com/SteveGT96)! - Signed-out pages and two-step verification: `AuthCard`, `EnrolmentSecret` and `RecoveryCodes`, the same names in both libraries (`@nxgt/material/components`, `@nxgt/material-vue/components`, registered by the Nuxt module). Fixes [#498](https://github.com/softistx/nxgt-material/issues/498).
+  
+  - **`AuthCard`** (Storybook `Navigation & layout/AuthCard`): the frame of a sign-in, sign-up or reset page. One `<main tabIndex={-1}>` (focusable by script, never by Tab), a centred card whose `title` is the page's `h1`, a `description`, a `notice` above the form (`noticeTone` `'info'` | `'success'` | `'warning'` are `role="status"`, `'error'` is `role="alert"`), `focusTitle` to move the focus to the `h1` on an end state ("Check your inbox"), a row above the card for `brand` and `toolbar` (rendered only when one is given), a `banner` above it and a `footer` under the card. Padded with `max(1rem, env(safe-area-inset-*))` by classes, no inline style. Vue: the same props, and slots `title`, `description`, `notice`, `brand`, `toolbar`, `banner`, `footer`.
+  - **`EnrolmentSecret`** (`Data display/EnrolmentSecret`): a TOTP enrolment — the `otpauth://` URI's QR code (the library's `QRCode`, level M, named "QR code to scan with your authenticator app"), the URI as a link ("Open in your authenticator app": a phone cannot scan its own screen) and the secret in groups of four in a group named "Setup key", with a `CopyButton` that copies it without spaces and announces "Key copied". `uri`, `secret`, `showQrCode` (default `true`), `qrSize` (default `192`) and a prop per label. Side by side once the component is 28rem wide, stacked on a phone, the key wrapping inside the card.
+  - **`RecoveryCodes`** (`Data display/RecoveryCodes`): one-time codes shown once, in a card. An ordered list named "Recovery codes"; "Copy codes" (one per line, announced "Codes copied" / "Copy failed" by the component's own polite status region, no `Toaster` needed); "Download" (a text file: `fileHeading`, `fileNote`, a blank line, the codes; `fileName` defaults to `recovery-codes.txt`); "Print" (the card alone, through the new print rules in `styles.css`); and "I have saved these codes", which "Done" requires: pressed before, it moves the focus to the box, marks it `aria-invalid` and says "Tick the box once your codes are safe". `title` / `titleAs` (`h2` by default), `description`, `warning` (`false` hides it), `focusTitle` (default `true`), `onDone` (the "Done" button shows only with it; Vue: `@done`), `saved` / `onSavedChange` (Vue: `v-model:saved`) and `labels`.
+  
+  ```tsx
+  <AuthCard title="Two-step verification" brand={<Logo />} toolbar={<LanguageSwitcher />}>
+    <EnrolmentSecret uri={enrolment.uri} secret={enrolment.secret} />
+  </AuthCard>
+  <RecoveryCodes codes={codes} fileHeading={`Recovery codes for ${email}`} saved={saved} onSavedChange={setSaved} onDone={done} />
+  ```
+  
+  ```vue
+  <RecoveryCodes v-model:saved="saved" :codes="codes" :file-heading="`Recovery codes for ${email}`" @done="done" />
+  ```
+  
+  `groupSecret`, `recoveryCodesText` and `downloadText` are re-exported beside them. `@nxgt/material-core` adds `/two-factor`: `groupSecret(secret, size = 4)`, `recoveryCodesText(codes, { heading?, note? })` and `downloadText(text, fileName, { type? })` (an object URL revoked a minute later, as `/pdf-download` does: both now share one helper). It also adds `/print-only`: `printOnly(element, name?)` prints one element of the page through `data-nxgt-print` on `<html>` and `data-nxgt-print-target` on the element, removed on `afterprint` or once a blocking `print()` returns; the rules are the new `print-only.css` in each library's `styles.css`, and both libraries re-export `printOnly`, `PRINT_ATTRIBUTE` and `PRINT_TARGET_ATTRIBUTE` from `/lib`. `CopyButton` and `RecoveryCodes` share the copy-and-announce state; `CopyButton` behaves as before. In `@nxgt/material-vue`, `Checkbox` now shows a `#helper-text` (or `#label`) slot that is added after the first render.
+  
+  Migration: local copies marked `To extract to material (request [#498](https://github.com/softistx/nxgt-material/issues/498))` can be deleted. A local sign-in frame becomes `AuthCard` (its subtitle is `description`; brand, language switcher and banner go in `brand`, `toolbar` and `banner`). A local enrolment block becomes `EnrolmentSecret uri secret`, and a local grouping helper `groupSecret`. A local recovery-codes display becomes `RecoveryCodes`, a local file builder `recoveryCodesText(codes, { heading, note })`, and a local print-only rule `printOnly`; the app keeps its wording (`title`, `description`, `fileHeading`, `fileNote`, `labels`), its data loading and its navigation guard while `saved` is false.
+
 ## 0.9.1
 
 ### Patch Changes

package/README.md

@@ -8,16 +8,21 @@ half (page geometry, scroll spy, text search), the currency field's decimals,
 the file-size formatter, the slider's tick marks, the emoji list's groups,
 the date range presets, a debounce, accent-insensitive text matching and a race-free async search (`/debounce`, `/text-match`, `/async-search`), the file preview's kind detection, the fields' blur
 rule, a field's first reachable control (`/focus-control`) and its `aria-describedby`
-(`/described-by`), the page behind a modal layer made inert
+(`/described-by`), where the focus goes in a repeatable row group
+(`/repeatable-group`), the page behind a modal layer made inert
 (`/inert-others`), Escape pressed while an overlay closes
 (`/escape-forward`), the Toaster's guard against a tap's emulated hover
 (`/touch-hover`), the focus a toast's action hands back (`/toast-focus`), a
 table row's activation, the zod error map's issue messages
-(`/zod-issue-messages`), the page's Content Security Policy nonce
-(`/csp-nonce`), an object built on its first use (`/lazy-object`), the Vite
-plugin that bundles pdfkit's standard fonts and a `build.assetsInlineLimit`
-that keeps fonts out of `data:` URIs, and the Node-only resolution of those
-fonts that the Next.js helper and the Nuxt module run at build time.
+(`/zod-issue-messages`), a zod error map that words an issue by its code
+(`/code-errors`), the page's Content Security Policy nonce (`/csp-nonce`), an
+object built on its first use (`/lazy-object`), one submit in flight
+(`/submit-guard`), the two-step verification helpers (`/two-factor`: a TOTP
+secret grouped to be typed, the recovery codes' text file, a text download),
+printing one element of the page (`/print-only`), the Vite plugin that
+bundles pdfkit's standard fonts and a `build.assetsInlineLimit` that keeps
+fonts out of `data:` URIs, and the Node-only resolution of those fonts that
+the Next.js helper and the Nuxt module run at build time.
 
 **You usually do not install it yourself.** Both libraries depend on it and
 re-export what they always exported, at the same subpaths:
@@ -84,6 +89,7 @@ built-in.
 | `/currency-digits` | `currencyFractionDigits` — the decimals `CurrencyField` shows |
 | `/field-blur-layers` | `layerOf`, `openerOf`, `FieldLayers` — whose overlay a layer of the page is, for a field's blur |
 | `/focus-control` | `firstControl`, `focusHandle`, `FocusHandle` — the first control of a field a user can reach, and a stand-in element that focuses it for a form library |
+| `/repeatable-group` | `focusAfterRemove`, `focusAfterMove`, `focusRowTarget`, `rowMoveTarget`, `canAddRow`, `canRemoveRow`, `RowFocusTarget`, `RowMoveDirection`, `RowAnnouncement`, `ROW_SLOT`, `ROW_FIELDS_SLOT`, `ADD_ATTRIBUTE` — where the focus goes after a row of a `RepeatableGroup` is added, removed or moved, and what its live region says |
 | `/escape-forward` | `forwardEscape` — Escape pressed while an overlay closes, pressed again for the overlay below once it has gone |
 | `/described-by` | `describedBy` — an `aria-describedby` value from the caller's ids and a field's help and error ids |
 | `/inert-others` | `inertOthers`, `INERT_MARKER` — the rest of the page `inert` behind a modal layer, live regions kept, nested layers counted |
@@ -100,6 +106,10 @@ built-in.
 | `/debounce` | `debounce`, the type `Debounced` — a function called once calls pause, with `cancel` and `flush` (`SearchField`'s `debounceMs`) |
 | `/text-match` | `foldText`, `matchesText` — case- and accent-insensitive matching (`'e'` finds "École"), lowercased for a locale |
 | `/async-search` | `createAsyncSearch`, `searchAnnouncement`, `DEFAULT_SEARCH_DEBOUNCE_MS`, `DEFAULT_MIN_QUERY_LENGTH` and the types `AsyncSearch`, `AsyncSearchConfig`, `AsyncSearchState`, `AsyncSearchStatus`, `SearchFn`, `SearchContext`, `SearchAnnouncement` — `Autocomplete`'s server search: debounced, each run aborting the last, a stale response dropped |
+| `/submit-guard` | `createSubmitGuard`, `busySettler` and the types `SubmitGuard`, `SubmitOnceOptions` — one submit in flight until its request ends, behind both libraries' `useSubmitOnce` |
+| `/code-errors` | `createCodeErrorMap`, `defaultCodeOf`, `isEmptyRequired` and the types `CodeErrorMap`, `CodeErrorMapOptions`, `CodeIssue` — a zod 4 error map that words an issue by the code it carries (a refinement's `params.code`), behind both libraries' `useCodeResolver` |
+| `/two-factor` | `groupSecret`, `recoveryCodesText`, `downloadText` and the types `RecoveryCodesTextOptions`, `DownloadTextOptions` — a TOTP secret in groups of four, the recovery codes as a text file, and saving a text file, behind both libraries' `EnrolmentSecret` and `RecoveryCodes` |
+| `/print-only` | `printOnly`, `PRINT_ATTRIBUTE`, `PRINT_TARGET_ATTRIBUTE` — printing one element of the page with no inline style, behind `RecoveryCodes`' Print button; re-exported by both libraries' `/lib` |
 | `/file-preview` | `fileKind`, `describeFile`, `safePreviewUrl`, `readTextPreview`, `FilePreviewHttpError`, `FilePreviewUnsafeUrlError`, `TEXT_PREVIEW_MAX_BYTES`, `fileExtension`, `fileNameFromUrl`, `dataUrlType`, `kindOfMimeType`, `normaliseMimeType`, `isTextFileKind`, `TEXT_FILE_KINDS` and the types `FileKind`, `FileKindInput`, `DescribedFile`, `FilePreviewSource`, `TextPreview` — `FilePreview`'s kind detection, URL allow-list and text reader |
 | `/vite` | `pdfkitStandardFonts()`, `cspAssetsInlineLimit` — see below |
 | `/pdfkit-fonts` | **Node only.** `pdfkitStandardFontDirs`, `pdfkitStandardFontFiles`, `PDFKIT_STANDARD_FONTS`, the types `PdfkitStandardFont` and `PdfkitFontsWarn` — where the app's pdfkit keeps its standard fonts, for a server tracer |
@@ -457,6 +467,132 @@ what a combobox's polite live region says: the failure, else "loading",
 else the count once the query has settled — `null` while the user is still
 typing.
 
+### One submit in flight: `/submit-guard`
+
+`createSubmitGuard()` returns `{ once, settle, pendingRun }`. `once(run)` wraps a
+handler so it runs only when no submit is on its way: a second click, or
+Enter, before the first request ends is dropped (its event, if it carries
+one, has its default prevented, so the browser does not submit the form on
+its own). `settle()` opens the guard again; a `run` that returns a promise
+opens it when that promise ends, fulfilled or rejected, and a `run` that
+throws opens it and rethrows. Any other result keeps it closed until
+`settle()` — unless `once(run, { settleSync: true })`, which opens it at
+once. So: **return the request's promise, or follow the request with a busy
+flag.** The wrapper returns `run`'s result — its promise as one that settles
+the same way, so a rejection still reaches the caller.
+
+`pendingRun()` is the run on its way (an increasing number, `undefined` when
+open), and `settle(run)` opens the guard only while that run is still the one
+on its way. `busySettler(guard)` uses them: call the function it returns
+with each value of a busy flag, and once the flag was true and is false
+again it settles the run that was on its way when the flag rose — never a
+newer one.
+
+```ts
+import { createSubmitGuard } from '@nxgt/material-core/submit-guard';
+
+const guard = createSubmitGuard();
+const submit = guard.once((event: SubmitEvent) => {
+	event.preventDefault();
+	return fetch('/api/subscribe', { method: 'POST', body: new FormData(form) });
+});
+form.addEventListener('submit', submit); // a second submit before the reply is dropped
+```
+
+Both libraries wrap it as `useSubmitOnce(busy?)`: `busy` is a boolean in
+React (`useSubmitOnce(navigation.state !== 'idle')`) and a ref or a getter in
+Vue (`useSubmitOnce(() => pending.value)`), followed through `busySettler`.
+Without `busy`, the hooks pass `settleSync: true`, so a handler that returns
+early does not lock the form.
+
+### Errors worded by code: `/code-errors`
+
+`createCodeErrorMap({ translate, codeOf?, fallback })` is a zod 4 error map
+(typed by shape: this package does not depend on zod). An issue's code —
+by default `defaultCodeOf`: a custom issue's `params.code`, when it is a
+string — is worded by `translate(code, params)`; when there is no code, or
+`translate` returns `undefined` or the code itself (a translator's answer for
+a key it lacks), `fallback(issue)` words it. `isEmptyRequired(issue)` tells
+an empty required field (a string shorter than one character, or a missing
+value), to give it a code of its own.
+
+```ts
+import { z } from 'zod';
+import {
+	createCodeErrorMap,
+	defaultCodeOf,
+	isEmptyRequired,
+} from '@nxgt/material-core/code-errors';
+
+const words: Record<string, string> = {
+	'errors.taken': 'This name is already taken.',
+	'errors.required': 'Please fill this in.',
+};
+const error = createCodeErrorMap({
+	translate: (code) => words[code],
+	codeOf: (issue) => (isEmptyRequired(issue) ? 'errors.required' : defaultCodeOf(issue)),
+	fallback: () => undefined, // zod's own message
+});
+
+const schema = z.object({
+	username: z.string().min(1).refine((name) => name !== 'admin', { params: { code: 'errors.taken' } }),
+});
+schema.safeParse({ username: 'admin' }, { error }); // "This name is already taken."
+```
+
+Both libraries wrap it as `useCodeResolver(schema)`, with their
+`zodLocaleError` as the fallback and the page's language.
+
+### Two-step verification: `/two-factor`
+
+`groupSecret(secret, size = 4)` reads a TOTP secret in groups, as a person
+types it into an authenticator app (`"JBSWY3DPEHPK3PXP"` → `"JBSW Y3DP EHPK
+3PXP"`); whitespace already in it is dropped first. `recoveryCodesText(codes,
+{ heading?, note? })` is the text file a person keeps: the heading, the note,
+a blank line, one code per line and a trailing newline (a line not given is
+left out). `downloadText(text, fileName, { type? })` saves it through an
+object URL and a temporary `<a download>`, revoked a minute later,
+as `/pdf-download` does (its `OBJECT_URL_TTL_MS`).
+
+```ts
+import {
+	downloadText,
+	groupSecret,
+	recoveryCodesText,
+} from '@nxgt/material-core/two-factor';
+
+groupSecret('JBSWY3DPEHPK3PXP'); // "JBSW Y3DP EHPK 3PXP"
+const text = recoveryCodesText(['7KQ2-M9XD', 'P4TW-8HZC'], {
+	heading: 'Recovery codes for ada@example.com',
+	note: 'Each code works once.',
+});
+downloadText(text, 'recovery-codes.txt');
+```
+
+Both libraries' `EnrolmentSecret` and `RecoveryCodes` are built on them.
+
+### Printing one element: `/print-only`
+
+`printOnly(element, name?)` prints that element and nothing else of the
+page: it sets `data-nxgt-print="<name>"` on `<html>` and
+`data-nxgt-print-target` on the element, calls `window.print()`, and removes
+both on `afterprint`, or as soon as `print()` returns where it blocks until
+the dialog closes. It returns a function that removes them at once; call it
+when the element unmounts. No inline style and no new window: the hiding is
+the libraries' stylesheet (`print-only.css`, in their `styles.css`),
+which under print media and `html[data-nxgt-print]` shows only the target.
+
+```ts
+import { printOnly } from '@nxgt/material-core/print-only';
+
+const stop = printOnly(document.querySelector('#codes') as HTMLElement, 'recovery-codes');
+// when the element unmounts:
+stop();
+```
+
+Both libraries re-export it from `/lib` (`@nxgt/material/lib`,
+`@nxgt/material-vue/lib`); `RecoveryCodes`' Print button uses it.
+
 ### The emoji list's groups: `/emoji-groups`
 
 How both libraries' `EmojiList` groups, searches and names its emojis:
@@ -677,6 +813,44 @@ firstControl(roots)?.focus(); // the first date input, not a hidden one
 field.ref(focusHandle(roots)); // React Hook Form: shouldFocusError reaches it
 ```
 
+### Rows added, removed and moved: `/repeatable-group`
+
+What both libraries' `RepeatableGroup` decides, as plain functions.
+`focusAfterRemove(removed, remaining)` names where the focus goes once a row
+is gone: the row that took its place, else the one before, else the Add
+button. `focusAfterMove(to, direction, count)` keeps it on the move button
+that was pressed, or on the row's other one when the row reached either end.
+`focusRowTarget(root, target)` moves the focus there, reading the DOM when
+called (rows are `[data-slot="repeatable-group-row"]`, the move buttons carry
+`data-move`, the Add button `data-repeatable-group-add`). `canAddRow(count, max)`, `canRemoveRow(count, min)` and
+`rowMoveTarget(index, direction, count)` are the limits (`RowMoveDirection`
+is `'up' | 'down'`), and `RowAnnouncement` is what the live region says
+(1-based positions). The DOM markers are exported as `ROW_SLOT`
+(`'repeatable-group-row'`), `ROW_FIELDS_SLOT` (`'repeatable-group-fields'`)
+and `ADD_ATTRIBUTE` (`'data-repeatable-group-add'`).
+
+```ts
+import {
+  canAddRow,
+  canRemoveRow,
+  focusAfterRemove,
+  focusRowTarget,
+  type RowAnnouncement,
+  rowMoveTarget,
+} from '@nxgt/material-core/repeatable-group';
+
+const addable = canAddRow(rows.length, 6); // false at 6 rows
+const removable = canRemoveRow(rows.length, 1); // false at 1 row
+const up = rowMoveTarget(index, 'up', rows.length); // null for the first row
+
+remove(index);
+await nextTick(); // or after React commits
+focusRowTarget(groupElement, focusAfterRemove(index, rows.length));
+
+const said: RowAnnouncement = { kind: 'removed', index: index + 1 };
+status.textContent = said.kind === 'removed' ? `Removed period ${said.index}` : '';
+```
+
 ### Escape while an overlay closes: `/escape-forward`
 
 Radix's and reka's dismissable layers give Escape to the highest layer only,

package/dist/chunks/index-15vj9xbx.js

@@ -0,0 +1,26 @@
+// src/lib/save-blob.ts
+var OBJECT_URL_TTL_MS2 = 60000;
+function revokeLater(url) {
+  window.setTimeout(() => URL.revokeObjectURL(url), OBJECT_URL_TTL_MS2);
+}
+function clickLink(href, attributes) {
+  const link = document.createElement("a");
+  link.href = href;
+  for (const [name, value] of Object.entries(attributes)) {
+    link.setAttribute(name, value);
+  }
+  link.style.display = "none";
+  document.body.append(link);
+  link.click();
+  link.remove();
+}
+function saveBlob(blob, fileName) {
+  const url = URL.createObjectURL(blob);
+  clickLink(url, { download: fileName });
+  revokeLater(url);
+}
+
+export { OBJECT_URL_TTL_MS2, revokeLater, clickLink, saveBlob };
+
+//# debugId=3BAD8691A74B531364756E2164756E21
+//# sourceMappingURL=index-15vj9xbx.js.map

package/dist/chunks/index-15vj9xbx.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/save-blob.ts"],
+  "sourcesContent": [
+    "/**\n * Saving a Blob as a file through a temporary `<a download>`: what\n * `/pdf-download` and `/two-factor`'s `downloadText` share. Reads the DOM\n * only when called.\n */\n\n/**\n * How long an object URL outlives the click that started its download or\n * opened its tab. Revoking it synchronously cancels the download in Firefox\n * and Safari, which read the URL after `click()` returns.\n */\nexport const OBJECT_URL_TTL_MS = 60_000;\n\nexport function revokeLater(url: string) {\n\twindow.setTimeout(() => URL.revokeObjectURL(url), OBJECT_URL_TTL_MS);\n}\n\nexport function clickLink(href: string, attributes: Record<string, string>) {\n\tconst link = document.createElement('a');\n\tlink.href = href;\n\tfor (const [name, value] of Object.entries(attributes)) {\n\t\tlink.setAttribute(name, value);\n\t}\n\tlink.style.display = 'none';\n\t// Firefox ignores a click on a link that is not in the document.\n\tdocument.body.append(link);\n\tlink.click();\n\tlink.remove();\n}\n\n/** Saves a Blob under `fileName`, and revokes its URL once the save began. */\nexport function saveBlob(blob: Blob, fileName: string) {\n\tconst url = URL.createObjectURL(blob);\n\tclickLink(url, { download: fileName });\n\trevokeLater(url);\n}\n"
+  ],
+  "mappings": ";AAWO,IAAM,qBAAoB;AAE1B,SAAS,WAAW,CAAC,KAAa;AAAA,EACxC,OAAO,WAAW,MAAM,IAAI,gBAAgB,GAAG,GAAG,kBAAiB;AAAA;AAG7D,SAAS,SAAS,CAAC,MAAc,YAAoC;AAAA,EAC3E,MAAM,OAAO,SAAS,cAAc,GAAG;AAAA,EACvC,KAAK,OAAO;AAAA,EACZ,YAAY,MAAM,UAAU,OAAO,QAAQ,UAAU,GAAG;AAAA,IACvD,KAAK,aAAa,MAAM,KAAK;AAAA,EAC9B;AAAA,EACA,KAAK,MAAM,UAAU;AAAA,EAErB,SAAS,KAAK,OAAO,IAAI;AAAA,EACzB,KAAK,MAAM;AAAA,EACX,KAAK,OAAO;AAAA;AAIN,SAAS,QAAQ,CAAC,MAAY,UAAkB;AAAA,EACtD,MAAM,MAAM,IAAI,gBAAgB,IAAI;AAAA,EACpC,UAAU,KAAK,EAAE,UAAU,SAAS,CAAC;AAAA,EACrC,YAAY,GAAG;AAAA;",
+  "debugId": "3BAD8691A74B531364756E2164756E21",
+  "names": []
+}

package/dist/chunks/index-407b6zs0.js

@@ -0,0 +1,41 @@
+// src/lib/focus-control.ts
+var TABBABLE = 'input:not([type="hidden"]):not(:disabled):not([tabindex="-1"]), textarea:not(:disabled):not([tabindex="-1"]), select:not(:disabled):not([tabindex="-1"]), button:not(:disabled):not([tabindex="-1"]), [contenteditable="true"], [tabindex]:not([tabindex="-1"])';
+function firstControl2(roots) {
+  for (const root of roots) {
+    const controls = root.matches(TABBABLE) ? [root] : root.querySelectorAll(TABBABLE);
+    for (const control of controls) {
+      if (control.getClientRects().length)
+        return control;
+    }
+  }
+  return null;
+}
+function focusHandle2(roots) {
+  return {
+    focus: () => {
+      firstControl2(roots)?.focus();
+      setTimeout(() => {
+        const list = [...roots];
+        const active = list[0]?.ownerDocument.activeElement ?? null;
+        if (!list.some((root) => root.contains(active))) {
+          firstControl2(list)?.focus();
+        }
+      });
+    },
+    select: () => {
+      const control = firstControl2(roots);
+      if (control && "select" in control) {
+        control.select();
+      }
+    },
+    setCustomValidity: () => {
+      return;
+    },
+    reportValidity: () => true
+  };
+}
+
+export { firstControl2, focusHandle2 };
+
+//# debugId=084F2A6FA5DCD68964756E2164756E21
+//# sourceMappingURL=index-407b6zs0.js.map

package/dist/chunks/index-407b6zs0.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/focus-control.ts"],
+  "sourcesContent": [
+    "/** What a user can Tab to inside a field. */\nconst TABBABLE =\n\t'input:not([type=\"hidden\"]):not(:disabled):not([tabindex=\"-1\"]), textarea:not(:disabled):not([tabindex=\"-1\"]), select:not(:disabled):not([tabindex=\"-1\"]), button:not(:disabled):not([tabindex=\"-1\"]), [contenteditable=\"true\"], [tabindex]:not([tabindex=\"-1\"])';\n\n/**\n * The first control of `roots` a user can reach, in document order: one a\n * user can Tab to that is rendered — not a `display: none` input a library\n * keeps for forms. A root that is itself such a control is its own first\n * control. `null` when none is. Reads the DOM when called.\n */\nexport function firstControl(roots: Iterable<Element>): HTMLElement | null {\n\tfor (const root of roots) {\n\t\tconst controls = root.matches(TABBABLE)\n\t\t\t? [root as HTMLElement]\n\t\t\t: root.querySelectorAll<HTMLElement>(TABBABLE);\n\t\tfor (const control of controls) {\n\t\t\tif (control.getClientRects().length) return control;\n\t\t}\n\t}\n\treturn null;\n}\n\n/** What a form library calls on the element a field registered. */\nexport type FocusHandle = {\n\tfocus: () => void;\n\tselect: () => void;\n\tsetCustomValidity: (message: string) => void;\n\treportValidity: () => boolean;\n};\n\n/**\n * A stand-in element for a field made of several controls, for a form\n * library that focuses an invalid field by calling `focus()` on what the\n * field registered (React Hook Form's `field.ref`). `focus()` focuses the\n * first control of `roots` a user can reach, looked up when it is called —\n * `roots` is read live, so pass the field's own set — and again a turn\n * later when focus is not in the field by then: the error that triggered it\n * may re-render the field and replace its control. `select()` selects that\n * control's text when it has any. Native validation is not used:\n * `setCustomValidity` does nothing and `reportValidity` returns `true`.\n */\nexport function focusHandle(roots: Iterable<Element>): FocusHandle {\n\treturn {\n\t\tfocus: () => {\n\t\t\tfirstControl(roots)?.focus();\n\t\t\tsetTimeout(() => {\n\t\t\t\tconst list = [...roots];\n\t\t\t\tconst active = list[0]?.ownerDocument.activeElement ?? null;\n\t\t\t\tif (!list.some((root) => root.contains(active))) {\n\t\t\t\t\tfirstControl(list)?.focus();\n\t\t\t\t}\n\t\t\t});\n\t\t},\n\t\tselect: () => {\n\t\t\tconst control = firstControl(roots);\n\t\t\tif (control && 'select' in control) {\n\t\t\t\t(control as HTMLInputElement).select();\n\t\t\t}\n\t\t},\n\t\tsetCustomValidity: () => undefined,\n\t\treportValidity: () => true,\n\t};\n}\n"
+  ],
+  "mappings": ";AACA,IAAM,WACL;AAQM,SAAS,aAAY,CAAC,OAA8C;AAAA,EAC1E,WAAW,QAAQ,OAAO;AAAA,IACzB,MAAM,WAAW,KAAK,QAAQ,QAAQ,IACnC,CAAC,IAAmB,IACpB,KAAK,iBAA8B,QAAQ;AAAA,IAC9C,WAAW,WAAW,UAAU;AAAA,MAC/B,IAAI,QAAQ,eAAe,EAAE;AAAA,QAAQ,OAAO;AAAA,IAC7C;AAAA,EACD;AAAA,EACA,OAAO;AAAA;AAsBD,SAAS,YAAW,CAAC,OAAuC;AAAA,EAClE,OAAO;AAAA,IACN,OAAO,MAAM;AAAA,MACZ,cAAa,KAAK,GAAG,MAAM;AAAA,MAC3B,WAAW,MAAM;AAAA,QAChB,MAAM,OAAO,CAAC,GAAG,KAAK;AAAA,QACtB,MAAM,SAAS,KAAK,IAAI,cAAc,iBAAiB;AAAA,QACvD,IAAI,CAAC,KAAK,KAAK,CAAC,SAAS,KAAK,SAAS,MAAM,CAAC,GAAG;AAAA,UAChD,cAAa,IAAI,GAAG,MAAM;AAAA,QAC3B;AAAA,OACA;AAAA;AAAA,IAEF,QAAQ,MAAM;AAAA,MACb,MAAM,UAAU,cAAa,KAAK;AAAA,MAClC,IAAI,WAAW,YAAY,SAAS;AAAA,QAClC,QAA6B,OAAO;AAAA,MACtC;AAAA;AAAA,IAED,mBAAmB,MAAG;AAAA,MAAG;AAAA;AAAA,IACzB,gBAAgB,MAAM;AAAA,EACvB;AAAA;",
+  "debugId": "084F2A6FA5DCD68964756E2164756E21",
+  "names": []
+}

package/dist/chunks/{index-h3vjydz7.js → index-r93kpbtg.js}

@@ -7,9 +7,13 @@ import {
 import {
   resolvePdfFileName2
 } from "./index-paaaedrm.js";
+import {
+  revokeLater,
+  clickLink,
+  saveBlob
+} from "./index-15vj9xbx.js";
 
 // src/lib/pdf-download.ts
-var OBJECT_URL_TTL_MS2 = 60000;
 function fetchInit(source) {
   if (!isPdfUrlSource2(source))
     return;
@@ -39,25 +43,6 @@ async function resolvePdfBlob(source, getData) {
     return null;
   }
 }
-function revokeLater(url) {
-  window.setTimeout(() => URL.revokeObjectURL(url), OBJECT_URL_TTL_MS2);
-}
-function clickLink(href, attributes) {
-  const link = document.createElement("a");
-  link.href = href;
-  for (const [name, value] of Object.entries(attributes)) {
-    link.setAttribute(name, value);
-  }
-  link.style.display = "none";
-  document.body.append(link);
-  link.click();
-  link.remove();
-}
-function saveBlob(blob, fileName) {
-  const url = URL.createObjectURL(blob);
-  clickLink(url, { download: fileName });
-  revokeLater(url);
-}
 function openInNewTab(href) {
   clickLink(href, { target: "_blank", rel: "noopener" });
 }
@@ -107,7 +92,7 @@ async function printPdfFile2(source, options = {}) {
   document.body.append(frame);
 }
 
-export { OBJECT_URL_TTL_MS2, downloadPdfFile2, printPdfFile2 };
+export { downloadPdfFile2, printPdfFile2 };
 
-//# debugId=77B6E1C9EF4463B464756E2164756E21
-//# sourceMappingURL=index-h3vjydz7.js.map
+//# debugId=3B08A2D665AEF3C464756E2164756E21
+//# sourceMappingURL=index-r93kpbtg.js.map

package/dist/chunks/index-r93kpbtg.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/pdf-download.ts"],
+  "sourcesContent": [
+    "import { resolvePdfFileName } from './pdf-file-name';\nimport {\n\tcopyPdfData,\n\tisBlob,\n\tisPdfUrlSource,\n\ttype PdfSource,\n\tpdfSourceUrl,\n} from './pdf-source';\nimport { clickLink, revokeLater, saveBlob } from './save-blob';\n\nexport { OBJECT_URL_TTL_MS } from './save-blob';\n\nexport type PdfFileOptions = {\n\t/** Name of the saved file; `.pdf` is added when missing. */\n\tfileName?: string;\n\t/**\n\t * Name used when neither `fileName`, a `File`'s name nor the URL gives\n\t * one: `document`, or its translation.\n\t */\n\tdefaultName?: string;\n\t/**\n\t * Bytes of the document the reader already loaded. Saving them needs no\n\t * second request, and works for a cross-origin URL, where the `download`\n\t * attribute is ignored.\n\t */\n\tgetData?: () =>\n\t\t| Uint8Array\n\t\t| null\n\t\t| undefined\n\t\t| Promise<Uint8Array | null | undefined>;\n};\n\nfunction fetchInit(source: PdfSource): RequestInit | undefined {\n\tif (!isPdfUrlSource(source)) return undefined;\n\treturn {\n\t\theaders: source.httpHeaders,\n\t\tcredentials: source.withCredentials ? 'include' : 'same-origin',\n\t};\n}\n\nasync function resolvePdfBlob(\n\tsource: PdfSource,\n\tgetData: PdfFileOptions['getData'],\n): Promise<Blob | null> {\n\tconst url = pdfSourceUrl(source);\n\tif (url === null) {\n\t\t// A Blob or bytes: a Blob copies what it is given.\n\t\treturn isBlob(source)\n\t\t\t? source\n\t\t\t: new Blob([copyPdfData(source as ArrayBuffer | Uint8Array)], {\n\t\t\t\t\ttype: 'application/pdf',\n\t\t\t\t});\n\t}\n\ttry {\n\t\tconst bytes = await getData?.();\n\t\tif (bytes?.byteLength) {\n\t\t\treturn new Blob([copyPdfData(bytes)], { type: 'application/pdf' });\n\t\t}\n\t} catch {\n\t\t/* the document may be gone; fetch it instead */\n\t}\n\ttry {\n\t\tconst init = fetchInit(source);\n\t\tconst response = await (init ? fetch(url, init) : fetch(url));\n\t\treturn response.ok ? await response.blob() : null;\n\t} catch {\n\t\treturn null;\n\t}\n}\n\nfunction openInNewTab(href: string) {\n\tclickLink(href, { target: '_blank', rel: 'noopener' });\n}\n\n/**\n * The URL a new tab may open when the document could not be read. None for\n * a URL with headers: a tab sends no `Authorization`, so it would only show\n * the server's refusal.\n */\nfunction fallbackUrl(source: PdfSource) {\n\tif (isPdfUrlSource(source) && source.httpHeaders) return null;\n\treturn pdfSourceUrl(source);\n}\n\n/**\n * Downloads the PDF under its resolved name. A URL is saved from the loaded\n * bytes or fetched; when neither works (CORS), it opens in a new tab, which\n * a popup blocker may stop once the click's activation has expired. A URL\n * with headers never opens in a tab: it would load without them.\n */\nexport async function downloadPdfFile(\n\tsource: PdfSource,\n\toptions: PdfFileOptions = {},\n) {\n\tconst name = resolvePdfFileName(\n\t\tsource,\n\t\toptions.fileName,\n\t\toptions.defaultName,\n\t);\n\tconst blob = await resolvePdfBlob(source, options.getData);\n\tconst url = fallbackUrl(source);\n\tif (blob) saveBlob(blob, name);\n\telse if (url !== null) openInNewTab(url);\n}\n\n/**\n * Prints the PDF from a same-origin object URL in a hidden frame. When the\n * browser refuses (a PDF plugin that blocks `print()`, a cross-origin URL\n * that could not be fetched), the document opens in a new tab instead.\n */\nexport async function printPdfFile(\n\tsource: PdfSource,\n\toptions: Pick<PdfFileOptions, 'getData'> = {},\n) {\n\tconst blob = await resolvePdfBlob(source, options.getData);\n\tif (!blob) {\n\t\tconst url = fallbackUrl(source);\n\t\tif (url !== null) openInNewTab(url);\n\t\treturn;\n\t}\n\tconst url = URL.createObjectURL(blob);\n\tconst frame = document.createElement('iframe');\n\tframe.setAttribute('aria-hidden', 'true');\n\tframe.style.position = 'fixed';\n\tframe.style.right = '0';\n\tframe.style.bottom = '0';\n\tframe.style.width = '0';\n\tframe.style.height = '0';\n\tframe.style.border = '0';\n\tframe.src = url;\n\tframe.onload = () => {\n\t\ttry {\n\t\t\tframe.contentWindow?.focus();\n\t\t\tframe.contentWindow?.print();\n\t\t} catch {\n\t\t\topenInNewTab(url);\n\t\t} finally {\n\t\t\twindow.setTimeout(() => frame.remove(), 1000);\n\t\t\trevokeLater(url);\n\t\t}\n\t};\n\tdocument.body.append(frame);\n}\n"
+  ],
+  "mappings": ";;;;;;;;;;;;;;;;AAgCA,SAAS,SAAS,CAAC,QAA4C;AAAA,EAC9D,IAAI,CAAC,gBAAe,MAAM;AAAA,IAAG;AAAA,EAC7B,OAAO;AAAA,IACN,SAAS,OAAO;AAAA,IAChB,aAAa,OAAO,kBAAkB,YAAY;AAAA,EACnD;AAAA;AAGD,eAAe,cAAc,CAC5B,QACA,SACuB;AAAA,EACvB,MAAM,MAAM,cAAa,MAAM;AAAA,EAC/B,IAAI,QAAQ,MAAM;AAAA,IAEjB,OAAO,QAAO,MAAM,IACjB,SACA,IAAI,KAAK,CAAC,aAAY,MAAkC,CAAC,GAAG;AAAA,MAC5D,MAAM;AAAA,IACP,CAAC;AAAA,EACJ;AAAA,EACA,IAAI;AAAA,IACH,MAAM,QAAQ,MAAM,UAAU;AAAA,IAC9B,IAAI,OAAO,YAAY;AAAA,MACtB,OAAO,IAAI,KAAK,CAAC,aAAY,KAAK,CAAC,GAAG,EAAE,MAAM,kBAAkB,CAAC;AAAA,IAClE;AAAA,IACC,MAAM;AAAA,EAGR,IAAI;AAAA,IACH,MAAM,OAAO,UAAU,MAAM;AAAA,IAC7B,MAAM,WAAW,OAAO,OAAO,MAAM,KAAK,IAAI,IAAI,MAAM,GAAG;AAAA,IAC3D,OAAO,SAAS,KAAK,MAAM,SAAS,KAAK,IAAI;AAAA,IAC5C,MAAM;AAAA,IACP,OAAO;AAAA;AAAA;AAIT,SAAS,YAAY,CAAC,MAAc;AAAA,EACnC,UAAU,MAAM,EAAE,QAAQ,UAAU,KAAK,WAAW,CAAC;AAAA;AAQtD,SAAS,WAAW,CAAC,QAAmB;AAAA,EACvC,IAAI,gBAAe,MAAM,KAAK,OAAO;AAAA,IAAa,OAAO;AAAA,EACzD,OAAO,cAAa,MAAM;AAAA;AAS3B,eAAsB,gBAAe,CACpC,QACA,UAA0B,CAAC,GAC1B;AAAA,EACD,MAAM,OAAO,oBACZ,QACA,QAAQ,UACR,QAAQ,WACT;AAAA,EACA,MAAM,OAAO,MAAM,eAAe,QAAQ,QAAQ,OAAO;AAAA,EACzD,MAAM,MAAM,YAAY,MAAM;AAAA,EAC9B,IAAI;AAAA,IAAM,SAAS,MAAM,IAAI;AAAA,EACxB,SAAI,QAAQ;AAAA,IAAM,aAAa,GAAG;AAAA;AAQxC,eAAsB,aAAY,CACjC,QACA,UAA2C,CAAC,GAC3C;AAAA,EACD,MAAM,OAAO,MAAM,eAAe,QAAQ,QAAQ,OAAO;AAAA,EACzD,IAAI,CAAC,MAAM;AAAA,IACV,MAAM,MAAM,YAAY,MAAM;AAAA,IAC9B,IAAI,QAAQ;AAAA,MAAM,aAAa,GAAG;AAAA,IAClC;AAAA,EACD;AAAA,EACA,MAAM,MAAM,IAAI,gBAAgB,IAAI;AAAA,EACpC,MAAM,QAAQ,SAAS,cAAc,QAAQ;AAAA,EAC7C,MAAM,aAAa,eAAe,MAAM;AAAA,EACxC,MAAM,MAAM,WAAW;AAAA,EACvB,MAAM,MAAM,QAAQ;AAAA,EACpB,MAAM,MAAM,SAAS;AAAA,EACrB,MAAM,MAAM,QAAQ;AAAA,EACpB,MAAM,MAAM,SAAS;AAAA,EACrB,MAAM,MAAM,SAAS;AAAA,EACrB,MAAM,MAAM;AAAA,EACZ,MAAM,SAAS,MAAM;AAAA,IACpB,IAAI;AAAA,MACH,MAAM,eAAe,MAAM;AAAA,MAC3B,MAAM,eAAe,MAAM;AAAA,MAC1B,MAAM;AAAA,MACP,aAAa,GAAG;AAAA,cACf;AAAA,MACD,OAAO,WAAW,MAAM,MAAM,OAAO,GAAG,IAAI;AAAA,MAC5C,YAAY,GAAG;AAAA;AAAA;AAAA,EAGjB,SAAS,KAAK,OAAO,KAAK;AAAA;",
+  "debugId": "3B08A2D665AEF3C464756E2164756E21",
+  "names": []
+}

package/dist/index.js

@@ -12,10 +12,9 @@ import {
   resolvePdfFileName2
 } from "./chunks/index-paaaedrm.js";
 import {
-  OBJECT_URL_TTL_MS2,
   downloadPdfFile2,
   printPdfFile2
-} from "./chunks/index-h3vjydz7.js";
+} from "./chunks/index-r93kpbtg.js";
 import {
   MAX_FRACTION_DIGITS2,
   fractionDigitsOption2
@@ -44,6 +43,9 @@ import {
   pdfBytesResponse2,
   toWebStream2
 } from "./chunks/index-2gcgcmc0.js";
+import {
+  OBJECT_URL_TTL_MS2
+} from "./chunks/index-15vj9xbx.js";
 import {
   text2,
   heading2,
@@ -129,5 +131,5 @@ export {
   totals2 as totals
 };
 
-//# debugId=1DC0C9D608FB064D64756E2164756E21
+//# debugId=E96D8B40D58DC02064756E2164756E21
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -4,6 +4,6 @@
   "sourcesContent": [
   ],
   "mappings": "",
-  "debugId": "1DC0C9D608FB064D64756E2164756E21",
+  "debugId": "E96D8B40D58DC02064756E2164756E21",
   "names": []
 }

package/dist/lib/code-errors.d.ts

@@ -0,0 +1,75 @@
+/**
+ * The part of a zod issue a code error map reads, by shape: core has no zod
+ * dependency, and every issue zod 4 hands an error map is assignable to it.
+ */
+export type CodeIssue = {
+    readonly code: string;
+    /** A custom issue's params: `.refine(…, { params: { code } })`. */
+    readonly params?: Record<string, unknown> | undefined;
+    /** The value that failed. */
+    readonly input?: unknown;
+    /** What a size issue measured: `'string'`, `'number'`, `'array'`… */
+    readonly origin?: string | undefined;
+    readonly minimum?: unknown;
+    readonly maximum?: unknown;
+    readonly expected?: unknown;
+    readonly message?: string | undefined;
+};
+/** The words for an issue, or `undefined` to let zod word it. */
+export type CodeErrorMap = (issue: CodeIssue) => string | undefined;
+export type CodeErrorMapOptions = {
+    /**
+     * The app's words for `code`, interpolating `params` (the custom issue's
+     * params, so `{ code, min: 3 }` can read "At least 3"). `undefined`, or
+     * the code returned verbatim (what a translator does with a key it lacks),
+     * means there are no words for it: `fallback` words the issue instead.
+     */
+    translate: (code: string, params: Record<string, unknown> | undefined) => string | undefined;
+    /**
+     * Which code an issue carries. Defaults to {@link defaultCodeOf}: a custom
+     * issue's `params.code`, when it is a string.
+     */
+    codeOf?: (issue: CodeIssue) => string | undefined;
+    /**
+     * Words an issue with no code, or one whose code has no words: the
+     * libraries pass `zodLocaleError({ language, translate })`.
+     */
+    fallback: CodeErrorMap;
+};
+/** A custom issue's `params.code`, when it is a string; otherwise none. */
+export declare function defaultCodeOf(issue: CodeIssue): string | undefined;
+/**
+ * Whether an issue only says the field was left empty: a string shorter than
+ * one character (`z.string().min(1)`), or a value of the wrong type that is
+ * not there at all (`undefined` or `null`).
+ *
+ * @example
+ * ```ts
+ * createCodeErrorMap({
+ *   translate,
+ *   fallback,
+ *   codeOf: (issue) =>
+ *     isEmptyRequired(issue) ? 'errors.required' : defaultCodeOf(issue),
+ * });
+ * ```
+ */
+export declare function isEmptyRequired(issue: CodeIssue): boolean;
+/**
+ * A zod 4 error map that words an issue by the code it carries, in the
+ * app's words: a refinement's `params.code` (an API error code, say) reads
+ * as `translate(code, params)`. An issue with no code, or whose code
+ * `translate` has no words for, is worded by `fallback`.
+ *
+ * @example
+ * ```ts
+ * import { createCodeErrorMap } from '@nxgt/material-core/code-errors';
+ *
+ * const error = createCodeErrorMap({
+ *   translate: (code, params) => translate(code, params, language),
+ *   fallback: zodLocaleError({ language, translate }),
+ * });
+ * schema.safeParse(values, { error });
+ * ```
+ */
+export declare function createCodeErrorMap({ translate, codeOf, fallback, }: CodeErrorMapOptions): CodeErrorMap;
+//# sourceMappingURL=code-errors.d.ts.map

package/dist/lib/code-errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"code-errors.d.ts","sourceRoot":"","sources":["../../src/lib/code-errors.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,MAAM,SAAS,GAAG;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAAC;IACtD,6BAA6B;IAC7B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,QAAQ,CAAC,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;CACtC,CAAC;AAEF,iEAAiE;AACjE,MAAM,MAAM,YAAY,GAAG,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,GAAG,SAAS,CAAC;AAEpE,MAAM,MAAM,mBAAmB,GAAG;IACjC;;;;;OAKG;IACH,SAAS,EAAE,CACV,IAAI,EAAE,MAAM,EACZ,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,KACvC,MAAM,GAAG,SAAS,CAAC;IACxB;;;OAGG;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,SAAS,KAAK,MAAM,GAAG,SAAS,CAAC;IAClD;;;OAGG;IACH,QAAQ,EAAE,YAAY,CAAC;CACvB,CAAC;AAEF,2EAA2E;AAC3E,wBAAgB,aAAa,CAAC,KAAK,EAAE,SAAS,GAAG,MAAM,GAAG,SAAS,CAIlE;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,SAAS,GAAG,OAAO,CAMzD;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,kBAAkB,CAAC,EAClC,SAAS,EACT,MAAsB,EACtB,QAAQ,GACR,EAAE,mBAAmB,GAAG,YAAY,CASpC"}