@zeyos/zx 5.2.0 → 5.3.0

package/CHANGELOG.md

@@ -8,6 +8,40 @@ and friends remain the complete record.
 
 ## Unreleased
 
+## 5.3.0 — 2026-10-29
+
+The record collection's toolbar, chips, drawers and pager become one shared composition in the
+layout kit, and the CRM and the issue tracker are rebuilt on it.
+
+### Added
+
+- `CardView` `keyboard: 'roving'` — the APG grid keyboard model the `Table` already has: the
+  collection is one Tab stop, arrows move between cards and group headings by the rendered rows,
+  Home/End and Page keys, Enter activates, Space and Shift+Arrow select, Ctrl/Cmd+A selects all;
+  focus is kept by record id across re-renders. `'tabs'`, the default, is unchanged.
+- `CardView` `collapsibleGroups`, `collapsedGroups`, `setGroupCollapsed()`, `getCollapsedGroups()`
+  and the `groupcollapse` event; `renderGroupHeading(context)` renders a group's heading with the
+  id, label, count, records, collapsed state and a `toggle()`.
+
+### Fixed
+
+- A narrow `Search` field squeezed its submit and clear buttons below the control height.
+
+### Website
+
+- The record collection's composition — toolbar, chip strip and chip editors, the Filters and View
+  settings drawers, page slicing, grouping, pagination, board axes and the keyboard map — is one
+  shared layout-kit module, with `other` buckets that write back, a base filter for tabs and
+  scopes, a split empty state, a `rendered` event and one-line toolbars beside an open drawer.
+- **CRM**: companies, people, deals and the curated lists use the shared overview: inline search,
+  the Filter, Sort and View drawers, the five-way shape switch, chips and the pager under the saved
+  view tabs. Companies gain cards and a stage board, people gain cards; owner and tier have
+  Unassigned and No tier buckets so no record drops out of a grouped view; the ARR total rides the
+  count line and the board columns keep their totals.
+- **Issue tracker**: the list is a roving `CardView` in the tracker's dense row anatomy with
+  collapsible group headings carrying status glyphs and counts and "New issue in <group>" on each;
+  the board takes its swim lanes from the grouping; the fixed tabs stay in the header.
+
 ## 5.2.0 — 2026-10-29
 
 A record collection pattern with a five-way view switch and filter chips, two components to go

package/dist/types/components/card-view/card-view.d.ts

@@ -113,7 +113,60 @@ export type CardViewOptions = {
      * `cardView.label`, "Card view".
      */
     label?: string | null;
+    /**
+     * 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"`.
+     */
+    keyboard?: 'tabs' | 'roving';
+    /**
+     * Whether group headings carry a toggle that hides
+     * and shows the group's cards.
+     */
+    collapsibleGroups?: boolean;
+    /**
+     * Group ids that start collapsed.
+     */
+    collapsedGroups?: unknown[];
+    /**
+     * 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.
+     */
+    renderGroupHeading?: ((context: CardGroupHeadingContext) => Node | string | null | undefined) | null;
     onrecordaction?: (event: CustomEvent<Record<string, unknown>>) => void;
+    ongroupcollapse?: (event: CustomEvent<{
+        id: string;
+        collapsed: boolean;
+        collapsedGroups: string[];
+    }>) => void;
+};
+export type CardGroupHeadingContext = {
+    /**
+     * Normalized group id (`''` for records without a value).
+     */
+    id: string;
+    /**
+     * Default label.
+     */
+    label: string;
+    /**
+     * Records in the group.
+     */
+    count: number;
+    /**
+     * The group's records in display order.
+     */
+    records: ViewRecord[];
+    /**
+     * Whether the group is collapsed.
+     */
+    collapsed: boolean;
+    /**
+     * Collapses or expands the group.
+     */
+    toggle: () => void;
 };
 export type CardViewState = {
     /**
@@ -148,6 +201,10 @@ export type CardViewState = {
      * Surface treatment.
      */
     variant: 'outlined' | 'raised' | 'filled';
+    /**
+     * Collapsed group ids.
+     */
+    collapsedGroups: string[];
 };
 export type CardRecordGroup = {
     /**
@@ -206,7 +263,29 @@ export type CardRecordGroup = {
  * @property {1|2|3|4|5|6} [headingLevel=3] Per-card title heading level.
  * @property {string|null} [label=null] Accessible collection label; null resolves message
  *   `cardView.label`, "Card view".
+ * @property {'tabs'|'roving'} [keyboard='tabs'] 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"`.
+ * @property {boolean} [collapsibleGroups=false] Whether group headings carry a toggle that hides
+ *   and shows the group's cards.
+ * @property {unknown[]} [collapsedGroups=[]] Group ids that start collapsed.
+ * @property {((context:CardGroupHeadingContext)=>Node|string|null|undefined)|null} [renderGroupHeading=null]
+ *   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.
  * @property {(event:CustomEvent<Record<string,unknown>>)=>void} [onrecordaction]
+ * @property {(event:CustomEvent<{id:string,collapsed:boolean,collapsedGroups:string[]}>)=>void} [ongroupcollapse]
+ */
+/**
+ * What `renderGroupHeading` is given for one group.
+ * @typedef {Object} CardGroupHeadingContext
+ * @property {string} id Normalized group id (`''` for records without a value).
+ * @property {string} label Default label.
+ * @property {number} count Records in the group.
+ * @property {ViewRecord[]} records The group's records in display order.
+ * @property {boolean} collapsed Whether the group is collapsed.
+ * @property {() => void} toggle Collapses or expands the group.
  */
 /**
  * @typedef {Object} CardViewState
@@ -218,6 +297,7 @@ export type CardRecordGroup = {
  * @property {string} minCardWidth Responsive minimum card width.
  * @property {number|null} maxColumns Maximum cards per row.
  * @property {'outlined'|'raised'|'filled'} variant Surface treatment.
+ * @property {string[]} collapsedGroups Collapsed group ids.
  */
 /**
  * @typedef {Object} CardRecordGroup
@@ -228,7 +308,20 @@ export type CardRecordGroup = {
 /**
  * Responsive, schema-friendly record cards with shared fields, sorting, selection, state, groups,
  * safe preview media, native title links, and delegated actions.
+ *
+ * With `keyboard: 'roving'` the collection follows the WAI-ARIA APG Grid pattern with row focus,
+ * the model `Table` uses: the content is a `grid`, each card a focusable `row` (`aria-selected`
+ * when selectable, `aria-multiselectable` on the grid for `multi`), and the collection is a single
+ * Tab stop. ArrowUp/ArrowDown move to the card above or below — columns are measured from where the
+ * cards actually are, so a multi-column layout moves by visual row — 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 (and activates otherwise),
+ * Shift+movement extends a `multi` selection, and Ctrl/Cmd+A selects every rendered card. A
+ * collapsible group heading is part of the same order: Enter or Space toggles it, ArrowLeft
+ * collapses, ArrowRight expands. The current card is kept by record id across `setData`, sorting,
+ * grouping, and collapsing, and focus is restored without scrolling.
  * @fires CardView#recordaction
+ * @fires CardView#groupcollapse
  * @extends {RecordView}
  */
 export declare class CardView extends RecordView {
@@ -242,6 +335,28 @@ export declare class CardView extends RecordView {
     _cardVariant: "filled" | "outlined" | "raised";
     _cardLoadingCount: number;
     _cardHeadingLevel: 1 | 2 | 3 | 4 | 5 | 6;
+    _cardRoving: boolean;
+    _cardIdPrefix: string;
+    _cardCollapsed: Set<string>;
+    /** @type {{kind:'card'|'group', id:unknown}|null} */
+    _cardCurrent: {
+        kind: 'card' | 'group';
+        id: unknown;
+    } | null;
+    _cardCurrentIndex: number;
+    /** @type {HTMLElement|null} */
+    _cardTabStop: HTMLElement | null;
+    /** @type {number|null} */
+    _cardStickyX: number | null;
+    _cardMoving: boolean;
+    /** @type {Map<string, HTMLElement>} */
+    _cardHeadersById: Map<string, HTMLElement>;
+    /** @type {Map<unknown, string>} */
+    _cardGroupOfId: Map<unknown, string>;
+    /** @type {Map<Element, string>} */
+    _cardSectionIds: Map<Element, string>;
+    /** @type {WeakMap<Element, unknown>} */
+    _cardIdOfNode: WeakMap<Element, unknown>;
     static cssName: string;
     /** @type {Readonly<CardViewOptions & RecordViewOptions>} */
     static defaults: Readonly<CardViewOptions & RecordViewOptions>;
@@ -264,6 +379,19 @@ export declare class CardView extends RecordView {
     setViewState(state: Partial<CardViewState> | null, options?: {
         silent?: boolean;
     }): this;
+    /**
+     * Collapses or expands one group. A collapsed group keeps its heading and hides its cards.
+     * @param {unknown} id Group id, as `groupBy` produces it.
+     * @param {boolean} [collapsed=true] Next state.
+     * @param {{silent?:boolean}} [options={}] Set `silent` to suppress `groupcollapse` and `statechange`.
+     * @returns {this}
+     * @fires CardView#groupcollapse
+     */
+    setGroupCollapsed(id: unknown, collapsed?: boolean, options?: {
+        silent?: boolean;
+    }): this;
+    /** Returns the collapsed group ids. @returns {string[]} */
+    getCollapsedGroups(): string[];
     /** Restores an enhanced target exactly, or removes an owned root. @returns {void} */
     destroy(): void;
     /** @protected @param {string} reason Refresh reason. @returns {void} */
@@ -278,6 +406,67 @@ export declare class CardView extends RecordView {
     private _renderCards;
     /** @private @param {CardRecordGroup} group @param {ViewField[]} fields @param {ViewField[]} visibleFields @param {number} groupIndex @returns {HTMLElement} */
     private _createCardGroup;
+    /**
+     * Builds a group heading: the label (or `renderGroupHeading` content), inside an APG
+     * disclosure button when the group can collapse.
+     * @private
+     * @param {CardRecordGroup} group Group.
+     * @param {string} headingId Heading id.
+     * @param {boolean} collapsible Whether the group can collapse.
+     * @param {boolean} collapsed Whether it is collapsed.
+     * @returns {HTMLElement}
+     */
+    private _createGroupHeader;
+    /**
+     * Turns a rendered card into a grid row for the roving model: row focus, `aria-selected` when
+     * selectable, and the controls inside it out of the Tab order.
+     * @private
+     * @param {HTMLElement} card Card element.
+     * @param {unknown} id Record id.
+     * @returns {void}
+     */
+    private _makeCardRow;
+    /**
+     * Moves the single Tab stop to the current item after a render — the same record or group by
+     * id; else the heading of the collapsed group that now hides the card; else the item now at its
+     * old position — and focuses it again, without scrolling, when the collection had focus.
+     * @private
+     * @param {boolean} hadFocus Whether focus was inside the collection before the render.
+     * @returns {void}
+     */
+    private _syncCardRoving;
+    /**
+     * @private
+     * @param {HTMLElement} item New Tab stop.
+     * @param {HTMLElement[]} [items] Every item, when already collected.
+     * @returns {void}
+     */
+    private _setCardTabStop;
+    /**
+     * While loading or empty there is no card to hold focus: the content takes it rather than
+     * letting it fall to the document, and gives the Tab order its old shape back afterwards.
+     * @private
+     * @param {boolean} hold Whether focus was inside and there is nothing to put it on.
+     * @returns {void}
+     */
+    private _syncCardEmptyFocus;
+    /** @private @returns {HTMLElement[]} Roving items in display order. */
+    private _cardItems;
+    /** @private @param {HTMLElement} item @returns {{kind:'card'|'group', id:unknown}|null} */
+    private _cardItemKey;
+    /** @private @param {{kind:'card'|'group', id:unknown}|null} key @returns {HTMLElement|null} */
+    private _cardItemFor;
+    /** @private @param {FocusEvent} event @returns {void} */
+    private _cardFocusIn;
+    /**
+     * The roving keyboard model; see the class description.
+     * @private
+     * @param {KeyboardEvent} event Key event.
+     * @returns {void}
+     */
+    private _cardRovingKeydown;
+    /** @private @param {HTMLElement[]} items @returns {unknown[]} Record ids of the card items. */
+    private _cardIdsOf;
     /** @private @returns {HTMLElement} */
     private _createCardSkeletons;
     /** @private @returns {HTMLElement} */
@@ -299,6 +488,53 @@ export declare class CardView extends RecordView {
     /** @private @returns {Readonly<CardViewOptions & RecordViewOptions>} */
     private _cardOptions;
 }
+/**
+ * Sorts item rectangles into visual rows: items whose tops are within `tolerance` pixels share a
+ * row, rows run top to bottom, and items within a row left to right.
+ * @param {Array<{top:number,left:number}>} rects Item rectangles in display order.
+ * @param {number} [tolerance=4] Pixels two tops may differ by and still share a row.
+ * @returns {number[][]} Item indexes per row.
+ */
+export declare function cardGridRows(rects: Array<{
+    top: number;
+    left: number;
+}>, tolerance?: number): number[][];
+/**
+ * How many columns the cards are laid out in: the length of the longest visual row.
+ * @param {Array<{top:number,left:number}>} rects Item rectangles.
+ * @returns {number} At least 1 for a non-empty list, 0 for an empty one.
+ */
+export declare function cardColumnCount(rects: Array<{
+    top: number;
+    left: number;
+}>): number;
+/**
+ * Where a navigation key moves in a laid-out card grid. ArrowUp/ArrowDown go to the previous or
+ * next visual row and PageUp/PageDown `page` rows, landing on the item nearest to `x` (the column
+ * the reader is travelling in); ArrowLeft/ArrowRight move within the row and stop at its ends;
+ * Home/End go to the first or last item.
+ * @param {Array<{top:number,left:number}>} rects Item rectangles in display order.
+ * @param {number} index Current item.
+ * @param {string} key `KeyboardEvent.key`.
+ * @param {{page?:number, x?:number}} [options={}] Rows per page (default 10) and preferred x.
+ * @returns {number|null} Next item index, or null when the key is not a move.
+ */
+export declare function cardGridTarget(rects: Array<{
+    top: number;
+    left: number;
+}>, index: number, key: string, options?: {
+    page?: number;
+    x?: number;
+}): number | null;
+/**
+ * How many rows a PageUp or PageDown moves: the rows that fit in the visible height, less one so
+ * the row focus leaves stays in view. Falls back when either height is unknown.
+ * @param {number} viewport Visible height of the scroll region.
+ * @param {number} rowHeight Height of one row of cards.
+ * @param {number} [fallback=10] Rows to move when the heights are unusable.
+ * @returns {number} At least 1.
+ */
+export declare function cardPageSize(viewport: number, rowHeight: number, fallback?: number): number;
 /**
  * Groups a cloned record list without mutating records or caller arrays. Explicit order entries
  * are always materialized, including empty groups; remaining values keep first-seen order.

package/dist/zx.css

@@ -2881,6 +2881,7 @@ button.zx-panel__toggle:focus-visible {
 }
 .zx-search__clear,
 .zx-search__submit {
+  flex: none;
   display: inline-grid;
   place-items: center;
   min-block-size: 0;
@@ -10472,6 +10473,61 @@ button.zx-stat-tile:focus-visible {
   font-weight: 600;
   line-height: 1.3;
 }
+.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);
+}
+.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;
+}
+.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, minmax(min(100%, max(var(--zx-card-view-min-card-width), calc(var(--zx-card-view-column-basis) - var(--zx-card-view-grid-gap)))), 1fr));