@fragments-sdk/ui 0.14.0 → 0.16.0

package/src/components/Select/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { Select as BaseSelect } from '@base-ui/react/select';
+import { mergeAriaIds, useFormFieldIds, type FormFieldProps } from '../../utils/aria';
 import styles from './Select.module.scss';
 
 // ============================================
@@ -20,7 +21,7 @@ export interface SelectOption {
  * Select dropdown for choosing from a list of options.
  * @see https://usefragments.com/components/select
  */
-export interface SelectProps {
+export interface SelectProps extends FormFieldProps {
   children?: React.ReactNode;
   /** Controlled selected value */
   value?: SelectValue | null;
@@ -36,8 +37,7 @@ export interface SelectProps {
   defaultOpen?: boolean;
   /** Called when open state changes */
   onOpenChange?: (open: boolean) => void;
-  /** Whether the select is non-interactive */
-  disabled?: boolean;
+  // disabled inherited from FormFieldProps
   /** Whether a selection is required */
   required?: boolean;
   /** Form field name */
@@ -46,6 +46,11 @@ export interface SelectProps {
   placeholder?: string;
   /** Convenience API for simple selects (renders Select.Item entries when children are omitted) */
   options?: SelectOption[];
+  /** Size variant.
+   * @default "md" */
+  size?: 'sm' | 'md' | 'lg';
+  /** Wrapper class name */
+  className?: string;
 }
 
 export interface SelectTriggerProps extends React.HTMLAttributes<HTMLButtonElement> {
@@ -127,19 +132,21 @@ interface SelectContextValue {
   items: Map<SelectValue, React.ReactNode>;
   registerItem: (value: SelectValue, content: React.ReactNode) => void;
   unregisterItem: (value: SelectValue) => void;
+  size: 'sm' | 'md' | 'lg';
 }
 
 const SelectContext = React.createContext<SelectContextValue>({
   items: new Map(),
   registerItem: () => {},
   unregisterItem: () => {},
+  size: 'md',
 });
 
 // ============================================
 // Components
 // ============================================
 
-function SelectRoot({
+const SelectRoot = React.forwardRef<HTMLDivElement, SelectProps>(function SelectRoot({
   children,
   value,
   defaultValue,
@@ -153,7 +160,12 @@ function SelectRoot({
   name,
   placeholder,
   options,
-}: SelectProps) {
+  label,
+  helperText,
+  error,
+  size = 'md',
+  className,
+}: SelectProps, ref) {
   // Track current value for controlled and uncontrolled modes
   const [internalValue, setInternalValue] = React.useState<SelectValue | null | undefined>(
     value ?? defaultValue ?? null
@@ -204,38 +216,66 @@ function SelectRoot({
       items,
       registerItem,
       unregisterItem,
+      size,
     }),
-    [placeholder, value, internalValue, items, registerItem, unregisterItem]
+    [placeholder, value, internalValue, items, registerItem, unregisterItem, size]
+  );
+
+  const { labelId, helperId, errorId, hasError, errorMessage } = useFormFieldIds('select', { label, helperText, error });
+
+  const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(' ');
+  const helperClasses = [styles.helper, hasError && styles.helperError]
+    .filter(Boolean)
+    .join(' ');
+
+  const selectContent = (
+    <BaseSelect.Root
+      value={value}
+      defaultValue={defaultValue}
+      onValueChange={handleValueChange}
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange}
+      disabled={disabled}
+      required={required}
+      name={name}
+      aria-labelledby={labelId}
+      aria-describedby={mergeAriaIds(errorId, helperId)}
+    >
+      {children ?? options?.map((option) => (
+        <SelectItem key={option.value} value={option.value} disabled={option.disabled}>
+          {option.label}
+        </SelectItem>
+      ))}
+    </BaseSelect.Root>
   );
 
   return (
     <SelectContext.Provider value={contextValue}>
-      <BaseSelect.Root
-        value={value}
-        defaultValue={defaultValue}
-        onValueChange={handleValueChange}
-        open={open}
-        defaultOpen={defaultOpen}
-        onOpenChange={onOpenChange}
-        disabled={disabled}
-        required={required}
-        name={name}
-      >
-        {children ?? options?.map((option) => (
-          <SelectItem key={option.value} value={option.value} disabled={option.disabled}>
-            {option.label}
-          </SelectItem>
-        ))}
-      </BaseSelect.Root>
+      <div ref={ref} className={wrapperClasses}>
+        {label && <span id={labelId} className={styles.label}>{label}</span>}
+        {selectContent}
+        {helperText && (
+          <span id={helperId} className={helperClasses}>{helperText}</span>
+        )}
+        {errorMessage && (
+          <span id={errorId} className={styles.errorMessage}>{errorMessage}</span>
+        )}
+      </div>
     </SelectContext.Provider>
   );
-}
+});
 
 function SelectTrigger({ children, placeholder, className, ...htmlProps }: SelectTriggerProps) {
   const context = React.useContext(SelectContext);
   const placeholderText = placeholder ?? context.placeholder;
 
-  const classes = [styles.trigger, className].filter(Boolean).join(' ');
+  const classes = [
+    styles.trigger,
+    context.size === 'sm' && styles.triggerSm,
+    context.size === 'lg' && styles.triggerLg,
+    className,
+  ].filter(Boolean).join(' ');
 
   // Get the selected item's children from the registry
   const selectedContent = context.value != null

package/src/components/Sidebar/Sidebar.module.scss

@@ -240,7 +240,7 @@
   border-radius: var(--fui-radius-md, $fui-radius-md);
   color: var(--fui-text-secondary, $fui-text-secondary);
   text-decoration: none;
-  min-height: $fui-sidebar-item-height;
+  min-height: var(--fui-sidebar-item-height, $fui-sidebar-item-height);
 
   &:hover:not(.itemDisabled) {
     background-color: var(--fui-bg-hover, $fui-bg-hover);
@@ -389,7 +389,7 @@
   color: var(--fui-text-secondary, $fui-text-secondary);
   text-decoration: none;
   font-size: var(--fui-font-size-sm, $fui-font-size-sm);
-  min-height: $fui-sidebar-subitem-height;
+  min-height: var(--fui-sidebar-item-height, $fui-sidebar-subitem-height);
   position: relative;
 
   // Left border indicator
@@ -637,7 +637,7 @@
   align-items: center;
   gap: var(--fui-space-3, $fui-space-3);
   padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
-  min-height: $fui-sidebar-item-height;
+  min-height: var(--fui-sidebar-item-height, $fui-sidebar-item-height);
 }
 
 .skeletonLabel {

package/src/components/Slider/Slider.module.scss

@@ -10,7 +10,7 @@
   display: flex;
   justify-content: space-between;
   align-items: center;
-  margin-bottom: var(--fui-space-2, $fui-space-2);
+  margin-bottom: var(--fui-space-1, $fui-space-1);
 }
 
 .label {
@@ -37,7 +37,7 @@
 
 .track {
   position: relative;
-  height: $fui-slider-track-height;
+  height: var(--fui-slider-track-height, $fui-slider-track-height);
   width: 100%;
   background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
   border-radius: var(--fui-radius-full, $fui-radius-full);
@@ -60,10 +60,10 @@
   @include min-target-size;
 
   position: relative;
-  width: $fui-slider-thumb-size;
-  height: $fui-slider-thumb-size;
+  width: var(--fui-slider-thumb-size, $fui-slider-thumb-size);
+  height: var(--fui-slider-thumb-size, $fui-slider-thumb-size);
   background-color: var(--fui-bg-primary, $fui-bg-primary);
-  border: $fui-slider-thumb-border solid var(--fui-color-accent, $fui-color-accent);
+  border: var(--fui-slider-thumb-border, $fui-slider-thumb-border) solid var(--fui-color-accent, $fui-color-accent);
   border-radius: var(--fui-radius-full, $fui-radius-full);
   cursor: grab;
   transition:
@@ -89,6 +89,15 @@
   }
 }
 
+.helper {
+  @include helper-text;
+  margin-top: var(--fui-space-1, $fui-space-1);
+}
+
+.helperError {
+  color: var(--fui-color-danger, $fui-color-danger);
+}
+
 .dragValueBubble {
   position: absolute;
   left: 50%;
@@ -118,3 +127,27 @@
     border-top: 5px solid var(--fui-tooltip-bg, $fui-tooltip-bg);
   }
 }
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .track {
+    border: 1px solid var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .thumb {
+    border-width: 3px;
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .thumb {
+    transition: none;
+  }
+}

package/src/components/Slider/index.tsx

@@ -12,6 +12,10 @@ import styles from './Slider.module.scss';
 export interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'defaultValue'> {
   /** Visible label text */
   label?: string;
+  /** Helper text shown below the slider */
+  helperText?: string;
+  /** Show error styling */
+  error?: boolean;
   /** Controlled value */
   value?: number;
   /** Default value for uncontrolled usage */
@@ -41,6 +45,8 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
   function Slider(
     {
       label,
+      helperText,
+      error = false,
       value,
       defaultValue,
       onChange,
@@ -99,8 +105,12 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
       }
     }, [disabled, isDragging]);
 
+    const helperClasses = [styles.helper, error && styles.helperError]
+      .filter(Boolean)
+      .join(' ');
+
     return (
-      <Field.Root {...htmlProps} disabled={disabled} className={[styles.wrapper, className].filter(Boolean).join(' ')}>
+      <Field.Root {...htmlProps} disabled={disabled} invalid={error} className={[styles.wrapper, className].filter(Boolean).join(' ')}>
         {(label || showValue) && (
           <div className={styles.header}>
             {label && <Field.Label className={styles.label}>{label}</Field.Label>}
@@ -144,6 +154,11 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
             </BaseSlider.Track>
           </BaseSlider.Control>
         </BaseSlider.Root>
+        {helperText && (
+          <Field.Description className={helperClasses}>
+            {helperText}
+          </Field.Description>
+        )}
       </Field.Root>
     );
   }

package/src/components/Textarea/Textarea.module.scss

@@ -1,20 +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);
-}
-
-.required {
-  color: var(--fui-color-danger, $fui-color-danger);
-  margin-left: 2px;
-}
+// Form field wrapper (label + helper + error)
+@include form-field-wrapper;
 
 .textarea {
   @include text-base;
@@ -27,18 +15,18 @@
   background-color: var(--fui-bg-elevated, $fui-bg-elevated);
   border: 1px solid var(--fui-border-strong, $fui-border-strong);
   border-radius: var(--fui-radius-md, $fui-radius-md);
-  line-height: $fui-line-height-normal;
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
   font-family: inherit;
 
   &::placeholder {
     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);
   }
@@ -50,6 +38,21 @@
   }
 }
 
+// Size variants
+.sm {
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.md {
+  // Default size
+}
+
+.lg {
+  padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
 // Resize variants
 .resize-none {
   resize: none;
@@ -67,11 +70,12 @@
   resize: both;
 }
 
-// Error state
-.error {
+// Error state via aria-invalid attribute (replaces JS class toggle: `error && styles.error`)
+.error,
+.textarea[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),
@@ -79,11 +83,37 @@
   }
 }
 
-.helper {
-  @include helper-text;
-  margin-top: var(--fui-space-1, $fui-space-1);
+// 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);
 }
 
-.helperError {
-  color: var(--fui-color-danger, $fui-color-danger);
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .textarea {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &:focus-visible {
+      border-color: var(--fui-color-accent, $fui-color-accent);
+    }
+  }
+
+  .error,
+  .textarea[aria-invalid] {
+    border-color: var(--fui-color-danger, $fui-color-danger);
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .textarea {
+    transition: none;
+  }
 }

package/src/components/Textarea/index.tsx

@@ -1,9 +1,10 @@
 import * as React from 'react';
+import { mergeAriaIds } from '../../utils/aria';
 import styles from './Textarea.module.scss';
 
 export interface TextareaProps extends Omit<
   React.TextareaHTMLAttributes<HTMLTextAreaElement>,
-  'onChange' | 'onBlur' | 'className' | 'style'
+  'onChange' | 'onBlur' | 'onFocus' | 'className' | 'style' | 'size'
 > {
   /** Controlled value */
   value?: string;
@@ -19,6 +20,9 @@ export interface TextareaProps extends Omit<
   maxRows?: number;
   /** Allow user to resize the textarea */
   resize?: 'none' | 'vertical' | 'horizontal' | 'both';
+  /** Size variant.
+   * @default "md" */
+  size?: 'sm' | 'md' | 'lg';
   /** Disabled state */
   disabled?: boolean;
   /** Error state */
@@ -33,6 +37,8 @@ export interface TextareaProps extends Omit<
   onValueChange?: (value: string) => void;
   /** Called when textarea loses focus */
   onBlur?: () => void;
+  /** Called when textarea receives focus */
+  onFocus?: () => void;
   /** Form field name */
   name?: string;
   /** Maximum character length */
@@ -53,11 +59,6 @@ export interface TextareaProps extends Omit<
   style?: React.CSSProperties;
 }
 
-function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
-  const merged = ids.filter(Boolean).join(' ').trim();
-  return merged.length > 0 ? merged : undefined;
-}
-
 const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
   function Textarea(
     {
@@ -68,6 +69,7 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       minRows,
       maxRows,
       resize = 'vertical',
+      size = 'md',
       disabled = false,
       error = false,
       label,
@@ -75,6 +77,7 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       onChange,
       onValueChange,
       onBlur,
+      onFocus,
       rootProps,
       className,
       style: wrapperStyle,
@@ -99,6 +102,7 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
 
     const textareaClasses = [
       styles.textarea,
+      styles[size],
       error && styles.error,
       styles[`resize-${resize}`],
     ]
@@ -154,6 +158,7 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
             onValueChange?.(e.target.value);
           }}
           onBlur={() => onBlur?.()}
+          onFocus={() => onFocus?.()}
           className={textareaClasses}
           style={Object.keys(textareaInlineStyle).length > 0 ? textareaInlineStyle : undefined}
         />

package/src/components/Theme/index.tsx

@@ -368,21 +368,9 @@ export { ThemeProvider, ThemeToggle, useTheme };
 // configureTheme — JS-only seed configuration
 // ============================================
 
-/**
- * Neutral palette for surfaces, text, and borders.
- * - `stone`: Cool gray (balanced, professional) — default
- * - `ice`: Cool blue-tinted grays (crisp, technical)
- * - `earth`: Warm brown-tinted grays (natural, grounded)
- * - `sand`: Warm tan-tinted grays (organic, approachable)
- * - `fire`: Warm red-tinted grays (bold, energetic)
- *
- * Preview palettes at https://usefragments.com/themes
- */
-export type NeutralPalette = 'stone' | 'ice' | 'earth' | 'sand' | 'fire';
-/** Spacing density: `compact` (tight), `default` (balanced), `relaxed` (spacious) */
-export type DensityPreset = 'compact' | 'default' | 'relaxed';
-/** Border radius style: `sharp` (0), `subtle` (2px), `default` (4px), `rounded` (8px), `pill` (9999px) */
-export type RadiusStyle = 'sharp' | 'subtle' | 'default' | 'rounded' | 'pill';
+// Import + re-export seed derivation types — canonical definitions in utils/seed-derivation.ts
+import type { NeutralPalette, DensityPreset, RadiusStyle } from '../../utils/seed-derivation';
+export type { NeutralPalette, DensityPreset, RadiusStyle };
 
 export interface ConfigureThemeOptions {
   /** Brand/accent color as hex */
@@ -420,12 +408,14 @@ interface DensityConfig {
   baseFontSize: number;
   buttonHeights: [number, number, number]; // sm, md, lg
   inputHeights: [number, number, number]; // sm, default, lg
+  touchTargets: [number, number, number]; // sm, md, lg — WCAG 2.5.8: ≥24px
+  sidebarItemHeight: number;
 }
 
 const DENSITY_CONFIGS: Record<DensityPreset, DensityConfig> = {
-  compact:  { baseUnit: 6,  baseFontSize: 14, buttonHeights: [24, 30, 36], inputHeights: [24, 32, 36] },
-  default:  { baseUnit: 7,  baseFontSize: 14, buttonHeights: [28, 36, 44], inputHeights: [28, 40, 44] },
-  relaxed:  { baseUnit: 8,  baseFontSize: 14, buttonHeights: [32, 40, 48], inputHeights: [32, 44, 48] },
+  compact:  { baseUnit: 6,  baseFontSize: 14, buttonHeights: [24, 30, 36], inputHeights: [24, 32, 36], touchTargets: [24, 28, 38], sidebarItemHeight: 30 },
+  default:  { baseUnit: 7,  baseFontSize: 14, buttonHeights: [28, 36, 44], inputHeights: [28, 40, 44], touchTargets: [24, 32, 44], sidebarItemHeight: 35 },
+  relaxed:  { baseUnit: 8,  baseFontSize: 14, buttonHeights: [32, 40, 48], inputHeights: [32, 44, 48], touchTargets: [28, 36, 48], sidebarItemHeight: 38 },
 };
 
 function pxToRem(px: number, baseFontSize: number): string {
@@ -508,6 +498,10 @@ export function configureTheme(options: ConfigureThemeOptions): void {
     if (d) {
       const unitRem = d.baseUnit / d.baseFontSize;
 
+      // Micro spacing
+      setVar(root, '--fui-space-0-5', `${unitRem * 0.3}rem`);
+      setVar(root, '--fui-space-0-75', `${unitRem * 0.43}rem`);
+
       // Spacing scale
       setVar(root, '--fui-space-1', `${unitRem}rem`);
       setVar(root, '--fui-space-2', `${unitRem * 2}rem`);
@@ -527,6 +521,14 @@ export function configureTheme(options: ConfigureThemeOptions): void {
       setVar(root, '--fui-input-height', pxToRem(d.inputHeights[1], d.baseFontSize));
       setVar(root, '--fui-input-height-lg', pxToRem(d.inputHeights[2], d.baseFontSize));
 
+      // Touch targets (WCAG 2.5.8: all values ≥24px)
+      setVar(root, '--fui-touch-sm', pxToRem(d.touchTargets[0], d.baseFontSize));
+      setVar(root, '--fui-touch-md', pxToRem(d.touchTargets[1], d.baseFontSize));
+      setVar(root, '--fui-touch-lg', pxToRem(d.touchTargets[2], d.baseFontSize));
+
+      // Sidebar navigation
+      setVar(root, '--fui-sidebar-item-height', pxToRem(d.sidebarItemHeight, d.baseFontSize));
+
       // Base unit
       setVar(root, '--fui-base-unit', `${d.baseUnit}px`);
     }