@nxgt/material-core 0.10.0 → 0.11.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @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

package/README.md

@@ -8,7 +8,8 @@ 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
@@ -88,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 |
@@ -811,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-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/lib/focus-control.js

@@ -1,43 +1,11 @@
-// 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 firstControl(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 focusHandle(roots) {
-  return {
-    focus: () => {
-      firstControl(roots)?.focus();
-      setTimeout(() => {
-        const list = [...roots];
-        const active = list[0]?.ownerDocument.activeElement ?? null;
-        if (!list.some((root) => root.contains(active))) {
-          firstControl(list)?.focus();
-        }
-      });
-    },
-    select: () => {
-      const control = firstControl(roots);
-      if (control && "select" in control) {
-        control.select();
-      }
-    },
-    setCustomValidity: () => {
-      return;
-    },
-    reportValidity: () => true
-  };
-}
+import {
+  firstControl2,
+  focusHandle2
+} from "../chunks/index-407b6zs0.js";
 export {
-  firstControl,
-  focusHandle
+  firstControl2 as firstControl,
+  focusHandle2 as focusHandle
 };
 
-//# debugId=F6055B3989727FBE64756E2164756E21
+//# debugId=3CD7CAE6F251A45964756E2164756E21
 //# sourceMappingURL=focus-control.js.map

package/dist/lib/focus-control.js.map

@@ -1,10 +1,9 @@
 {
   "version": 3,
-  "sources": ["../src/lib/focus-control.ts"],
+  "sources": [],
   "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,YAAY,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,WAAW,CAAC,OAAuC;AAAA,EAClE,OAAO;AAAA,IACN,OAAO,MAAM;AAAA,MACZ,aAAa,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,aAAa,IAAI,GAAG,MAAM;AAAA,QAC3B;AAAA,OACA;AAAA;AAAA,IAEF,QAAQ,MAAM;AAAA,MACb,MAAM,UAAU,aAAa,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": "F6055B3989727FBE64756E2164756E21",
+  "mappings": "",
+  "debugId": "3CD7CAE6F251A45964756E2164756E21",
   "names": []
 }

package/dist/lib/repeatable-group.d.ts

@@ -0,0 +1,70 @@
+/** Which way a row moves: towards the first row, or towards the last. */
+export type RowMoveDirection = 'up' | 'down';
+/**
+ * Where the focus goes once a RepeatableGroup's rows have changed: a row's
+ * first field, the Add button, or one of a row's move buttons. Indexes are
+ * 0-based, in the rows as they are after the change.
+ */
+export type RowFocusTarget = {
+    kind: 'field';
+    index: number;
+} | {
+    kind: 'add';
+} | {
+    kind: 'move';
+    index: number;
+    direction: RowMoveDirection;
+};
+/**
+ * What the group's polite live region says about a change. `index`, `from`
+ * and `to` are 1-based: they are what a user reads ("period 2").
+ */
+export type RowAnnouncement = {
+    kind: 'added';
+    index: number;
+} | {
+    kind: 'removed';
+    index: number;
+} | {
+    kind: 'moved';
+    from: number;
+    to: number;
+};
+/** Another row can be added: no `max`, or fewer rows than it. */
+export declare const canAddRow: (count: number, max?: number) => boolean;
+/** A row can be removed: no `min`, or more rows than it. */
+export declare const canRemoveRow: (count: number, min?: number) => boolean;
+/**
+ * The index the row at `index` moves to, or `null` when it cannot move that
+ * way (the first row up, the last one down).
+ */
+export declare function rowMoveTarget(index: number, direction: RowMoveDirection, count: number): number | null;
+/**
+ * Where the focus goes once the row at `removed` is gone and `remaining`
+ * rows are left: the row that took its place, else the row before it (the
+ * last one was removed), else the Add button (no row is left).
+ */
+export declare function focusAfterRemove(removed: number, remaining: number): RowFocusTarget;
+/**
+ * Where the focus goes once a row moved `direction` to `to`: the button that
+ * moved it, so the user can press it again — unless the row can no longer
+ * move that way (it reached the first or the last place, and that button is
+ * now disabled), then the other move button of the same row.
+ */
+export declare function focusAfterMove(to: number, direction: RowMoveDirection, count: number): RowFocusTarget;
+/** The `data-slot` of each row and of its fields. */
+export declare const ROW_SLOT = "repeatable-group-row";
+export declare const ROW_FIELDS_SLOT = "repeatable-group-fields";
+/**
+ * The attribute that marks the Add button: an attribute of its own, as the
+ * button keeps the `data-slot` of the library's Button.
+ */
+export declare const ADD_ATTRIBUTE = "data-repeatable-group-add";
+/**
+ * Moves the focus to `target` inside the group's `root`: the first control a
+ * user can reach in the row's fields, the Add button (`data-repeatable-group-add`), or the row's move
+ * button (`data-move="up"` / `"down"`). Reads the DOM when called; returns
+ * whether something took the focus.
+ */
+export declare function focusRowTarget(root: Element, target: RowFocusTarget): boolean;
+//# sourceMappingURL=repeatable-group.d.ts.map

package/dist/lib/repeatable-group.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repeatable-group.d.ts","sourceRoot":"","sources":["../../src/lib/repeatable-group.ts"],"names":[],"mappings":"AAEA,yEAAyE;AACzE,MAAM,MAAM,gBAAgB,GAAG,IAAI,GAAG,MAAM,CAAC;AAE7C;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACvB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,gBAAgB,CAAA;CAAE,CAAC;AAEhE;;;GAGG;AACH,MAAM,MAAM,eAAe,GACxB;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAChC;IAAE,IAAI,EAAE,SAAS,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,EAAE,EAAE,MAAM,CAAA;CAAE,CAAC;AAE/C,iEAAiE;AACjE,eAAO,MAAM,SAAS,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,OACvB,CAAC;AAElC,4DAA4D;AAC5D,eAAO,MAAM,YAAY,GAAI,OAAO,MAAM,EAAE,MAAM,MAAM,KAAG,OAC1B,CAAC;AAElC;;;GAGG;AACH,wBAAgB,aAAa,CAC5B,KAAK,EAAE,MAAM,EACb,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,GACX,MAAM,GAAG,IAAI,CAGf;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC/B,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM,GACf,cAAc,CAGhB;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC7B,EAAE,EAAE,MAAM,EACV,SAAS,EAAE,gBAAgB,EAC3B,KAAK,EAAE,MAAM,GACX,cAAc,CAIhB;AAED,qDAAqD;AACrD,eAAO,MAAM,QAAQ,yBAAyB,CAAC;AAC/C,eAAO,MAAM,eAAe,4BAA4B,CAAC;AACzD;;;GAGG;AACH,eAAO,MAAM,aAAa,8BAA8B,CAAC;AAEzD;;;;;GAKG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,cAAc,GAAG,OAAO,CAK7E"}

package/dist/lib/repeatable-group.js

@@ -0,0 +1,59 @@
+import {
+  firstControl2
+} from "../chunks/index-407b6zs0.js";
+
+// src/lib/repeatable-group.ts
+var canAddRow = (count, max) => max === undefined || count < max;
+var canRemoveRow = (count, min) => min === undefined || count > min;
+function rowMoveTarget(index, direction, count) {
+  const to = direction === "up" ? index - 1 : index + 1;
+  return to < 0 || to >= count ? null : to;
+}
+function focusAfterRemove(removed, remaining) {
+  if (remaining <= 0)
+    return { kind: "add" };
+  return { kind: "field", index: Math.min(removed, remaining - 1) };
+}
+function focusAfterMove(to, direction, count) {
+  const stays = rowMoveTarget(to, direction, count) !== null;
+  const other = direction === "up" ? "down" : "up";
+  return { kind: "move", index: to, direction: stays ? direction : other };
+}
+var ROW_SLOT = "repeatable-group-row";
+var ROW_FIELDS_SLOT = "repeatable-group-fields";
+var ADD_ATTRIBUTE = "data-repeatable-group-add";
+function focusRowTarget(root, target) {
+  const el = targetElement(root, target);
+  if (!el)
+    return false;
+  el.focus();
+  return el.ownerDocument.activeElement === el;
+}
+function targetElement(root, target) {
+  if (target.kind === "add") {
+    return root.querySelector(`[${ADD_ATTRIBUTE}]`);
+  }
+  const rows = root.querySelectorAll(`[data-slot="${ROW_SLOT}"]`);
+  const row = rows[target.index];
+  if (!row)
+    return null;
+  if (target.kind === "move") {
+    return row.querySelector(`[data-move="${target.direction}"]`);
+  }
+  const fields = row.querySelector(`[data-slot="${ROW_FIELDS_SLOT}"]`);
+  return firstControl2([fields ?? row]);
+}
+export {
+  ADD_ATTRIBUTE,
+  ROW_FIELDS_SLOT,
+  ROW_SLOT,
+  canAddRow,
+  canRemoveRow,
+  focusAfterMove,
+  focusAfterRemove,
+  focusRowTarget,
+  rowMoveTarget
+};
+
+//# debugId=EF31DAFB676F33B564756E2164756E21
+//# sourceMappingURL=repeatable-group.js.map

package/dist/lib/repeatable-group.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/lib/repeatable-group.ts"],
+  "sourcesContent": [
+    "import { firstControl } from './focus-control';\n\n/** Which way a row moves: towards the first row, or towards the last. */\nexport type RowMoveDirection = 'up' | 'down';\n\n/**\n * Where the focus goes once a RepeatableGroup's rows have changed: a row's\n * first field, the Add button, or one of a row's move buttons. Indexes are\n * 0-based, in the rows as they are after the change.\n */\nexport type RowFocusTarget =\n\t| { kind: 'field'; index: number }\n\t| { kind: 'add' }\n\t| { kind: 'move'; index: number; direction: RowMoveDirection };\n\n/**\n * What the group's polite live region says about a change. `index`, `from`\n * and `to` are 1-based: they are what a user reads (\"period 2\").\n */\nexport type RowAnnouncement =\n\t| { kind: 'added'; index: number }\n\t| { kind: 'removed'; index: number }\n\t| { kind: 'moved'; from: number; to: number };\n\n/** Another row can be added: no `max`, or fewer rows than it. */\nexport const canAddRow = (count: number, max?: number): boolean =>\n\tmax === undefined || count < max;\n\n/** A row can be removed: no `min`, or more rows than it. */\nexport const canRemoveRow = (count: number, min?: number): boolean =>\n\tmin === undefined || count > min;\n\n/**\n * The index the row at `index` moves to, or `null` when it cannot move that\n * way (the first row up, the last one down).\n */\nexport function rowMoveTarget(\n\tindex: number,\n\tdirection: RowMoveDirection,\n\tcount: number,\n): number | null {\n\tconst to = direction === 'up' ? index - 1 : index + 1;\n\treturn to < 0 || to >= count ? null : to;\n}\n\n/**\n * Where the focus goes once the row at `removed` is gone and `remaining`\n * rows are left: the row that took its place, else the row before it (the\n * last one was removed), else the Add button (no row is left).\n */\nexport function focusAfterRemove(\n\tremoved: number,\n\tremaining: number,\n): RowFocusTarget {\n\tif (remaining <= 0) return { kind: 'add' };\n\treturn { kind: 'field', index: Math.min(removed, remaining - 1) };\n}\n\n/**\n * Where the focus goes once a row moved `direction` to `to`: the button that\n * moved it, so the user can press it again — unless the row can no longer\n * move that way (it reached the first or the last place, and that button is\n * now disabled), then the other move button of the same row.\n */\nexport function focusAfterMove(\n\tto: number,\n\tdirection: RowMoveDirection,\n\tcount: number,\n): RowFocusTarget {\n\tconst stays = rowMoveTarget(to, direction, count) !== null;\n\tconst other: RowMoveDirection = direction === 'up' ? 'down' : 'up';\n\treturn { kind: 'move', index: to, direction: stays ? direction : other };\n}\n\n/** The `data-slot` of each row and of its fields. */\nexport const ROW_SLOT = 'repeatable-group-row';\nexport const ROW_FIELDS_SLOT = 'repeatable-group-fields';\n/**\n * The attribute that marks the Add button: an attribute of its own, as the\n * button keeps the `data-slot` of the library's Button.\n */\nexport const ADD_ATTRIBUTE = 'data-repeatable-group-add';\n\n/**\n * Moves the focus to `target` inside the group's `root`: the first control a\n * user can reach in the row's fields, the Add button (`data-repeatable-group-add`), or the row's move\n * button (`data-move=\"up\"` / `\"down\"`). Reads the DOM when called; returns\n * whether something took the focus.\n */\nexport function focusRowTarget(root: Element, target: RowFocusTarget): boolean {\n\tconst el = targetElement(root, target);\n\tif (!el) return false;\n\tel.focus();\n\treturn el.ownerDocument.activeElement === el;\n}\n\nfunction targetElement(\n\troot: Element,\n\ttarget: RowFocusTarget,\n): HTMLElement | null {\n\tif (target.kind === 'add') {\n\t\treturn root.querySelector<HTMLElement>(`[${ADD_ATTRIBUTE}]`);\n\t}\n\tconst rows = root.querySelectorAll(`[data-slot=\"${ROW_SLOT}\"]`);\n\tconst row = rows[target.index];\n\tif (!row) return null;\n\tif (target.kind === 'move') {\n\t\treturn row.querySelector<HTMLElement>(`[data-move=\"${target.direction}\"]`);\n\t}\n\tconst fields = row.querySelector(`[data-slot=\"${ROW_FIELDS_SLOT}\"]`);\n\treturn firstControl([fields ?? row]);\n}\n"
+  ],
+  "mappings": ";;;;;AAyBO,IAAM,YAAY,CAAC,OAAe,QACxC,QAAQ,aAAa,QAAQ;AAGvB,IAAM,eAAe,CAAC,OAAe,QAC3C,QAAQ,aAAa,QAAQ;AAMvB,SAAS,aAAa,CAC5B,OACA,WACA,OACgB;AAAA,EAChB,MAAM,KAAK,cAAc,OAAO,QAAQ,IAAI,QAAQ;AAAA,EACpD,OAAO,KAAK,KAAK,MAAM,QAAQ,OAAO;AAAA;AAQhC,SAAS,gBAAgB,CAC/B,SACA,WACiB;AAAA,EACjB,IAAI,aAAa;AAAA,IAAG,OAAO,EAAE,MAAM,MAAM;AAAA,EACzC,OAAO,EAAE,MAAM,SAAS,OAAO,KAAK,IAAI,SAAS,YAAY,CAAC,EAAE;AAAA;AAS1D,SAAS,cAAc,CAC7B,IACA,WACA,OACiB;AAAA,EACjB,MAAM,QAAQ,cAAc,IAAI,WAAW,KAAK,MAAM;AAAA,EACtD,MAAM,QAA0B,cAAc,OAAO,SAAS;AAAA,EAC9D,OAAO,EAAE,MAAM,QAAQ,OAAO,IAAI,WAAW,QAAQ,YAAY,MAAM;AAAA;AAIjE,IAAM,WAAW;AACjB,IAAM,kBAAkB;AAKxB,IAAM,gBAAgB;AAQtB,SAAS,cAAc,CAAC,MAAe,QAAiC;AAAA,EAC9E,MAAM,KAAK,cAAc,MAAM,MAAM;AAAA,EACrC,IAAI,CAAC;AAAA,IAAI,OAAO;AAAA,EAChB,GAAG,MAAM;AAAA,EACT,OAAO,GAAG,cAAc,kBAAkB;AAAA;AAG3C,SAAS,aAAa,CACrB,MACA,QACqB;AAAA,EACrB,IAAI,OAAO,SAAS,OAAO;AAAA,IAC1B,OAAO,KAAK,cAA2B,IAAI,gBAAgB;AAAA,EAC5D;AAAA,EACA,MAAM,OAAO,KAAK,iBAAiB,eAAe,YAAY;AAAA,EAC9D,MAAM,MAAM,KAAK,OAAO;AAAA,EACxB,IAAI,CAAC;AAAA,IAAK,OAAO;AAAA,EACjB,IAAI,OAAO,SAAS,QAAQ;AAAA,IAC3B,OAAO,IAAI,cAA2B,eAAe,OAAO,aAAa;AAAA,EAC1E;AAAA,EACA,MAAM,SAAS,IAAI,cAAc,eAAe,mBAAmB;AAAA,EACnE,OAAO,cAAa,CAAC,UAAU,GAAG,CAAC;AAAA;",
+  "debugId": "EF31DAFB676F33B564756E2164756E21",
+  "names": []
+}

package/docs/roadmap.md

@@ -76,6 +76,10 @@ Nothing is in progress.
 
 ## Shipped
 
+- **A repeatable row group's focus rules** (`/repeatable-group`) — where the
+  focus goes after a row is added, removed or moved, the add and remove
+  limits, and what the live region announces, behind both libraries'
+  `RepeatableGroup`. 0.11.0.
 - **Two-step verification helpers and printing one element** (`/two-factor`,
   `/print-only`) — a TOTP secret grouped to be typed by hand, the recovery
   codes as a text file, saving a text file, and printing one element of the

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@nxgt/material-core",
-	"version": "0.10.0",
-	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes, the Toaster's touch-hover guard and its focus hand-back, the page's Content Security Policy nonce, an object built on first use, the zod issue messages, the date range presets, the debounce, accent-insensitive text matching and the race-free async search behind Autocomplete and SearchField, the submit guard, the code error map, the two-factor helpers (a grouped TOTP secret, the recovery codes' file, a text download), printing one element of the page, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin, a CSP-safe Vite assetsInlineLimit and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
+	"version": "0.11.0",
+	"description": "The framework-free core of @nxgt/material and @nxgt/material-vue: the PDF document model and its react-pdf renderer, print formatters, PDF file helpers, the PDF viewer's pure modules, the currency digits, the file-size formatter, the field-blur layers, a field's first focusable control, a repeatable row group's focus and announcement rules, the aria-describedby joiner, the inert background of a modal layer, Escape forwarded while an overlay closes, the Toaster's touch-hover guard and its focus hand-back, the page's Content Security Policy nonce, an object built on first use, the zod issue messages, the date range presets, the debounce, accent-insensitive text matching and the race-free async search behind Autocomplete and SearchField, the submit guard, the code error map, the two-factor helpers (a grouped TOTP secret, the recovery codes' file, a text download), printing one element of the page, the file preview's kind detection and text reader, the pdfkit fonts Vite plugin, a CSP-safe Vite assetsInlineLimit and the Node-only pdfkit fonts resolution for Next.js and Nuxt builds",
 	"license": "MIT",
 	"bugs": {
 		"email": "stevegires@gmail.com"
@@ -103,6 +103,11 @@
 			"import": "./dist/lib/focus-control.js",
 			"default": "./dist/lib/focus-control.js"
 		},
+		"./repeatable-group": {
+			"types": "./dist/lib/repeatable-group.d.ts",
+			"import": "./dist/lib/repeatable-group.js",
+			"default": "./dist/lib/repeatable-group.js"
+		},
 		"./escape-forward": {
 			"types": "./dist/lib/escape-forward.d.ts",
 			"import": "./dist/lib/escape-forward.js",
@@ -268,6 +273,7 @@
 			"src/lib/currency-digits.ts",
 			"src/lib/field-blur-layers.ts",
 			"src/lib/focus-control.ts",
+			"src/lib/repeatable-group.ts",
 			"src/lib/escape-forward.ts",
 			"src/lib/described-by.ts",
 			"src/lib/touch-hover.ts",