@usefragments/ui 1.5.4 → 1.7.0

package/src/components/Table/Table.module.scss

@@ -1,135 +1,72 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/table-chrome" as table-chrome;
 
 .wrapper {
+  min-inline-size: 0;
+  max-inline-size: 100%;
   overflow-x: auto;
   -webkit-overflow-scrolling: touch;
 }
 
 .table {
-  width: 100%;
-  border-collapse: collapse;
-  font-family: var(--fui-font-sans, $fui-font-sans);
-  -webkit-font-smoothing: antialiased;
-  -moz-osx-font-smoothing: grayscale;
+  @include table-chrome.root;
+
+  @each $density in ("compact", "regular", "relaxed") {
+    &[data-density="#{$density}"] {
+      @include table-chrome.density($density);
+    }
+  }
 }
 
-// Caption for accessibility
 .caption {
-  padding: var(--fui-space-3, $fui-space-3) 0;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  color: var(--fui-text-secondary, $fui-text-secondary);
-  text-align: left;
-  caption-side: top;
+  @include table-chrome.caption;
 }
 
-// Visually hidden caption (screen readers only)
 .captionHidden {
   @include visually-hidden;
 }
 
-// Size variants
-.sm {
-  .th,
-  .td {
-    padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
-    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  }
-}
-
-.md {
-  .th,
-  .td {
-    padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
-    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  }
-}
-
-// Dashboard-dense rows — 36px tall, 14px horizontal padding, 12px text.
-// Hairline dividers only; no striping. Header sits flush on the same rail
-// as rows so it reads as part of the list, not a separate band.
-.compact {
-  .th,
-  .td {
-    padding: 0 var(--fui-space-2, $fui-space-2);
-    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-    height: 2.571rem; // 36px
-    line-height: var(--fui-line-height-tight, $fui-line-height-tight);
-  }
-
-  .th {
-    font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
-    color: var(--fui-text-tertiary, $fui-text-tertiary);
-    text-transform: uppercase;
-    letter-spacing: var(--fui-letter-spacing-wide, $fui-letter-spacing-wide);
-    font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  }
-}
-
-// Tabular numerals on a cell — digits align in columns so updating numbers
-// don't jitter. Essential for numeric columns, timestamps, currencies.
 .tabular {
   font-variant-numeric: tabular-nums;
 }
 
-// Header
 .thead {
   position: sticky;
-  top: 0;
+  inset-block-start: 0;
   z-index: 1;
 
   > tr {
-    border-bottom: 1px solid var(--fui-table-header-border, var(--fui-border, #{$fui-border}));
+    @include table-chrome.row;
   }
 }
 
 .th {
-  text-align: left;
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  color: var(--fui-text-secondary, $fui-text-secondary);
-  white-space: nowrap;
-  vertical-align: middle;
-
-  &:first-child {
-    border-top-left-radius: var(--fui-radius-md, $fui-radius-md);
-  }
+  @include table-chrome.header-cell;
 
-  &:last-child {
-    border-top-right-radius: var(--fui-radius-md, $fui-radius-md);
-  }
+  white-space: nowrap;
 }
 
 .headerContent {
   display: flex;
   align-items: center;
-  gap: var(--fui-space-1, $fui-space-1);
-}
-
-// Body
-.tbody {
-  .td {
-    padding-top: var(--fui-space-2, $fui-space-2);
-    padding-bottom: var(--fui-space-2, $fui-space-2);
-  }
+  gap: var(--fui-raw-space-4, 4px);
 }
 
 .row {
+  @include table-chrome.row;
+
   --fui-table-row-base-bg: var(
     --fui-table-bg,
     var(--fui-main-bg, var(--fui-bg-primary, #{$fui-bg-primary}))
   );
   --fui-table-row-bg: var(--fui-table-row-base-bg);
 
-  border-bottom: 1px solid var(--fui-table-border, var(--fui-border, #{$fui-border}));
-  background-color: var(
-    --fui-table-row-bg,
-    var(--fui-table-row-base-bg, var(--fui-bg-primary, #{$fui-bg-primary}))
-  );
+  background-color: var(--fui-table-row-bg);
   transition: background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:last-child {
-    border-bottom: none;
+    border-block-end: 0;
   }
 
   &:hover {
@@ -137,39 +74,43 @@
   }
 }
 
+.td {
+  @include table-chrome.body-cell;
+}
+
+// Unbordered ledger edge: the first column starts at the surrounding surface's
+// own inset so a table inside a card reads as part of the card, not a box within
+// a box. A bordered table owns its frame and keeps the recipe's inline inset.
+.wrapper:not(.bordered) > .table {
+  > .thead > .row > .th:first-child,
+  > .tbody > .row > .td:first-child,
+  > .tfoot > .row > .td:first-child {
+    padding-inline-start: 0;
+  }
+}
+
 .selected {
   --fui-table-row-bg: var(
     --fui-table-row-selected-bg,
     color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 8%, transparent)
   );
-  box-shadow: inset 1px 0 0
-    var(--fui-table-row-selected-border, var(--fui-border-strong, #{$fui-border-strong}));
 
-  &:hover {
-    --fui-table-row-bg: var(
-      --fui-table-row-selected-bg,
-      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent)
-    );
+  .td:first-child {
+    box-shadow: inset var(--fui-table-divider-size) 0 0
+      var(--fui-table-row-selected-border, var(--fui-border-strong, #{$fui-border-strong}));
   }
-}
 
-.td {
-  color: var(--fui-text-primary, $fui-text-primary);
-  vertical-align: middle;
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  &:dir(rtl) .td:first-child {
+    box-shadow: inset calc(-1 * var(--fui-table-divider-size)) 0 0
+      var(--fui-table-row-selected-border, var(--fui-border-strong, #{$fui-border-strong}));
+  }
 }
 
-// Footer
 .tfoot {
-  border-top: 1px solid var(--fui-table-header-border, var(--fui-border, #{$fui-border}));
-
-  .td,
-  .th {
-    font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  }
+  border-block-start: var(--fui-table-divider-size) solid
+    var(--fui-table-header-border, var(--fui-border, #{$fui-border}));
 }
 
-// Striped rows
 .striped {
   .tbody .row:nth-child(even),
   .tbody .row[data-band="alt"] {
@@ -181,41 +122,21 @@
   }
 }
 
-// Bordered
 .bordered {
-  border: 1px solid var(--fui-table-border, var(--fui-border, #{$fui-border}));
+  overflow-x: auto;
+  overflow-y: hidden;
+  border: var(--fui-table-divider-size, var(--fui-stroke-hairline, $fui-stroke-hairline)) solid
+    var(--fui-table-border, var(--fui-border, #{$fui-border}));
   border-radius: var(--fui-radius-md, $fui-radius-md);
-  overflow: hidden;
-}
-
-// Responsive: allow horizontal scroll on small screens
-@include below-sm {
-  .wrapper {
-    margin-left: calc(-1 * var(--fui-space-4, $fui-space-4));
-    margin-right: calc(-1 * var(--fui-space-4, $fui-space-4));
-    padding-left: var(--fui-space-4, $fui-space-4);
-    padding-right: var(--fui-space-4, $fui-space-4);
-  }
 }
 
-// ============================================
-// Accessibility: High Contrast Mode
-// ============================================
-
 @media (prefers-contrast: more) {
+  .row,
   .thead > tr {
-    border-bottom-width: 2px;
-  }
-
-  .row {
-    border-bottom-width: 2px;
+    border-block-end-color: CanvasText;
   }
 }
 
-// ============================================
-// Accessibility: Reduced Motion
-// ============================================
-
 @media (prefers-reduced-motion: reduce) {
   .row {
     transition: none;

package/src/components/Table/index.tsx

@@ -1,6 +1,11 @@
 "use client";
 
 import * as React from "react";
+import {
+  resolveTableDensity,
+  type LegacyTableSize,
+  type TableDensity,
+} from "../../recipes/table-chrome";
 import styles from "./Table.module.scss";
 
 // ============================================
@@ -8,10 +13,10 @@ import styles from "./Table.module.scss";
 // ============================================
 
 export interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
-  /** Size variant. `compact` gives dense 36px-row dashboard lists with 12px
-   * text and hairline dividers — use when the table is a status surface,
-   * not a reading experience. */
-  size?: "sm" | "md" | "compact";
+  /** Canonical row density. */
+  density?: TableDensity;
+  /** @deprecated Use density. Retained until the next major-version review. */
+  size?: LegacyTableSize;
   /** Show alternating row backgrounds */
   striped?: boolean;
   /** Wrap table in a bordered container */
@@ -158,6 +163,7 @@ function TableCaption({
 
 function TableRoot({
   size = "md",
+  density,
   striped = false,
   bordered = false,
   wrapperClassName,
@@ -166,7 +172,8 @@ function TableRoot({
   children,
   ...htmlProps
 }: TableProps) {
-  const tableClasses = [styles.table, styles[size], striped && styles.striped, className]
+  const resolvedDensity = resolveTableDensity({ density, size });
+  const tableClasses = [styles.table, striped && styles.striped, className]
     .filter(Boolean)
     .join(" ");
 
@@ -182,7 +189,7 @@ function TableRoot({
         .filter(Boolean)
         .join(" ")}
     >
-      <table className={tableClasses} {...htmlProps}>
+      <table className={tableClasses} {...htmlProps} data-density={resolvedDensity}>
         {children}
       </table>
     </div>

package/src/components/TableOfContents/TableOfContents.contract.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "TableOfContents",
-  "description": "Sticky sidebar navigation for long-form content or filterable lists. Renders a quiet, flush index with nested indentation and an ink-weight active state.",
+  "description": "Indexes a long page and marks the section currently in view.",
   "category": "navigation",
   "tags": [
     "toc",
@@ -20,7 +20,8 @@
     "children: node (required)",
     "label: string (default: Table of contents)",
     "title: string (default: On This Page)",
-    "hideTitle: boolean (default: false)"
+    "hideTitle: boolean (default: false)",
+    "hideSubItems: boolean (default: false)"
   ],
   "props": {
     "children": {
@@ -45,28 +46,34 @@
       "description": "Hide the visible title",
       "default": "false",
       "required": false
+    },
+    "hideSubItems": {
+      "type": "boolean",
+      "description": "Hide indented items and nested groups",
+      "default": "false",
+      "required": false
     }
   },
   "usage": {
     "when": [
-      "Long-form content pages (docs, blog posts, articles)",
-      "Component documentation with multiple sections",
-      "Filterable list sidebars where items are grouped by category",
-      "Any page with 3+ headings or nested sections that benefit from quick navigation"
+      "Docs, articles, and other long reads",
+      "Reference pages with many sections",
+      "Filterable sidebars grouped by category",
+      "Anything past three headings"
     ],
     "whenNot": [
-      "Short pages with only 1-2 sections",
-      "Primary site navigation (use Sidebar or Header)",
-      "Step-by-step flows (use Stepper)"
+      "Pages with one or two sections",
+      "Site navigation (use Sidebar or Header)",
+      "Steps in an order (use Stepper)"
     ],
     "guidelines": [
-      "Pair with a scroll spy hook (e.g., IntersectionObserver) to track active heading",
-      "Use TableOfContents.Group to nest items under a labeled, optionally-collapsible parent",
-      "The legacy `indent` boolean on Item is preserved for back-compat; prefer Group for new code",
-      "Place in a sticky aside for best UX",
-      "Heading IDs must match between TOC items and the actual DOM headings",
-      "TableOfContents.Item performs smooth scrolling by default; call event.preventDefault() in onClick to override",
-      "Group is uncontrolled (defaultOpen=true) by default; pass open + onOpenChange for controlled state"
+      "Drive the active item from an IntersectionObserver scroll spy",
+      "Sub-items show by default — pass hideSubItems for a compact index",
+      "Group nests items under a labelled, optionally collapsible parent",
+      "Item ids must match the real heading ids",
+      "Items smooth-scroll — call preventDefault() in onClick to take over",
+      "Group is uncontrolled and open by default; pass open and onOpenChange to drive it",
+      "The legacy indent boolean still works; prefer Group in new code"
     ],
     "accessibility": [
       "Uses <nav aria-label=\"Table of contents\"> for landmark navigation",
@@ -79,27 +86,32 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Basic table of contents with section links",
+      "description": "Sections and their subsections, indented.",
       "code": "<TableOfContents>\n  <TableOfContents.Item id=\"introduction\">Introduction</TableOfContents.Item>\n  <TableOfContents.Item id=\"getting-started\">Getting Started</TableOfContents.Item>\n  <TableOfContents.Item id=\"installation\" indent>Installation</TableOfContents.Item>\n  <TableOfContents.Item id=\"configuration\" indent>Configuration</TableOfContents.Item>\n  <TableOfContents.Item id=\"api-reference\">API Reference</TableOfContents.Item>\n  <TableOfContents.Item id=\"examples\">Examples</TableOfContents.Item>\n</TableOfContents>"
     },
+    {
+      "name": "Top-level Only",
+      "description": "Drops subsections when the index would crowd.",
+      "code": "<TableOfContents hideSubItems>\n  <TableOfContents.Item id=\"overview\">Overview</TableOfContents.Item>\n  <TableOfContents.Item id=\"basic-usage\" indent>Basic usage</TableOfContents.Item>\n  <TableOfContents.Item id=\"advanced-usage\" indent>Advanced usage</TableOfContents.Item>\n  <TableOfContents.Item id=\"accessibility\">Accessibility</TableOfContents.Item>\n</TableOfContents>"
+    },
     {
       "name": "Nested Groups",
-      "description": "Filterable list grouped by category with clear nested indentation",
+      "description": "Collapsible categories with counts.",
       "code": "<TableOfContents title=\"Components\">\n  <TableOfContents.Item id=\"all\" active>All</TableOfContents.Item>\n  <TableOfContents.Group label=\"Primitives\" trailing={<span>3</span>}>\n    <TableOfContents.Item id=\"button\">Button</TableOfContents.Item>\n    <TableOfContents.Item id=\"card\">Card</TableOfContents.Item>\n    <TableOfContents.Item id=\"input\">Input</TableOfContents.Item>\n  </TableOfContents.Group>\n  <TableOfContents.Group label=\"Custom\" defaultOpen={false}>\n    <TableOfContents.Item id=\"features\">Features</TableOfContents.Item>\n    <TableOfContents.Item id=\"plans\">Plans</TableOfContents.Item>\n  </TableOfContents.Group>\n</TableOfContents>"
     },
     {
       "name": "With Active Item",
-      "description": "Active state highlighting the current section",
+      "description": "The current section stays marked while you read.",
       "code": "<TableOfContents>\n  <TableOfContents.Item id=\"overview\">Overview</TableOfContents.Item>\n  <TableOfContents.Item id=\"setup\" active>Setup</TableOfContents.Item>\n  <TableOfContents.Item id=\"usage\" indent>Basic Usage</TableOfContents.Item>\n  <TableOfContents.Item id=\"advanced\" indent>Advanced</TableOfContents.Item>\n  <TableOfContents.Item id=\"props\">Props</TableOfContents.Item>\n  <TableOfContents.Item id=\"accessibility\">Accessibility</TableOfContents.Item>\n</TableOfContents>"
     },
     {
       "name": "Custom Title",
-      "description": "Table of contents with a custom title",
+      "description": "Any heading in place of the default.",
       "code": "<TableOfContents title=\"Contents\">\n  <TableOfContents.Item id=\"chapter-1\">Chapter 1: The Beginning</TableOfContents.Item>\n  <TableOfContents.Item id=\"chapter-2\">Chapter 2: The Middle</TableOfContents.Item>\n  <TableOfContents.Item id=\"chapter-3\">Chapter 3: The End</TableOfContents.Item>\n</TableOfContents>"
     },
     {
       "name": "No Title",
-      "description": "Table of contents without a visible title",
+      "description": "Bare list where the surrounding layout already says enough.",
       "code": "<TableOfContents hideTitle>\n  <TableOfContents.Item id=\"section-a\">Section A</TableOfContents.Item>\n  <TableOfContents.Item id=\"section-b\" active>Section B</TableOfContents.Item>\n  <TableOfContents.Item id=\"section-c\">Section C</TableOfContents.Item>\n</TableOfContents>"
     }
   ],
@@ -124,6 +136,7 @@
     "propsSummary": [
       "title: string - visible heading (default \"On This Page\")",
       "hideTitle: boolean - hide the title",
+      "hideSubItems: boolean - hide indented items and nested groups (default false)",
       "label: string - aria-label for nav landmark",
       "TableOfContents.Item id: string - heading ID to link to",
       "TableOfContents.Item active: boolean - highlight the current item with ink and weight",