@zeyos/zx 5.2.0 → 5.3.0

package/docs/api.json

@@ -1914,6 +1914,30 @@
         "type": "string|null",
         "default": "null",
         "description": "Accessible collection label; null resolves message `cardView.label`, \"Card view\"."
+      },
+      {
+        "name": "keyboard",
+        "type": "'tabs'|'roving'",
+        "default": "'tabs'",
+        "description": "Keyboard model. `'tabs'` makes every card, title link, checkbox, and action its own Tab stop. `'roving'` — recommended for lists — follows the APG Grid pattern with row focus: the collection is one Tab stop, the arrow keys, Home/End, and PageUp/PageDown move between cards, Enter activates, Space selects, and the controls inside a card stay pointer targets with `tabindex=\"-1\"`."
+      },
+      {
+        "name": "collapsibleGroups",
+        "type": "boolean",
+        "default": "false",
+        "description": "Whether group headings carry a toggle that hides and shows the group's cards."
+      },
+      {
+        "name": "collapsedGroups",
+        "type": "unknown[]",
+        "default": "[]",
+        "description": "Group ids that start collapsed."
+      },
+      {
+        "name": "renderGroupHeading",
+        "type": "((context:CardGroupHeadingContext)=>Node|string|null|undefined)|null",
+        "default": "null",
+        "description": "Content of a group heading in place of its label. With `collapsibleGroups` it is placed inside the toggle button, so it must not contain interactive elements."
       }
     ],
     "events": [
@@ -1921,6 +1945,11 @@
         "name": "recordaction",
         "payload": "Record<string,unknown>",
         "description": ""
+      },
+      {
+        "name": "groupcollapse",
+        "payload": "{id:string,collapsed:boolean,collapsedGroups:string[]}",
+        "description": ""
       }
     ],
     "methods": [
@@ -1936,6 +1965,18 @@
         "returns": "this",
         "description": "Restores shared and CardView configuration. Unknown shared fields reconcile in RecordView."
       },
+      {
+        "name": "setGroupCollapsed",
+        "signature": "setGroupCollapsed(id, [collapsed], [options])",
+        "returns": "this",
+        "description": "Collapses or expands one group. A collapsed group keeps its heading and hides its cards."
+      },
+      {
+        "name": "getCollapsedGroups",
+        "signature": "getCollapsedGroups()",
+        "returns": "string[]",
+        "description": "Returns the collapsed group ids."
+      },
       {
         "name": "destroy",
         "signature": "destroy()",

package/docs/llms.md

@@ -1700,8 +1700,13 @@ portable state as TableView and KanbanView.
 
 - **Options** — the shared RecordView options plus `titleField`, `subtitleField`, `preview`,
   `previewAlt`, `link`, `actions`, `groupBy`, `groupOrder`, `minCardWidth`, `maxColumns`,
-  `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, and `label` (null
-  resolves message `cardView.label`, "Card view").
+  `variant: 'outlined'|'raised'|'filled'`, `loadingCount`, `headingLevel`, `label` (null
+  resolves message `cardView.label`, "Card view"), `keyboard: 'tabs'|'roving'` (default `'tabs'`),
+  `collapsibleGroups`, `collapsedGroups`, and `renderGroupHeading`.
+- **Methods** — the shared RecordView methods plus `setGroupCollapsed(id, collapsed, {silent})` and
+  `getCollapsedGroups()`. **Events** — the shared set plus `recordaction` and
+  `groupcollapse {id, collapsed, collapsedGroups}` (also a `statechange` with reason
+  `'groupcollapse'`). The view state carries `collapsedGroups`.
 - **Messages** — `cardView.label`, `cardView.sort`, `cardView.sortCards`, `cardView.unsorted`,
   `cardView.sortAscending`/`cardView.sortDescending` (`%1` the field), `cardView.ungrouped`
   ("Ungrouped"), `cardView.groupEmpty` ("No records in this group."), `table.empty` for the empty
@@ -1728,6 +1733,29 @@ portable state as TableView and KanbanView.
   a stable fallback. Title/action links are normalized; `_blank` links receive `noopener`.
 - **Grouping and layout** — `groupBy` is a field ID or callback; `groupOrder` may deliberately show
   empty groups. Cards reflow through container queries and may cap columns without viewport logic.
+- **Keyboard model** — `keyboard: 'roving'` is the recommended setting for lists; `'tabs'` stays the
+  default for compatibility, and makes every card, title link, checkbox, and action its own Tab
+  stop (44 stops for 22 selectable cards). `'roving'` follows the WAI-ARIA APG **Grid** pattern with
+  row focus, the same model as `Table`: the content is `role="grid"` (`aria-multiselectable` for
+  `multi`), each card a `row` with `aria-selected` when selectable, and the collection is one Tab
+  stop. Grid rather than listbox because a card holds a link and buttons, which a listbox option
+  would flatten. ArrowUp/ArrowDown move to the card above or below — columns are measured from the
+  rendered positions, and the column you travel in is remembered — ArrowLeft/ArrowRight within a
+  row, Home/End to the first or last card, PageUp/PageDown by a visible page. Enter activates
+  (`recordclick`), Space toggles selection in `selectable` modes (activates otherwise),
+  Shift+movement extends a `multi` selection, Ctrl/Cmd+A selects every rendered card. Title links,
+  checkboxes, and actions get `tabindex="-1"`: they still work with the pointer, and Enter on the
+  card is the keyboard route. The current card is kept by record id across `setData`, sorting,
+  grouping, and collapsing, and focus is restored with `preventScroll`. Focus shows as an inset
+  `--zx-focus-ring` with a transparent outline for forced-colors mode.
+- **Group headings** — `renderGroupHeading({id, label, count, records, collapsed, toggle})` returns
+  the heading content in place of the label. `collapsibleGroups: true` makes each heading an APG
+  disclosure: a button with `aria-expanded` and `aria-controls` pointing at the group's list, which
+  holds the label (and so the custom content, which must then not contain interactive elements).
+  A collapsed group keeps its heading and renders no cards; `collapsedGroups` sets the initial
+  ones. In the roving model a collapsible heading is a row in the arrow-key order: Enter or Space
+  toggles it, ArrowLeft collapses, ArrowRight expands, and collapsing the group of the focused card
+  moves focus to its heading.
 - **Interaction** — By default Enter activates a focused card; Space toggles selection. With
   `selectionTrigger:'card'`, Enter also toggles selection. Links, actions,
   selection controls, and selected text do not also activate the card. `recordaction` adds the

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zeyos/zx",
-  "version": "5.2.0",
+  "version": "5.3.0",
   "description": "Dependency-free JavaScript implementation of the Xenon Design System.",
   "type": "module",
   "license": "MIT",

package/src/components/card-view/card-view.css

@@ -59,6 +59,77 @@
   line-height: 1.3;
 }
 
+/* The heading row: a plain wrapper in the tab model, a grid row in the roving one. */
+.zx-card-view__group-header {
+  border-radius: var(--zx-radius-sm);
+}
+
+.zx-card-view__group-header:focus-visible {
+  outline: 2px solid transparent;
+  box-shadow: inset var(--zx-focus-ring);
+}
+
+/* A collapsible heading is an APG disclosure: the button carries the label, the chevron turns. */
+.zx-card-view__group-toggle {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--zx-space-1);
+  min-block-size: 0;
+  margin-inline-start: calc(-1 * var(--zx-space-1));
+  padding: var(--zx-space-1);
+  border: 0;
+  border-radius: var(--zx-radius-sm);
+  background: none;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+}
+
+.zx-card-view__group-toggle:hover {
+  background: var(--zx-color-bg-hover);
+}
+
+.zx-card-view__group-toggle:focus-visible {
+  outline: 2px solid transparent;
+  box-shadow: var(--zx-focus-ring);
+}
+
+.zx-card-view__group-toggle > .zx-icon {
+  flex: none;
+  color: var(--zx-color-text-subtle);
+}
+
+.zx-card-view__group-toggle[aria-expanded="false"] > .zx-icon {
+  transform: rotate(-90deg);
+}
+
+.zx-card-view__group[data-collapsed="true"] .zx-card-view__group-heading {
+  margin-block-end: 0;
+}
+
+.zx-card-view__list[hidden] {
+  display: none;
+}
+
+/* Roving focus sits inside the card, so a host that restyles cards into flush rows still shows
+   it; the transparent outline is what forced-colors mode paints. */
+.zx-card-view[data-keyboard="roving"] .zx-record-card:focus-visible {
+  outline: 2px solid transparent;
+  outline-offset: -2px;
+  box-shadow: inset var(--zx-focus-ring);
+}
+
+.zx-card-view__content[data-empty-focus]:focus-visible {
+  outline: 2px solid transparent;
+  box-shadow: inset var(--zx-focus-ring);
+}
+
+@media (prefers-reduced-motion: no-preference) {
+  .zx-card-view__group-toggle > .zx-icon {
+    transition: transform var(--zx-dur-fast) var(--zx-ease);
+  }
+}
+
 .zx-card-view__list {
   display: grid;
   grid-template-columns: repeat(auto-fill,