@recursica/mui-adapter 0.28.0 → 0.29.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.28.0",
+  "version": "0.29.0",
   "publishConfig": {
     "access": "public"
   },
@@ -102,8 +102,8 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "*",
-    "@recursica/official-release": "*",
+    "@recursica/adapter-common": "^0.20.0",
+    "@recursica/official-release": "^2.8.0",
     "dayjs": "^1.11.21"
   },
   "peerDependencies": {

package/src/components/Link/Link.module.css

@@ -51,6 +51,10 @@ HARDCODED VALUES:
   );
 }
 
+.root:hover {
+  text-decoration: var(--recursica_brand_states_link_decoration);
+}
+
 /* Icon Support */
 .iconWrapper {
   /* HARDCODE: maintain intrinsic icon bounds */

package/src/components/Table/TABLE_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,64 @@
+# Table — Implementation Notes (Internal)
+
+## Background
+
+Unlike `mantine-adapter`, this package's `Table.module.css` was an empty stub — none of the
+header/cell/footer/row tokens were wired at all (the "table-header/table-footer/table-cell, 88
+tokens" gap from the 2026-08-21 token-analyzer review). This pass writes that CSS from scratch,
+porting the structure/token references already proven out in `mantine-adapter`'s
+`Table.module.css`, adapted to MUI's DOM and class model.
+
+## One `Table.Cell`, not separate header/body/footer components
+
+MUI's own `TableCell` is a single primitive for header, body, and footer cells — it auto-detects
+which one it is (and whether to render `<th>` or `<td>`) from its ancestor
+(`Table.Head`/`Table.Body`/`Table.Footer`). Recursica's `Table.Cell` mirrors that instead of
+splitting into per-context components (see the Forge reference-implementation review,
+2026-08-22, and direction from Matt the same day: align with the underlying kit's own
+components). Its props cover both concerns: `sorted` (header-only in practice) and `variant`
+(body/footer). `sorted` has no effect on styling unless the cell also carries the header's
+`data-sorted`-driven CSS (i.e. it's meaningless on a body/footer cell) — nothing prevents a
+caller from passing it there by mistake; that's an accepted tradeoff of unifying the three
+contexts into one component, same tradeoff MUI's own `TableCell` makes.
+
+## Every sub-component now attaches its own CSS module class
+
+Before this change, `Table.Body`/`Table.Cell`/`Table.Container`/`Table.Head`/`Table.Row`/
+`Table.Footer`/`Table.SortLabel` attached no Recursica class at all — only the root `Table` did.
+`Table.Cell` and `Table.Row` now attach `.cell`/`.row` (needed so the CSS in `Table.module.css`
+can select on state, e.g. `.cell[data-disabled="true"]`, instead of bare `td`/`tr` tag
+selectors). `Table.SortLabel` attaches `.sortLabel` (see below). `Body`/`Container`/`Head`/
+`Footer` were left alone — the CSS only needs to reach them structurally (`thead`/`tbody`/
+`tfoot`), so they don't need a class of their own for this to work.
+
+## Sort icon comes from `Table.SortLabel`, not `Table.Cell`
+
+MUI already has a sortable-header primitive — `TableSortLabel` — that renders its own
+arrow icon and flips it based on `direction`/`active`. `Table.Cell` only sets the sorted-state
+_styling_ (`data-sorted` → background/text/font tokens, matching `mantine-adapter`'s `Table.Th`);
+the icon itself is `Table.SortLabel`'s job, composed by the consumer the same way MUI's own docs
+demonstrate (`<Table.Cell sorted><Table.SortLabel active direction="asc">Name</Table.SortLabel></Table.Cell>`).
+`Table.module.css` re-colors the icon to `inherit` (overriding MUI's default sort-label color)
+and sizes/spaces it with the same `table-header` icon-size/label-sort-gap tokens
+`mantine-adapter` uses for its own inline chevron — see that adapter's `Table.icons.tsx` for the
+Mantine-side equivalent. This is intentionally asymmetric between the two adapters: Mantine has
+no equivalent primitive, so its `Table.Th` renders the chevron itself.
+
+## MUI's own `.Mui-selected` background is reset
+
+`Table.Row`'s `selected` prop passes straight through to MUI's native `TableRow.selected` (kept
+for the `aria-selected`/`Mui-selected` semantics it drives) _and_ sets `data-selected`. Found via
+screenshot comparison against `mantine-adapter` (2026-08-22): MUI's own default `.Mui-selected`
+row background was compositing underneath our token-driven `.cell` background (semi-transparent
+`color-mix` over MUI's own tint instead of over nothing), producing a visibly different color
+than Mantine's. `Table.module.css` resets `.row:global(.Mui-selected)` to
+`background-color: transparent` so only the Recursica token color shows — same
+override-the-library's-own-styling rule the canonical guide documents for hover.
+
+## Selectable rows (checkboxes)
+
+See `mantine-adapter`'s `TABLE_IMPLEMENTATION_NOTES.md` — confirmed 2026-08-22 that neither
+Mantine's nor MUI's base `Table` has a built-in checkbox-selection feature (MUI's only comes via
+`@mui/x-data-grid`, not installed here). `Table.Row`'s `selected` prop maps directly onto MUI's
+own native `TableRow.selected` (which already sets `aria-selected`/`Mui-selected`) plus a
+`data-selected` attribute so our CSS selectors stay identical in shape to `mantine-adapter`'s.

package/src/components/Table/Table.module.css

@@ -1,7 +1,448 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Global hover state tokens (recursica_variables_scoped.css header, 'Hover & Focus states' —
+ * implicit rule for every interactive element; components must not define their own
+ * per-component hover treatment).
+ *   recursica-allow-brand: --recursica_brand_states_hover_color
+ *   recursica-allow-brand: --recursica_brand_states_hover_opacity
+ */
+
 /* HARDCODED VALUES:
- * None. This is a generic layout wrapper.
+ * - border-collapse: separate; border-spacing: 0; (To support custom border-radius on table elements)
+ * - overflow: hidden; (To prevent content from bleeding outside the rounded table border)
  */
 
 .root {
-  /* MUI Table handles table layout natively. */
+  border-collapse: separate;
+  border-spacing: 0;
+  border-radius: var(
+    --recursica_ui-kit_components_table_properties_border-radius
+  );
+  border: var(--recursica_ui-kit_components_table_properties_border-size) solid
+    var(--recursica_ui-kit_components_table_properties_colors_border-color);
+  overflow: hidden;
+}
+
+/* ==========================================
+   1. General Cell Dividers & Padding Defaults
+   ========================================== */
+
+.root .cell {
+  padding: var(--recursica_ui-kit_components_table_properties_row-padding)
+    var(--recursica_ui-kit_components_table_properties_padding);
+  border-bottom: var(
+      --recursica_ui-kit_components_table_properties_row-divider-size
+    )
+    solid
+    var(--recursica_ui-kit_components_table_properties_colors_row-divider-color);
+}
+
+.root .cell + .cell {
+  border-left: var(
+      --recursica_ui-kit_components_table_properties_column-divider-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_table_properties_colors_column-divider-color
+    );
+}
+
+/* ==========================================
+   2. Row Highlighting & Selection Styles
+   ========================================== */
+
+/* Striped rows */
+.root tbody .row:nth-of-type(even) .cell {
+  background-color: color-mix(
+    in srgb,
+    var(--recursica_ui-kit_components_table_properties_colors_striped-color)
+      calc(
+        var(
+            --recursica_ui-kit_components_table_properties_opacities_striped-opacity
+          ) *
+          100%
+      ),
+    transparent
+  );
+}
+
+/* MUI's TableRow applies its own default background when `selected` — reset it so only the
+   token-driven .cell background below shows (kept as a genuine `<tr selected>` for the
+   aria-selected/Mui-selected semantics MUI derives from it, just not its default coloring). */
+.root tbody .row:global(.Mui-selected) {
+  background-color: transparent;
+}
+
+/* Selected rows */
+.root tbody .row[data-selected="true"] .cell {
+  background-color: color-mix(
+    in srgb,
+    var(--recursica_ui-kit_components_table_properties_colors_selected-color)
+      calc(
+        var(
+            --recursica_ui-kit_components_table_properties_opacities_selected-opacity
+          ) *
+          100%
+      ),
+    transparent
+  );
+}
+
+/* Hover rows */
+/* Table's dedicated highlight-on-hover token was removed from the schema; hover feedback now
+   uses the generic cross-component overlay tokens instead. */
+.root tbody .row:hover .cell {
+  background-color: color-mix(
+    in srgb,
+    var(--recursica_brand_states_hover_color)
+      calc(var(--recursica_brand_states_hover_opacity) * 100%),
+    transparent
+  );
+}
+
+/* ==========================================
+   3. Table Headers (th)
+   ========================================== */
+
+.root thead .cell {
+  background-color: var(
+    --recursica_ui-kit_components_table-header_properties_colors_cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-header_properties_colors_text-color
+  );
+  padding: var(
+      --recursica_ui-kit_components_table-header_properties_padding-vertical
+    )
+    var(
+      --recursica_ui-kit_components_table-header_properties_padding-horizontal
+    );
+  margin-top: var(
+    --recursica_ui-kit_components_table-header_properties_vertical-margin
+  );
+  margin-bottom: var(
+    --recursica_ui-kit_components_table-header_properties_vertical-margin
+  );
+  border-bottom: var(
+      --recursica_ui-kit_components_table-header_properties_horizontal-divider-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_table-header_properties_colors_horizontal-divider-color
+    );
+
+  /* Unsorted text style by default */
+  font-family: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_table-header_properties_unsorted-text-style_text-transform
+  );
+}
+
+.root thead .cell + .cell {
+  border-left: var(
+      --recursica_ui-kit_components_table-header_properties_vertical-divider-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_table-header_properties_colors_vertical-divider-color
+    );
+}
+
+/* Unsorted specific state overrides */
+.root thead .cell:not([data-sorted="true"]) {
+  background-color: var(
+    --recursica_ui-kit_components_table-header_properties_colors_unsorted-cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-header_properties_colors_unsorted-text-color
+  );
+}
+
+/* Sorted specific state overrides */
+.root thead .cell[data-sorted="true"] {
+  background-color: var(
+    --recursica_ui-kit_components_table-header_properties_colors_sorted-cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-header_properties_colors_sorted-text-color
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_table-header_properties_sorted-text-style_text-transform
+  );
+}
+
+/* Disabled Header */
+.root thead .cell[data-disabled="true"] {
+  background-color: var(
+    --recursica_ui-kit_components_table-header_variants_states_disabled_properties_colors_cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-header_variants_states_disabled_properties_colors_text-color
+  );
+  opacity: var(
+    --recursica_ui-kit_components_table-header_variants_states_disabled_properties_opacity
+  );
+}
+
+/* Sort label — MUI's TableSortLabel renders its own arrow icon; re-color it to inherit the
+   cell's own text color (instead of MUI's default sort-label color) and size/space it with the
+   same tokens Mantine's own inline chevron uses. */
+.sortLabel {
+  color: inherit;
+}
+
+.sortLabel:global(.Mui-active) {
+  color: inherit;
+}
+
+.sortLabel :global(.MuiTableSortLabel-icon) {
+  width: var(--recursica_ui-kit_components_table-header_properties_icon-size);
+  height: var(--recursica_ui-kit_components_table-header_properties_icon-size);
+  margin-left: var(
+    --recursica_ui-kit_components_table-header_properties_label-sort-gap
+  );
+  color: inherit;
+}
+
+/* ==========================================
+   4. Table Cells (td)
+   ========================================== */
+
+.root tbody .cell {
+  background-color: var(
+    --recursica_ui-kit_components_table-cell_properties_colors_cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-cell_properties_colors_text-color
+  );
+  padding: var(
+      --recursica_ui-kit_components_table-cell_properties_padding-vertical
+    )
+    var(--recursica_ui-kit_components_table-cell_properties_padding-horizontal);
+  max-width: var(--recursica_ui-kit_components_table-cell_properties_max-width);
+
+  /* Standard text style */
+  font-family: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_line-height
+  );
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_text-align
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_table-cell_properties_text-style_text-transform
+  );
+}
+
+/* Currency formatted cell layout override */
+.root tbody .cell[data-currency="true"] {
+  font-family: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_line-height
+  );
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-align
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-transform
+  );
+}
+
+/* Disabled Cells */
+.root tbody .row[data-disabled="true"] .cell,
+.root tbody .cell[data-disabled="true"] {
+  background-color: var(
+    --recursica_ui-kit_components_table-cell_variants_states_disabled_properties_colors_cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-cell_variants_states_disabled_properties_colors_text-color
+  );
+  opacity: var(
+    --recursica_ui-kit_components_table-cell_variants_states_disabled_properties_opacity
+  );
+}
+
+/* ==========================================
+   5. Table Footers (tfoot td)
+   ========================================== */
+
+.root tfoot .cell {
+  background-color: var(
+    --recursica_ui-kit_components_table-footer_properties_colors_cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-footer_properties_colors_text-color
+  );
+  padding: var(
+      --recursica_ui-kit_components_table-footer_properties_padding-vertical
+    )
+    var(
+      --recursica_ui-kit_components_table-footer_properties_padding-horizontal
+    );
+  margin-top: var(
+    --recursica_ui-kit_components_table-footer_properties_vertical-margin
+  );
+  margin-bottom: var(
+    --recursica_ui-kit_components_table-footer_properties_vertical-margin
+  );
+  border-top: var(
+      --recursica_ui-kit_components_table-footer_properties_horizontal-divider-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_table-footer_properties_colors_horizontal-divider-color
+    );
+
+  /* Footer typography style */
+  font-family: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_table-footer_properties_text-style_text-transform
+  );
+}
+
+.root tfoot .cell + .cell {
+  border-left: var(
+      --recursica_ui-kit_components_table-footer_properties_vertical-divider-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_table-footer_properties_colors_vertical-divider-color
+    );
+}
+
+/* Currency formatted footer cell layout override */
+.root tfoot .cell[data-currency="true"] {
+  font-family: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_table-footer_properties_currency-style_text-transform
+  );
+}
+
+/* Disabled Footer Row/Cells */
+.root tfoot .row[data-disabled="true"] .cell,
+.root tfoot .cell[data-disabled="true"] {
+  background-color: var(
+    --recursica_ui-kit_components_table-footer_variants_states_disabled_properties_colors_cell-color
+  );
+  color: var(
+    --recursica_ui-kit_components_table-footer_variants_states_disabled_properties_colors_text-color
+  );
+  opacity: var(
+    --recursica_ui-kit_components_table-footer_variants_states_disabled_properties_opacity
+  );
 }

package/src/components/Table/Table.stories.tsx

@@ -47,3 +47,108 @@ export const Default: Story = {
     );
   },
 };
+
+export const SortedColumn: Story = {
+  render: () => {
+    const sorted = [...elements].sort((a, b) => a.mass - b.mass);
+    const rows = sorted.map((element) => (
+      <Table.Row key={element.name}>
+        <Table.Cell>{element.position}</Table.Cell>
+        <Table.Cell>{element.name}</Table.Cell>
+        <Table.Cell>{element.symbol}</Table.Cell>
+        <Table.Cell>{element.mass}</Table.Cell>
+      </Table.Row>
+    ));
+
+    return (
+      <Table.Container>
+        <Table>
+          <Table.Head>
+            <Table.Row>
+              <Table.Cell>Element position</Table.Cell>
+              <Table.Cell>Element name</Table.Cell>
+              <Table.Cell>Symbol</Table.Cell>
+              <Table.Cell sorted="asc">
+                <Table.SortLabel active direction="asc">
+                  Atomic mass
+                </Table.SortLabel>
+              </Table.Cell>
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>{rows}</Table.Body>
+        </Table>
+      </Table.Container>
+    );
+  },
+};
+
+export const SelectedAndDisabledRows: Story = {
+  render: () => (
+    <Table.Container>
+      <Table>
+        <Table.Head>
+          <Table.Row>
+            <Table.Cell>Element position</Table.Cell>
+            <Table.Cell>Element name</Table.Cell>
+            <Table.Cell>Symbol</Table.Cell>
+            <Table.Cell>Atomic mass</Table.Cell>
+          </Table.Row>
+        </Table.Head>
+        <Table.Body>
+          {elements.map((element, index) => (
+            <Table.Row
+              key={element.name}
+              selected={index === 0}
+              disabled={index === elements.length - 1}
+            >
+              <Table.Cell>{element.position}</Table.Cell>
+              <Table.Cell>{element.name}</Table.Cell>
+              <Table.Cell>{element.symbol}</Table.Cell>
+              <Table.Cell>{element.mass}</Table.Cell>
+            </Table.Row>
+          ))}
+        </Table.Body>
+      </Table>
+    </Table.Container>
+  ),
+};
+
+export const CurrencyColumnWithFooter: Story = {
+  render: () => {
+    const prices = [
+      { item: "Widget", price: 19.99 },
+      { item: "Gadget", price: 49.5 },
+      { item: "Gizmo", price: 9.25 },
+    ];
+    const total = prices.reduce((sum, row) => sum + row.price, 0);
+
+    return (
+      <Table.Container>
+        <Table>
+          <Table.Head>
+            <Table.Row>
+              <Table.Cell>Item</Table.Cell>
+              <Table.Cell>Price</Table.Cell>
+            </Table.Row>
+          </Table.Head>
+          <Table.Body>
+            {prices.map((row) => (
+              <Table.Row key={row.item}>
+                <Table.Cell>{row.item}</Table.Cell>
+                <Table.Cell variant="currency">
+                  ${row.price.toFixed(2)}
+                </Table.Cell>
+              </Table.Row>
+            ))}
+          </Table.Body>
+          <Table.Footer>
+            <Table.Row>
+              <Table.Cell>Total</Table.Cell>
+              <Table.Cell variant="currency">${total.toFixed(2)}</Table.Cell>
+            </Table.Row>
+          </Table.Footer>
+        </Table>
+      </Table.Container>
+    );
+  },
+};