@usefragments/ui 1.5.4 → 1.7.0

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

@@ -1,8 +1,27 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/action";
+@use "../../recipes/field";
+@use "../../recipes/layout";
+@use "../../recipes/popup";
+@use "../../recipes/typography";
 
-// Form field wrapper (label + helper + error)
-@include form-field-wrapper;
+.wrapper {
+  @include field.wrapper;
+}
+
+.label {
+  @include field.label;
+}
+
+.helper {
+  @include field.helper;
+}
+
+.helperError,
+.errorMessage {
+  @include field.error;
+}
 
 // ============================================
 // Trigger
@@ -11,28 +30,37 @@
 .trigger {
   @include button-reset;
   @include interactive-base;
-  @include text-base;
-  @include field-shell;
-  @include control-size("md", "input");
+  @include field.size("md");
+  @include field.shell;
 
   display: inline-flex;
   align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: action.gap("md");
   width: 100%;
-  min-width: 10rem;
+  min-width: layout.measure("field-minimum");
   text-align: left;
 
   &[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 {
-  @include control-size("sm", "input");
+  @include field.size("sm");
+
+  gap: action.gap("sm");
 }
 
 .triggerLg {
-  @include control-size("lg", "input");
+  @include field.size("lg");
+
+  gap: action.gap("lg");
 }
 
 .triggerIcon {
@@ -42,11 +70,18 @@
   color: var(--fui-text-secondary, $fui-text-secondary);
 
   svg {
-    width: var(--fui-icon-sm, $fui-icon-sm);
-    height: var(--fui-icon-sm, $fui-icon-sm);
+    @include action.glyph("md");
   }
 }
 
+.triggerSm .triggerIcon svg {
+  @include action.glyph("sm");
+}
+
+.triggerLg .triggerIcon svg {
+  @include action.glyph("lg");
+}
+
 .triggerValue {
   flex: 1;
   min-width: 0;
@@ -77,7 +112,7 @@
   @include surface-elevated;
 
   border-color: var(--fui-form-group-border, $fui-border);
-  padding: var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-surface-inset-compact, 12px);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 
   // Animation
@@ -105,10 +140,12 @@
 // ============================================
 
 .calendar {
-  @include text-base;
+  @include typography.role("body-compact");
 
   // Square size shared by weekday headers + day cells/buttons (32px grid).
-  --_day-size: var(--fui-icon-2xl, #{$fui-icon-2xl});
+  --_day-size: #{action.track("md")};
+
+  color: var(--fui-text-primary, $fui-text-primary);
 }
 
 .months {
@@ -151,12 +188,9 @@
 .navButton {
   @include button-reset;
   @include interactive-base;
+  @include action.base;
+  @include action.icon-only("sm");
 
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: var(--fui-button-height-sm, $fui-button-height-sm);
-  height: var(--fui-button-height-sm, $fui-button-height-sm);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   color: var(--fui-text-secondary, $fui-text-secondary);
 
@@ -166,8 +200,7 @@
   }
 
   svg {
-    width: var(--fui-icon-sm, $fui-icon-sm);
-    height: var(--fui-icon-sm, $fui-icon-sm);
+    @include action.glyph("sm");
   }
 }
 
@@ -189,13 +222,11 @@
 }
 
 .weekday {
-  @include text-base;
+  @include typography.role("ui-compact");
 
   width: var(--_day-size);
   height: var(--_day-size);
   padding: 0;
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   color: var(--fui-text-tertiary, $fui-text-tertiary);
   text-align: center;
   vertical-align: middle;
@@ -251,12 +282,13 @@
 // ============================================
 
 .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);
 }
 
 .selected > .dayButton {
-  @include popup-item-selected;
+  @include popup.selected-state;
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 
   &:hover {
@@ -293,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%,
@@ -314,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%,
@@ -326,7 +358,7 @@
   > .dayButton {
     position: relative;
     z-index: 1;
-    @include popup-item-selected;
+    @include popup.selected-state;
     font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 
     &:hover {
@@ -344,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%,
@@ -356,7 +388,7 @@
   > .dayButton {
     position: relative;
     z-index: 1;
-    @include popup-item-selected;
+    @include popup.selected-state;
     font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 
     &:hover {
@@ -371,14 +403,10 @@
 
 .preset {
   @include button-reset;
-  @include text-base;
+  @include popup.row;
 
-  display: flex;
-  align-items: center;
   width: 100%;
-  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   color: var(--fui-text-primary, $fui-text-primary);
   white-space: nowrap;
   transition: background-color var(--fui-transition-fast, $fui-transition-fast);
@@ -398,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] {
@@ -407,7 +435,7 @@
   }
 
   .dayButton {
-    border: 1px solid transparent;
+    border: var(--fui-stroke-hairline, 1px) solid transparent;
 
     &:focus-visible {
       border-color: var(--fui-text-primary, $fui-text-primary);

package/src/components/DatePicker/index.tsx

@@ -3,8 +3,10 @@
 import * as React from "react";
 import { Popover as BasePopover } from "@base-ui/react/popover";
 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)
@@ -248,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"
@@ -475,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}
@@ -557,7 +561,7 @@ function DatePickerTrigger({
 function DatePickerContent({
   children,
   className,
-  sideOffset = 4,
+  sideOffset = POPUP_OFFSET_PX,
   align = "start",
   ...htmlProps
 }: DatePickerContentProps) {

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

@@ -1,14 +1,13 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
+@use "../../recipes/action" as action;
+@use "../../recipes/overlay" as overlay;
 
-// Backdrop overlay
 .backdrop {
   position: fixed;
+  z-index: var(--fui-overlay-layer-backdrop, 50);
   inset: 0;
   background-color: var(--fui-backdrop, $fui-backdrop);
-  z-index: 50;
-
-  // Animation
   opacity: 0;
   transition: opacity var(--fui-transition-normal, $fui-transition-normal);
 
@@ -22,33 +21,28 @@
   }
 }
 
-// Positioner centers the popup
 .positioner {
+  @include overlay.safe-viewport;
+
   position: fixed;
+  z-index: var(--fui-overlay-layer-modal, 51);
   inset: 0;
-  z-index: 51;
   display: flex;
   align-items: center;
   justify-content: center;
-  padding: var(--fui-space-2, $fui-space-2);
-  overflow-y: auto;
+  padding-block: var(--_fui-overlay-safe-top) var(--_fui-overlay-safe-bottom);
+  padding-inline: var(--_fui-overlay-safe-left) var(--_fui-overlay-safe-right);
+  overflow: auto;
 }
 
-// The popup container
 .popup {
-  @include surface-elevated;
-  @include text-base;
+  @include overlay.modal-shell;
 
   position: relative;
-  width: 100%;
-  max-width: 28rem; // 448px
-  max-height: calc(100vh - var(--fui-space-8, $fui-space-8));
-  overflow-y: auto;
-  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
-
-  // Animation
+  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);
@@ -60,88 +54,70 @@
 
   &[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}));
   }
 }
 
-// Size variants
 .sm {
-  max-width: 24rem; // 384px
+  max-inline-size: overlay.dialog-max("sm");
 }
 
 .md {
-  max-width: 28rem; // 448px - default
+  max-inline-size: overlay.dialog-max("md");
 }
 
 .lg {
-  max-width: 36rem; // 576px
+  max-inline-size: overlay.dialog-max("lg");
 }
 
 .xl {
-  max-width: 48rem; // 768px
+  max-inline-size: overlay.dialog-max("xl");
 }
 
 .full {
-  max-width: calc(100vw - var(--fui-space-8, $fui-space-8));
+  max-inline-size: var(--_fui-overlay-safe-inline);
 }
 
-// Header area
 .header {
-  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+  @include overlay.header;
 }
 
-// Title
 .title {
+  @include overlay.modal-title;
+
   margin: 0;
-  font-size: var(--fui-font-size-lg, $fui-font-size-lg);
-  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
   color: var(--fui-text-primary, $fui-text-primary);
-  line-height: var(--fui-line-height-tight, $fui-line-height-tight);
 }
 
-// Description
 .description {
-  margin: var(--fui-space-1, $fui-space-1) 0 0;
-  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  @include overlay.description;
+
+  margin: 0;
   color: var(--fui-text-secondary, $fui-text-secondary);
-  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
 }
 
-// Body content
 .body {
-  padding: 0 var(--fui-space-4, $fui-space-4) var(--fui-space-3, $fui-space-3);
+  @include overlay.body;
 }
 
-// Footer for actions
 .footer {
-  display: flex;
-  align-items: center;
-  justify-content: flex-end;
-  gap: var(--fui-space-1, $fui-space-1);
-  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
-  border-top: 1px solid var(--fui-border, $fui-border);
-  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  @include overlay.footer;
+
+  border-top: var(--fui-stroke-hairline, 1px) solid var(--fui-border, $fui-border);
   border-radius: 0 0 var(--fui-radius-lg, $fui-radius-lg) var(--fui-radius-lg, $fui-radius-lg);
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
 }
 
-// Close button (X in corner)
 .close {
   @include button-reset;
   @include interactive-base;
+  @include overlay.close;
 
-  position: absolute;
-  top: var(--fui-space-3, $fui-space-3);
-  right: var(--fui-space-3, $fui-space-3);
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 2rem;
-  height: 2rem;
   border-radius: var(--fui-radius-md, $fui-radius-md);
   color: var(--fui-text-secondary, $fui-text-secondary);
 
@@ -151,27 +127,27 @@
   }
 
   svg {
-    width: 1rem;
-    height: 1rem;
+    inline-size: action.icon-size("sm");
+    block-size: action.icon-size("sm");
   }
 }
 
-// ============================================
-// Accessibility: Reduced Motion
-// ============================================
+.popup:has(.close) .header {
+  padding-inline-end: calc(
+    var(--fui-overlay-close-inset, var(--fui-raw-space-12, 12px)) + #{action.track("sm")} +
+      var(--fui-overlay-section-gap, var(--fui-raw-space-8, 8px))
+  );
+}
 
 @media (prefers-reduced-motion: reduce) {
-  .backdrop {
+  .backdrop,
+  .popup {
     transition: none;
   }
 
-  .popup {
-    transition: none;
+  .popup,
+  .popup[data-starting-style],
+  .popup[data-ending-style] {
     transform: none;
-
-    &[data-starting-style],
-    &[data-ending-style] {
-      transform: none;
-    }
   }
 }