@aceshooting/lyra-ui 6.1.0 → 7.0.0

package/dist/components/data/table/table.class.js

@@ -10,15 +10,15 @@ import { repeat } from 'lit/directives/repeat.js';
 import { styleMap } from 'lit/directives/style-map.js';
 import { LyraElement } from '../../../internal/lyra-element.js';
 import { isRtl } from '../../../internal/rtl.js';
-import { srOnly } from '../../../internal/a11y.js';
+import { srOnly, nextId } from '../../../internal/a11y.js';
 import { finiteCount, finiteInteger } from '../../../internal/numbers.js';
+import { getCollator } from '../../../internal/intl-cache.js';
+import { readPersistedState, writePersistedState } from '../../../internal/persisted-state.js';
 import { styles } from './table.styles.js';
 import { chevronIcon } from '../../../internal/icons.js';
 import { minMax } from '../heatmap/heatmap-scale.js';
 import '../../overlays/empty/empty.class.js';
-import '../pagination/pagination.js';
-import '../../overlays/spinner/spinner.js';
-import '../../overlays/skeleton/skeleton.js';
+import { trueDefaultSpellcheckConverter as spellcheckConverter } from '../../../internal/converters.js';
 /** Placeholder body rows rendered by `loadingAppearance="skeleton"` when neither `skeletonRows`
  *  nor `pageSize` supplies a count -- enough to read as "rows are coming" without pretending to
  *  know how many. */
@@ -28,24 +28,6 @@ const DEFAULT_SKELETON_ROWS = 3;
  *  thousands of nodes for a state that exists for a few hundred milliseconds. An explicit
  *  `skeletonRows` is honored verbatim and is not capped. */
 const MAX_DERIVED_SKELETON_ROWS = 20;
-/**
- * String-aware boolean attribute converter for `spellcheck`. Lit's built-in `type: Boolean`
- * converter is presence-based -- the attribute's mere presence (regardless of its string value)
- * maps to `true`, so a plain-markup consumer writing the literal `spellcheck="false"` would
- * actually get `true` (this property's default), the opposite of what that string reads as -- the
- * same bug class `<lr-textarea>`'s `spellcheckConverter` and `<lr-model-select>`'s identical
- * converter document and fix.
- */
-const spellcheckConverter = {
-    fromAttribute(value) {
-        return value !== 'false';
-    },
-    toAttribute(value) {
-        // `true` is this property's default, so there's nothing worth reflecting for it; only the
-        // non-default `false` needs an attribute at all.
-        return value ? null : 'false';
-    },
-};
 /**
  * Tri-state boolean converter for `empty-compact`. An absent attribute stays `undefined` -- "keep
  * each empty branch's own built-in default" -- rather than collapsing to `false`, which Lit's
@@ -64,6 +46,22 @@ const optionalBooleanConverter = {
         return value ? '' : 'false';
     },
 };
+/**
+ * Development-only diagnostics need to disappear from production bundles and unbundled browser
+ * use. Prefer an explicit NODE_ENV when a bundler exposes one, then Vite's import-meta contract;
+ * an unknown environment fails quiet instead of logging to end users.
+ */
+function isDevelopmentRuntime() {
+    const nodeEnv = globalThis.process?.env?.NODE_ENV;
+    if (nodeEnv === 'production')
+        return false;
+    if (nodeEnv === 'development')
+        return true;
+    const viteEnv = import.meta.env;
+    if (typeof viteEnv?.DEV === 'boolean')
+        return viteEnv.DEV;
+    return viteEnv?.MODE === 'development';
+}
 /** Interactive elements a nested `cell()` template may render (e.g. an
  *  actions-column button). Clicks/keydowns landing on one of these — or
  *  bubbling up through one — must not be re-interpreted as row/column
@@ -141,7 +139,15 @@ function closestInteractive(target, boundary) {
     return null;
 }
 /**
- * `<lr-table>` — a presentational, sort/select-aware data table.
+ * `<lr-table>` — a sort/select-aware data table.
+ *
+ * Sorting is the one area the table owns outright: under the default
+ * `sortMode: 'client'` a sortable-header activation writes `sortKey`/`sortDir`
+ * itself and reorders the rendered rows (see `sortMode`, `defaultSortDir` and
+ * `columns[].sortValue`). Everything else here stays presentational —
+ * selection state beyond `selectionMode` and expansion state are read, never
+ * written. Set `sortMode="server"` to keep `lr-sort` a pure notification and
+ * drive `sortKey`/`sortDir` plus the row order entirely from your own state.
  *
  * Header/row activation is delegated: one `click` and one `keydown`
  * listener on `<table>` resolve the target via `closest('[data-col-key]'
@@ -188,8 +194,10 @@ function closestInteractive(target, boundary) {
  * alignment. Which rows are currently open is fully consumer-owned via
  * `expandedKeys` (a `Set<string | number>` of row keys, per `rowKey`/
  * `keyOf()`) — the table only reads it and emits `lr-row-expand-toggle`
- * on activation, mirroring `sortKey`/`selectedKey`'s existing
- * presentational-only convention.
+ * on activation, mirroring `selectedKey`'s existing presentational-only
+ * convention. (`sortKey`/`sortDir` are *not* a parallel case any more: under
+ * the default `sortMode: 'client'` the table writes them on header
+ * activation.)
  *
  * Selection is opt-in through the `selectionMode` property. Use `single` or
  * `multiple` to self-manage row selection; the default `none` remains
@@ -226,7 +234,9 @@ function closestInteractive(target, boundary) {
  * `spellcheck`/`autocapitalize`/`autoCorrect` forward to the filter input and, for a `'text'`
  * (the default) `editType`, the inline cell editor -- no effect on a `'number'` cell editor.
  * `groupBy` inserts non-focusable group header rows before each group; use
- * `groupLabel` when the raw group key needs custom content.
+ * `groupLabel` when the raw group key needs custom content. A client-mode
+ * sort applies *within* each group, so grouping survives sorting on a column
+ * unrelated to the group key.
  *
  * `columns[].heatValue` opts a column into heat-tint mode: its numeric return value is normalized
  * against a shared scale spanning every `heatValue`-defining column across every currently-rendered
@@ -251,7 +261,12 @@ function closestInteractive(target, boundary) {
  * or a drag-resize is in flight (column resizing does not work under `table-layout: auto`).
  *
  * @customElement lr-table
- * @event lr-sort - A sortable header was activated. `detail: { key }`.
+ * @event lr-sort - A sortable header was activated. `detail: { key }`. The
+ *   activation additionally updates `sortKey`/`sortDir` on the table itself
+ *   (switching column seeds `defaultSortDir`, re-activating the current one
+ *   toggles), and under the default `sortMode: 'client'` reorders the
+ *   rendered rows. Use `sortMode="server"` for notification-only behavior
+ *   with the row order left exactly as supplied.
  * @event lr-row-click - A row was activated. `detail: { row }`.
  * @event lr-load-more - The "load more" control was activated.
  * @event lr-columns-hidden-change - `columnsHidden` actually changed value
@@ -276,6 +291,7 @@ function closestInteractive(target, boundary) {
  *   the same reason as `focus`.
  * @csspart base - The root wrapper around the `<table>` and its footer controls.
  * @csspart table - The `<table role="grid">` element.
+ * @csspart caption - The `<caption>` element, rendered only when `caption` is set.
  * @csspart head - The `<thead>` element.
  * @csspart header-cell - Each `<th>` header cell.
  * @csspart resize-handle - The focusable separator used to resize a `resizable` column.
@@ -344,6 +360,15 @@ function closestInteractive(target, boundary) {
  *   `aria-selected` is `true`. Shadow Parts forbids an attribute selector after `::part()`, so
  *   `::part(row)[aria-selected]` is invalid CSS and the selected row could otherwise only be
  *   restyled by hijacking the library-wide `--lr-color-brand-quiet` token.
+ * @cssprop [--lr-table-row-stripe-bg=transparent] - Background of alternating body rows. The
+ *   token is read only on rows carrying the internal stripe marker, so it can be set on the table
+ *   or an ancestor without affecting group, expanded, hover, or selected rows.
+ * @cssprop [--lr-table-header-sorted-bg=transparent] - Background of the currently-sorted column's
+ *   header cell (`[aria-sort]` other than `none`). Same rationale as `--lr-table-row-selected-bg`:
+ *   `::part(header-cell)[aria-sort]` is invalid CSS, so this token is the supported way to recolor
+ *   the sorted header without hijacking a library-wide token.
+ * @cssprop [--lr-table-header-sorted-color=inherit] - Text color of the currently-sorted column's
+ *   header cell.
  * @cssprop [--lr-table-sticky-offset=0] - Distance a `sticky` column pins from the inline edge.
  *   Measured and set inline per column by the component so multiple sticky columns stack instead
  *   of overlapping; falls back to `0` for the first one, or before the first measurement pass.
@@ -368,6 +393,31 @@ export class LyraTable extends LyraElement {
         this.layout = 'auto';
         this.sortKey = '';
         this.sortDir = 'asc';
+        /** `'client'` (the default) orders `rows` itself, in the browser, from `sortKey`/`sortDir` and
+         *  the active column's `sortValue`. `'server'` renders `rows` in exactly the order given,
+         *  assuming the caller has already sorted them — mirroring `paginationMode`'s identical
+         *  client/server split. `lr-sort` is emitted on header activation either way.
+         *
+         *  With no `sortKey` set (the default) `'client'` is a no-op: the input order is preserved
+         *  verbatim, so an existing consumer that only listens for `lr-sort` sees unchanged rendering
+         *  until a header is actually activated. */
+        this.sortMode = 'client';
+        /** The direction applied whenever header activation switches sorting to a *different* column —
+         *  including the first column ever sorted. Re-activating the column that is already `sortKey`
+         *  toggles between `'asc'` and `'desc'` instead, so this never overrides a direction the user
+         *  just chose for the column they are still on. Defaults to `'asc'`; set `'desc'` for a
+         *  most-recent-first or highest-first table. */
+        this.defaultSortDir = 'asc';
+        /** Accessible name for the `role="grid"` — a typed alternative to setting `aria-label` on the
+         *  host. When set it becomes the grid's `aria-label`; a host `aria-label` is used as a fallback
+         *  when this is unset. Consumer-supplied text, so it is NOT run through `this.localize()`. */
+        this.accessibleLabel = '';
+        /** Optional visible caption rendered as the table's `<caption>`. Also names the grid (via
+         *  `aria-labelledby`) when no `accessibleLabel`/host `aria-label` is set. Consumer-supplied
+         *  text, not localized. */
+        this.caption = '';
+        /** Stable id for the `<caption>`, so `aria-labelledby` can point at it. */
+        this.captionId = nextId('lr-table-caption');
         this.selectedKey = null;
         this.selectionMode = 'none';
         this.selectedKeys = new Set();
@@ -417,8 +467,10 @@ export class LyraTable extends LyraElement {
         /** Consumer-owned open/closed state, keyed the same way as `rowKey`/
          *  `selectedKey`. The table never mutates this itself — it only reads it
          *  to decide which rows currently render `expandedContent`; toggle it in
-         *  response to `lr-row-expand-toggle`, mirroring how `sortKey`/
-         *  `selectedKey` already work. */
+         *  response to `lr-row-expand-toggle`, mirroring how `selectedKey` already
+         *  works. Note that `sortKey`/`sortDir` are no longer analogous: under the
+         *  default `sortMode: 'client'` the table owns them and writes them on
+         *  header activation. */
         this.expandedKeys = new Set();
         this.hasMore = false;
         this.moreLabel = '';
@@ -447,6 +499,11 @@ export class LyraTable extends LyraElement {
          *  the `lr-columns-revealed` event, fired whenever the button toggles it
          *  — to persist the current one. */
         this.showAllColumns = false;
+        /** Skips the very first `updated()` pass so mounting never writes to storage -- `willUpdate()`
+         *  restored `showAllColumns` on that first pass, and Lit has already flipped `hasUpdated` to true
+         *  by the time `updated()` runs, so a dedicated flag is needed. Mirrors `lr-app-rail`'s
+         *  `persistReady`. */
+        this.persistReady = false;
         /** Roving-tabindex position among header cells; `null` until a header is
          *  clicked/navigated to, at which point `focusedColKey()` falls back to
          *  the first column. */
@@ -572,13 +629,28 @@ export class LyraTable extends LyraElement {
          *  next update, `setLyraLocale()`'s keyless `requestUpdate()`) still recomputes. */
         this.cachedMatchingEntries = null;
         this.matchingEntriesInputs = null;
+        /** Memoized on the same principle as `matchingEntries()` above, and re-validated against the
+         *  exact inputs the sort reads. `renderedEntries()` is read several times per update pass (the
+         *  `rowsByKey` rebuild, `focusedRowKey()`, and `render()` itself), and a miss costs one
+         *  consumer-supplied `sortValue()`/`cell()` call per row on top of the comparison pass — sorting
+         *  once per reader would multiply that callback work by the number of readers for no benefit.
+         *  `columns` is compared by identity because the ordering reads `sortValue`/`cell` off the
+         *  active column object; `locale` because it selects the collator. */
+        this.cachedSortedEntries = null;
+        this.sortedEntriesInputs = null;
         this.onFilterInput = (event) => {
             const input = event.currentTarget;
             this.filterText = input.value;
             this.emit('lr-filter-change', { text: this.filterText });
         };
-        this.onNativeFocus = () => { this.emit('focus'); };
-        this.onNativeBlur = () => { this.emit('blur'); };
+        this.onNativeFocus = (event) => {
+            event.stopPropagation();
+            this.emit('focus');
+        };
+        this.onNativeBlur = (event) => {
+            event.stopPropagation();
+            this.emit('blur');
+        };
         this.onPaginationChange = (event) => {
             event.stopPropagation();
             this.emit('lr-page-change', event.detail);
@@ -675,6 +747,9 @@ export class LyraTable extends LyraElement {
         };
     }
     static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    get storageFullKey() {
+        return this.storageKey ? `lr-table:${this.storageKey}` : undefined;
+    }
     parsePixelLength(value) {
         if (!value)
             return undefined;
@@ -762,6 +837,18 @@ export class LyraTable extends LyraElement {
                 handle.setAttribute('aria-valuenow', String(Math.round(rendered)));
         }
     }
+    firstUpdated(changed) {
+        super.firstUpdated(changed);
+        // A grid with no accessible name is a real a11y defect but silently renders. Warn once per
+        // element (dev signal; the guard keeps it out of hot render paths and prevents log spam).
+        if (isDevelopmentRuntime() &&
+            !this.accessibleLabel &&
+            !this.getAttribute('aria-label') &&
+            !this.caption) {
+            console.warn('<lr-table> has no accessible name: set `accessibleLabel`, a host `aria-label`, or ' +
+                '`caption` so assistive technology can identify the grid.');
+        }
+    }
     connectedCallback() {
         super.connectedCallback();
         this.resizeObserver = new ResizeObserver(this.scheduleLayoutSync);
@@ -920,8 +1007,124 @@ export class LyraTable extends LyraElement {
             return 1;
         return finiteInteger(this.page, 1, 1, this.pageCount);
     }
-    renderedEntries() {
+    /** `matchingEntries()` reordered by the active sort column. A no-op — the filtered array is
+     *  returned by identity, never copied — under `sortMode: 'server'`, with no `sortKey`, or when
+     *  `sortKey` names a column that is missing or not `sortable`, which is what keeps a table that
+     *  never sets `sortKey` rendering its input order verbatim.
+     *
+     *  When `groupBy` is set the sort is applied *within* each group rather than across the whole
+     *  set. `render()` emits a group header wherever the group key changes between consecutive
+     *  rendered rows, so a flat global sort on a column uncorrelated with the group key would
+     *  interleave the groups and emit a header before nearly every row — the grouping would be
+     *  visually destroyed by sorting. Groups keep their first-appearance order in `rows` (a `Map`
+     *  iterates in insertion order); the group key is deliberately *not* collated, because the
+     *  consumer controls group order through the order it supplies `rows` in, exactly as it does
+     *  when no sort is active.
+     *
+     *  The one exception: when the active column's value is constant inside *every* group, the
+     *  within-group sort is provably inert, so the *groups* are ordered by that constant value
+     *  instead. Without it, sorting on the group column would flip `aria-sort` and the chevron while
+     *  changing nothing — announcing an ordering the table never applied. */
+    sortedEntries() {
         const entries = this.matchingEntries();
+        if (this.sortMode !== 'client' || this.sortKey === '')
+            return entries;
+        const col = this.columnsByKey.get(this.sortKey);
+        if (!col?.sortable)
+            return entries;
+        const locale = this.effectiveLocale;
+        const inputs = this.sortedEntriesInputs;
+        if (this.cachedSortedEntries !== null &&
+            inputs !== null &&
+            inputs.entries === entries &&
+            inputs.columns === this.columns &&
+            inputs.mode === this.sortMode &&
+            inputs.key === this.sortKey &&
+            inputs.dir === this.sortDir &&
+            inputs.locale === locale &&
+            inputs.groupBy === this.groupBy) {
+            return this.cachedSortedEntries;
+        }
+        const collator = getCollator(locale, { numeric: true });
+        const dir = this.sortDir === 'desc' ? -1 : 1;
+        // Decorate/sort/undecorate: `sortValue()`/`cell()` runs once per row rather than once per
+        // comparison, so a costly consumer accessor stays O(n) instead of O(n log n). A non-finite
+        // number is folded into the same "missing" bucket as null/undefined -- NaN would otherwise
+        // make the comparator self-inconsistent (every comparison against it returns 0) and leave the
+        // order engine-defined rather than merely surprising.
+        const decorated = entries.map((entry) => {
+            const raw = col.sortValue ? col.sortValue(entry.row) : String(col.cell(entry.row) ?? '');
+            return { entry, value: typeof raw === 'number' && !Number.isFinite(raw) ? null : raw };
+        });
+        // Array.prototype.sort is stable, so rows comparing equal keep their `rows` order.
+        const compare = (a, b) => {
+            const av = a.value;
+            const bv = b.value;
+            // Missing values sort last in BOTH directions -- multiplying by `dir` here would float a
+            // block of blanks to the top the moment the user flipped to descending.
+            if (av == null && bv == null)
+                return 0;
+            if (av == null)
+                return 1;
+            if (bv == null)
+                return -1;
+            if (typeof av === 'number' && typeof bv === 'number')
+                return (av - bv) * dir;
+            return collator.compare(String(av), String(bv)) * dir;
+        };
+        let sorted;
+        const groupBy = this.groupBy;
+        if (groupBy === undefined) {
+            decorated.sort(compare);
+            sorted = decorated.map((decoration) => decoration.entry);
+        }
+        else {
+            // Partition first, sort inside each partition. A `Map` keyed by the group key iterates in
+            // insertion order, so the groups come back in their first-appearance order in `rows` and
+            // stay contiguous -- see this method's doc comment.
+            const buckets = new Map();
+            for (const decoration of decorated) {
+                const groupKey = groupBy(decoration.entry.row);
+                const bucket = buckets.get(groupKey);
+                if (bucket === undefined)
+                    buckets.set(groupKey, [decoration]);
+                else
+                    bucket.push(decoration);
+            }
+            const ordered = [...buckets.values()];
+            // A column whose value never varies inside a group -- the group column itself being the
+            // obvious case, but also any column functionally determined by the group key, and the
+            // one-row-per-group case -- makes the within-group sort provably inert: every comparison
+            // ties, the sort is stable, and the rendered order is identical to the unsorted one. Sorting
+            // only the rows would then leave `render()` announcing `aria-sort="ascending"` and painting a
+            // chevron for an ordering the table never applied. Move the groups instead, keyed by that
+            // constant value, so the announced ordering genuinely holds. Every bucket is non-empty by
+            // construction, and `sort` is stable, so groups whose values tie keep first appearance.
+            const constantWithinEveryGroup = ordered.every((bucket) => bucket.every((decoration) => compare(decoration, bucket[0]) === 0));
+            if (constantWithinEveryGroup)
+                ordered.sort((a, b) => compare(a[0], b[0]));
+            sorted = [];
+            for (const bucket of ordered) {
+                if (!constantWithinEveryGroup)
+                    bucket.sort(compare);
+                for (const decoration of bucket)
+                    sorted.push(decoration.entry);
+            }
+        }
+        this.sortedEntriesInputs = {
+            entries,
+            columns: this.columns,
+            mode: this.sortMode,
+            key: this.sortKey,
+            dir: this.sortDir,
+            locale,
+            groupBy,
+        };
+        this.cachedSortedEntries = sorted;
+        return sorted;
+    }
+    renderedEntries() {
+        const entries = this.sortedEntries();
         if (this.normalizedPageSize === 0 || this.paginationMode === 'server')
             return entries;
         const start = (this.appliedPage - 1) * this.normalizedPageSize;
@@ -952,6 +1155,24 @@ export class LyraTable extends LyraElement {
     }
     willUpdate(changed) {
         super.willUpdate(changed);
+        // Restore a persisted `showAllColumns` preference once, before the first render, so the restored
+        // value folds into the first paint with no follow-up update -- doing this in firstUpdated()
+        // (after the first render) would schedule a second update and trip Lit's dev warning. Mirrors
+        // lr-app-rail's loadPersisted() call in its own willUpdate(). The `persistReady` gate in
+        // updated() keeps this restored value from being written straight back.
+        if (!this.hasUpdated) {
+            const parsed = readPersistedState(this.storageFullKey, (v) => typeof v === 'object' && v !== null);
+            if (parsed && typeof parsed.showAllColumns === 'boolean')
+                this.showAllColumns = parsed.showAllColumns;
+        }
+        // Ordered before the rowsByKey rebuild below, not after: client-mode sorting resolves the
+        // active column through `columnsByKey`, so rebuilding it second would have the very first
+        // update (where `columns` and `rows` land together) key rowsByKey off an *unsorted* order
+        // while render() -- reading the now-populated map -- paints the sorted one, silently
+        // resolving delegated row clicks to the wrong row.
+        if (changed.has('columns')) {
+            this.columnsByKey = new Map(this.columns.map((c) => [c.key, c]));
+        }
         if (changed.has('rows') ||
             changed.has('rowKey') ||
             changed.has('filterText') ||
@@ -959,15 +1180,21 @@ export class LyraTable extends LyraElement {
             changed.has('page') ||
             changed.has('pageSize') ||
             changed.has('paginationMode') ||
-            changed.has('totalItems')) {
+            changed.has('totalItems') ||
+            // Sorting reorders the entries and, under pagination, changes which of them the current
+            // page even contains -- so the key->entry map has to be rebuilt alongside it.
+            changed.has('columns') ||
+            changed.has('sortKey') ||
+            changed.has('sortDir') ||
+            changed.has('sortMode') ||
+            // A client sort is applied within each group, so swapping `groupBy` re-orders the entries
+            // (and, under pagination, changes which of them the current page holds) too.
+            changed.has('groupBy')) {
             this.rowsByKey = new Map(this.renderedEntries().map((entry) => [
                 encodeKey(this.keyOf(entry.row, entry.index)),
                 entry,
             ]));
         }
-        if (changed.has('columns')) {
-            this.columnsByKey = new Map(this.columns.map((c) => [c.key, c]));
-        }
         // Read *before* render() gets to move the node out from under the focus it currently holds --
         // by the time updated() runs, "the editor was focused a moment ago" and "the user clicked away
         // a while ago" are indistinguishable from the DOM alone.
@@ -1084,6 +1311,13 @@ export class LyraTable extends LyraElement {
      *  reflects the rendered columns. */
     updated(changed) {
         super.updated(changed);
+        // Persist `showAllColumns` whenever it changes, but never on the initial update -- willUpdate()
+        // restored it on that pass, so writing it back would be redundant, and with no `storage-key` set
+        // `writePersistedState(undefined, ...)` is a silent no-op regardless.
+        if (this.persistReady && changed.has('showAllColumns')) {
+            writePersistedState(this.storageFullKey, { showAllColumns: this.showAllColumns });
+        }
+        this.persistReady = true;
         if (changed.has('columns') || changed.has('rows') || changed.has('rowKey'))
             this.applyStickyOffsets();
         this.syncResizeHandleValues();
@@ -1114,11 +1348,24 @@ export class LyraTable extends LyraElement {
         // triggered one instead.
         queueMicrotask(() => this.recomputeColumnsHidden());
     }
+    /** Header activation (click, Enter, Space). Owns `sortKey`/`sortDir` end-to-end now that
+     *  `sortMode: 'client'` makes the table responsible for the order it renders: switching to a
+     *  different column seeds the direction from `defaultSortDir`, re-activating the current one
+     *  toggles it. `lr-sort` still fires exactly as before, so a `sortMode: 'server'` consumer that
+     *  re-sorts on the event and pushes fresh `rows` back in keeps working unchanged. */
     activateColumn(key) {
         this.activeColKey = key;
         const col = this.columnsByKey.get(key);
-        if (col?.sortable)
-            this.emit('lr-sort', { key: col.key });
+        if (!col?.sortable)
+            return;
+        if (this.sortKey === key) {
+            this.sortDir = this.sortDir === 'asc' ? 'desc' : 'asc';
+        }
+        else {
+            this.sortKey = key;
+            this.sortDir = this.defaultSortDir;
+        }
+        this.emit('lr-sort', { key: col.key });
     }
     activateRow(key) {
         this.activeRowKey = key;
@@ -1420,7 +1667,11 @@ export class LyraTable extends LyraElement {
         </div>
       </div>`;
         }
-        const matchingEntries = this.matchingEntries();
+        // Sorted, not merely filtered: `footer`/`grandTotal` are documented as seeing every rendered
+        // row "post-sort, pre-pagination", and an aggregate that reads position (a first/last value, a
+        // running comparison) would otherwise disagree with the order actually painted below. Free
+        // when no sort is active -- `sortedEntries()` returns the filtered array by identity.
+        const matchingEntries = this.sortedEntries();
         // A cold load is exactly the case where `rows` is still empty, so skeleton mode must not take
         // either empty-state branch -- "no data" is a *result*, and the load has not produced one yet.
         if (!skeletonLoading && this.rows.length === 0 && !this.filterable && this.normalizedPageSize === 0) {
@@ -1454,6 +1705,22 @@ export class LyraTable extends LyraElement {
         // column (the same way hasExpand/hasRowTotal were each added) only has to be added here once.
         const spanningColspan = this.columns.length + (hasExpand ? 1 : 0) + (hasRowTotal ? 1 : 0);
         const renderedEntries = this.renderedEntries();
+        const renderedGroupKeys = this.groupBy
+            ? renderedEntries.map((entry) => this.groupBy(entry.row))
+            : [];
+        const renderedGroupRows = new Map();
+        if (this.groupLabel) {
+            renderedEntries.forEach((entry, index) => {
+                const groupKey = renderedGroupKeys[index];
+                if (groupKey === undefined)
+                    return;
+                const rows = renderedGroupRows.get(groupKey);
+                if (rows)
+                    rows.push(entry.row);
+                else
+                    renderedGroupRows.set(groupKey, [entry.row]);
+            });
+        }
         const hasPagination = this.normalizedPageSize > 0;
         const filterLabel = this.localize('tableFilterLabel', this.filterLabel || undefined);
         const filterPlaceholder = this.localize('tableFilterPlaceholder', this.filterPlaceholder || undefined);
@@ -1470,7 +1737,10 @@ export class LyraTable extends LyraElement {
             : html `<table
             part="table"
             role="grid"
-            aria-label=${this.getAttribute('aria-label') || nothing}
+            aria-label=${this.accessibleLabel || this.getAttribute('aria-label') || nothing}
+            aria-labelledby=${!this.accessibleLabel && !this.getAttribute('aria-label') && this.caption
+                ? this.captionId
+                : nothing}
             aria-multiselectable=${this.selectionMode === 'multiple' ? 'true' : nothing}
             ?data-has-column-widths=${hasColumnWidths}
             data-layout=${effectiveLayout}
@@ -1479,6 +1749,7 @@ export class LyraTable extends LyraElement {
             @dblclick=${this.onTableDoubleClick}
             @focusin=${this.onTableFocusIn}
           >
+            ${this.caption ? html `<caption part="caption" id=${this.captionId}>${this.caption}</caption>` : nothing}
             <colgroup>
               ${hasExpand ? html `<col style=${styleMap({ 'inline-size': 'var(--lr-icon-button-size)' })} />` : nothing}
               ${this.columns.map((col) => html `<col style=${styleMap({
@@ -1530,8 +1801,8 @@ export class LyraTable extends LyraElement {
                     const selected = (this.selectedKey !== null && this.selectedKey === key) || this.selectedKeys.has(key);
                     const canExpandRow = hasExpand && (this.canExpand ? this.canExpand(row) : true);
                     const rowExpanded = canExpandRow && this.expandedKeys.has(key);
-                    const groupKey = this.groupBy?.(row);
-                    const previousGroupKey = entryIndex > 0 ? this.groupBy?.(renderedEntries[entryIndex - 1].row) : undefined;
+                    const groupKey = renderedGroupKeys[entryIndex];
+                    const previousGroupKey = entryIndex > 0 ? renderedGroupKeys[entryIndex - 1] : undefined;
                     const isNewGroup = this.groupBy !== undefined && (entryIndex === 0 || groupKey !== previousGroupKey);
                     return [
                         isNewGroup
@@ -1542,9 +1813,7 @@ export class LyraTable extends LyraElement {
                             colspan=${spanningColspan}
                           >
                             ${this.groupLabel
-                                ? this.groupLabel(groupKey, renderedEntries
-                                    .filter((candidate) => this.groupBy?.(candidate.row) === groupKey)
-                                    .map((candidate) => candidate.row))
+                                ? this.groupLabel(groupKey, renderedGroupRows.get(groupKey) ?? [])
                                 : String(groupKey)}
                           </td>
                         </tr>`
@@ -1553,7 +1822,8 @@ export class LyraTable extends LyraElement {
                       part="row"
                       role="row"
                       data-row-key=${encodeKey(key)}
-                      aria-selected=${selected ? 'true' : 'false'}
+                      ?data-stripe=${entryIndex % 2 === 0}
+                      aria-selected=${this.selectionMode === 'none' ? nothing : selected ? 'true' : 'false'}
                       tabindex=${encodeKey(key) === focusedRow ? '0' : '-1'}
                     >
                       ${hasExpand
@@ -1712,6 +1982,18 @@ __decorate([
 __decorate([
     property({ attribute: 'sort-dir' })
 ], LyraTable.prototype, "sortDir", void 0);
+__decorate([
+    property({ reflect: true, attribute: 'sort-mode' })
+], LyraTable.prototype, "sortMode", void 0);
+__decorate([
+    property({ attribute: 'default-sort-dir' })
+], LyraTable.prototype, "defaultSortDir", void 0);
+__decorate([
+    property({ attribute: 'accessible-label' })
+], LyraTable.prototype, "accessibleLabel", void 0);
+__decorate([
+    property()
+], LyraTable.prototype, "caption", void 0);
 __decorate([
     property({ attribute: false })
 ], LyraTable.prototype, "rowKey", void 0);
@@ -1829,6 +2111,9 @@ __decorate([
 __decorate([
     property({ type: Boolean, attribute: 'show-all-columns', reflect: true })
 ], LyraTable.prototype, "showAllColumns", void 0);
+__decorate([
+    property({ attribute: 'storage-key' })
+], LyraTable.prototype, "storageKey", void 0);
 __decorate([
     state()
 ], LyraTable.prototype, "activeColKey", void 0);