@fragments-sdk/ui 0.14.0 → 0.16.0

package/src/components/Input/index.tsx

@@ -2,6 +2,7 @@
 
 import * as React from 'react';
 import { Field } from '@base-ui/react/field';
+import { mergeAriaIds } from '../../utils/aria';
 import styles from './Input.module.scss';
 
 /**
@@ -30,6 +31,8 @@ export interface InputProps extends Omit<
   error?: boolean;
   /** Visible label text */
   label?: string;
+  /** Whether the field is required */
+  required?: boolean;
   /** Helper text shown below the input */
   helperText?: string;
   /** Keyboard shortcut hint displayed inside the input (e.g., "⌘K"). */
@@ -59,11 +62,6 @@ export interface InputProps 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;
-}
-
 function parseShortcut(shortcut: string): { meta: boolean; shift: boolean; alt: boolean; key: string } | null {
   let meta = false, shift = false, alt = false;
   let remaining = shortcut;
@@ -88,6 +86,7 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(
       size = 'md',
       disabled = false,
       error = false,
+      required = false,
       label,
       helperText,
       shortcut,
@@ -176,6 +175,7 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(
       defaultValue,
       placeholder,
       disabled,
+      required,
       onChange: (e: React.ChangeEvent<HTMLInputElement>) => {
         onChange?.(e.target.value);
         onValueChange?.(e.target.value);
@@ -222,7 +222,12 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(
           className={[styles.wrapper, rootProps?.className, className].filter(Boolean).join(' ')}
           style={{ ...(rootProps?.style ?? {}), ...(style ?? {}) }}
         >
-          {label && <label htmlFor={resolvedInputId} className={labelClasses}>{label}</label>}
+          {label && (
+            <label htmlFor={resolvedInputId} className={labelClasses}>
+              {label}
+              {required && <span className={styles.required}>*</span>}
+            </label>
+          )}
           {content}
           {helperText && (
             <div id={helperId} className={helperClasses}>
@@ -241,7 +246,12 @@ const InputRoot = React.forwardRef<HTMLInputElement, InputProps>(
         className={[wrapperClasses, rootProps?.className].filter(Boolean).join(' ')}
         style={{ ...(rootProps?.style ?? {}), ...(style ?? {}) }}
       >
-        {label && <Field.Label className={labelClasses}>{label}</Field.Label>}
+        {label && (
+          <Field.Label className={labelClasses}>
+            {label}
+            {required && <span className={styles.required}>*</span>}
+          </Field.Label>
+        )}
         {content}
         {helperText && (
           <Field.Description id={helperId} className={helperClasses}>

package/src/components/Listbox/Listbox.module.scss

@@ -1,3 +1,4 @@
+@use '../../tokens/variables' as *;
 @use '../../tokens/mixins' as *;
 
 // ============================================
@@ -6,10 +7,9 @@
 
 .listbox {
   @include surface-elevated;
+  @include popup-container;
 
   min-width: 12rem;
-  padding: var(--fui-space-1, 0.25rem);
-  box-shadow: var(--fui-shadow-lg);
   max-height: 320px;
   overflow-y: auto;
 
@@ -23,24 +23,13 @@
 // ============================================
 
 .item {
-  @include button-reset;
-  @include text-base;
+  @include popup-item;
 
-  display: flex;
-  align-items: center;
-  gap: var(--fui-space-2, 0.5rem);
-  width: 100%;
-  padding: var(--fui-space-1, 0.25rem) var(--fui-space-3, 0.75rem);
-  border-radius: var(--fui-radius-sm, 0.25rem);
-  cursor: pointer;
   text-align: left;
-  color: var(--fui-text-primary);
-  background: transparent;
-  border: none;
-  transition: background-color 0.1s ease;
+  transition: background-color var(--fui-transition-fast, $fui-transition-fast);
 
   &:hover {
-    background-color: var(--fui-bg-hover);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
   }
 
   &:focus-visible {
@@ -49,15 +38,15 @@
 }
 
 .itemSelected {
-  background-color: var(--fui-bg-hover);
+  background-color: var(--fui-bg-hover, $fui-bg-hover);
 }
 
 .itemActive {
-  background-color: var(--fui-bg-hover);
+  background-color: var(--fui-bg-hover, $fui-bg-hover);
 }
 
 .itemDisabled {
-  color: var(--fui-text-tertiary);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
   cursor: not-allowed;
 }
 
@@ -67,17 +56,14 @@
 
 .group {
   &:not(:first-child) {
-    margin-top: var(--fui-space-1, 0.25rem);
-    padding-top: var(--fui-space-1, 0.25rem);
-    border-top: 1px solid var(--fui-border);
+    margin-top: var(--fui-space-1, $fui-space-1);
+    padding-top: var(--fui-space-1, $fui-space-1);
+    border-top: 1px solid var(--fui-border, $fui-border);
   }
 }
 
 .groupLabel {
-  padding: var(--fui-space-1, 0.25rem) var(--fui-space-3, 0.75rem);
-  font-size: var(--fui-font-size-xs, 0.75rem);
-  font-weight: var(--fui-font-weight-medium, 500);
-  color: var(--fui-text-tertiary);
+  @include popup-group-label;
 }
 
 // ============================================
@@ -85,9 +71,10 @@
 // ============================================
 
 .empty {
-  padding: var(--fui-space-3, 0.75rem);
-  font-size: var(--fui-font-size-sm, 0.875rem);
-  color: var(--fui-text-secondary);
+  @include text-base;
+
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-2, $fui-space-2);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
   text-align: center;
 }
 
@@ -102,7 +89,7 @@
 
   .itemSelected,
   .itemActive {
-    outline: 2px solid var(--fui-color-accent);
+    outline: 2px solid var(--fui-color-accent, $fui-color-accent);
     outline-offset: -2px;
   }
 }

package/src/components/Menu/Menu.module.scss

@@ -10,12 +10,11 @@
 // Popup container
 .popup {
   @include surface-elevated;
+  @include popup-container;
 
   list-style: none;
   margin: 0;
   min-width: 12rem;
-  padding: var(--fui-space-1, $fui-space-1);
-  box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 
   // Animation
   opacity: 0;
@@ -39,17 +38,7 @@
 
 // Menu item (shared base)
 .item {
-  @include button-reset;
-  @include text-base;
-
-  display: flex;
-  align-items: center;
-  gap: var(--fui-space-1, $fui-space-1);
-  width: 100%;
-  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1);
-  border-radius: var(--fui-radius-sm, $fui-radius-sm);
-  cursor: pointer;
-  outline: none;
+  @include popup-item;
 
   &[data-highlighted] {
     background-color: var(--fui-bg-hover, $fui-bg-hover);
@@ -154,10 +143,7 @@
 
 // Group label
 .groupLabel {
-  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-1, $fui-space-1);
-  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);
+  @include popup-group-label;
 }
 
 // Arrow

package/src/components/Menu/index.tsx

@@ -73,7 +73,7 @@ export interface MenuGroupLabelProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
 }
 
-export interface MenuSeparatorProps extends React.HTMLAttributes<HTMLElement> {}
+export type MenuSeparatorProps = React.HTMLAttributes<HTMLElement>;
 
 export interface MenuSubmenuProps {
   children: React.ReactNode;

package/src/components/NavigationMenu/NavigationMenu.module.scss

@@ -6,6 +6,9 @@
 // ============================================
 
 .root {
+  // Container query context: children respond to nav menu width, not viewport
+  @include container(fui-navmenu);
+
   position: relative;
   display: flex;
   align-items: center;
@@ -28,7 +31,9 @@
   margin: 0;
   padding: 0;
 
-  // Hide on mobile — hamburger replaces it
+  // Use viewport breakpoint (matches useIsMobile in NavigationMenu.tsx).
+  // Self container queries on a shrink-to-content nav root can incorrectly hide
+  // the desktop list even on large screens.
   @include below-md {
     display: none;
   }
@@ -293,7 +298,7 @@
     opacity: 1;
   }
 
-  // Hide on mobile
+  // Keep viewport visibility in sync with JS mobile mode.
   @include below-md {
     display: none;
   }
@@ -325,6 +330,7 @@
     height: var(--fui-icon-xl, $fui-icon-xl);
   }
 
+  // Keep viewport visibility in sync with JS mobile mode.
   @include below-md {
     display: flex;
   }

package/src/components/NavigationMenu/index.tsx

@@ -63,13 +63,13 @@ export interface NavigationMenuContentProps {
   className?: string;
 }
 
-export interface NavigationMenuLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+export interface NavigationMenuLinkProps extends Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'title'> {
   /** Simple mode: children as text content */
   children?: React.ReactNode;
-  /** Structured mode: title text */
-  title?: string;
-  /** Structured mode: description text */
-  description?: string;
+  /** Structured mode: title (string or ReactNode) */
+  title?: React.ReactNode;
+  /** Structured mode: description (string or ReactNode) */
+  description?: React.ReactNode;
   /** Structured mode: icon element */
   icon?: React.ReactNode;
   /** Whether this link is the current page */
@@ -534,7 +534,17 @@ function NavigationMenuLink({
     if (!ctx || !itemCtx) return;
 
     const existing = ctx.itemInfoMap.current.get(itemCtx.value);
-    const fallbackLabel = typeof children === 'string' ? children : title || '';
+    const fallbackLabel =
+      typeof children === 'string'
+        ? children
+        : typeof title === 'string'
+          ? title
+          : React.Children.toArray(title ?? children)
+              .filter(
+                (node): node is string | number =>
+                  typeof node === 'string' || typeof node === 'number'
+              )
+              .join('');
     const resolvedHref = typeof href === 'string' ? href : existing?.linkHref;
 
     ctx.itemInfoMap.current.set(itemCtx.value, {

package/src/components/NavigationMenu/useNavigationMenu.ts

@@ -64,10 +64,13 @@ export function useNavigationMenu({
 
   // Clean up timers on unmount
   React.useEffect(() => {
+    const openTimer = openTimerRef.current;
+    const closeTimer = closeTimerRef.current;
+    const skipDelayTimer = skipDelayTimerRef.current;
     return () => {
-      if (openTimerRef.current) clearTimeout(openTimerRef.current);
-      if (closeTimerRef.current) clearTimeout(closeTimerRef.current);
-      if (skipDelayTimerRef.current) clearTimeout(skipDelayTimerRef.current);
+      if (openTimer) clearTimeout(openTimer);
+      if (closeTimer) clearTimeout(closeTimer);
+      if (skipDelayTimer) clearTimeout(skipDelayTimer);
     };
   }, []);
 

package/src/components/RadioGroup/RadioGroup.module.scss

@@ -5,7 +5,7 @@
 .wrapper {
   display: flex;
   flex-direction: column;
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: var(--fui-space-1, $fui-space-1);
 }
 
 .groupLabel {
@@ -145,7 +145,7 @@
   font-size: var(--fui-font-size-base, $fui-font-size-base);
 }
 
-.description {
+.helper {
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   color: var(--fui-text-secondary, $fui-text-secondary);
   line-height: var(--fui-line-height-normal, $fui-line-height-normal);
@@ -156,3 +156,32 @@
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   color: var(--fui-color-danger, $fui-color-danger);
 }
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .radio {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+
+    &[data-checked] {
+      border-color: var(--fui-color-accent, $fui-color-accent);
+    }
+
+    &[data-invalid] {
+      border-color: var(--fui-color-danger, $fui-color-danger);
+    }
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .indicator {
+    transition: none;
+  }
+}

package/src/components/RadioGroup/index.tsx

@@ -3,6 +3,7 @@
 import * as React from 'react';
 import { RadioGroup as BaseRadioGroup } from '@base-ui/react/radio-group';
 import { Radio as BaseRadio } from '@base-ui/react/radio';
+import { mergeAriaIds, useFormFieldIds } from '../../utils/aria';
 import styles from './RadioGroup.module.scss';
 
 // ============================================
@@ -30,8 +31,10 @@ export interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElemen
   name?: string;
   /** Label for the group */
   label?: string;
-  /** Error message */
-  error?: string;
+  /** Helper text shown below the group */
+  helperText?: string;
+  /** Show error styling. When a string is provided, it is displayed as an error message. */
+  error?: boolean | string;
   /** Size variant */
   size?: 'sm' | 'md' | 'lg';
   /** Class applied to the outer wrapper (label + group + error) */
@@ -47,7 +50,9 @@ export interface RadioItemProps {
   value: string;
   /** Label text */
   label?: string;
-  /** Description text below the label */
+  /** Helper text shown below the label */
+  helperText?: string;
+  /** @deprecated Use helperText instead. Description text below the label. */
   description?: string;
   /** Whether this item is disabled */
   disabled?: boolean;
@@ -65,11 +70,6 @@ export interface RadioItemProps {
   contentClassName?: string;
 }
 
-function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
-  const merged = ids.filter(Boolean).join(' ').trim();
-  return merged.length > 0 ? merged : undefined;
-}
-
 // ============================================
 // Context for size
 // ============================================
@@ -83,6 +83,7 @@ const RadioSizeContext = React.createContext<'sm' | 'md' | 'lg'>('md');
 function RadioItem({
   value,
   label,
+  helperText,
   description,
   disabled = false,
   'aria-label': ariaLabel,
@@ -92,10 +93,11 @@ function RadioItem({
   controlClassName,
   contentClassName,
 }: RadioItemProps) {
+  const resolvedHelperText = helperText ?? description;
   const size = React.useContext(RadioSizeContext);
   const id = React.useId();
   const labelId = label ? `radio-label-${id}` : undefined;
-  const descriptionId = description ? `radio-desc-${id}` : undefined;
+  const descriptionId = resolvedHelperText ? `radio-desc-${id}` : undefined;
 
   const radioClasses = [
     styles.radio,
@@ -113,7 +115,7 @@ function RadioItem({
   const wrapperClasses = [styles.itemWrapper, className].filter(Boolean).join(' ');
 
   // If no label/description, render just the radio
-  if (!label && !description) {
+  if (!label && !resolvedHelperText) {
     return (
       <BaseRadio.Root
         value={value}
@@ -132,7 +134,7 @@ function RadioItem({
     <label
       className={wrapperClasses}
       data-disabled={disabled || undefined}
-      data-has-description={description ? true : undefined}
+      data-has-description={resolvedHelperText ? true : undefined}
     >
       <BaseRadio.Root
         value={value}
@@ -146,8 +148,8 @@ function RadioItem({
       </BaseRadio.Root>
       <div className={[styles.content, contentClassName].filter(Boolean).join(' ')}>
         <span id={labelId} className={labelClasses}>{label}</span>
-        {description && (
-          <span id={descriptionId} className={styles.description}>{description}</span>
+        {resolvedHelperText && (
+          <span id={descriptionId} className={styles.helper}>{resolvedHelperText}</span>
         )}
       </div>
     </label>
@@ -158,7 +160,7 @@ function RadioItem({
 // Radio Group Component
 // ============================================
 
-function RadioGroupRoot({
+const RadioGroupRoot = React.forwardRef<HTMLDivElement, RadioGroupProps>(function RadioGroupRoot({
   value,
   defaultValue,
   onValueChange,
@@ -167,6 +169,7 @@ function RadioGroupRoot({
   disabled = false,
   name,
   label,
+  helperText,
   error,
   size = 'md',
   wrapperClassName,
@@ -177,10 +180,8 @@ function RadioGroupRoot({
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
   ...htmlProps
-}: RadioGroupProps) {
-  const groupId = React.useId();
-  const labelId = label ? `radio-group-label-${groupId}` : undefined;
-  const errorId = error ? `radio-group-error-${groupId}` : undefined;
+}: RadioGroupProps, ref) {
+  const { labelId, helperId, errorId, hasError, errorMessage } = useFormFieldIds('radio-group', { label, helperText, error });
 
   const groupClasses = [
     styles.group,
@@ -193,7 +194,7 @@ function RadioGroupRoot({
 
   return (
     <RadioSizeContext.Provider value={size}>
-      <div {...htmlProps} className={[styles.wrapper, wrapperClassName].filter(Boolean).join(' ')}>
+      <div ref={ref} {...htmlProps} className={[styles.wrapper, wrapperClassName].filter(Boolean).join(' ')}>
         {label && <span id={labelId} className={styles.groupLabel}>{label}</span>}
         <BaseRadioGroup
           value={value}
@@ -203,16 +204,21 @@ function RadioGroupRoot({
           name={name}
           aria-label={ariaLabel}
           aria-labelledby={mergeAriaIds(ariaLabelledBy, labelId)}
-          aria-describedby={mergeAriaIds(ariaDescribedBy, errorId)}
+          aria-describedby={mergeAriaIds(ariaDescribedBy, errorId, helperId)}
           className={groupClasses}
         >
           {children}
         </BaseRadioGroup>
-        {error && <span id={errorId} className={styles.error}>{error}</span>}
+        {helperText && (
+          <span id={helperId} className={hasError ? [styles.helper, styles.error].join(' ') : styles.helper}>
+            {helperText}
+          </span>
+        )}
+        {errorMessage && <span id={errorId} className={styles.error}>{errorMessage}</span>}
       </div>
     </RadioSizeContext.Provider>
   );
-}
+});
 
 // ============================================
 // Compound Component Export

package/src/components/Select/Select.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 button
 .trigger {
   @include button-reset;
@@ -34,6 +37,19 @@
   }
 }
 
+// Trigger size variants
+.triggerSm {
+  height: var(--fui-input-height-sm, $fui-input-height-sm);
+  padding: 0 var(--fui-space-2, $fui-space-2);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+}
+
+.triggerLg {
+  height: var(--fui-input-height-lg, $fui-input-height-lg);
+  padding: 0 var(--fui-space-4, $fui-space-4);
+  font-size: var(--fui-font-size-base, $fui-font-size-base);
+}
+
 // Value display
 .value {
   flex: 1;
@@ -81,6 +97,7 @@
 // Popup container
 .popup {
   @include surface-elevated;
+  @include popup-container;
 
   // Item height derived from text-base font + vertical padding
   --_item-h: calc(
@@ -96,8 +113,6 @@
     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;
@@ -121,17 +136,7 @@
 
 // Individual option
 .item {
-  @include button-reset;
-  @include text-base;
-
-  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;
+  @include popup-item;
 
   &[data-highlighted] {
     background-color: var(--fui-bg-hover, $fui-bg-hover);
@@ -178,12 +183,40 @@
 
 // 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) {
+  .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);
+    }
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .trigger {
+    transition: none;
+  }
+
+  .popup {
+    transition: none;
+  }
+
+  .icon svg {
+    transition: none;
+  }
 }
 
 // Arrow