@adia-ai/web-components 0.4.8 → 0.5.0

package/components/swatch/swatch.a2ui.json

@@ -13,6 +13,16 @@
     }
   ],
   "properties": {
+    "autoContrast": {
+      "description": "When set, computes the swatch color's OKLab L and switches the label /\ndetail color between light + dark so it remains legible against the\ntile background. Only applies to shape=\"block\" (where the label sits\nON the tile). Uses a 1px canvas probe to handle any CSS color form\n(oklch / hex / hsl / named / var() references).\n",
+      "type": "boolean",
+      "default": false
+    },
+    "badge": {
+      "description": "Optional marker(s) rendered in the upper-right of the tile. Single value\nOR comma/space-separated list of variants (v0.4.9+ multi-badge support).\nVariants: out-of-gamut (△), p3-only (✦), apca-pass (✓), apca-fail (✗).\nEach pip carries an aria-label so screen readers surface the semantic\n(\"Outside sRGB gamut\", \"Contrast passes APCA\", etc.). Unknown variants\nare silently dropped.\n",
+      "type": "string",
+      "default": ""
+    },
     "color": {
       "description": "Swatch color. Accepts any CSS color value or var() reference. Sets the internal --swatch-color custom property; consumers can also set --swatch-color via inline style.",
       "type": "string",
@@ -21,11 +31,36 @@
     "component": {
       "const": "Swatch"
     },
+    "copyable": {
+      "description": "When set, renders an inline copy-to-clipboard button. Defaults to copying [color]; override via [copy-value].",
+      "type": "boolean",
+      "default": false
+    },
+    "copyValue": {
+      "description": "Override what gets copied when [copyable] is set. Defaults to [color]. Not reflected (color strings are long; attr round-tripping reads poorly).",
+      "type": "string",
+      "default": ""
+    },
+    "detail": {
+      "description": "Optional secondary line of text rendered below the label. Typically the raw token value (e.g. \"oklch(0.53 0.18 240)\") when the swatch represents a design-token step.",
+      "type": "string",
+      "default": ""
+    },
     "label": {
       "description": "Optional label rendered next to (or below, for shape=\"block\") the swatch. Use the default slot for richer content.",
       "type": "string",
       "default": ""
     },
+    "selectable": {
+      "description": "When set, makes the swatch keyboard-focusable + clickable. Sets role=\"button\" + tabindex=\"0\". Dispatches a \"select\" event on activation (click / Enter / Space).",
+      "type": "boolean",
+      "default": false
+    },
+    "selected": {
+      "description": "Reflected visual selected state. Pair with [selectable] to make the swatch behave like a radio-style picker. Sets aria-pressed.",
+      "type": "boolean",
+      "default": false
+    },
     "shape": {
       "description": "Visual shape — block (filled tile), dot (small circle), square (small filled square), line (solid hairline), dashed (dashed hairline).",
       "type": "string",
@@ -57,7 +92,25 @@
     "anti_patterns": [],
     "category": "display",
     "composes": [],
-    "events": {},
+    "events": {
+      "select": {
+        "description": "Fired when a selectable swatch is activated (click / Enter / Space). detail carries the swatch's value, color, and label.",
+        "detail": {
+          "color": {
+            "description": "The raw [color] attribute value.",
+            "type": "string"
+          },
+          "label": {
+            "description": "The [label] attribute value.",
+            "type": "string"
+          },
+          "value": {
+            "description": "The swatch's effective value — [color] when present, else [label].",
+            "type": "string"
+          }
+        }
+      }
+    },
     "examples": [
       {
         "description": "A single dot swatch with text label, e.g. as a chart-legend row.",
@@ -94,6 +147,11 @@
       {
         "description": "Default, ready for display.",
         "name": "idle"
+      },
+      {
+        "description": "Reflected when the swatch is in the selected state (pair with [selectable]).",
+        "attribute": "selected",
+        "name": "selected"
       }
     ],
     "synonyms": {
@@ -107,8 +165,17 @@
     },
     "tag": "swatch-ui",
     "tokens": {
+      "--swatch-badge-fg": {
+        "description": "Color of the badge symbol. Defaults to chrome-foreground; overridden per-badge variant."
+      },
       "--swatch-color": {
         "description": "Resolved color of the swatch fill / line. Wins over the [color] attr if set inline."
+      },
+      "--swatch-detail-fg": {
+        "description": "Color of the secondary detail line. Defaults to subtle-foreground."
+      },
+      "--swatch-select-ring": {
+        "description": "Color of the focus + selected ring when [selectable] is set."
       }
     },
     "traits": [],

package/components/swatch/swatch.css

@@ -31,6 +31,25 @@
     --swatch-label-size:        var(--a-ui-size);
     --swatch-label-step-size:   10px;
     --swatch-label-step-mt:     4px;
+    --swatch-detail-size:       var(--a-ui-xs);
+    --swatch-detail-fg:         var(--a-fg-subtle);
+
+    /* ── Badge ── */
+    --swatch-badge-size:        var(--a-ui-xs);
+    --swatch-badge-fg:          var(--a-chrome-fg);
+    --swatch-badge-bg:          var(--a-chrome-bg);
+    --swatch-badge-pad:         2px 4px;
+    --swatch-badge-radius:      var(--a-radius-xs);
+
+    /* ── Copy button ── */
+    --swatch-copy-size:         var(--a-space-3);
+    --swatch-copy-fg:           var(--a-fg-muted);
+    --swatch-copy-fg-ok:        var(--a-success);
+    --swatch-copy-fg-fail:      var(--a-warning);
+
+    /* ── Selectable ring ── */
+    --swatch-select-ring:       var(--a-accent);
+    --swatch-select-ring-width: 2px;
   }
 
   :scope {
@@ -138,4 +157,135 @@
     --_size: calc(var(--swatch-tile-md) * 1.4);
     --_block-h: var(--swatch-tile-lg);
   }
+
+  /* ═══════ Detail line ═══════
+     Second line below the label — typically the raw token value for a
+     design-token swatch. For shape="block" sits under the label; for
+     non-block shapes is inline (small, muted, after label). */
+  :scope > [data-detail] {
+    color: var(--swatch-detail-fg);
+    font-size: var(--swatch-detail-size);
+    font-family: var(--a-font-family-code);
+    font-variant-numeric: tabular-nums;
+    white-space: nowrap;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    min-width: 0;
+  }
+  :scope > [data-detail][hidden] { display: none; }
+
+  :scope[shape="block"] > [data-detail] {
+    text-align: center;
+    margin-block-start: 2px;
+  }
+
+  /* ═══════ Badge stack ═══════
+     Symbol pips (△ / ✦ / ✓ / ✗) in the upper-right of the tile. v0.4.9 §92
+     supports multiple simultaneous badges — the container is a flex row;
+     each pip is a positioned child with semantic color. */
+  :scope > [data-badge] {
+    position: absolute;
+    top: -4px;
+    right: -4px;
+    display: inline-flex;
+    align-items: center;
+    gap: 2px;
+    pointer-events: none;
+  }
+  :scope > [data-badge][hidden] { display: none; }
+
+  :scope > [data-badge] > [data-badge-variant] {
+    display: inline-flex;
+    align-items: center;
+    justify-content: center;
+    min-width: var(--a-space-4);
+    height: var(--a-space-4);
+    padding: var(--swatch-badge-pad);
+    background: var(--swatch-badge-bg);
+    color: var(--swatch-badge-fg);
+    font-size: var(--swatch-badge-size);
+    line-height: 1;
+    border-radius: var(--swatch-badge-radius);
+    box-shadow: 0 0 0 1px color-mix(in oklab, var(--a-border-subtle) 60%, transparent);
+  }
+
+  /* Make sure the badge has a positioning context — the tile holds it. */
+  :scope { position: relative; }
+
+  /* Badge variants — symbol color encodes semantic */
+  :scope > [data-badge] > [data-badge-variant="out-of-gamut"] { color: var(--a-warning); }
+  :scope > [data-badge] > [data-badge-variant="p3-only"]      { color: var(--a-info); }
+  :scope > [data-badge] > [data-badge-variant="apca-pass"]    { color: var(--a-success); }
+  :scope > [data-badge] > [data-badge-variant="apca-fail"]    { color: var(--a-danger); }
+
+  /* ═══════ Auto-contrast label color ═══════
+     When [auto-contrast] is set, JS computes the swatch's OKLab L and
+     stamps [data-on-light] or [data-on-dark] on the label. The label then
+     swaps fg color so it remains legible against the tile background.
+     Only fires for shape="block" (label sits ON the tile); for other
+     shapes the label is beside the tile and uses the normal chrome fg. */
+  :scope[shape="block"][auto-contrast] > [data-label] {
+    position: relative;
+    z-index: 1;
+  }
+  :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] {
+    color: var(--a-chrome-light, #fafafa);
+  }
+  :scope[shape="block"][auto-contrast] > [data-label][data-on-light] {
+    color: var(--a-chrome-dark, #111);
+  }
+  /* Detail line follows the same auto-contrast choice. */
+  :scope[shape="block"][auto-contrast] > [data-detail] {
+    position: relative;
+    z-index: 1;
+  }
+  :scope[shape="block"][auto-contrast] > [data-label][data-on-dark] ~ [data-detail] {
+    color: color-mix(in oklab, var(--a-chrome-light, #fafafa) 80%, transparent);
+  }
+  :scope[shape="block"][auto-contrast] > [data-label][data-on-light] ~ [data-detail] {
+    color: color-mix(in oklab, var(--a-chrome-dark, #111) 70%, transparent);
+  }
+
+  /* ═══════ Copy button ═══════ */
+  :scope > [data-copy] {
+    appearance: none;
+    -webkit-appearance: none;
+    background: transparent;
+    border: 0;
+    padding: 2px 4px;
+    margin-inline-start: var(--a-space-1);
+    color: var(--swatch-copy-fg);
+    font-size: var(--a-ui-sm);
+    line-height: 1;
+    cursor: pointer;
+    border-radius: var(--a-radius-xs);
+    transition: color 100ms ease-out, background 100ms ease-out;
+  }
+  :scope > [data-copy]:hover { color: var(--a-fg); background: var(--a-bg-2); }
+  :scope > [data-copy]:focus-visible {
+    outline: var(--swatch-select-ring-width) solid var(--swatch-select-ring);
+    outline-offset: 1px;
+  }
+  :scope > [data-copy][hidden] { display: none; }
+  :scope > [data-copy][data-copy-state="ok"]   { color: var(--swatch-copy-fg-ok); }
+  :scope > [data-copy][data-copy-state="fail"] { color: var(--swatch-copy-fg-fail); }
+
+  /* ═══════ Selectable + selected states ═══════
+     [selectable] makes the whole host focusable; ring on :focus-visible.
+     [selected] always shows the ring. */
+  :scope[selectable] {
+    cursor: pointer;
+    border-radius: var(--a-radius-sm);
+    transition: box-shadow 120ms ease-out;
+  }
+  :scope[selectable]:focus { outline: none; }
+  :scope[selectable]:focus-visible {
+    box-shadow: 0 0 0 var(--swatch-select-ring-width) var(--swatch-select-ring);
+  }
+  :scope[selected] {
+    box-shadow: 0 0 0 var(--swatch-select-ring-width) var(--swatch-select-ring);
+  }
+  :scope[selectable]:hover:not([selected]) {
+    box-shadow: 0 0 0 1px color-mix(in oklab, var(--swatch-select-ring) 50%, transparent);
+  }
 }

package/components/swatch/swatch.d.ts

@@ -17,13 +17,56 @@ spacing demo pages.
 
 import { UIElement } from '../../core/element.js';
 
+export interface SwatchSelectEventDetail {
+  /** The raw [color] attribute value. */
+  color: string;
+  /** The [label] attribute value. */
+  label: string;
+  /** The swatch's effective value — [color] when present, else [label]. */
+  value: string;
+}
+
+export type SwatchSelectEvent = CustomEvent<SwatchSelectEventDetail>;
+
 export class UISwatch extends UIElement {
+  /** When set, computes the swatch color's OKLab L and switches the label /
+detail color between light + dark so it remains legible against the
+tile background. Only applies to shape="block" (where the label sits
+ON the tile). Uses a 1px canvas probe to handle any CSS color form
+(oklch / hex / hsl / named / var() references).
+ */
+  autoContrast: boolean;
+  /** Optional marker(s) rendered in the upper-right of the tile. Single value
+OR comma/space-separated list of variants (v0.4.9+ multi-badge support).
+Variants: out-of-gamut (△), p3-only (✦), apca-pass (✓), apca-fail (✗).
+Each pip carries an aria-label so screen readers surface the semantic
+("Outside sRGB gamut", "Contrast passes APCA", etc.). Unknown variants
+are silently dropped.
+ */
+  badge: string;
   /** Swatch color. Accepts any CSS color value or var() reference. Sets the internal --swatch-color custom property; consumers can also set --swatch-color via inline style. */
   color: string;
+  /** When set, renders an inline copy-to-clipboard button. Defaults to copying [color]; override via [copy-value]. */
+  copyable: boolean;
+  /** Override what gets copied when [copyable] is set. Defaults to [color]. Not reflected (color strings are long; attr round-tripping reads poorly). */
+  copyValue: string;
+  /** Optional secondary line of text rendered below the label. Typically the raw token value (e.g. "oklch(0.53 0.18 240)") when the swatch represents a design-token step. */
+  detail: string;
   /** Optional label rendered next to (or below, for shape="block") the swatch. Use the default slot for richer content. */
   label: string;
+  /** When set, makes the swatch keyboard-focusable + clickable. Sets role="button" + tabindex="0". Dispatches a "select" event on activation (click / Enter / Space). */
+  selectable: boolean;
+  /** Reflected visual selected state. Pair with [selectable] to make the swatch behave like a radio-style picker. Sets aria-pressed. */
+  selected: boolean;
   /** Visual shape — block (filled tile), dot (small circle), square (small filled square), line (solid hairline), dashed (dashed hairline). */
   shape: 'block' | 'dot' | 'square' | 'line' | 'dashed';
   /** Size preset — sm / md / lg. Drives the swatch's intrinsic dimensions; lg is reserved for the token-scale demo (40 px tall). */
   size: 'sm' | 'md' | 'lg';
+
+  addEventListener<K extends keyof HTMLElementEventMap>(
+    type: K,
+    listener: (this: UISwatch, ev: HTMLElementEventMap[K]) => unknown,
+    options?: boolean | AddEventListenerOptions,
+  ): void;
+  addEventListener(type: 'select', listener: (ev: SwatchSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }

package/components/swatch/swatch.yaml

@@ -41,17 +41,83 @@ props:
     type: string
     default: ""
     reflect: true
-events: {}
+  detail:
+    description: Optional secondary line of text rendered below the label. Typically the raw token value (e.g. "oklch(0.53 0.18 240)") when the swatch represents a design-token step.
+    type: string
+    default: ""
+    reflect: true
+  badge:
+    description: |
+      Optional marker(s) rendered in the upper-right of the tile. Single value
+      OR comma/space-separated list of variants (v0.4.9+ multi-badge support).
+      Variants: out-of-gamut (△), p3-only (✦), apca-pass (✓), apca-fail (✗).
+      Each pip carries an aria-label so screen readers surface the semantic
+      ("Outside sRGB gamut", "Contrast passes APCA", etc.). Unknown variants
+      are silently dropped.
+    type: string
+    default: ""
+    reflect: true
+  copyable:
+    description: When set, renders an inline copy-to-clipboard button. Defaults to copying [color]; override via [copy-value].
+    type: boolean
+    default: false
+    reflect: true
+  copyValue:
+    description: Override what gets copied when [copyable] is set. Defaults to [color]. Not reflected (color strings are long; attr round-tripping reads poorly).
+    type: string
+    default: ""
+  selectable:
+    description: When set, makes the swatch keyboard-focusable + clickable. Sets role="button" + tabindex="0". Dispatches a "select" event on activation (click / Enter / Space).
+    type: boolean
+    default: false
+    reflect: true
+  selected:
+    description: Reflected visual selected state. Pair with [selectable] to make the swatch behave like a radio-style picker. Sets aria-pressed.
+    type: boolean
+    default: false
+    reflect: true
+  autoContrast:
+    description: |
+      When set, computes the swatch color's OKLab L and switches the label /
+      detail color between light + dark so it remains legible against the
+      tile background. Only applies to shape="block" (where the label sits
+      ON the tile). Uses a 1px canvas probe to handle any CSS color form
+      (oklch / hex / hsl / named / var() references).
+    type: boolean
+    default: false
+    reflect: true
+events:
+  select:
+    description: Fired when a selectable swatch is activated (click / Enter / Space). detail carries the swatch's value, color, and label.
+    detail:
+      value:
+        type: string
+        description: The swatch's effective value — [color] when present, else [label].
+      color:
+        type: string
+        description: The raw [color] attribute value.
+      label:
+        type: string
+        description: The [label] attribute value.
 slots:
   default:
     description: Optional rich label content. When present, replaces the [label] attribute's text.
 states:
   - name: idle
     description: Default, ready for display.
+  - name: selected
+    attribute: selected
+    description: Reflected when the swatch is in the selected state (pair with [selectable]).
 traits: []
 tokens:
   --swatch-color:
     description: Resolved color of the swatch fill / line. Wins over the [color] attr if set inline.
+  --swatch-badge-fg:
+    description: Color of the badge symbol. Defaults to chrome-foreground; overridden per-badge variant.
+  --swatch-detail-fg:
+    description: Color of the secondary detail line. Defaults to subtle-foreground.
+  --swatch-select-ring:
+    description: Color of the focus + selected ring when [selectable] is set.
 a2ui:
   rules: []
 anti_patterns: []

package/components/swiper/swiper.a2ui.json

@@ -75,13 +75,29 @@
     ],
     "events": {
       "autoplay-pause": {
-        "description": "Fired on autoplay-pause."
+        "description": "Fired on autoplay-pause.",
+        "detail": {
+          "reason": {
+            "description": "Pause reason (\"hover\" or \"focus\").",
+            "type": "string"
+          }
+        }
       },
       "autoplay-resume": {
         "description": "Fired on autoplay-resume."
       },
       "change": {
-        "description": "Fired when the active slide changes. Detail: { index, slide }."
+        "description": "Fired when the active slide changes. Detail: { index, slide }.",
+        "detail": {
+          "index": {
+            "description": "New active slide index.",
+            "type": "number"
+          },
+          "slide": {
+            "description": "The active slide element.",
+            "type": "object"
+          }
+        }
       }
     },
     "examples": [

package/components/swiper/swiper.d.ts

@@ -12,9 +12,21 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type SwiperAutoplayPauseEvent = CustomEvent<unknown>;
+export interface SwiperAutoplayPauseEventDetail {
+  /** Pause reason ("hover" or "focus"). */
+  reason: string;
+}
+
+export type SwiperAutoplayPauseEvent = CustomEvent<SwiperAutoplayPauseEventDetail>;
 export type SwiperAutoplayResumeEvent = CustomEvent<unknown>;
-export type SwiperChangeEvent = CustomEvent<unknown>;
+export interface SwiperChangeEventDetail {
+  /** New active slide index. */
+  index: number;
+  /** The active slide element. */
+  slide: Record<string, unknown>;
+}
+
+export type SwiperChangeEvent = CustomEvent<SwiperChangeEventDetail>;
 
 export class UISwiper extends UIElement {
   /** Enable auto-advance */

package/components/swiper/swiper.yaml

@@ -53,10 +53,21 @@ props:
 events:
   autoplay-pause:
     description: Fired on autoplay-pause.
+    detail:
+      reason:
+        type: string
+        description: Pause reason ("hover" or "focus").
   autoplay-resume:
     description: Fired on autoplay-resume.
   change:
     description: 'Fired when the active slide changes. Detail: { index, slide }.'
+    detail:
+      index:
+        type: number
+        description: New active slide index.
+      slide:
+        type: object
+        description: The active slide element.
 slots:
   default:
     description: Default slot — primary child content.

package/components/table/table.a2ui.json

@@ -93,19 +93,94 @@
     ],
     "events": {
       "cell-click": {
-        "description": "Fired when a data cell is clicked."
+        "description": "Fired when a data cell is clicked. detail carries the cell location + value.",
+        "detail": {
+          "dataIndex": {
+            "description": "Row index in the underlying data array.",
+            "type": "number"
+          },
+          "key": {
+            "description": "Column key.",
+            "type": "string"
+          },
+          "row": {
+            "description": "Row data object.",
+            "type": "object"
+          },
+          "value": {
+            "description": "Cell value (type depends on column)."
+          }
+        }
+      },
+      "filter-change": {
+        "description": "Fired when an interactive filter row applies / clears. detail.filters is the current filter map.",
+        "detail": {
+          "filters": {
+            "description": "Map of `{ [columnKey]: filterValue }` reflecting active filters.",
+            "type": "object"
+          }
+        }
       },
       "page": {
-        "description": "Fired when the user navigates to a different page."
+        "description": "Fired when the user navigates to a different page.",
+        "detail": {
+          "page": {
+            "description": "New active page index (1-based).",
+            "type": "number"
+          }
+        }
       },
       "resize": {
-        "description": "Fired when a column is resized via drag."
+        "description": "Fired when a column is resized via drag.",
+        "detail": {
+          "key": {
+            "description": "Column key being resized.",
+            "type": "string"
+          },
+          "width": {
+            "description": "New column width in pixels.",
+            "type": "number"
+          }
+        }
+      },
+      "row-expand": {
+        "description": "Fired when an expandable row's chevron is activated. detail.index is the row position; detail.row is the row data.",
+        "detail": {
+          "index": {
+            "description": "Row index in the underlying data array.",
+            "type": "number"
+          },
+          "row": {
+            "description": "Row data object.",
+            "type": "object"
+          }
+        }
       },
       "select": {
-        "description": "Fired when row selection changes."
+        "description": "Fired when row selection changes. detail.selected is an array of row indices or IDs.",
+        "detail": {
+          "selected": {
+            "description": "Array of selected row indices or IDs (driven by [select-mode]).",
+            "type": "array"
+          }
+        }
       },
       "sort": {
-        "description": "Fired when sort state changes via header click."
+        "description": "Fired when sort state changes via header click.",
+        "detail": {
+          "dir": {
+            "description": "Sort direction — \"asc\" / \"desc\" / null (cleared).",
+            "type": "string"
+          },
+          "key": {
+            "description": "Column key being sorted.",
+            "type": "string"
+          },
+          "sortState": {
+            "description": "Full sort state array (multi-column support).",
+            "type": "array"
+          }
+        }
       }
     },
     "examples": [

package/components/table/table.d.ts

@@ -12,11 +12,62 @@
 
 import { UIElement } from '../../core/element.js';
 
-export type TableCellClickEvent = CustomEvent<unknown>;
-export type TablePageEvent = CustomEvent<unknown>;
-export type TableResizeEvent = CustomEvent<unknown>;
-export type TableSelectEvent = CustomEvent<unknown>;
-export type TableSortEvent = CustomEvent<unknown>;
+export interface TableCellClickEventDetail {
+  /** Row index in the underlying data array. */
+  dataIndex: number;
+  /** Column key. */
+  key: string;
+  /** Row data object. */
+  row: Record<string, unknown>;
+  /** Cell value (type depends on column). */
+  value: string;
+}
+
+export type TableCellClickEvent = CustomEvent<TableCellClickEventDetail>;
+export interface TableFilterChangeEventDetail {
+  /** Map of `{ [columnKey]: filterValue }` reflecting active filters. */
+  filters: Record<string, unknown>;
+}
+
+export type TableFilterChangeEvent = CustomEvent<TableFilterChangeEventDetail>;
+export interface TablePageEventDetail {
+  /** New active page index (1-based). */
+  page: number;
+}
+
+export type TablePageEvent = CustomEvent<TablePageEventDetail>;
+export interface TableResizeEventDetail {
+  /** Column key being resized. */
+  key: string;
+  /** New column width in pixels. */
+  width: number;
+}
+
+export type TableResizeEvent = CustomEvent<TableResizeEventDetail>;
+export interface TableRowExpandEventDetail {
+  /** Row index in the underlying data array. */
+  index: number;
+  /** Row data object. */
+  row: Record<string, unknown>;
+}
+
+export type TableRowExpandEvent = CustomEvent<TableRowExpandEventDetail>;
+export interface TableSelectEventDetail {
+  /** Array of selected row indices or IDs (driven by [select-mode]). */
+  selected: unknown[];
+}
+
+export type TableSelectEvent = CustomEvent<TableSelectEventDetail>;
+export interface TableSortEventDetail {
+  /** Sort direction — "asc" / "desc" / null (cleared). */
+  dir: string;
+  /** Column key being sorted. */
+  key: string;
+  /** Full sort state array (multi-column support). */
+  sortState: unknown[];
+}
+
+export type TableSortEvent = CustomEvent<TableSortEventDetail>;
 
 export class UITable extends UIElement {
   /** Column definitions. Array of {key, label, type?, width?, minWidth?, maxWidth?, flex?, sortable?, resizable?, filterable?, pinned?, hidden?, accessor?, format?, render?, sortFn?, filterType?, meta?}. Alternative to declarative <col-def> children. */
@@ -48,8 +99,10 @@ export class UITable extends UIElement {
     options?: boolean | AddEventListenerOptions,
   ): void;
   addEventListener(type: 'cell-click', listener: (ev: TableCellClickEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'filter-change', listener: (ev: TableFilterChangeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'page', listener: (ev: TablePageEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'resize', listener: (ev: TableResizeEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
+  addEventListener(type: 'row-expand', listener: (ev: TableRowExpandEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'select', listener: (ev: TableSelectEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
   addEventListener(type: 'sort', listener: (ev: TableSortEvent) => unknown, options?: boolean | AddEventListenerOptions): void;
 }