@fragments-sdk/ui 0.14.0 → 0.15.1

package/src/components/Combobox/Combobox.module.scss

@@ -1,11 +1,21 @@
 @use "../../tokens/variables" as *;
 @use "../../tokens/mixins" as *;
 
-// Multi-select container — stacks input and chips vertically
-.multiContainer {
-  display: flex;
-  flex-direction: column;
-  width: 100%;
+// Form field wrapper (label + helper + error)
+@include form-field-wrapper;
+
+
+// Size variants for input wrapper
+.inputWrapperSm {
+  min-height: var(--fui-input-height-sm, $fui-input-height-sm);
+}
+
+.inputWrapperMd {
+  // Default — inherits from .inputWrapper
+}
+
+.inputWrapperLg {
+  min-height: var(--fui-input-height-lg, $fui-input-height-lg);
 }
 
 // Input + trigger wrapper
@@ -41,6 +51,17 @@
   }
 }
 
+// Size variants for text input
+.inputSm {
+  height: calc(var(--fui-input-height-sm, $fui-input-height-sm) - var(--fui-space-2, $fui-space-2));
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.inputLg {
+  height: calc(var(--fui-input-height-lg, $fui-input-height-lg) - var(--fui-space-2, $fui-space-2));
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
 // Text input
 .input {
   @include text-base;
@@ -65,26 +86,23 @@
   }
 }
 
-// Chips container (multi-select) — rendered below the input wrapper
+// Chips container (multi-select) — flows inline within inputWrapper
 .chips {
-  display: flex;
-  flex-wrap: wrap;
-  gap: var(--fui-space-1, $fui-space-1);
-  width: 100%;
-  padding-top: var(--fui-space-1, $fui-space-1);
+  display: contents;
 }
 
-// Individual chip (multi-select)
+// Individual chip (multi-select) — matches Chip component outlined xs
 .chip {
   display: inline-flex;
   align-items: center;
-  gap: var(--fui-space-1, $fui-space-1);
-  padding: 2px var(--fui-space-2, $fui-space-2);
-  background-color: var(--fui-bg-subtle, $fui-bg-subtle);
+  gap: var(--fui-space-0-5, $fui-space-0-5);
+  height: var(--fui-target-size-min, $fui-target-size-min);
+  padding: 0 var(--fui-space-2, $fui-space-2);
+  background-color: transparent;
   border: 1px solid var(--fui-border, $fui-border);
-  border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
-  line-height: 1.4;
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+  font-size: var(--fui-font-size-2xs, $fui-font-size-2xs);
+  line-height: 1;
   white-space: nowrap;
   max-width: 12rem;
 }
@@ -95,18 +113,23 @@
   white-space: nowrap;
 }
 
-// Chip remove button
+// Chip remove button — round icon button inside the pill
 .chipRemove {
   @include button-reset;
   @include touch-target;
 
+  display: flex;
+  align-items: center;
+  justify-content: center;
   flex-shrink: 0;
   width: 1rem;
   height: 1rem;
-  border-radius: var(--fui-radius-xs, 2px);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
   color: var(--fui-text-tertiary, $fui-text-tertiary);
   cursor: pointer;
-  transition: color var(--fui-transition-fast, $fui-transition-fast);
+  transition:
+    color var(--fui-transition-fast, $fui-transition-fast),
+    background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:hover {
     color: var(--fui-text-primary, $fui-text-primary);
@@ -129,7 +152,7 @@
   cursor: pointer;
   border-radius: 0 var(--fui-radius-md, $fui-radius-md) var(--fui-radius-md, $fui-radius-md) 0;
   transition: color var(--fui-transition-fast, $fui-transition-fast);
-  margin-inline-end: 0.5rem;
+  margin-inline-end: var(--fui-space-2, $fui-space-2);
 
   &:hover {
     color: var(--fui-text-primary, $fui-text-primary);
@@ -160,6 +183,7 @@
 // Popup container
 .popup {
   @include surface-elevated;
+  @include popup-container;
 
   // Item height derived from text-base font + vertical padding
   --_item-h: calc(
@@ -175,8 +199,6 @@
     var(--_item-h) * var(--fui-select-max-items, 4.5) + var(--fui-space-1, #{$fui-space-1}) * 2
   ) !important;
   overflow-y: auto !important;
-  padding: var(--fui-space-1, $fui-space-1);
-  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 
   // Animation
   opacity: 0;
@@ -200,19 +222,10 @@
 
 // Individual option
 .item {
-  @include button-reset;
-  @include text-base;
+  @include popup-item;
 
-  display: flex;
-  align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
-  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);
-  cursor: pointer;
-  outline: none;
-
-  &[data-highlighted] {
+  &[data-highlighted],
+  &:hover:not([data-disabled]) {
     background-color: var(--fui-bg-hover, $fui-bg-hover);
   }
 
@@ -220,7 +233,8 @@
     background-color: var(--fui-color-accent, $fui-color-accent);
     color: var(--fui-text-inverse, $fui-text-inverse);
 
-    &[data-highlighted] {
+    &[data-highlighted],
+    &:hover:not([data-disabled]) {
       background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
     }
   }
@@ -269,10 +283,38 @@
 
 // Group label
 .groupLabel {
-  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);
-  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
-  color: var(--fui-text-tertiary, $fui-text-tertiary);
-  text-transform: uppercase;
-  letter-spacing: 0.05em;
+  @include popup-group-label;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .inputWrapper {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &:focus-within {
+      border-color: var(--fui-color-accent, $fui-color-accent);
+    }
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .inputWrapper {
+    transition: none;
+  }
+
+  .popup {
+    transition: none;
+  }
+
+  .trigger svg {
+    transition: none;
+  }
 }

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 { mergeAriaIds, 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/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;
+}