@usefragments/ui 1.1.1 → 1.3.0

package/src/components/DataTable/DataTable.module.scss

@@ -3,7 +3,10 @@
 
 .wrapper {
   --fui-data-table-bg: var(--fui-table-bg, var(--fui-bg-elevated, #{$fui-bg-elevated}));
-  --fui-data-table-header-bg: var(--fui-table-header-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent));
+  --fui-data-table-header-bg: var(
+    --fui-table-header-bg,
+    color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 5%, transparent)
+  );
 
   overflow-x: auto;
   -webkit-overflow-scrolling: touch;
@@ -69,7 +72,10 @@
   user-select: none;
   // Opaque so the sticky header doesn't let rows bleed through on scroll,
   // while inheriting the table surface instead of forcing the page background.
-  background: var(--fui-data-table-header-bg);
+  background: var(
+    --fui-data-table-header-bg,
+    var(--fui-data-table-bg, var(--fui-bg-primary, #{$fui-bg-primary}))
+  );
 
   &:first-child {
     border-top-left-radius: var(--fui-radius-md, $fui-radius-md);
@@ -142,6 +148,10 @@
 
 // Body
 .tbody {
+  .td {
+    padding-top: var(--fui-space-2, $fui-space-2);
+    padding-bottom: var(--fui-space-2, $fui-space-2);
+  }
 }
 
 .row {
@@ -174,11 +184,18 @@
 }
 
 .selected {
-  background-color: 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}));
+  background-color: 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 {
-    background-color: var(--fui-table-row-selected-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent));
+    background-color: var(
+      --fui-table-row-selected-bg,
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent)
+    );
   }
 }
 
@@ -204,10 +221,16 @@
   }
 
   .selected {
-    background-color: var(--fui-table-row-selected-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 8%, transparent));
+    background-color: var(
+      --fui-table-row-selected-bg,
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 8%, transparent)
+    );
 
     &:hover {
-      background-color: var(--fui-table-row-selected-bg, color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent));
+      background-color: var(
+        --fui-table-row-selected-bg,
+        color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent)
+      );
     }
   }
 }
@@ -216,7 +239,7 @@
 .bordered {
   border: 1px solid var(--fui-table-border, var(--fui-border, #{$fui-border}));
   border-radius: var(--fui-radius-md, $fui-radius-md);
-  background: var(--fui-data-table-bg);
+  background: var(--fui-data-table-bg, var(--fui-bg-primary, #{$fui-bg-primary}));
   overflow: hidden;
 }
 

package/src/components/DataTable/index.tsx

@@ -5,13 +5,40 @@ import styles from "./DataTable.module.scss";
 import { Checkbox } from "../Checkbox";
 import { ExpandIcon, SortAscIcon, SortDescIcon, SortIcon } from "./DataTable.icons";
 import { DataTableSkeletonRows, useArrowKeyRowNav } from "./DataTable.support";
-import {
-  flexRender,
-  getCoreRowModel,
-  getExpandedRowModel,
-  getSortedRowModel,
-  useReactTable,
-} from "@tanstack/react-table";
+
+// ============================================
+// Dependency (@tanstack/react-table) — lazy-required
+// ============================================
+// `@tanstack/react-table` is an optional peer dependency. It is pulled in via a
+// synchronous `require()` (mirroring Chart/Editor) rather than a static ESM
+// import so a bundler's dep-optimizer (e.g. Vite dev) does not create a static
+// import edge for consumers who only use, say, `{ Button }`. `require` resolves
+// synchronously, so `useReactTable` (a hook) is available before the first hook
+// call and hook order stays stable across renders. When the peer is absent the
+// component throws a friendly install message on first render.
+
+type ReactTableModule = {
+  flexRender: (...args: any[]) => React.ReactNode;
+  getCoreRowModel: (...args: any[]) => any;
+  getExpandedRowModel: (...args: any[]) => any;
+  getSortedRowModel: (...args: any[]) => any;
+  useReactTable: (options: any) => any;
+};
+
+let _reactTable: ReactTableModule | null = null;
+let _reactTableLoaded = false;
+let _reactTableFailed = false;
+
+function loadReactTable() {
+  if (_reactTableLoaded) return;
+  _reactTableLoaded = true;
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    _reactTable = require("@tanstack/react-table") as ReactTableModule;
+  } catch {
+    _reactTableFailed = true;
+  }
+}
 
 /** Horizontal alignment for a column's header + cells. */
 export type ColumnAlign = "left" | "right" | "center";
@@ -50,15 +77,6 @@ export type DataTableRowClickEvent =
 
 export type DataTableColumn<T> = ColumnDef<T, unknown>;
 
-// ============================================
-// Dependency (@tanstack/react-table)
-// ============================================
-// Statically imported (ESM) so DataTable works in every bundler, including
-// browser SPAs (Vite) where `require` is unavailable. `useReactTable` is a
-// hook and must resolve synchronously on first render. The package is an
-// optional peer dep + `sideEffects: false`, so this import is tree-shaken
-// out of bundles that never import DataTable.
-
 export interface DataTableProps<T> extends Omit<React.HTMLAttributes<HTMLTableElement>, "onClick"> {
   /** Column definitions */
   columns: DataTableColumn<T>[];
@@ -186,6 +204,16 @@ function DataTableRoot<T>({
   "aria-describedby": ariaDescribedBy,
   ...htmlProps
 }: DataTableProps<T>) {
+  loadReactTable();
+  if (_reactTableFailed || !_reactTable) {
+    throw new Error(
+      "[@usefragments/ui] DataTable: @tanstack/react-table is not installed. " +
+        "Install it with: npm install @tanstack/react-table"
+    );
+  }
+  const { flexRender, getCoreRowModel, getExpandedRowModel, getSortedRowModel, useReactTable } =
+    _reactTable;
+
   const tableRef = React.useRef<HTMLTableElement>(null);
   useArrowKeyRowNav(tableRef, !!onRowClick);
 

package/src/components/Main/Main.contract.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Main",
+  "description": "Canonical page composition owning gutter, measure, and vertical rhythm.",
+  "category": "layout",
+  "tags": ["main", "page", "layout", "compound"],
+  "status": "stable",
+  "sourcePath": "src/components/Main/index.tsx",
+  "exportName": "Main",
+  "propsSummary": [
+    "children: node (required)",
+    "measure: full|narrow (default: full)",
+    "as: semantic element (default: main)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Page regions composed from Main.Header, Main.Description, Main.Content, and Main.Footer",
+      "required": true
+    },
+    "measure": {
+      "type": "enum",
+      "description": "Maximum width applied to the page composition",
+      "default": "full",
+      "required": false,
+      "values": ["full", "narrow"]
+    },
+    "as": {
+      "type": "enum",
+      "description": "Semantic HTML element rendered by the root",
+      "default": "main",
+      "required": false,
+      "values": [
+        "div",
+        "section",
+        "nav",
+        "article",
+        "aside",
+        "header",
+        "footer",
+        "main",
+        "ul",
+        "ol"
+      ]
+    }
+  },
+  "usage": {
+    "when": ["Composing a page header, description, content, and footer"],
+    "whenNot": ["Application shell navigation (use AppShell)"],
+    "guidelines": [
+      "Use one Main gutter owner per page",
+      "Compose page regions with Main.Header, Main.Description, Main.Content, and Main.Footer"
+    ],
+    "accessibility": [
+      "Use the default main element unless an existing shell already owns the main landmark"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Full Measure",
+      "description": "Page composition that uses the full available canvas",
+      "code": "<Main measure=\"full\">\n  <Main.Header>Page statement</Main.Header>\n  <Main.Description>Supporting page context.</Main.Description>\n  <Main.Content>Page content</Main.Content>\n  <Main.Footer>Page actions</Main.Footer>\n</Main>"
+    },
+    {
+      "name": "Narrow Measure",
+      "description": "Readable page composition constrained to the canonical 800px measure",
+      "code": "<Main measure=\"narrow\">\n  <Main.Header>Settings</Main.Header>\n  <Main.Description>Manage the workspace contract.</Main.Description>\n  <Main.Content>Settings content</Main.Content>\n  <Main.Footer>Save changes</Main.Footer>\n</Main>"
+    }
+  ],
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": ["Header", "Description", "Content", "Footer"]
+  },
+  "provenance": {
+    "source": "manual",
+    "verified": true,
+    "frameworkSupport": "native"
+  }
+}

package/src/components/Main/Main.module.scss

@@ -0,0 +1,31 @@
+@use "../../tokens/variables" as *;
+
+$fui-main-measure-narrow: 57.143rem !default;
+
+.root {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  min-height: 100%;
+  margin-inline: auto;
+  padding: var(--fui-space-3, $fui-space-3);
+}
+
+.full {
+  max-width: none;
+}
+
+.narrow {
+  max-width: $fui-main-measure-narrow;
+}
+
+.header,
+.description,
+.content,
+.footer {
+  min-width: 0;
+}
+
+.description {
+  max-width: 68ch;
+}

package/src/components/Main/index.tsx

@@ -0,0 +1,124 @@
+import * as React from "react";
+import { Stack, type StackProps } from "../Stack";
+import styles from "./Main.module.scss";
+
+export type MainMeasure = "full" | "narrow";
+
+export interface MainProps extends Omit<StackProps, "as" | "children" | "direction" | "gap"> {
+  as?: StackProps["as"];
+  children: React.ReactNode;
+  /** Maximum readable width for the page content. */
+  measure?: MainMeasure;
+}
+
+export type MainRegionProps = StackProps;
+
+function joinClasses(...classes: Array<string | false | undefined>) {
+  return classes.filter(Boolean).join(" ");
+}
+
+const MainRoot = React.forwardRef<HTMLElement, MainProps>(function MainRoot(
+  { as = "main", children, className, measure = "full", ...htmlProps },
+  ref
+) {
+  return (
+    <Stack
+      {...htmlProps}
+      ref={ref}
+      as={as}
+      direction="column"
+      gap="lg"
+      className={joinClasses(
+        styles.root,
+        measure === "narrow" ? styles.narrow : styles.full,
+        className
+      )}
+      data-main-measure={measure}
+    >
+      {children}
+    </Stack>
+  );
+});
+
+function MainHeader({
+  as = "header",
+  direction = "column",
+  gap = "sm",
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      className={joinClasses(styles.header, className)}
+    />
+  );
+}
+
+function MainDescription({
+  as = "div",
+  direction = "column",
+  gap = "xs",
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      className={joinClasses(styles.description, className)}
+    />
+  );
+}
+
+function MainContent({
+  as = "div",
+  direction = "column",
+  gap = "lg",
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      className={joinClasses(styles.content, className)}
+    />
+  );
+}
+
+function MainFooter({
+  as = "footer",
+  direction = "row",
+  gap = "sm",
+  justify = "end",
+  wrap = true,
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      justify={justify}
+      wrap={wrap}
+      className={joinClasses(styles.footer, className)}
+    />
+  );
+}
+
+export const Main = Object.assign(MainRoot, {
+  Header: MainHeader,
+  Description: MainDescription,
+  Content: MainContent,
+  Footer: MainFooter,
+});

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

@@ -108,14 +108,24 @@
 
 // Body
 .tbody {
+  .td {
+    padding-top: var(--fui-space-2, $fui-space-2);
+    padding-bottom: var(--fui-space-2, $fui-space-2);
+  }
 }
 
 .row {
-  --fui-table-row-base-bg: var(--fui-table-bg, var(--fui-main-bg, var(--fui-bg-primary, #{$fui-bg-primary})));
+  --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);
+  background-color: var(
+    --fui-table-row-bg,
+    var(--fui-table-row-base-bg, var(--fui-bg-primary, #{$fui-bg-primary}))
+  );
   transition: background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:last-child {
@@ -128,11 +138,18 @@
 }
 
 .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}));
+  --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));
+    --fui-table-row-bg: var(
+      --fui-table-row-selected-bg,
+      color-mix(in srgb, var(--fui-text-primary, #{$fui-text-primary}) 10%, transparent)
+    );
   }
 }
 

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 heading links with a continuous hierarchy rail that branches in for nested groups and back out for parent items, with active-segment highlighting.",
+  "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.",
   "category": "navigation",
   "tags": [
     "toc",
@@ -84,7 +84,7 @@
     },
     {
       "name": "Nested Groups",
-      "description": "Filterable list grouped by category — the hierarchy rail branches in for children and back out for the next parent item",
+      "description": "Filterable list grouped by category with clear nested indentation",
       "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>"
     },
     {
@@ -126,7 +126,7 @@
       "hideTitle: boolean - hide the title",
       "label: string - aria-label for nav landmark",
       "TableOfContents.Item id: string - heading ID to link to",
-      "TableOfContents.Item active: boolean - highlight as current (also paints the rail segment in accent)",
+      "TableOfContents.Item active: boolean - highlight the current item with ink and weight",
       "TableOfContents.Item indent: boolean - legacy depth=1 indent for flat lists; prefer Group for new code",
       "TableOfContents.Item leading/trailing: node - optional adornments before/after the label",
       "TableOfContents.Group label: node - header text for the group",
@@ -135,22 +135,12 @@
       "TableOfContents.Group trailing/leading: node - optional adornments on the group header row",
       "Forwards standard nav/anchor DOM props; TableOfContents.Item onClick can prevent default smooth scroll"
     ],
-    "a11yRules": [
-      "A11Y_NAV_LANDMARK",
-      "A11Y_ARIA_CURRENT",
-      "A11Y_ARIA_EXPANDED"
-    ]
+    "a11yRules": ["A11Y_NAV_LANDMARK", "A11Y_ARIA_CURRENT", "A11Y_ARIA_EXPANDED"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Item",
-      "Group"
-    ],
-    "requiredChildren": [
-      "Item",
-      "Group"
-    ],
+    "subComponents": ["Item", "Group"],
+    "requiredChildren": ["Item", "Group"],
     "commonPatterns": [
       "<TableOfContents>{headings.map(h => <TableOfContents.Item key={h.id} id={h.id} active={activeId === h.id} indent={h.level === 3}>{h.text}</TableOfContents.Item>)}</TableOfContents>",
       "<TableOfContents>{groups.map(g => <TableOfContents.Group key={g.label} label={g.label} trailing={g.count}>{g.items.map(i => <TableOfContents.Item key={i.id} id={i.id} active={activeId === i.id}>{i.label}</TableOfContents.Item>)}</TableOfContents.Group>)}</TableOfContents>"

package/src/components/TableOfContents/TableOfContents.module.scss

@@ -2,21 +2,17 @@
 @use "../../tokens/mixins" as *;
 
 // ============================================
-// Single-rail "snake" geometry
+// Dormant single-rail geometry
 // ============================================
 //
-// All <li>s are siblings in one flat <ul>. Each carries data-depth, which
-// sets the X of its per-row rail (drawn as `::before`). At depth-0 → depth-1
-// transitions an opening elbow is drawn via `::after` on the depth-1 item;
-// at depth-1 → depth-0 transitions a closing elbow is drawn via `::after`
-// on the depth-0 item. Active items paint their rail in accent; the curves
-// into and out of an active depth-1 also flip to accent so the section
-// reads as one continuous coloured snake.
+// The public default is the quiet, flush index disabled below. These values
+// retain the existing optional rail geometry without making its inset part of
+// the default list contract.
 
 $rail-x-0: 7px;
 $rail-indent: 14px;
 $rail-x-1: 21px; // = $rail-x-0 + $rail-indent
-$rail-pad: 18px; // <ul> padding-left
+$rail-pad: 18px; // optional rail inset; never default <ul> padding
 $rail-curve: 14px;
 $rail-thickness: 1px;
 $rail-active-thickness: 1px;
@@ -44,11 +40,13 @@ $rail-from-item-1: $rail-x-1 - $rail-pad; //  3px
   padding: 0 var(--fui-space-2, $fui-space-2);
 }
 
+// Plain index (the design-system default, see below) draws no rail, so the
+// list is flush — its links/group headers share the same inline inset as
+// .title. A future rail variant must reinstate its own $rail-pad inset.
 .list {
   list-style: none;
   margin: 0;
   padding: 0;
-  padding-left: $rail-pad;
   position: relative;
   display: flex;
   flex-direction: column;
@@ -210,9 +208,8 @@ $rail-from-item-1: $rail-x-1 - $rail-pad; //  3px
   }
 }
 
-// Depth-1 link sits to the right of the rail (which lives at x=3px from li edge).
-// Margin pushes the link's hover/active background past the rail so it doesn't
-// paint over the line. Reduced padding-left keeps the text in the same x-position.
+// Depth-1 links carry the hierarchy indent while the top-level index remains
+// flush with the title and group headers.
 [data-depth="1"] .link {
   margin-left: var(--fui-space-2, $fui-space-2);
   padding-left: $rail-indent;