@usefragments/ui 1.6.0 → 1.7.0

package/src/components/ConversationList/ConversationList.contract.json

@@ -1,16 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "ConversationList",
-  "description": "Scrollable message container with auto-scroll and history loading",
+  "description": "Stacks chat messages in a scroller that follows new arrivals.",
   "category": "ai",
-  "tags": [
-    "conversation",
-    "chat",
-    "messages",
-    "scroll",
-    "ai",
-    "list"
-  ],
+  "tags": ["conversation", "chat", "messages", "scroll", "ai", "list"],
   "status": "stable",
   "sourcePath": "src/components/ConversationList/index.tsx",
   "exportName": "ConversationList",
@@ -73,24 +66,24 @@
   },
   "usage": {
     "when": [
-      "Building a chat interface with multiple messages",
-      "Need auto-scroll behavior when new messages arrive",
-      "Require infinite scroll for loading message history",
-      "Want date separators between message groups"
+      "Chat interfaces holding many messages",
+      "Transcripts that should follow new arrivals",
+      "Paging back through older message history",
+      "Runs of messages grouped day by day"
     ],
     "whenNot": [
-      "Simple list of items without chat context (use List)",
-      "Single message display (use Message directly)",
-      "Non-scrolling message layout"
+      "Plain item lists with no chat context (use List)",
+      "A single message (use Message directly)",
+      "Layouts that never scroll"
     ],
     "guidelines": [
-      "Use autoScroll=\"smart\" for best UX (only auto-scrolls when near bottom)",
-      "Set showAvatars={false} for avatarless transcripts; messages remove their outer inline inset automatically",
-      "Conversation chrome uses neutral surfaces and the body foreground; reserve brand accent for actions or semantic state",
-      "Implement onScrollTop for loading older messages",
-      "ConversationList composes your onScroll handler with internal auto-scroll/history logic",
-      "Provide an emptyState for new conversations",
-      "Use DateSeparator between messages from different days"
+      "autoScroll=\"smart\" follows only when the reader is already near the bottom",
+      "showAvatars={false} drops the avatar gutter and the inset that goes with it",
+      "Chrome stays on neutral surfaces; reserve accent for actions and semantic state",
+      "Implement onScrollTop to page in older messages",
+      "Your onScroll handler composes with the internal auto-scroll and history logic",
+      "Give new conversations an emptyState",
+      "Put a DateSeparator between messages from different days"
     ],
     "accessibility": [
       "Uses proper ARIA roles for separators",
@@ -102,28 +95,33 @@
   "examples": [
     {
       "name": "Basic",
-      "description": "Simple conversation with messages",
+      "description": "Three turns stacked in reading order.",
       "code": "<ConversationList>\n  <Message role=\"user\">\n    <Message.Content>Hello!</Message.Content>\n  </Message>\n  <Message role=\"assistant\">\n    <Message.Content>Hi there! How can I help you today?</Message.Content>\n  </Message>\n  <Message role=\"user\">\n    <Message.Content>Can you explain React hooks?</Message.Content>\n  </Message>\n</ConversationList>"
     },
     {
       "name": "With Date Separators",
-      "description": "Messages grouped by date",
+      "description": "A labelled rule marks where one day ends.",
       "code": "<ConversationList>\n  <ConversationList.DateSeparator date={new Date(Date.now() - 86400000)} />\n  <Message role=\"user\">\n    <Message.Content>A message from yesterday</Message.Content>\n  </Message>\n  <ConversationList.DateSeparator date={new Date()} />\n  <Message role=\"assistant\">\n    <Message.Content>And a message from today!</Message.Content>\n  </Message>\n</ConversationList>"
     },
     {
       "name": "Without Avatars",
-      "description": "Compact transcript without message or typing-indicator avatars",
+      "description": "Turns sit flush when nothing needs an avatar gutter.",
       "code": "<ConversationList showAvatars={false}>\n  <Message role=\"user\">\n    <Message.Content>Hello!</Message.Content>\n  </Message>\n  <Message role=\"assistant\">\n    <Message.Content>How can I help?</Message.Content>\n  </Message>\n</ConversationList>"
     },
     {
       "name": "With Typing Indicator",
-      "description": "Shows assistant is typing",
+      "description": "Animated dots hold the reply's place before it lands.",
       "code": "<ConversationList>\n  <Message role=\"user\">\n    <Message.Content>What is TypeScript?</Message.Content>\n  </Message>\n  <ConversationList.TypingIndicator name=\"Assistant\" />\n</ConversationList>"
     },
     {
       "name": "Loading History",
-      "description": "Loading older messages",
+      "description": "A spinner pins to the top while older turns load.",
       "code": "<ConversationList loadingHistory>\n  <Message role=\"user\">\n    <Message.Content>This is the latest message</Message.Content>\n  </Message>\n</ConversationList>"
+    },
+    {
+      "name": "Empty",
+      "description": "A fresh conversation shows its placeholder instead of blank space.",
+      "code": "<ConversationList\n  emptyState={\n    <EmptyState>\n      <EmptyState.Title>No messages yet</EmptyState.Title>\n      <EmptyState.Description>\n        Ask a question to get started.\n      </EmptyState.Description>\n    </EmptyState>\n  }\n/>"
     }
   ],
   "relations": [
@@ -152,10 +150,7 @@
       "loadingHistory: boolean - show history loading spinner",
       "emptyState: ReactNode - empty conversation content"
     ],
-    "a11yRules": [
-      "A11Y_ARIA_ROLES",
-      "A11Y_MOTION_PREFERENCE"
-    ]
+    "a11yRules": ["A11Y_ARIA_ROLES", "A11Y_MOTION_PREFERENCE"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/DataTable/DataTable.icons.tsx

@@ -5,9 +5,7 @@ import styles from "./DataTable.module.scss";
 export function ExpandIcon({ expanded }: { expanded: boolean }) {
   return (
     <svg
-      className={[styles.expandIcon, expanded && styles.expandIconOpen]
-        .filter(Boolean)
-        .join(" ")}
+      className={[styles.expandIcon, expanded && styles.expandIconOpen].filter(Boolean).join(" ")}
       viewBox="0 0 12 12"
       fill="none"
       xmlns="http://www.w3.org/2000/svg"
@@ -28,12 +26,7 @@ export function ExpandIcon({ expanded }: { expanded: boolean }) {
 // (--fui-icon-xs) in CSS so all sort glyphs share the icon ladder.
 export function SortIcon() {
   return (
-    <svg
-      viewBox="0 0 12 12"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-      aria-hidden="true"
-    >
+    <svg viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
       <path d="M6 2L8.5 5H3.5L6 2Z" fill="currentColor" opacity="0.3" />
       <path d="M6 10L3.5 7H8.5L6 10Z" fill="currentColor" opacity="0.3" />
     </svg>
@@ -42,12 +35,7 @@ export function SortIcon() {
 
 export function SortAscIcon() {
   return (
-    <svg
-      viewBox="0 0 12 12"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-      aria-hidden="true"
-    >
+    <svg viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
       <path d="M6 2L8.5 5H3.5L6 2Z" fill="currentColor" />
     </svg>
   );
@@ -55,12 +43,7 @@ export function SortAscIcon() {
 
 export function SortDescIcon() {
   return (
-    <svg
-      viewBox="0 0 12 12"
-      fill="none"
-      xmlns="http://www.w3.org/2000/svg"
-      aria-hidden="true"
-    >
+    <svg viewBox="0 0 12 12" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
       <path d="M6 10L3.5 7H8.5L6 10Z" fill="currentColor" />
     </svg>
   );

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

@@ -66,7 +66,7 @@
 .sortButton {
   display: flex;
   align-items: center;
-  gap: var(--fui-raw-space-4);
+  gap: var(--fui-raw-space-4, 4px);
 }
 
 .sortButton {
@@ -176,8 +176,11 @@
 }
 
 .bordered {
-  overflow: hidden;
-  border: var(--fui-table-divider-size, var(--fui-stroke-hairline)) solid
+  /* Keep the rounded corners clipping the table, but never trap the
+     horizontal scroll the wrapper needs for wide tables. */
+  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);
   background: var(--fui-data-table-bg, var(--fui-bg-primary, #{$fui-bg-primary}));
@@ -215,7 +218,7 @@
 
 .skeletonBar {
   display: block;
-  block-size: var(--fui-raw-space-10);
+  block-size: var(--fui-raw-space-10, 10px);
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
   background: linear-gradient(
     90deg,
@@ -224,7 +227,8 @@
     color-mix(in srgb, currentColor 8%, transparent) 75%
   );
   background-size: 200% 100%;
-  animation: dataTableShimmer 1.4s ease-in-out infinite;
+  animation: dataTableShimmer var(--fui-duration-shimmer, $fui-duration-shimmer) ease-in-out
+    infinite;
 }
 
 @keyframes dataTableShimmer {
@@ -246,7 +250,7 @@
 .expandCell {
   display: inline-flex;
   align-items: center;
-  gap: var(--fui-raw-space-4);
+  gap: var(--fui-raw-space-4, 4px);
 }
 
 .expandButton {
@@ -286,8 +290,8 @@
   display: flex;
   align-items: center;
   justify-content: center;
-  padding-block: var(--fui-raw-space-48);
-  padding-inline: var(--fui-raw-space-24);
+  padding-block: var(--fui-raw-space-48, 48px);
+  padding-inline: var(--fui-raw-space-24, 24px);
 }
 
 .emptyMessage {

package/src/components/DataTable/index.tsx

@@ -6,6 +6,7 @@ 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 { isDevelopmentBuild } from "../../utils/env";
 
 // ============================================
 // Dependency (@tanstack/react-table) — lazy import()
@@ -36,7 +37,7 @@ function loadReactTable(): Promise<void> {
         _reactTable = (await import("@tanstack/react-table")) as unknown as ReactTableModule;
       } catch {
         _reactTableFailed = true;
-        if (process.env.NODE_ENV === "development") {
+        if (isDevelopmentBuild()) {
           console.warn(
             "[@usefragments/ui] DataTable: @tanstack/react-table is not installed. " +
               "Rendering a static table without sorting, selection, or expansion. " +
@@ -469,9 +470,9 @@ function DataTableLive<T>({
             <DataTableSkeletonRows
               rowCount={skeletonRows}
               columnCount={columns.length}
-              rowClassName={styles.row}
-              cellClassName={styles.td}
-              barClassName={styles.skeletonBar}
+              rowClassName={styles.row ?? ""}
+              cellClassName={styles.td ?? ""}
+              barClassName={styles.skeletonBar ?? ""}
             />
           ) : (
             table.getRowModel().rows.map((row: any) => {
@@ -711,9 +712,9 @@ function DataTableStatic<T>({
             <DataTableSkeletonRows
               rowCount={skeletonRows}
               columnCount={columnCount}
-              rowClassName={styles.row}
-              cellClassName={styles.td}
-              barClassName={styles.skeletonBar}
+              rowClassName={styles.row ?? ""}
+              cellClassName={styles.td ?? ""}
+              barClassName={styles.skeletonBar ?? ""}
             />
           ) : isEmpty ? (
             <tr className={styles.row}>

package/src/components/DatePicker/DatePicker.contract.json

@@ -1,8 +1,8 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "DatePicker",
-  "description": "Date picker with calendar dropdown for selecting single dates or date ranges. Built on react-day-picker with seed-based theming.",
-  "category": "forms",
+  "description": "Selects a date or date range from a calendar.",
+  "category": "inputs",
   "tags": ["date", "picker", "calendar", "range", "form", "input"],
   "status": "stable",
   "dependencies": [
@@ -165,75 +165,74 @@
   },
   "usage": {
     "when": [
-      "Selecting a single date from a calendar",
-      "Selecting a date range (start/end)",
-      "Date inputs in forms",
-      "Filtering by date or date range"
+      "A date the user picks off a calendar",
+      "A start and end date together",
+      "Filtering by date"
     ],
     "whenNot": [
-      "Time-only input - use a dedicated TimePicker",
-      "Selecting from a small set of known dates - use Select",
-      "Free-form date entry - use Input with date masking"
+      "Time on its own (use a dedicated TimePicker)",
+      "A handful of known dates (use Select)",
+      "Typed date entry (use Input with a date mask)"
     ],
     "guidelines": [
-      "Use range mode with numberOfMonths={2} for date range selection",
-      "Use size=\"sm\" in dense toolbars so DatePicker aligns with Input, Select, Combobox, Button, and IconButton",
-      "Add presets for common ranges (Today, Last 7 days, Last 30 days)",
-      "Use disabledDates to prevent selecting past dates or unavailable dates",
-      "Provide a meaningful placeholder",
-      "DatePicker.Trigger forwards button props and defaults to type=\"button\" (safe inside forms)"
+      "Pair range mode with numberOfMonths={2} so both ends are visible",
+      "size=\"sm\" lines the trigger up with other dense toolbar controls",
+      "Offer presets for the common ranges: Today, Last 7 days, Last 30 days",
+      "disabledDates blocks past or unavailable days before the user tries",
+      "Placeholder names the date, not the action",
+      "DatePicker.Trigger defaults to type=\"button\", so it is safe inside a form"
     ],
     "accessibility": [
-      "Full keyboard navigation within the calendar grid",
-      "Arrow keys navigate between days",
+      "The calendar grid is fully keyboard navigable",
+      "Arrow keys move between days",
       "Escape closes the calendar",
-      "Focus returns to trigger on close"
+      "Focus returns to the trigger on close"
     ]
   },
   "examples": [
     {
       "name": "Default",
-      "description": "Single date picker with default settings",
+      "description": "Trigger opens one month; today is outlined.",
       "code": "<StatefulDatePicker placeholder=\"Pick a date\">\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulDatePicker>"
     },
     {
       "name": "Small Trigger",
-      "description": "Dense toolbar date picker aligned to other small controls",
+      "description": "Matches the height of other sm toolbar controls.",
       "code": "<StatefulDatePicker size=\"sm\" placeholder=\"Last scanned\">\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulDatePicker>"
     },
     {
       "name": "Date Range",
-      "description": "Range mode with dual months",
+      "description": "Two months side by side so both ends of the range are visible.",
       "code": "<StatefulRangePicker placeholder=\"Select date range\" numberOfMonths={2}>\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulRangePicker>"
     },
     {
       "name": "Multi-Month",
-      "description": "Single date with 3 months visible",
+      "description": "Three months at once, for dates far from today.",
       "code": "<StatefulDatePicker placeholder=\"Pick a date\" numberOfMonths={3}>\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulDatePicker>"
     },
     {
       "name": "Disabled Dates",
-      "description": "Past dates disabled",
+      "description": "Everything before today is greyed out and unclickable.",
       "code": "<StatefulDatePicker\n  placeholder=\"Select a future date\"\n  disabledDates={{ before: new Date() }}\n>\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulDatePicker>"
     },
     {
       "name": "With Presets",
-      "description": "Range picker with sidebar preset buttons",
+      "description": "Shortcut buttons beside the calendar skip the common ranges.",
       "code": "<StatefulRangePicker placeholder=\"Select date range\" numberOfMonths={2}>\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <div style={{ display: 'flex', gap: '1rem' }}>\n      <div style={{ display: 'flex', flexDirection: 'column', gap: '0.25rem', minWidth: '8rem' }}>\n        <DatePicker.Preset range={{ from: today, to: today }}>Today</DatePicker.Preset>\n        <DatePicker.Preset range={{ from: subDays(today, 7), to: today }}>Last 7 days</DatePicker.Preset>\n        <DatePicker.Preset range={{ from: subDays(today, 30), to: today }}>Last 30 days</DatePicker.Preset>\n        <DatePicker.Preset range={{ from: subDays(today, 90), to: today }}>Last 90 days</DatePicker.Preset>\n      </div>\n      <DatePicker.Calendar />\n    </div>\n  </DatePicker.Content>\n</StatefulRangePicker>"
     },
     {
       "name": "With Label and Helper Text",
-      "description": "Date picker with built-in label and helper text",
-      "code": "<StatefulDatePicker placeholder=\"Pick a date\">\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulDatePicker>"
+      "description": "Label above the trigger, supporting text below it.",
+      "code": "<StatefulDatePicker\n  label=\"Renewal date\"\n  placeholder=\"Pick a date\"\n  helperText=\"Billing restarts on this day each month.\"\n>\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulDatePicker>"
     },
     {
       "name": "Error State",
-      "description": "Validation error with message",
+      "description": "Red border on the trigger, and the reason below it.",
       "code": "<DatePicker\n  label=\"Start Date\"\n  placeholder=\"Pick a date\"\n  error=\"Please select a start date\"\n>\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</DatePicker>"
     },
     {
       "name": "Disabled",
-      "description": "Disabled date picker",
+      "description": "Dimmed; the calendar will not open.",
       "code": "<StatefulDatePicker placeholder=\"Pick a date\" disabled>\n  <DatePicker.Trigger />\n  <DatePicker.Content>\n    <DatePicker.Calendar />\n  </DatePicker.Content>\n</StatefulDatePicker>"
     }
   ],

package/src/components/DatePicker/DatePicker.module.scss

@@ -43,6 +43,12 @@
   &[data-popup-open] {
     border-color: var(--fui-field-border-focus, $fui-color-accent);
   }
+
+  // Error border, matching Input. Set from the wrapper's data-invalid so the
+  // control reads as failed, not just the message beneath it.
+  .wrapper[data-invalid] & {
+    border-color: var(--fui-color-danger-text, $fui-color-danger-text);
+  }
 }
 
 .triggerSm {
@@ -276,7 +282,8 @@
 // ============================================
 
 .today > .dayButton {
-  box-shadow: inset 0 0 0 1px var(--fui-field-border, $fui-border-strong);
+  box-shadow: inset 0 0 0 var(--fui-stroke-hairline, 1px)
+    var(--fui-field-border, $fui-border-strong);
   background-color: color-mix(in srgb, var(--fui-bg-hover, $fui-bg-hover) 55%, transparent);
 }
 
@@ -318,7 +325,7 @@
   &::before {
     content: "";
     position: absolute;
-    inset: 2px 0;
+    inset: var(--fui-raw-space-2, 2px) 0;
     background-color: color-mix(
       in srgb,
       var(--fui-color-accent, $fui-color-accent) 10%,
@@ -339,7 +346,7 @@
   &::before {
     content: "";
     position: absolute;
-    inset: 2px 0 2px 50%;
+    inset: var(--fui-raw-space-2, 2px) 0 var(--fui-raw-space-2, 2px) 50%;
     background-color: color-mix(
       in srgb,
       var(--fui-color-accent, $fui-color-accent) 10%,
@@ -369,7 +376,7 @@
   &::before {
     content: "";
     position: absolute;
-    inset: 2px 50% 2px 0;
+    inset: var(--fui-raw-space-2, 2px) 50% var(--fui-raw-space-2, 2px) 0;
     background-color: color-mix(
       in srgb,
       var(--fui-color-accent, $fui-color-accent) 10%,
@@ -419,7 +426,7 @@
 
 @media (prefers-contrast: more) {
   .trigger {
-    border-width: 2px;
+    border-width: var(--fui-stroke-default, 2px);
     border-color: var(--fui-text-primary, $fui-text-primary);
 
     &[data-popup-open] {

package/src/components/DatePicker/index.tsx

@@ -6,6 +6,7 @@ import { useFormFieldIds, type FormFieldProps } from "../../utils/aria";
 import { POPUP_OFFSET_PX } from "../../recipes/popup";
 import { useResolvedControlSize } from "../ComponentDefaults";
 import styles from "./DatePicker.module.scss";
+import { isDevelopmentBuild } from "../../utils/env";
 
 // ============================================
 // Types (self-owned — no external dependency for types)
@@ -249,7 +250,7 @@ function loadDayPickerDeps(): Promise<void> {
         _DayFlag = rdp.DayFlag as unknown as RdpEnum;
       } catch {
         _rdpFailed = true;
-        if (process.env.NODE_ENV === "development") {
+        if (isDevelopmentBuild()) {
           console.warn(
             "[@usefragments/ui] DatePicker: react-day-picker is not installed. " +
               "Install it with: npm install react-day-picker"
@@ -476,7 +477,9 @@ const DatePickerRoot = React.forwardRef<HTMLDivElement, DatePickerProps>(functio
 
   return (
     <DatePickerContext.Provider value={contextValue}>
-      <div ref={ref} className={wrapperClasses}>
+      {/* data-invalid lets the trigger pick up the error border; without it only
+          the message turns red and the control still looks valid. */}
+      <div ref={ref} className={wrapperClasses} data-invalid={hasError || undefined}>
         {label && (
           <span id={labelId} className={styles.label}>
             {label}

package/src/components/Dialog/Dialog.module.scss

@@ -42,7 +42,7 @@
   inline-size: 100%;
   max-inline-size: overlay.dialog-max("md");
   opacity: 0;
-  transform: scale(0.95) translateY(-$fui-anim-offset-md);
+  transform: scale(0.95) translateY(calc(-1 * var(--fui-anim-offset-md, #{$fui-anim-offset-md})));
   transition:
     opacity var(--fui-transition-normal, $fui-transition-normal),
     transform var(--fui-transition-normal, $fui-transition-normal);
@@ -54,12 +54,12 @@
 
   &[data-starting-style] {
     opacity: 0;
-    transform: scale(0.95) translateY(-$fui-anim-offset-md);
+    transform: scale(0.95) translateY(calc(-1 * var(--fui-anim-offset-md, #{$fui-anim-offset-md})));
   }
 
   &[data-ending-style] {
     opacity: 0;
-    transform: scale(0.95) translateY($fui-anim-offset-md);
+    transform: scale(0.95) translateY(var(--fui-anim-offset-md, #{$fui-anim-offset-md}));
   }
 }