reke-ui 0.1.2 → 0.2.0

package/custom-elements.json

@@ -128,139 +128,6 @@
         }
       ]
     },
-    {
-      "kind": "javascript-module",
-      "path": "src/components/reke-badge/reke-badge.ts",
-      "declarations": [
-        {
-          "kind": "class",
-          "description": "",
-          "name": "RekeBadge",
-          "cssProperties": [
-            {
-              "description": "Default variant background color.",
-              "name": "--reke-color-surface",
-              "default": "#1A1A1A"
-            },
-            {
-              "description": "Default variant text color.",
-              "name": "--reke-color-text",
-              "default": "#E5E5E5"
-            },
-            {
-              "description": "Default variant border color.",
-              "name": "--reke-color-border",
-              "default": "#252525"
-            },
-            {
-              "description": "Primary/success variant accent color.",
-              "name": "--reke-color-primary",
-              "default": "#22C55E"
-            },
-            {
-              "description": "Danger variant accent color.",
-              "name": "--reke-color-danger",
-              "default": "#EF4444"
-            }
-          ],
-          "cssParts": [
-            {
-              "description": "The inner badge element.",
-              "name": "badge"
-            }
-          ],
-          "slots": [
-            {
-              "description": "Default slot for badge text.",
-              "name": ""
-            }
-          ],
-          "members": [
-            {
-              "kind": "field",
-              "name": "variant",
-              "type": {
-                "text": "BadgeVariant"
-              },
-              "default": "'default'",
-              "attribute": "variant",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "size",
-              "type": {
-                "text": "BadgeSize"
-              },
-              "default": "'md'",
-              "attribute": "size",
-              "reflects": true
-            },
-            {
-              "kind": "field",
-              "name": "shape",
-              "type": {
-                "text": "BadgeShape"
-              },
-              "default": "'pill'",
-              "attribute": "shape",
-              "reflects": true
-            }
-          ],
-          "attributes": [
-            {
-              "name": "variant",
-              "type": {
-                "text": "BadgeVariant"
-              },
-              "default": "'default'",
-              "fieldName": "variant"
-            },
-            {
-              "name": "size",
-              "type": {
-                "text": "BadgeSize"
-              },
-              "default": "'md'",
-              "fieldName": "size"
-            },
-            {
-              "name": "shape",
-              "type": {
-                "text": "BadgeShape"
-              },
-              "default": "'pill'",
-              "fieldName": "shape"
-            }
-          ],
-          "superclass": {
-            "name": "RekeElement",
-            "module": "/src/shared/base-element.js"
-          },
-          "tagName": "reke-badge",
-          "customElement": true,
-          "summary": "A badge component for displaying labels, statuses, and counts."
-        }
-      ],
-      "exports": [
-        {
-          "kind": "js",
-          "name": "RekeBadge",
-          "declaration": {
-            "name": "RekeBadge",
-            "module": "src/components/reke-badge/reke-badge.ts"
-          }
-        },
-        {
-          "kind": "custom-element-definition",
-          "name": "reke-badge",
-          "declaration": {
-            "name": "RekeBadge",
-            "module": "src/components/reke-badge/reke-badge.ts"
-          }
-        }
-      ]
-    },
     {
       "kind": "javascript-module",
       "path": "src/components/reke-button/reke-button.ts",
@@ -454,6 +321,139 @@
         }
       ]
     },
+    {
+      "kind": "javascript-module",
+      "path": "src/components/reke-badge/reke-badge.ts",
+      "declarations": [
+        {
+          "kind": "class",
+          "description": "",
+          "name": "RekeBadge",
+          "cssProperties": [
+            {
+              "description": "Default variant background color.",
+              "name": "--reke-color-surface",
+              "default": "#1A1A1A"
+            },
+            {
+              "description": "Default variant text color.",
+              "name": "--reke-color-text",
+              "default": "#E5E5E5"
+            },
+            {
+              "description": "Default variant border color.",
+              "name": "--reke-color-border",
+              "default": "#252525"
+            },
+            {
+              "description": "Primary/success variant accent color.",
+              "name": "--reke-color-primary",
+              "default": "#22C55E"
+            },
+            {
+              "description": "Danger variant accent color.",
+              "name": "--reke-color-danger",
+              "default": "#EF4444"
+            }
+          ],
+          "cssParts": [
+            {
+              "description": "The inner badge element.",
+              "name": "badge"
+            }
+          ],
+          "slots": [
+            {
+              "description": "Default slot for badge text.",
+              "name": ""
+            }
+          ],
+          "members": [
+            {
+              "kind": "field",
+              "name": "variant",
+              "type": {
+                "text": "BadgeVariant"
+              },
+              "default": "'default'",
+              "attribute": "variant",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "size",
+              "type": {
+                "text": "BadgeSize"
+              },
+              "default": "'md'",
+              "attribute": "size",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "shape",
+              "type": {
+                "text": "BadgeShape"
+              },
+              "default": "'pill'",
+              "attribute": "shape",
+              "reflects": true
+            }
+          ],
+          "attributes": [
+            {
+              "name": "variant",
+              "type": {
+                "text": "BadgeVariant"
+              },
+              "default": "'default'",
+              "fieldName": "variant"
+            },
+            {
+              "name": "size",
+              "type": {
+                "text": "BadgeSize"
+              },
+              "default": "'md'",
+              "fieldName": "size"
+            },
+            {
+              "name": "shape",
+              "type": {
+                "text": "BadgeShape"
+              },
+              "default": "'pill'",
+              "fieldName": "shape"
+            }
+          ],
+          "superclass": {
+            "name": "RekeElement",
+            "module": "/src/shared/base-element.js"
+          },
+          "tagName": "reke-badge",
+          "customElement": true,
+          "summary": "A badge component for displaying labels, statuses, and counts."
+        }
+      ],
+      "exports": [
+        {
+          "kind": "js",
+          "name": "RekeBadge",
+          "declaration": {
+            "name": "RekeBadge",
+            "module": "src/components/reke-badge/reke-badge.ts"
+          }
+        },
+        {
+          "kind": "custom-element-definition",
+          "name": "reke-badge",
+          "declaration": {
+            "name": "RekeBadge",
+            "module": "src/components/reke-badge/reke-badge.ts"
+          }
+        }
+      ]
+    },
     {
       "kind": "javascript-module",
       "path": "src/components/reke-card/reke-card.ts",
@@ -2458,9 +2458,19 @@
               "default": "#E5E5E5"
             },
             {
-              "description": "Header text color. Props: - `expandedRowRender`: Lit-based expand render. Receives `(row, index)` → TemplateResult. - `expandedRowElement`: Framework-agnostic expand render. Receives `(host, row, index)` — mount any framework. Return cleanup or void.",
+              "description": "Header text color.",
               "name": "--reke-color-text-muted",
               "default": "#525252"
+            },
+            {
+              "description": "Chevron focus outline color.",
+              "name": "--reke-color-primary",
+              "default": "#22C55E"
+            },
+            {
+              "description": "Chevron button corner radius. Props: - `expandedRowElement`: Framework-agnostic expand render. Receives `(host, row, key)`. Mount any framework. Return cleanup or void. - `getRowKey`: Optional `(row, index) => RowKey`. Defaults to `String(index)`. Use a stable domain id for identity-keyed expand state across sorts. - `expandable`: Opt-in boolean (default `false`). When `true`, `reke-table` prepends a leading toggle column with an accessible chevron `<button>` per row: `aria-expanded` reflects the row's expand state, `aria-controls` points at the expand `<td>`, and `Enter`/`Space` activate the toggle. Consumers can also build their own toggles by leaving `expandable=false` (default) and calling `toggleExpand(key)` directly. - `expandOnRowClick` (attribute `expand-on-row-click`): Opt-in boolean (default `false`). When `true`, clicking anywhere on a row calls `toggleExpand(key)` internally. `reke-row-click` is STILL emitted on every row click. The chevron button calls `stopPropagation()` so chevron clicks do NOT double-toggle. Consumers MUST use EITHER this prop OR their own `reke-row-click` → `toggleExpand` handler, not both. For keyboard / screen-reader users, pair with `expandable`.",
+              "name": "--reke-radius",
+              "default": "4px"
             }
           ],
           "cssParts": [
@@ -2503,6 +2513,14 @@
             {
               "description": "The td spanning all columns in the expanded row.",
               "name": "expand-content"
+            },
+            {
+              "description": "The leading `<td>` that contains the chevron button (only when `expandable`).",
+              "name": "expand-toggle-cell"
+            },
+            {
+              "description": "The chevron `<button>` itself (only when `expandable`).",
+              "name": "expand-toggle-button"
             }
           ],
           "slots": [
@@ -2586,6 +2604,28 @@
               "attribute": "borderless",
               "reflects": true
             },
+            {
+              "kind": "field",
+              "name": "expandable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt-in: when `true`, the table prepends a leading toggle column whose\n`<button>` calls `toggleExpand(key)`, exposes `aria-expanded` reflecting\nthe expand state, `aria-controls` pointing at the expand `<td>` id\n(`reke-table-expand-<key>`), and accepts `Enter` / `Space` activation.\n\nDefaults to `false` so consumers that already wire their own toggles\n(chips, links, custom buttons) are unaffected.",
+              "attribute": "expandable",
+              "reflects": true
+            },
+            {
+              "kind": "field",
+              "name": "expandOnRowClick",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt-in: when `true`, clicking anywhere on a row (outside the chevron, if\npresent) calls `toggleExpand(key)` internally using the row's identity\nkey. The `reke-row-click` event is STILL emitted on every row click so\nconsumers can react in addition to the built-in toggle.\n\nDefault is `false` to preserve non-breaking behavior: existing consumers\nthat wire their own `reke-row-click` → `toggleExpand` handlers are\nunaffected.\n\nA11y note: row clicks are a pointer convenience only. The `<tr>` does NOT\nreceive `role=\"button\"` or `tabindex` (that would be a clickable-row\na11y anti-pattern). For keyboard / screen-reader users, pair this prop\nwith `expandable` so the accessible chevron `<button>` is available.\n\nDouble-wiring caveat: consumers MUST use EITHER `expandOnRowClick` OR\ntheir own `reke-row-click` → `toggleExpand` handler — not both — or the\nrow will toggle twice and net to no change.\n\nChevron interaction: the chevron `<button>` calls `stopPropagation()`, so\nclicking the chevron does NOT trigger the row-click toggle (no double\ntoggle).",
+              "attribute": "expand-on-row-click",
+              "reflects": true
+            },
             {
               "kind": "field",
               "name": "sortKey",
@@ -2608,36 +2648,81 @@
             },
             {
               "kind": "field",
-              "name": "expandedRowRender",
+              "name": "expandedRowElement",
               "type": {
-                "text": "ExpandedRowRenderer | null"
+                "text": "ExpandedRowElement | null"
               },
               "default": "null",
-              "description": "When set, rows become expandable with a chevron toggle."
+              "description": "Framework-agnostic expand callback. Sole expand API."
             },
             {
               "kind": "field",
-              "name": "expandedRowElement",
+              "name": "getRowKey",
               "type": {
-                "text": "((host: HTMLElement, row: TableRow, index: number) => (() => void) | void) | null"
+                "text": "GetRowKey | undefined"
               },
-              "default": "null",
-              "description": "Framework-agnostic alternative to expandedRowRender.\nReceives an HTMLElement host — mount any framework's content into it.\nReturn a cleanup function (called on collapse) or void."
+              "description": "Resolve a stable identifier for each row.\nDefaults to `String(index)` — identity-equivalent only when rows are stable.\nProvide a domain id (e.g. `row => row.id`) to keep expand state across sorts."
             },
             {
               "kind": "field",
               "name": "expandedRows",
               "type": {
-                "text": "Set<number>"
+                "text": "Set<RowKey>"
               },
               "default": "new Set()",
-              "description": "Set of row indices currently expanded."
+              "description": "Set of row keys currently expanded."
+            },
+            {
+              "kind": "field",
+              "name": "_hostCache",
+              "privacy": "private",
+              "default": "new Map<RowKey, HTMLElement>()",
+              "description": "Host element cached per row key. Survives unrelated re-renders."
+            },
+            {
+              "kind": "field",
+              "name": "_cleanupMap",
+              "privacy": "private",
+              "default": "new Map<RowKey, Cleanup>()",
+              "description": "Cleanup cached per row key. Invoked exactly once on collapse / row removal / disconnect."
+            },
+            {
+              "kind": "field",
+              "name": "_warnedDupKeys",
+              "privacy": "private",
+              "default": "new Set<RowKey>()",
+              "description": "Keys we have already warned about as duplicates (one-shot per component lifetime)."
+            },
+            {
+              "kind": "field",
+              "name": "_warnedNumericTarget",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false",
+              "description": "One-shot guard for the numeric-target-with-getRowKey ambiguity warning."
+            },
+            {
+              "kind": "field",
+              "name": "_mountedKeys",
+              "privacy": "private",
+              "default": "new Set<RowKey>()",
+              "description": "Track which keys are currently mounted in the DOM, to honor the contract that mount happens after `updated()` reconciles."
+            },
+            {
+              "kind": "field",
+              "name": "_keyToRow",
+              "privacy": "private",
+              "default": "new Map<RowKey, TableRow>()",
+              "description": "Latest resolved row map: key → row. Filled during render so callbacks can look up rows."
             },
             {
               "kind": "field",
-              "name": "_expandCleanups",
+              "name": "_refCallbacks",
               "privacy": "private",
-              "default": "new Map<number, () => void>()"
+              "default": "new Map<RowKey, (el: Element | undefined) => void>()",
+              "description": "Stable ref callback per row key. One closure per key, reused across renders."
             },
             {
               "kind": "field",
@@ -2657,6 +2742,30 @@
               "privacy": "private",
               "default": "false"
             },
+            {
+              "kind": "method",
+              "name": "_resolveKey",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "RowKey"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "row",
+                  "type": {
+                    "text": "TableRow"
+                  }
+                },
+                {
+                  "name": "index",
+                  "type": {
+                    "text": "number"
+                  }
+                }
+              ]
+            },
             {
               "kind": "method",
               "name": "handleHeaderClick",
@@ -2689,18 +2798,73 @@
                 }
               ]
             },
+            {
+              "kind": "method",
+              "name": "_handleChevronClick",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "Event"
+                  }
+                },
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "RowKey"
+                  }
+                }
+              ],
+              "description": "Chevron button click handler. Stops propagation so it does NOT also fire\nthe row-level `reke-row-click` event, then toggles the row by key."
+            },
+            {
+              "kind": "method",
+              "name": "_handleChevronKeydown",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "event",
+                  "type": {
+                    "text": "KeyboardEvent"
+                  }
+                },
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "RowKey"
+                  }
+                }
+              ],
+              "description": "Chevron keyboard activation. The element is a native `<button>`, so Enter\nalready fires `click` natively. We still handle it here to keep the\nkeyboard contract explicit and testable across environments where the\n`KeyboardEvent` is dispatched programmatically (Vitest browser mode tests\ndispatch raw `keydown`s without the synthesized `click`).\n\nFor Space we MUST call `preventDefault()` so the page does not scroll."
+            },
             {
               "kind": "method",
               "name": "toggleExpand",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
               "parameters": [
                 {
-                  "name": "index",
+                  "name": "target",
                   "type": {
-                    "text": "number"
+                    "text": "number | RowKey"
                   }
                 }
               ],
-              "description": "Toggle expand state for a row at the given index."
+              "description": "Toggle expand state for a row.\nAccepts either a numeric `index` into `rows` or a `RowKey` (the value returned by `getRowKey`).\nWhen `getRowKey` is unset, indices and keys collapse onto `String(index)`."
             },
             {
               "kind": "method",
@@ -2712,13 +2876,13 @@
               },
               "parameters": [
                 {
-                  "name": "index",
+                  "name": "key",
                   "type": {
-                    "text": "number"
+                    "text": "RowKey"
                   }
                 }
               ],
-              "description": "Check whether a row at the given index is currently expanded."
+              "description": "Check whether a row with the given key is currently expanded."
             },
             {
               "kind": "method",
@@ -2748,26 +2912,44 @@
             },
             {
               "kind": "method",
-              "name": "_renderRow",
+              "name": "_getOrCreateHost",
               "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "HTMLElement"
+                }
+              },
               "parameters": [
                 {
-                  "name": "row",
+                  "name": "key",
                   "type": {
-                    "text": "TableRow"
+                    "text": "RowKey"
                   }
-                },
+                }
+              ]
+            },
+            {
+              "kind": "method",
+              "name": "_expandTdRef",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "(el: Element | undefined) => void"
+                }
+              },
+              "parameters": [
                 {
-                  "name": "i",
+                  "name": "key",
                   "type": {
-                    "text": "number"
+                    "text": "RowKey"
                   }
                 }
-              ]
+              ],
+              "description": "Return a STABLE ref callback for a given row key. Lit's `ref()` directive accepts a\ncallback `(el: Element | undefined) => void` directly, so no cast is needed. The callback\nis memoized per key to avoid churning Lit's ref directive on every render."
             },
             {
               "kind": "method",
-              "name": "_renderExpandedElement",
+              "name": "_renderRow",
               "privacy": "private",
               "parameters": [
                 {
@@ -2781,8 +2963,52 @@
                   "type": {
                     "text": "number"
                   }
+                },
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "RowKey"
+                  }
                 }
               ]
+            },
+            {
+              "kind": "field",
+              "name": "_warnedLegacyApi",
+              "type": {
+                "text": "boolean"
+              },
+              "privacy": "private",
+              "default": "false"
+            },
+            {
+              "kind": "method",
+              "name": "_safeCleanup",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              },
+              "parameters": [
+                {
+                  "name": "key",
+                  "type": {
+                    "text": "RowKey"
+                  }
+                }
+              ],
+              "description": "Invoke the cached cleanup for a key, swallowing consumer errors so our own state\nmutation (`expandedRows`, host/cleanup/ref maps) and `emit` stay consistent even if\nthe consumer's cleanup throws. Deletes the cleanup entry after running."
+            },
+            {
+              "kind": "method",
+              "name": "_runAllCleanupsAndClear",
+              "privacy": "private",
+              "return": {
+                "type": {
+                  "text": "void"
+                }
+              }
             }
           ],
           "events": [
@@ -2795,7 +3021,7 @@
               "name": "reke-sort"
             },
             {
-              "description": "Fired when a row is expanded or collapsed. Detail: `{ row: TableRow, index: number, expanded: boolean }`.",
+              "description": "Fired when a row is expanded or collapsed. Detail: `{ row: TableRow, index: number, key: RowKey, expanded: boolean }`.",
               "name": "reke-row-expand"
             }
           ],
@@ -2840,6 +3066,24 @@
               "default": "false",
               "fieldName": "borderless"
             },
+            {
+              "name": "expandable",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt-in: when `true`, the table prepends a leading toggle column whose\n`<button>` calls `toggleExpand(key)`, exposes `aria-expanded` reflecting\nthe expand state, `aria-controls` pointing at the expand `<td>` id\n(`reke-table-expand-<key>`), and accepts `Enter` / `Space` activation.\n\nDefaults to `false` so consumers that already wire their own toggles\n(chips, links, custom buttons) are unaffected.",
+              "fieldName": "expandable"
+            },
+            {
+              "name": "expand-on-row-click",
+              "type": {
+                "text": "boolean"
+              },
+              "default": "false",
+              "description": "Opt-in: when `true`, clicking anywhere on a row (outside the chevron, if\npresent) calls `toggleExpand(key)` internally using the row's identity\nkey. The `reke-row-click` event is STILL emitted on every row click so\nconsumers can react in addition to the built-in toggle.\n\nDefault is `false` to preserve non-breaking behavior: existing consumers\nthat wire their own `reke-row-click` → `toggleExpand` handlers are\nunaffected.\n\nA11y note: row clicks are a pointer convenience only. The `<tr>` does NOT\nreceive `role=\"button\"` or `tabindex` (that would be a clickable-row\na11y anti-pattern). For keyboard / screen-reader users, pair this prop\nwith `expandable` so the accessible chevron `<button>` is available.\n\nDouble-wiring caveat: consumers MUST use EITHER `expandOnRowClick` OR\ntheir own `reke-row-click` → `toggleExpand` handler — not both — or the\nrow will toggle twice and net to no change.\n\nChevron interaction: the chevron `<button>` calls `stopPropagation()`, so\nclicking the chevron does NOT trigger the row-click toggle (no double\ntoggle).",
+              "fieldName": "expandOnRowClick"
+            },
             {
               "name": "sort-key",
               "type": {
@@ -2863,7 +3107,7 @@
           },
           "tagName": "reke-table",
           "customElement": true,
-          "summary": "A data table with custom cell rendering, expandable rows, and toolbar/footer slots."
+          "summary": "A data table with custom cell rendering, framework-agnostic expandable rows, and toolbar/footer slots."
         }
       ],
       "exports": [