@aceshooting/lyra-ui 5.0.0 → 5.2.0

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

@@ -10,6 +10,7 @@ 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 { finiteCount, finiteInteger } from '../../../internal/numbers.js';
 import { styles } from './table.styles.js';
 import { chevronIcon } from '../../../internal/icons.js';
@@ -17,6 +18,16 @@ 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';
+/** 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. */
+const DEFAULT_SKELETON_ROWS = 3;
+/** Ceiling on the `pageSize`-derived placeholder row count. A page size is a *data* bound (it can
+ *  legitimately be 500), and one placeholder element per cell means a large one would emit
+ *  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)
@@ -35,6 +46,24 @@ const spellcheckConverter = {
         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
+ * presence-based `type: Boolean` converter cannot express. Same shape as `spellcheckConverter`
+ * above, one state wider; `empty-compact="false"` is parsed as `false`, not `true`.
+ */
+const optionalBooleanConverter = {
+    fromAttribute(value) {
+        if (value === null)
+            return undefined;
+        return value !== 'false';
+    },
+    toAttribute(value) {
+        if (value === undefined)
+            return null;
+        return value ? '' : 'false';
+    },
+};
 /** 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
@@ -50,6 +79,19 @@ function stickyDirection(sticky) {
         return sticky;
     return undefined;
 }
+/** Normalizes TableColumn.editable's legacy boolean form (`true` == open an
+ *  editor on double-click) alongside the `'always'` union member (a persistent
+ *  editor in every body cell of that column) -- `false`/`undefined` both
+ *  resolve to "not editable". Sibling of `stickyDirection()` above, and the
+ *  single place the widened union is interpreted, so no call site has to
+ *  re-derive which of the two triggers a column is asking for. */
+function editTrigger(editable) {
+    if (editable === 'always')
+        return 'always';
+    if (editable === true)
+        return 'double-click';
+    return undefined;
+}
 /** Encodes a row/column identity key for use as a Map key or a DOM
  *  `data-row-key` attribute value, preserving the distinction between a
  *  numeric key and a string key that happen to stringify the same way
@@ -160,10 +202,27 @@ function closestInteractive(target, boundary) {
  * `pageSize` enables controlled pagination through the existing
  * `<lr-pagination>` primitive. Client mode slices `rows`; server mode
  * renders the supplied page unchanged while using `totalItems` for the
- * navigation summary. `loading` keeps the table shell busy and renders an
- * indeterminate spinner.
+ * navigation summary. `loading` keeps the table shell busy; `loadingAppearance`
+ * chooses how — the default `'spinner'` replaces the grid with an indeterminate
+ * spinner, while `'skeleton'` keeps the real `<colgroup>`/`<thead>` (and the
+ * filter/pagination chrome) and fills the body with `skeletonRows` placeholder
+ * rows, so column geometry survives the load instead of collapsing and
+ * reflowing. Either way exactly one `role="status"` live region announces the
+ * state — every placeholder opts out of `<lr-skeleton>`'s own announcement.
  * Columns with `editable: true` open a native text/number editor on
  * double-click and emit `lr-cell-edit`; row mutation remains consumer-owned.
+ * `editable: 'always'` instead renders that editor in every body cell of the
+ * column from first paint — a settings/rate-style column meant to be typed
+ * straight into. Persistent editors are plain tab stops (no `tabindex` of their
+ * own, exactly like the row-expand toggle) outside the header/row roving model,
+ * so arrow keys still navigate the grid from a row's own tab stop and act as
+ * caret movement once focus is inside a field. Enter commits and keeps focus;
+ * Escape has nothing to cancel back to, so it is left uncancelled for an
+ * ancestor dialog/popover. Their value binds as a content attribute, so once
+ * the user has typed into one an out-of-band `rows` update to that same cell no
+ * longer replaces the draft; an untouched editor still picks up a new value.
+ * Focus is restored across a re-sort that moves the editor's node, and dropped
+ * (never re-aimed at an unrelated row) when its row leaves the rendered page.
  * `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
@@ -178,6 +237,19 @@ function closestInteractive(target, boundary) {
  * the footer row (only when a column also defines `footer`) — both share `footer`'s own
  * "consumer computes/renders" contract rather than assuming addition.
  *
+ * The built-in empty state is addressable rather than fixed: every `<lr-empty>` the table renders
+ * carries `part="empty"` and re-exports its own inner parts as `empty-heading`/`empty-description`/
+ * `empty-icon`/`empty-actions`/`empty-base`, the two *data*-empty branches (no rows at all, and
+ * filtered/paginated down to zero) render it as the fallback content of a named `empty` slot so a
+ * consumer can replace it wholesale, and `emptyCompact` overrides each branch's built-in `compact`
+ * default. The no-columns branch is deliberately **not** slot-replaceable — it reports a
+ * configuration problem (`noColumnsHeading`), not "this query returned nothing", and a single slot
+ * covering all three would collapse that distinction.
+ *
+ * `layout` sets a floor on the `<table>`'s `table-layout`: `'fixed'` forces it even with no column
+ * widths, while the default `'auto'` still resolves to `fixed` whenever a column declares a `width`
+ * 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-row-click - A row was activated. `detail: { row }`.
@@ -215,7 +287,9 @@ function closestInteractive(target, boundary) {
  * @csspart foot - The `<tfoot>`, only rendered when at least one column defines `footer`.
  * @csspart footer-row - The single footer row.
  * @csspart footer-cell - A single footer cell.
- * @csspart cell-editor - The native inline cell editor, shown after a double-click on an editable cell.
+ * @csspart cell-editor - The native inline cell editor: shown after a double-click on an
+ *   `editable: true` cell, and rendered persistently in every body cell of an `editable: 'always'`
+ *   column.
  * @csspart more-button - The "load more" control, shown when `hasMore` is true.
  * @csspart sort-icon - The chevron shown in the active sortable column's header cell.
  * @csspart reveal-columns-button - The button that toggles `priority`-hidden columns back into view.
@@ -232,17 +306,66 @@ function closestInteractive(target, boundary) {
  * @csspart group-cell - The full-width group header cell.
  * @csspart filter - The optional row-filter input.
  * @csspart filter-label - The `<label>` wrapping the filter input.
- * @csspart loading - The loading-state wrapper.
+ * @csspart loading - The loading-state wrapper. Under `loadingAppearance="spinner"` (the default)
+ *   it is the visible block holding the spinner; under `"skeleton"` it is the visually-hidden
+ *   `role="status"` node, since the placeholder rows are the visible affordance.
+ * @csspart skeleton - Each `<lr-skeleton>` placeholder inside a `loadingAppearance="skeleton"`
+ *   body cell. Its rows and cells reuse the ordinary `row`/`cell`/`row-total-cell` parts (that
+ *   is what keeps them geometrically identical to real rows), so this is the part to target for
+ *   the placeholder's own look — e.g. `::part(skeleton) { --lr-skeleton-h: 2em; }`.
  * @csspart pagination - The optional pagination component.
+ * @csspart empty - The built-in `<lr-empty>` host, in all three empty states (no columns
+ *   configured, no rows at all, and filtered/paginated down to zero rows). The two data-empty
+ *   states render it as the `empty` slot's fallback, so it disappears once that slot is filled.
+ *   Note that the no-columns and no-rows states return the empty element as the shadow root's own
+ *   root, with no `[part='base']` wrapper around it — `::part(base)` does not apply in those two
+ *   states, only in the filtered-to-zero one.
+ * @csspart empty-base - Exported from the built-in `<lr-empty>`'s own `base` part.
+ * @csspart empty-icon - Exported from the built-in `<lr-empty>`'s `icon` part.
+ * @csspart empty-heading - Exported from the built-in `<lr-empty>`'s `heading` part.
+ * @csspart empty-description - Exported from the built-in `<lr-empty>`'s `description` part.
+ * @csspart empty-actions - Exported from the built-in `<lr-empty>`'s `actions` part.
+ * @slot empty - Replaces the built-in empty state on the two *data*-empty branches (no rows at
+ *   all, and filtered/paginated down to zero). Left unfilled, the built-in `[part='empty']`
+ *   `<lr-empty>` renders as this slot's fallback content. The no-columns branch renders its own
+ *   `noColumnsHeading` state and is not slot-replaceable.
  * @cssprop [--lr-table-resize-min-width=var(--lr-size-3rem)] - Default minimum width for a
  *   resizable column without an explicit pixel `minWidth`.
  * @cssprop [--lr-table-resize-handle-opacity=0.12] - Hover/focus opacity of the resize handle.
+ * @cssprop [--lr-table-max-height=none] - Cap on the scroll container's block size, past which the
+ *   table body scrolls.
+ * @cssprop [--lr-table-heat-tint-lo=var(--lr-color-brand-quiet)] - Low endpoint of the heat-tint
+ *   ramp used by `heatValue` columns.
+ * @cssprop [--lr-table-heat-tint-hi=var(--lr-color-brand)] - High endpoint of the heat-tint ramp
+ *   used by `heatValue` columns.
+ * @cssprop [--lr-table-heat-t] - This cell's position on the heat-tint ramp, as a percentage
+ *   string. Set inline by the component on each `[data-heat]` cell; not consumer-settable.
+ * @cssprop [--lr-table-row-selected-bg=var(--lr-color-brand-quiet)] - Background of a row whose
+ *   `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-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.
  */
 export class LyraTable extends LyraElement {
     constructor() {
         super(...arguments);
         this.columns = [];
         this.rows = [];
+        /** Floor for the `<table>`'s `table-layout`. `'fixed'` forces the fixed algorithm even when no
+         *  column declares a `width`, so every column shares the available width evenly and long cell
+         *  content is clipped/wrapped instead of stretching its column. The default `'auto'` is only a
+         *  floor: it still resolves to `fixed` whenever a column declares a `width`, a column has been
+         *  drag-resized, or a resize gesture is in flight — resizing does not work under
+         *  `table-layout: auto`.
+         *
+         *  Two consequences of the fixed algorithm are worth knowing before opting in: with no declared
+         *  widths the *first* row (header row included) determines every column's width, so revealing a
+         *  `priority`-hidden column via `[part='reveal-columns-button']` re-measures and changes all of
+         *  them; and `columns[].minWidth`/`maxWidth` are silently ignored by `table-layout: fixed`
+         *  (declare `width` instead when you need a specific column sized). */
+        this.layout = 'auto';
         this.sortKey = '';
         this.sortDir = 'asc';
         this.selectedKey = null;
@@ -266,6 +389,24 @@ export class LyraTable extends LyraElement {
         this.autoCorrect = '';
         this.loading = false;
         this.loadingLabel = '';
+        /** How `loading` renders. `'spinner'` (the default, unchanged output) replaces the whole grid
+         *  with an indeterminate spinner. `'skeleton'` instead renders the real table — the same
+         *  `<colgroup>` (declared *and* drag-resized widths included), the same `<thead>`, the filter
+         *  field and the pagination footer — and fills `<tbody>` with placeholder rows, so a cold load
+         *  sketches the grid's shape rather than collapsing to a spinner and reflowing when the rows
+         *  land. Kept separate from `loading` rather than widening it to a string union, so
+         *  `?loading=${…}` bindings and `el.loading === true` checks keep working.
+         *
+         *  Column *widths* only stay pixel-identical across the load if the browser isn't sizing them
+         *  from cell content: declare `columns[].width`, or set `layout="fixed"`. Under the default
+         *  `table-layout: auto`, placeholder cells have no intrinsic width, so the columns re-measure
+         *  when real content arrives — exactly as they do between any two different data sets. */
+        this.loadingAppearance = 'spinner';
+        /** Number of placeholder rows rendered by `loadingAppearance="skeleton"`. `0` (the default)
+         *  derives the count instead: the normalized `pageSize` when pagination is on (capped at 20, so
+         *  a large page size can't emit thousands of placeholder cells), otherwise 3. Any positive value
+         *  is used verbatim and is not capped. Ignored entirely under the default spinner appearance. */
+        this.skeletonRows = 0;
         /** Set to a positive value to enable the controlled pagination footer. */
         this.pageSize = 0;
         /** Controlled current page used when `pageSize` is positive. */
@@ -315,6 +456,18 @@ export class LyraTable extends LyraElement {
          *  `selectedKey` (if it matches a row) or the first row. */
         this.activeRowKey = null;
         this.editingCell = null;
+        /** The persistent (`editable: 'always'`) editor cell that most recently took focus, recorded by
+         *  the delegated `focusin` handler. `repeat()` is keyed by row key, so a re-sort *moves* the
+         *  `<input>` node (its typed value rides along) rather than recreating it -- but a DOM move drops
+         *  focus, so `updated()` puts it back. Deliberately non-reactive: it tracks focus, and writing it
+         *  must never schedule a render. */
+        this.focusedEditorCell = null;
+        /** Whether `focusedEditorCell` still actually held focus when the in-flight update started.
+         *  Captured in `willUpdate()`, i.e. before `render()` has had the chance to move the node out
+         *  from under it. Without this, a record left behind by a user who has since clicked away
+         *  entirely (no `focusin` reaches this component to clear it) would let any later, unrelated
+         *  update yank focus back into the table. */
+        this.editorHadFocusBeforeUpdate = false;
         this.resizedColumnWidths = new Map();
         this.rowsByKey = new Map();
         this.columnsByKey = new Map();
@@ -388,6 +541,24 @@ export class LyraTable extends LyraElement {
             window.removeEventListener('pointerup', this.onResizePointerEnd);
             window.removeEventListener('pointercancel', this.onResizePointerEnd);
         };
+        /** Coalesces however many `resizeObserver` callback ticks land in one animation frame (an
+         *  animated/dragged ancestor resize can fire the observer once per frame) into a single
+         *  read+write pass, instead of re-running `recomputeColumnsHidden()` / `applyStickyOffsets()` /
+         *  `syncResizeHandleValues()` -- each its own DOM query plus per-element measurement -- on every
+         *  tick. A second tick that lands while a frame is already pending is a no-op; the id resets once
+         *  the scheduled frame runs, so the very next tick after that schedules a fresh one. */
+        this.scheduleLayoutSync = () => {
+            if (this.layoutRafId !== undefined)
+                return;
+            this.layoutRafId = requestAnimationFrame(() => {
+                this.layoutRafId = undefined;
+                if (!this.isConnected)
+                    return;
+                this.recomputeColumnsHidden();
+                this.applyStickyOffsets();
+                this.syncResizeHandleValues();
+            });
+        };
         /** Memoized across update cycles and re-validated against the exact inputs the computation
          *  reads — `rows` and `filter` by identity, the trimmed filter text, and (only when there is
          *  text to case-fold at all) the effective locale. This method is read (directly or
@@ -412,13 +583,41 @@ export class LyraTable extends LyraElement {
             event.stopPropagation();
             this.emit('lr-page-change', event.detail);
         };
+        /** Records which persistent editor holds focus, and drops the record as soon as focus lands on
+         *  anything else inside the grid. Only `'always'` columns are tracked: a double-click editor is
+         *  closed (and its node removed) by the very updates this would restore focus across. */
+        this.onTableFocusIn = (event) => {
+            const target = event.target;
+            const cell = target?.closest?.('td[data-col-key]');
+            const row = target?.closest?.('[data-row-key]');
+            const columnKey = cell?.dataset.colKey;
+            const rowKey = row?.dataset.rowKey;
+            this.focusedEditorCell =
+                target?.getAttribute('part') === 'cell-editor' &&
+                    columnKey !== undefined &&
+                    rowKey !== undefined &&
+                    editTrigger(this.columnsByKey.get(columnKey)?.editable) === 'always'
+                    ? { rowKey, columnKey }
+                    : null;
+        };
+        /** The editor owns its own keys. `stopPropagation()` is unconditional and stays that way: inside
+         *  a text field arrow keys are caret movement, not grid navigation.
+         *
+         *  Enter commits either flavor. For a double-click editor that also closes it (`commitEdit`
+         *  clears `editingCell`); a persistent editor has no closed state to fall back to, so it stays
+         *  open and keeps focus.
+         *
+         *  Escape cancels a double-click edit, which is a real action, so it is consumed. A persistent
+         *  editor has nothing to cancel back to -- `editingCell` was never set for it -- so Escape is
+         *  left uncancelled and an ancestor dialog/popover still closes on it. */
         this.onEditorKeyDown = (event, rowKey, columnKey) => {
             event.stopPropagation();
+            const alwaysOn = editTrigger(this.columnsByKey.get(columnKey)?.editable) === 'always';
             if (event.key === 'Enter') {
                 event.preventDefault();
                 this.commitEdit(event, rowKey, columnKey);
             }
-            else if (event.key === 'Escape') {
+            else if (event.key === 'Escape' && !alwaysOn) {
                 event.preventDefault();
                 this.editingCell = null;
             }
@@ -475,7 +674,7 @@ export class LyraTable extends LyraElement {
                 this.onRowKeyDown(e, tr);
         };
     }
-    static { this.styles = [LyraElement.styles, styles]; }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
     parsePixelLength(value) {
         if (!value)
             return undefined;
@@ -565,11 +764,7 @@ export class LyraTable extends LyraElement {
     }
     connectedCallback() {
         super.connectedCallback();
-        this.resizeObserver = new ResizeObserver(() => {
-            this.recomputeColumnsHidden();
-            this.applyStickyOffsets();
-            this.syncResizeHandleValues();
-        });
+        this.resizeObserver = new ResizeObserver(this.scheduleLayoutSync);
         // A reconnect re-creates the observer above but the shadow root content
         // survives across disconnect/reconnect (Lit doesn't tear down the shadow
         // root) — re-observe [part='base'] here if it already exists from before
@@ -594,6 +789,10 @@ export class LyraTable extends LyraElement {
         window.removeEventListener('pointercancel', this.onResizePointerEnd);
         this.resizeState = undefined;
         this.resizeObserver?.disconnect();
+        if (this.layoutRafId !== undefined) {
+            cancelAnimationFrame(this.layoutRafId);
+            this.layoutRafId = undefined;
+        }
         this.observedBase = undefined;
         this.observedHeaders.clear();
     }
@@ -690,6 +889,18 @@ export class LyraTable extends LyraElement {
     get normalizedPageSize() {
         return finiteCount(this.pageSize);
     }
+    /** Placeholder row count actually rendered by `loadingAppearance="skeleton"`. An explicit,
+     *  positive `skeletonRows` wins verbatim; otherwise the count is derived from the normalized
+     *  `pageSize` (bounded by MAX_DERIVED_SKELETON_ROWS), and falls back to DEFAULT_SKELETON_ROWS
+     *  when pagination is off -- `pageSize` defaults to 0, so "one placeholder per page row" has no
+     *  count of its own for the (common) unpaginated table. */
+    get effectiveSkeletonRows() {
+        const explicit = finiteCount(this.skeletonRows);
+        if (explicit > 0)
+            return explicit;
+        const pageSize = this.normalizedPageSize;
+        return pageSize > 0 ? Math.min(pageSize, MAX_DERIVED_SKELETON_ROWS) : DEFAULT_SKELETON_ROWS;
+    }
     /** `totalItems: -1` (the default) is a sentinel meaning "derive from filtered rows" -- normalize
      *  first so a non-finite/garbage `totalItems` degrades to that same derived-count fallback
      *  instead of propagating NaN, while a genuine non-negative value is still honored verbatim. */
@@ -740,6 +951,7 @@ export class LyraTable extends LyraElement {
         return first ? encodeKey(this.keyOf(first.row, first.index)) : null;
     }
     willUpdate(changed) {
+        super.willUpdate(changed);
         if (changed.has('rows') ||
             changed.has('rowKey') ||
             changed.has('filterText') ||
@@ -756,6 +968,13 @@ export class LyraTable extends LyraElement {
         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.
+        this.editorHadFocusBeforeUpdate =
+            this.focusedEditorCell !== null &&
+                this.shadowRoot?.activeElement ===
+                    this.editorElementFor(this.focusedEditorCell.rowKey, this.focusedEditorCell.columnKey);
     }
     /** Each sticky column's cumulative inline-start offset — the sum of the *rendered
      *  width* of every earlier sticky column — so multiple sticky columns
@@ -862,6 +1081,7 @@ export class LyraTable extends LyraElement {
      *  update; column widths are measured per update so the current layout
      *  reflects the rendered columns. */
     updated(changed) {
+        super.updated(changed);
         if (changed.has('columns') || changed.has('rows') || changed.has('rowKey'))
             this.applyStickyOffsets();
         this.syncResizeHandleValues();
@@ -873,10 +1093,14 @@ export class LyraTable extends LyraElement {
         if (base)
             this.observeBase(base);
         this.observeHeaders();
+        if (this.hasAlwaysOnEditors)
+            this.restoreAlwaysOnEditorFocus();
+        // Scoped to the cell that actually opened: an unqualified `[part="cell-editor"]` lookup would
+        // steal focus to whichever editor happens to be first in the tree, which stopped being "the
+        // one that just opened" as soon as a column could render persistent editors of its own.
         if (changed.has('editingCell') && this.editingCell) {
-            queueMicrotask(() => {
-                this.renderRoot.querySelector('[part="cell-editor"]')?.focus();
-            });
+            const { rowKey, columnKey } = this.editingCell;
+            queueMicrotask(() => this.editorElementFor(rowKey, columnKey)?.focus());
         }
         // Deferred to a microtask rather than called synchronously here: a real
         // priority-hidden transition mutates the reactive `columnsHidden`
@@ -916,13 +1140,23 @@ export class LyraTable extends LyraElement {
             this.emit('lr-selection-change', { keys: [...next] });
         }
     }
+    /** Whether any column opts into persistent (`editable: 'always'`) editors --
+     *  the table-level flag inferred from the columns themselves, mirroring how
+     *  `heatValue`/`width` opt their own modes in with no separate boolean. */
+    get hasAlwaysOnEditors() {
+        return this.columns.some((col) => editTrigger(col.editable) === 'always');
+    }
     editorValue(row, column) {
         const value = column.editValue?.(row) ?? row[column.key] ?? '';
         return String(value);
     }
+    /** Double-click only ever *opens* an editor, so an `'always'` column is
+     *  deliberately excluded: its editor is already open, and setting
+     *  `editingCell` for it would render a second, competing editor in the same
+     *  cell. */
     startEditing(rowKey, columnKey) {
         const column = this.columnsByKey.get(columnKey);
-        if (!column?.editable || !this.rowsByKey.has(rowKey))
+        if (editTrigger(column?.editable) !== 'double-click' || !this.rowsByKey.has(rowKey))
             return;
         this.editingCell = { rowKey, columnKey };
     }
@@ -930,12 +1164,41 @@ export class LyraTable extends LyraElement {
         const input = event.currentTarget;
         const entry = this.rowsByKey.get(rowKey);
         const column = this.columnsByKey.get(columnKey);
-        if (!entry || !column?.editable)
+        if (!entry || !column || editTrigger(column.editable) === undefined)
             return;
         const value = column.editType === 'number' && input.value !== '' ? Number(input.value) : input.value;
         this.emit('lr-cell-edit', { row: entry.row, key: columnKey, value });
         this.editingCell = null;
     }
+    /** The `[part='cell-editor']` rendered in one specific body cell, or `null` when that row/column
+     *  is not currently rendered (paginated away, filtered out, column removed) or holds no editor.
+     *  Matched by walking `data-row-key`/`data-col-key` rather than by interpolating them into a
+     *  selector: both are consumer-supplied strings, and the row key additionally carries an encoding
+     *  prefix (`string:a`), so neither is safe to splat into CSS unescaped. */
+    editorElementFor(rowKey, columnKey) {
+        const row = [...this.renderRoot.querySelectorAll('[data-row-key]')].find((el) => el.dataset.rowKey === rowKey);
+        const cell = row
+            ? [...row.querySelectorAll('td[data-col-key]')].find((el) => el.dataset.colKey === columnKey)
+            : undefined;
+        return cell?.querySelector('[part="cell-editor"]') ?? null;
+    }
+    /** Puts focus back into the persistent editor this update moved it out of. Runs from `updated()`,
+     *  after `render()`'s DOM moves have landed. A row that left the rendered set entirely
+     *  (pagination, filtering) only clears the record: yanking focus to whichever unrelated row now
+     *  occupies that position would be worse than losing it. */
+    restoreAlwaysOnEditorFocus() {
+        const cell = this.focusedEditorCell;
+        if (cell === null)
+            return;
+        const editor = this.editorElementFor(cell.rowKey, cell.columnKey);
+        if (editor === null) {
+            this.focusedEditorCell = null;
+        }
+        else if (this.editorHadFocusBeforeUpdate && this.shadowRoot?.activeElement !== editor) {
+            editor.focus();
+        }
+        this.editorHadFocusBeforeUpdate = false;
+    }
     activateExpandToggle(key) {
         const entry = this.rowsByKey.get(encodeKey(key));
         if (entry !== undefined)
@@ -1044,14 +1307,109 @@ export class LyraTable extends LyraElement {
                 return;
         }
     }
+    /** One body cell's inline editor.
+     *
+     *  The persistent (`editable: 'always'`) and double-click flavors differ in exactly one binding:
+     *  the persistent editor binds `value` as a **content attribute**, the double-click one keeps the
+     *  `.value` **property**. Native HTML sets an input's dirty-value flag on the user's first edit,
+     *  after which content-attribute updates no longer overwrite what is displayed -- so an
+     *  out-of-band `rows` update to a cell the user is already typing into leaves their draft alone,
+     *  with no is-focused bookkeeping of the library's own. An untouched persistent editor has no
+     *  dirty flag set, so it still picks up a new `rows` value normally. A double-click editor is
+     *  short-lived and opens against the value it is editing, so the property binding's deliberate
+     *  re-assert is right for it. Two templates rather than one because a lit template literal fixes
+     *  each binding's kind at authoring time.
+     *
+     *  No `tabindex` on either: a persistent editor is a plain tab stop, exactly like the row-expand
+     *  toggle rendered a few lines above, and stays outside the header/row roving model. */
+    renderCellEditor(row, col, rowKey, alwaysOn) {
+        const type = col.editType ?? 'text';
+        const isText = type === 'text';
+        const value = this.editorValue(row, col);
+        const label = this.localize('tableEditCell', undefined, { column: col.label });
+        const spellcheck = isText ? this.spellcheck : nothing;
+        const autocapitalize = isText ? this.autocapitalize || nothing : nothing;
+        const autocorrect = isText ? this.autoCorrect || nothing : nothing;
+        const onChange = (event) => this.commitEdit(event, rowKey, col.key);
+        const onKeyDown = (event) => this.onEditorKeyDown(event, rowKey, col.key);
+        return alwaysOn
+            ? html `<input
+          part="cell-editor"
+          type=${type}
+          value=${value}
+          aria-label=${label}
+          spellcheck=${spellcheck}
+          autocapitalize=${autocapitalize}
+          autocorrect=${autocorrect}
+          @change=${onChange}
+          @focus=${this.onNativeFocus}
+          @blur=${this.onNativeBlur}
+          @keydown=${onKeyDown}
+        />`
+            : html `<input
+          part="cell-editor"
+          type=${type}
+          .value=${value}
+          aria-label=${label}
+          spellcheck=${spellcheck}
+          autocapitalize=${autocapitalize}
+          autocorrect=${autocorrect}
+          @change=${onChange}
+          @focus=${this.onNativeFocus}
+          @blur=${this.onNativeBlur}
+          @keydown=${onKeyDown}
+        />`;
+    }
+    /** One placeholder. `announce` is switched off on every one of them: `<lr-skeleton>` defaults it
+     *  to `true`, which would make each of the N x M cells its own `role="status"` live region and
+     *  turn a single "Loading rows" announcement into a storm of them. The one status node
+     *  `render()` puts inside `[part='base']` carries the announcement for the whole grid instead.
+     *  A property binding (not `?announce=`) is required to assign `false` to a `true`-defaulting
+     *  boolean property. */
+    renderSkeletonPlaceholder() {
+        return html `<lr-skeleton part="skeleton" variant="rect" effect="sheen" .announce=${false}></lr-skeleton>`;
+    }
+    /** `loadingAppearance="skeleton"`'s body rows. Deliberately built from the same per-column
+     *  attributes (`data-col-key`/`data-align`/`data-priority`/`data-sticky`) and the same
+     *  `cell`/`row` parts as a real row, so the `@container` priority-hide rules, the sticky-offset
+     *  measurement pass and every cell style apply to them unchanged -- that, plus rendering inside
+     *  the real `<colgroup>`/`<thead>`, is what keeps the grid's geometry stable across the load.
+     *  They carry no `data-row-key` and no `tabindex`: they are not data rows, so the delegated
+     *  click/keydown handlers and the roving tab stop ignore them. */
+    renderSkeletonRows(hasExpand, hasRowTotal) {
+        return Array.from({ length: this.effectiveSkeletonRows }, () => html `<tr part="row" role="row" data-skeleton-row>
+        ${hasExpand ? html `<td part="expand-toggle-cell"></td>` : nothing}
+        ${this.columns.map((col) => html `<td
+            part="cell"
+            role="gridcell"
+            data-col-key=${col.key}
+            data-align=${col.align ?? 'start'}
+            data-priority=${col.priority ?? nothing}
+            data-sticky=${stickyDirection(col.sticky) ?? nothing}
+          >
+            ${this.renderSkeletonPlaceholder()}
+          </td>`)}
+        ${hasRowTotal ? html `<td part="row-total-cell">${this.renderSkeletonPlaceholder()}</td>` : nothing}
+      </tr>`);
+    }
     render() {
         if (this.columns.length === 0) {
+            // Deliberately not wrapped in the `empty` slot: this branch reports a *configuration*
+            // problem, with its own `noColumnsHeading` copy, rather than "this data set is empty" --
+            // one slot covering both would silently replace it with a no-results message.
             return html `<lr-empty
+        part="empty"
+        exportparts="base:empty-base, icon:empty-icon, heading:empty-heading, description:empty-description, actions:empty-actions"
+        ?compact=${this.emptyCompact ?? false}
         heading=${this.localize('noColumns', this.noColumnsHeading || undefined)}
         description=${this.noColumnsDescription}
       ></lr-empty>`;
         }
-        if (this.loading) {
+        // Skeleton mode deliberately falls through to the full grid render below instead of returning
+        // its own shell here: its whole point is that the <colgroup>/<thead>/filter/pagination chrome
+        // stays put, which is only achievable by rendering the real table.
+        const skeletonLoading = this.loading && this.loadingAppearance === 'skeleton';
+        if (this.loading && !skeletonLoading) {
             return html `<div part="base" aria-busy="true">
         <div part="loading" role="status" aria-live="polite">
           <lr-spinner label-placement="after" accessible-label=${this.localize('tableLoading', this.loadingLabel || undefined)}>
@@ -1061,38 +1419,63 @@ export class LyraTable extends LyraElement {
       </div>`;
         }
         const matchingEntries = this.matchingEntries();
-        if (this.rows.length === 0 && !this.filterable && this.normalizedPageSize === 0) {
-            return html `<lr-empty
-        heading=${this.localize('noData', this.emptyHeading || undefined)}
-        description=${this.emptyDescription}
-      ></lr-empty>`;
+        // 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) {
+            return html `<slot name="empty"
+        ><lr-empty
+          part="empty"
+          exportparts="base:empty-base, icon:empty-icon, heading:empty-heading, description:empty-description, actions:empty-actions"
+          ?compact=${this.emptyCompact ?? false}
+          heading=${this.localize('noData', this.emptyHeading || undefined)}
+          description=${this.emptyDescription}
+        ></lr-empty
+      ></slot>`;
         }
         const focusedCol = this.focusedColKey();
         const focusedRow = this.focusedRowKey();
         const hasColumnWidths = this.columns.some((col) => col.width || this.resizedColumnWidths.has(col.key));
+        // `layout` is a floor, never an override: a declared/resized column width still forces the
+        // fixed algorithm, and so does an in-flight drag (`resizeState` is deliberately non-reactive,
+        // but a *consumer*-triggered re-render mid-gesture -- before the first effective pointermove
+        // has populated `resizedColumnWidths` -- would otherwise flip the table back to `auto` and
+        // break the gesture, since resizing does not work under `table-layout: auto`).
+        // Kept separate from `data-has-column-widths`, which additionally signals that `<colgroup>`
+        // carries real widths.
+        const effectiveLayout = this.layout === 'fixed' || hasColumnWidths || this.resizeState !== undefined ? 'fixed' : 'auto';
         const hasExpand = Boolean(this.expandedContent);
         const hasHeatTint = this.columns.some((col) => col.heatValue !== undefined);
         const heatDomain = this.computeHeatDomain(hasHeatTint);
         const hasRowTotal = Boolean(this.rowTotal);
+        // Computed once and reused at both full-width call sites below (the group-header row and the
+        // expanded-row panel) rather than hand-duplicated -- a future new leading/trailing structural
+        // 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 hasPagination = this.normalizedPageSize > 0;
         const filterLabel = this.localize('tableFilterLabel', this.filterLabel || undefined);
         const filterPlaceholder = this.localize('tableFilterPlaceholder', this.filterPlaceholder || undefined);
-        const tableContent = renderedEntries.length === 0
-            ? html `<lr-empty
-            compact
-            heading=${this.localize('noData', this.emptyHeading || undefined)}
-            description=${this.emptyDescription}
-          ></lr-empty>`
+        const tableContent = renderedEntries.length === 0 && !skeletonLoading
+            ? html `<slot name="empty"
+            ><lr-empty
+              part="empty"
+              exportparts="base:empty-base, icon:empty-icon, heading:empty-heading, description:empty-description, actions:empty-actions"
+              ?compact=${this.emptyCompact ?? true}
+              heading=${this.localize('noData', this.emptyHeading || undefined)}
+              description=${this.emptyDescription}
+            ></lr-empty
+          ></slot>`
             : html `<table
             part="table"
             role="grid"
             aria-label=${this.getAttribute('aria-label') || nothing}
             aria-multiselectable=${this.selectionMode === 'multiple' ? 'true' : nothing}
             ?data-has-column-widths=${hasColumnWidths}
+            data-layout=${effectiveLayout}
             @click=${this.onTableClick}
             @keydown=${this.onTableKeyDown}
             @dblclick=${this.onTableDoubleClick}
+            @focusin=${this.onTableFocusIn}
           >
             <colgroup>
               ${hasExpand ? html `<col style=${styleMap({ 'inline-size': 'var(--lr-icon-button-size)' })} />` : nothing}
@@ -1137,32 +1520,34 @@ export class LyraTable extends LyraElement {
               </tr>
             </thead>
             <tbody>
-              ${repeat(renderedEntries, (entry) => this.keyOf(entry.row, entry.index), (entry, entryIndex) => {
-                const { row, index } = entry;
-                const key = this.keyOf(row, index);
-                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 isNewGroup = this.groupBy !== undefined && (entryIndex === 0 || groupKey !== previousGroupKey);
-                return [
-                    isNewGroup
-                        ? html `<tr part="group-row" role="row">
+              ${skeletonLoading
+                ? this.renderSkeletonRows(hasExpand, hasRowTotal)
+                : repeat(renderedEntries, (entry) => this.keyOf(entry.row, entry.index), (entry, entryIndex) => {
+                    const { row, index } = entry;
+                    const key = this.keyOf(row, index);
+                    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 isNewGroup = this.groupBy !== undefined && (entryIndex === 0 || groupKey !== previousGroupKey);
+                    return [
+                        isNewGroup
+                            ? html `<tr part="group-row" role="row">
                           <td
                             part="group-cell"
                             role="gridcell"
-                            colspan=${this.columns.length + (hasExpand ? 1 : 0) + (hasRowTotal ? 1 : 0)}
+                            colspan=${spanningColspan}
                           >
                             ${this.groupLabel
-                            ? this.groupLabel(groupKey, renderedEntries
-                                .filter((candidate) => this.groupBy?.(candidate.row) === groupKey)
-                                .map((candidate) => candidate.row))
-                            : String(groupKey)}
+                                ? this.groupLabel(groupKey, renderedEntries
+                                    .filter((candidate) => this.groupBy?.(candidate.row) === groupKey)
+                                    .map((candidate) => candidate.row))
+                                : String(groupKey)}
                           </td>
                         </tr>`
-                        : nothing,
-                    html `<tr
+                            : nothing,
+                        html `<tr
                       part="row"
                       role="row"
                       data-row-key=${encodeKey(key)}
@@ -1170,9 +1555,9 @@ export class LyraTable extends LyraElement {
                       tabindex=${encodeKey(key) === focusedRow ? '0' : '-1'}
                     >
                       ${hasExpand
-                        ? html `<td part="expand-toggle-cell">
+                            ? html `<td part="expand-toggle-cell">
                             ${canExpandRow
-                            ? html `<button
+                                ? html `<button
                                   type="button"
                                   part="row-expand-toggle"
                                   aria-expanded=${String(rowExpanded)}
@@ -1181,16 +1566,28 @@ export class LyraTable extends LyraElement {
                                 >
                                   <span part="row-expand-icon" aria-hidden="true">${chevronIcon()}</span>
                                 </button>`
-                            : nothing}
+                                : nothing}
                           </td>`
-                        : nothing}
+                            : nothing}
                       ${this.columns.map((col) => {
-                        const heatShare = this.heatShare(col, row, heatDomain);
-                        const cellStyle = {
-                            ...(col.cellStyle ? col.cellStyle(row) ?? {} : {}),
-                            ...(heatShare !== null ? { '--lr-table-heat-t': heatShare } : {}),
-                        };
-                        return html `<td
+                            const heatShare = this.heatShare(col, row, heatDomain);
+                            const cellStyle = {
+                                ...(col.cellStyle ? col.cellStyle(row) ?? {} : {}),
+                                ...(heatShare !== null ? { '--lr-table-heat-t': heatShare } : {}),
+                            };
+                            // An `'always'` column renders its editor unconditionally, from first
+                            // paint and with no interaction; `editingCell` (a single nullable object,
+                            // one open editor at a time) only ever drives the double-click flavor.
+                            const alwaysOn = editTrigger(col.editable) === 'always';
+                            const editing = alwaysOn ||
+                                (this.editingCell?.rowKey === encodeKey(key) && this.editingCell.columnKey === col.key);
+                            // `|| nothing`, not `?? nothing`: an empty `title=""` is not "no tooltip",
+                            // it actively suppresses an ancestor's tooltip, so an empty return omits
+                            // the attribute the same way `undefined` does (mirroring `lr-stat`'s
+                            // `exactValue`). Suppressed while editing so the tooltip can't shadow the
+                            // open `[part='cell-editor']`.
+                            const cellTitle = editing ? undefined : col.cellTitle?.(row);
+                            return html `<td
                             part="cell"
                             role="gridcell"
                             data-col-key=${col.key}
@@ -1198,44 +1595,27 @@ export class LyraTable extends LyraElement {
                             data-priority=${col.priority ?? nothing}
                             data-sticky=${stickyDirection(col.sticky) ?? nothing}
                             ?data-heat=${heatShare !== null}
+                            title=${cellTitle || nothing}
                             style=${Object.keys(cellStyle).length ? styleMap(cellStyle) : nothing}
                           >
-                            ${this.editingCell?.rowKey === encodeKey(key) && this.editingCell.columnKey === col.key
-                            ? html `<input
-                                  part="cell-editor"
-                                  type=${col.editType ?? 'text'}
-                                  .value=${this.editorValue(row, col)}
-                                  aria-label=${this.localize('tableEditCell', undefined, { column: col.label })}
-                                  spellcheck=${(col.editType ?? 'text') === 'text' ? this.spellcheck : nothing}
-                                  autocapitalize=${(col.editType ?? 'text') === 'text'
-                                ? this.autocapitalize || nothing
-                                : nothing}
-                                  autocorrect=${(col.editType ?? 'text') === 'text'
-                                ? this.autoCorrect || nothing
-                                : nothing}
-                                  @change=${(event) => this.commitEdit(event, encodeKey(key), col.key)}
-                                  @focus=${this.onNativeFocus}
-                                  @blur=${this.onNativeBlur}
-                                  @keydown=${(event) => this.onEditorKeyDown(event, encodeKey(key), col.key)}
-                                />`
-                            : col.cell(row)}
+                            ${editing ? this.renderCellEditor(row, col, encodeKey(key), alwaysOn) : col.cell(row)}
                           </td>`;
-                    })}
+                        })}
                       ${hasRowTotal ? html `<td part="row-total-cell">${this.rowTotal?.(row)}</td>` : nothing}
                     </tr>`,
-                    rowExpanded
-                        ? html `<tr part="expanded-row" role="row">
+                        rowExpanded
+                            ? html `<tr part="expanded-row" role="row">
                           <td
                             part="expanded-cell"
                             role="gridcell"
-                            colspan=${this.columns.length + (hasExpand ? 1 : 0) + (hasRowTotal ? 1 : 0)}
+                            colspan=${spanningColspan}
                           >
                             ${this.expandedContent?.(row)}
                           </td>
                         </tr>`
-                        : nothing,
-                ];
-            })}
+                            : nothing,
+                    ];
+                })}
             </tbody>
             ${this.columns.some((c) => c.footer)
                 ? html `<tfoot part="foot">
@@ -1254,7 +1634,12 @@ export class LyraTable extends LyraElement {
                 : nothing}
           </table>`;
         return html `
-      <div part="base" ?data-force-visible=${this.showAllColumns} aria-busy="false">
+      <div part="base" ?data-force-visible=${this.showAllColumns} aria-busy=${skeletonLoading ? 'true' : 'false'}>
+        ${skeletonLoading
+            ? html `<div part="loading" class="sr-only" role="status" aria-live="polite">
+              ${this.localize('tableLoading', this.loadingLabel || undefined)}
+            </div>`
+            : nothing}
         ${this.filterable
             ? html `<label part="filter-label">
               ${filterLabel}
@@ -1316,6 +1701,9 @@ __decorate([
 __decorate([
     property({ attribute: false })
 ], LyraTable.prototype, "rows", void 0);
+__decorate([
+    property({ reflect: true })
+], LyraTable.prototype, "layout", void 0);
 __decorate([
     property({ attribute: 'sort-key' })
 ], LyraTable.prototype, "sortKey", void 0);
@@ -1364,6 +1752,12 @@ __decorate([
 __decorate([
     property({ attribute: 'loading-label' })
 ], LyraTable.prototype, "loadingLabel", void 0);
+__decorate([
+    property({ reflect: true, attribute: 'loading-appearance' })
+], LyraTable.prototype, "loadingAppearance", void 0);
+__decorate([
+    property({ type: Number, attribute: 'skeleton-rows' })
+], LyraTable.prototype, "skeletonRows", void 0);
 __decorate([
     property({ attribute: false })
 ], LyraTable.prototype, "groupBy", void 0);
@@ -1412,6 +1806,9 @@ __decorate([
 __decorate([
     property({ attribute: 'empty-description' })
 ], LyraTable.prototype, "emptyDescription", void 0);
+__decorate([
+    property({ attribute: 'empty-compact', converter: optionalBooleanConverter })
+], LyraTable.prototype, "emptyCompact", void 0);
 __decorate([
     property({ attribute: 'no-columns-heading' })
 ], LyraTable.prototype, "noColumnsHeading", void 0);