@fragments-sdk/ui 0.14.0 → 0.16.0

package/src/components/Combobox/index.tsx

@@ -2,23 +2,28 @@
 
 import * as React from 'react';
 import { Combobox as BaseCombobox } from '@base-ui/react/combobox';
+import { mergeAriaIds, useFormFieldIds, type FormFieldProps } from '../../utils/aria';
 import styles from './Combobox.module.scss';
 
 // ============================================
 // Types
 // ============================================
 
-interface ComboboxCommonProps {
+interface ComboboxCommonProps extends FormFieldProps {
   children: React.ReactNode;
   open?: boolean;
   defaultOpen?: boolean;
   onOpenChange?: (open: boolean) => void;
-  disabled?: boolean;
   required?: boolean;
   name?: string;
   placeholder?: string;
   /** Auto-highlight first matching item while filtering */
   autoHighlight?: boolean;
+  /** Size variant.
+   * @default "md" */
+  size?: 'sm' | 'md' | 'lg';
+  /** Wrapper class name */
+  className?: string;
 }
 
 export interface ComboboxSingleProps extends ComboboxCommonProps {
@@ -163,6 +168,7 @@ interface ComboboxContextValue {
   incrementItemsVersion: () => void;
   explicitTriggerCount: number;
   registerTrigger: () => () => void;
+  size: 'sm' | 'md' | 'lg';
 }
 
 const ComboboxContext = React.createContext<ComboboxContextValue>({
@@ -172,6 +178,7 @@ const ComboboxContext = React.createContext<ComboboxContextValue>({
   incrementItemsVersion: () => {},
   explicitTriggerCount: 0,
   registerTrigger: () => () => {},
+  size: 'md',
 });
 
 function getNodeText(node: React.ReactNode): string {
@@ -187,7 +194,7 @@ function getNodeText(node: React.ReactNode): string {
 // Components
 // ============================================
 
-function ComboboxRoot({
+const ComboboxRoot = React.forwardRef<HTMLDivElement, ComboboxProps>(function ComboboxRoot({
   children,
   value,
   defaultValue,
@@ -202,7 +209,12 @@ function ComboboxRoot({
   name,
   placeholder,
   autoHighlight = true,
-}: ComboboxProps) {
+  label,
+  helperText,
+  error,
+  size = 'md',
+  className,
+}: ComboboxProps, ref) {
   // Track selected values for chip rendering
   const [internalValue, setInternalValue] = React.useState<string | string[] | null>(
     value ?? defaultValue ?? (multiple ? [] : null)
@@ -260,8 +272,29 @@ function ComboboxRoot({
       incrementItemsVersion,
       explicitTriggerCount,
       registerTrigger,
+      size,
     }),
-    [placeholder, multiple, selectedValues, itemsVersion, incrementItemsVersion, explicitTriggerCount, registerTrigger]
+    [placeholder, multiple, selectedValues, itemsVersion, incrementItemsVersion, explicitTriggerCount, registerTrigger, size]
+  );
+
+  const { labelId, helperId, errorId, hasError, errorMessage } = useFormFieldIds('combobox', { label, helperText, error });
+
+  const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(' ');
+  const helperClasses = [styles.helper, hasError && styles.helperError]
+    .filter(Boolean)
+    .join(' ');
+
+  const wrapperContent = (inner: React.ReactNode) => (
+    <div ref={ref} className={wrapperClasses}>
+      {label && <span id={labelId} className={styles.label}>{label}</span>}
+      {inner}
+      {helperText && (
+        <span id={helperId} className={helperClasses}>{helperText}</span>
+      )}
+      {errorMessage && (
+        <span id={errorId} className={styles.errorMessage}>{errorMessage}</span>
+      )}
+    </div>
   );
 
   if (multiple) {
@@ -277,22 +310,26 @@ function ComboboxRoot({
 
     return (
       <ComboboxContext.Provider value={contextValue}>
-        <BaseCombobox.Root<string, true>
-          value={controlledValue}
-          defaultValue={uncontrolledValue}
-          onValueChange={handleValueChange}
-          open={open}
-          defaultOpen={defaultOpen}
-          onOpenChange={(nextOpen) => handleOpenChange(nextOpen)}
-          disabled={disabled}
-          required={required}
-          name={name}
-          multiple
-          autoHighlight={autoHighlight}
-          itemToStringLabel={itemToStringLabel}
-        >
-          {children}
-        </BaseCombobox.Root>
+        {wrapperContent(
+          <BaseCombobox.Root<string, true>
+            value={controlledValue}
+            defaultValue={uncontrolledValue}
+            onValueChange={handleValueChange}
+            open={open}
+            defaultOpen={defaultOpen}
+            onOpenChange={(nextOpen) => handleOpenChange(nextOpen)}
+            disabled={disabled}
+            required={required}
+            name={name}
+            multiple
+            autoHighlight={autoHighlight}
+            itemToStringLabel={itemToStringLabel}
+            aria-labelledby={labelId}
+            aria-describedby={mergeAriaIds(errorId, helperId)}
+          >
+            {children}
+          </BaseCombobox.Root>
+        )}
       </ComboboxContext.Provider>
     );
   }
@@ -309,46 +346,41 @@ function ComboboxRoot({
 
   return (
     <ComboboxContext.Provider value={contextValue}>
-      <BaseCombobox.Root<string, false>
-        value={controlledValue}
-        defaultValue={uncontrolledValue ?? null}
-        onValueChange={handleValueChange}
-        open={open}
-        defaultOpen={defaultOpen}
-        onOpenChange={(nextOpen) => handleOpenChange(nextOpen)}
-        disabled={disabled}
-        required={required}
-        name={name}
-        multiple={false}
-        autoHighlight={autoHighlight}
-        itemToStringLabel={itemToStringLabel}
-      >
-        {children}
-      </BaseCombobox.Root>
+      {wrapperContent(
+        <BaseCombobox.Root<string, false>
+          value={controlledValue}
+          defaultValue={uncontrolledValue ?? null}
+          onValueChange={handleValueChange}
+          open={open}
+          defaultOpen={defaultOpen}
+          onOpenChange={(nextOpen) => handleOpenChange(nextOpen)}
+          disabled={disabled}
+          required={required}
+          name={name}
+          multiple={false}
+          autoHighlight={autoHighlight}
+          itemToStringLabel={itemToStringLabel}
+          aria-labelledby={labelId}
+          aria-describedby={mergeAriaIds(errorId, helperId)}
+        >
+          {children}
+        </BaseCombobox.Root>
+      )}
     </ComboboxContext.Provider>
   );
-}
+});
 
 function ComboboxInput({ className, showTrigger = true, ...htmlProps }: ComboboxInputProps) {
   const context = React.useContext(ComboboxContext);
-  const classes = [styles.input, className].filter(Boolean).join(' ');
+  const inputSizeClass = context.size === 'sm' ? styles.inputSm : context.size === 'lg' ? styles.inputLg : undefined;
+  const wrapperSizeClass = context.size === 'sm' ? styles.inputWrapperSm : context.size === 'lg' ? styles.inputWrapperLg : undefined;
+  const classes = [styles.input, inputSizeClass, className].filter(Boolean).join(' ');
+  const wrapperClasses = [styles.inputWrapper, wrapperSizeClass].filter(Boolean).join(' ');
   const renderTrigger = showTrigger && context.explicitTriggerCount === 0;
 
   if (context.multiple) {
     return (
-      <div className={styles.multiContainer}>
-        <div className={styles.inputWrapper}>
-          <BaseCombobox.Input
-            placeholder={context.selectedValues.length === 0 ? context.placeholder : undefined}
-            {...htmlProps}
-            className={classes}
-          />
-          {renderTrigger && (
-            <BaseCombobox.Trigger className={styles.trigger}>
-              <ChevronDownIcon />
-            </BaseCombobox.Trigger>
-          )}
-        </div>
+      <div className={wrapperClasses}>
         {context.selectedValues.length > 0 && (
           <BaseCombobox.Chips className={styles.chips}>
             {context.selectedValues.map((chipValue) => (
@@ -363,12 +395,22 @@ function ComboboxInput({ className, showTrigger = true, ...htmlProps }: Combobox
             ))}
           </BaseCombobox.Chips>
         )}
+        <BaseCombobox.Input
+          placeholder={context.selectedValues.length === 0 ? context.placeholder : undefined}
+          {...htmlProps}
+          className={classes}
+        />
+        {renderTrigger && (
+          <BaseCombobox.Trigger className={styles.trigger}>
+            <ChevronDownIcon />
+          </BaseCombobox.Trigger>
+        )}
       </div>
     );
   }
 
   return (
-    <div className={styles.inputWrapper}>
+    <div className={wrapperClasses}>
       <BaseCombobox.Input
         placeholder={context.placeholder}
         {...htmlProps}

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

@@ -1,6 +1,9 @@
 @use '../../tokens/variables' as *;
 @use '../../tokens/mixins' as *;
 
+// Form field wrapper (label + helper + error)
+@include form-field-wrapper;
+
 // ============================================
 // Trigger
 // ============================================
@@ -266,7 +269,7 @@
 
 .disabled > .dayButton {
   color: var(--fui-text-tertiary, $fui-text-tertiary);
-  opacity: 0.35;
+  opacity: 0.5;
   pointer-events: none;
 }
 
@@ -375,6 +378,29 @@
   }
 }
 
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .trigger {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &[data-popup-open] {
+      border-color: var(--fui-color-accent, $fui-color-accent);
+    }
+  }
+
+  .dayButton {
+    border: 1px solid transparent;
+
+    &:focus-visible {
+      border-color: var(--fui-text-primary, $fui-text-primary);
+    }
+  }
+}
+
 // ============================================
 // Reduced motion
 // ============================================

package/src/components/DatePicker/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { Popover as BasePopover } from '@base-ui/react/popover';
+import { useFormFieldIds, type FormFieldProps } from '../../utils/aria';
 import styles from './DatePicker.module.scss';
 // Import globals to ensure CSS variables are defined
 import '../../styles/globals.scss';
@@ -14,8 +15,10 @@ export type DateRange = { from: Date | undefined; to?: Date | undefined };
 export type Matcher = Date | DateRange | ((date: Date) => boolean) | Date[];
 type Locale = { [key: string]: unknown };
 
-export interface DatePickerProps {
+export interface DatePickerProps extends FormFieldProps {
   children: React.ReactNode;
+  /** Wrapper class name */
+  className?: string;
   /** Selection mode */
   mode?: 'single' | 'range';
   /** Controlled date (single mode) */
@@ -24,6 +27,8 @@ export interface DatePickerProps {
   selectedRange?: DateRange | null;
   /** Single selection callback */
   onSelect?: (date: Date | null) => void;
+  /** Alias for onSelect (consistent with Input/Select onChange convention) */
+  onChange?: (date: Date | null) => void;
   /** Range selection callback */
   onRangeSelect?: (range: DateRange | null) => void;
   /** Number of months displayed side-by-side */
@@ -271,12 +276,17 @@ function getCalendarClassNames() {
 // Components
 // ============================================
 
-function DatePickerRoot({
+const DatePickerRoot = React.forwardRef<HTMLDivElement, DatePickerProps>(function DatePickerRoot({
   children,
+  label,
+  helperText,
+  error,
+  className,
   mode = 'single',
   selected: selectedProp,
   selectedRange: selectedRangeProp,
   onSelect,
+  onChange: onChangeProp,
   onRangeSelect,
   numberOfMonths = 1,
   disabled = false,
@@ -289,7 +299,7 @@ function DatePickerRoot({
   open: openProp,
   onOpenChange,
   name,
-}: DatePickerProps) {
+}: DatePickerProps, ref) {
   // Load deps eagerly so date formatters are available in the trigger
   loadDatePickerDeps();
   const [internalSelected, setInternalSelected] = React.useState<Date | null>(
@@ -327,12 +337,14 @@ function DatePickerRoot({
     [isControlledOpen, onOpenChange]
   );
 
+  const resolvedOnSelect = onSelect ?? onChangeProp;
+
   const setSelected = React.useCallback(
     (date: Date | null) => {
       if (selectedProp === undefined) {
         setInternalSelected(date);
       }
-      onSelect?.(date);
+      resolvedOnSelect?.(date);
 
       // Auto-close after single selection (controlled and uncontrolled).
       if (date) {
@@ -341,7 +353,7 @@ function DatePickerRoot({
         }, 150);
       }
     },
-    [selectedProp, onSelect, handleOpenChange]
+    [selectedProp, resolvedOnSelect, handleOpenChange]
   );
 
   const setSelectedRange = React.useCallback(
@@ -405,14 +417,30 @@ function DatePickerRoot({
     ]
   );
 
+  const { labelId, helperId, errorId, hasError, errorMessage } = useFormFieldIds('datepicker', { label, helperText, error });
+
+  const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(' ');
+  const helperClasses = [styles.helper, hasError && styles.helperError]
+    .filter(Boolean)
+    .join(' ');
+
   return (
     <DatePickerContext.Provider value={contextValue}>
-      <BasePopover.Root
-        open={isOpen}
-        onOpenChange={handleOpenChange}
-      >
-        {children}
-      </BasePopover.Root>
+      <div ref={ref} className={wrapperClasses}>
+        {label && <span id={labelId} className={styles.label}>{label}</span>}
+        <BasePopover.Root
+          open={isOpen}
+          onOpenChange={handleOpenChange}
+        >
+          {children}
+        </BasePopover.Root>
+        {helperText && (
+          <span id={helperId} className={helperClasses}>{helperText}</span>
+        )}
+        {errorMessage && (
+          <span id={errorId} className={styles.errorMessage}>{errorMessage}</span>
+        )}
+      </div>
       {name && (
         <input
           type="hidden"
@@ -428,7 +456,7 @@ function DatePickerRoot({
       )}
     </DatePickerContext.Provider>
   );
-}
+});
 
 function DatePickerTrigger({
   children,

package/src/components/Form/index.tsx

@@ -28,7 +28,7 @@ function FormRoot({
   errors,
   onSubmit,
   onFormSubmit,
-  onClearErrors,
+  onClearErrors: _onClearErrors,
   validationMode,
   className,
   ...htmlProps

package/src/components/Grid/Grid.module.scss

@@ -140,3 +140,26 @@
 .selfAlignCenter  { align-self: center; }
 .selfAlignEnd     { align-self: end; }
 .selfAlignStretch { align-self: stretch; }
+
+// ============================================
+// Subgrid — item children align to parent tracks
+// ============================================
+// Usage: <Grid.Item subgrid colSpan={3}> or <Grid.Item subgrid="rows" rowSpan={3}>
+// Children of the item participate in the parent grid's tracks.
+// ~97% browser support (Chrome 117+, Firefox 71+, Safari 16+).
+
+.subgridRows {
+  display: grid;
+  grid-template-rows: subgrid;
+}
+
+.subgridColumns {
+  display: grid;
+  grid-template-columns: subgrid;
+}
+
+.subgridBoth {
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-template-columns: subgrid;
+}

package/src/components/Grid/index.tsx

@@ -59,6 +59,14 @@ export interface GridItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   rowSpan?: 1 | 2 | 3 | 4 | 5 | 6;
   /** Override alignment for this item */
   alignSelf?: 'start' | 'center' | 'end' | 'stretch';
+  /**
+   * Enable CSS subgrid so children align to parent grid tracks.
+   * - `true` or `"rows"` — children align to parent row tracks
+   * - `"columns"` — children align to parent column tracks
+   * - `"both"` — children align to both row and column tracks
+   * Requires the item to span multiple rows/columns for visible effect.
+   */
+  subgrid?: boolean | 'rows' | 'columns' | 'both';
   /** Additional class name */
   className?: string;
   style?: React.CSSProperties;
@@ -163,6 +171,12 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(
 // Grid.Item Sub-component
 // ============================================
 
+const subgridClasses: Record<string, string> = {
+  rows: styles.subgridRows,
+  columns: styles.subgridColumns,
+  both: styles.subgridBoth,
+};
+
 const GridItem = React.forwardRef<HTMLDivElement, GridItemProps>(
   function GridItem(
     {
@@ -170,17 +184,23 @@ const GridItem = React.forwardRef<HTMLDivElement, GridItemProps>(
       colSpan,
       rowSpan,
       alignSelf,
+      subgrid,
       className,
       style,
       ...htmlProps
     },
     ref
   ) {
+    const subgridClass = subgrid
+      ? subgridClasses[subgrid === true ? 'rows' : subgrid]
+      : undefined;
+
     const classes = [
       styles.item,
       colSpan && (colSpan === 'full' ? styles.colSpanFull : styles[`colSpan${colSpan}`]),
       rowSpan && styles[`rowSpan${rowSpan}`],
       alignSelf && styles[`selfAlign${cap(alignSelf)}`],
+      subgridClass,
       className,
     ]
       .filter(Boolean)

package/src/components/Header/Header.module.scss

@@ -6,6 +6,9 @@
 // ============================================
 
 .header {
+  // Container query context: children respond to header width, not viewport
+  @include container(fui-header);
+
   display: flex;
   align-items: center;
   height: var(--header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
@@ -34,7 +37,8 @@
   width: 100%;
   max-width: 100%;
 
-  @include below-md {
+  // Compact gap when header container is narrow (replaces viewport media query)
+  @include container-max($fui-breakpoint-md, fui-header) {
     gap: var(--fui-space-1, $fui-space-1);
   }
 }
@@ -70,7 +74,8 @@
 .nav {
   display: none;
 
-  @include breakpoint-md {
+  // Show navigation when header has enough space
+  @include container-min($fui-breakpoint-md, fui-header) {
     display: flex;
     align-items: center;
   }
@@ -235,7 +240,8 @@
 .search {
   display: none;
 
-  @include breakpoint-md {
+  // Show search when header has enough space
+  @include container-min($fui-breakpoint-md, fui-header) {
     display: flex;
     align-items: center;
   }

package/src/components/Input/Input.module.scss

@@ -1,15 +1,8 @@
 @use '../../tokens/variables' as *;
 @use '../../tokens/mixins' as *;
 
-.wrapper {
-  display: flex;
-  flex-direction: column;
-}
-
-.label {
-  @include label-text;
-  margin-bottom: var(--fui-space-1, $fui-space-1);
-}
+// Form field wrapper (label + helper + error)
+@include form-field-wrapper;
 
 .input {
   @include text-base;
@@ -25,11 +18,11 @@
     color: var(--fui-text-tertiary, $fui-text-tertiary);
   }
 
-  &:hover:not(:disabled):not(:focus) {
+  &:hover:not(:disabled):not(:focus-visible) {
     border-color: var(--fui-text-tertiary, $fui-text-tertiary);
   }
 
-  &:focus {
+  &:focus-visible {
     @include focus-ring;
     border-color: var(--fui-color-accent, $fui-color-accent);
   }
@@ -64,10 +57,14 @@
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
 }
 
-.error {
+// Error state via :has() — detects aria-invalid on the input element.
+// Replaces JS class toggle: `error && styles.error`
+// The .error class is kept as a fallback for direct usage.
+.error,
+.input[aria-invalid] {
   border-color: var(--fui-color-danger, $fui-color-danger);
 
-  &:focus {
+  &:focus-visible {
     border-color: var(--fui-color-danger, $fui-color-danger);
     box-shadow:
       0 0 0 var(--fui-focus-ring-offset, $fui-focus-ring-offset) var(--fui-bg-primary, $fui-bg-primary),
@@ -75,12 +72,8 @@
   }
 }
 
-.helper {
-  @include helper-text;
-  margin-top: var(--fui-space-1, $fui-space-1);
-}
-
-.helperError {
+// Auto-detect error state via :has() — applies error color to helper when sibling has aria-invalid
+.wrapper:has([aria-invalid]) .helper {
   color: var(--fui-color-danger, $fui-color-danger);
 }
 
@@ -92,15 +85,21 @@
   position: relative;
   display: flex;
   align-items: center;
+
+  // Auto-detect shortcut kbd via :has() — replaces JS class toggle: `shortcut && styles.hasShortcut`
+  &:has(> .shortcut) .input {
+    padding-right: var(--fui-space-12, 3rem);
+  }
 }
 
+// Kept as fallback for direct usage
 .hasShortcut {
   padding-right: var(--fui-space-12, 3rem);
 }
 
 .shortcut {
   position: absolute;
-  right: var(--fui-space-2, 0.5rem);
+  right: var(--fui-space-2, $fui-space-2);
   top: 50%;
   transform: translateY(-50%);
   display: inline-flex;
@@ -109,12 +108,12 @@
   padding:
     calc(var(--fui-space-px, $fui-space-px) * 2)
     calc(var(--fui-space-px, $fui-space-px) * 6);
-  font-size: var(--fui-font-size-xs, 0.75rem);
-  font-family: var(--fui-font-mono, ui-monospace, monospace);
-  color: var(--fui-text-secondary);
-  background: var(--fui-bg-subtle);
-  border: 1px solid var(--fui-border-default);
-  border-radius: var(--fui-radius-sm, 0.25rem);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-family: var(--fui-font-mono, $fui-font-mono);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  background: var(--fui-bg-subtle, $fui-bg-subtle);
+  border: 1px solid var(--fui-border-default, $fui-border-default);
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
   pointer-events: none;
   white-space: nowrap;
 }
@@ -128,12 +127,23 @@
     border-width: 2px;
     border-color: var(--fui-text-primary, $fui-text-primary);
 
-    &:focus {
+    &:focus-visible {
       border-color: var(--fui-color-accent, $fui-color-accent);
     }
   }
 
-  .error {
+  .error,
+  .input[aria-invalid] {
     border-color: var(--fui-color-danger, $fui-color-danger);
   }
 }
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .input {
+    transition: none;
+  }
+}