@fragments-sdk/ui 0.13.0 → 0.15.1

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);
@@ -59,10 +59,11 @@
 .thumb {
   @include min-target-size;
 
-  width: $fui-slider-thumb-size;
-  height: $fui-slider-thumb-size;
+  position: relative;
+  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:
@@ -87,3 +88,66 @@
     opacity: 0.5;
   }
 }
+
+.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%;
+  bottom: calc(100% + var(--fui-space-2, $fui-space-2));
+  transform: translateX(-50%);
+  pointer-events: none;
+  white-space: nowrap;
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-2, $fui-space-2);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  background: var(--fui-tooltip-bg, $fui-tooltip-bg);
+  color: var(--fui-tooltip-text, $fui-tooltip-text);
+  font-family: var(--fui-font-mono, $fui-font-mono);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  line-height: 1;
+  box-shadow: var(--fui-tooltip-shadow, $fui-tooltip-shadow);
+
+  &::after {
+    content: '';
+    position: absolute;
+    top: 100%;
+    left: 50%;
+    transform: translateX(-50%);
+    width: 0;
+    height: 0;
+    border-left: 5px solid transparent;
+    border-right: 5px solid transparent;
+    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 */
@@ -24,6 +28,8 @@ export interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   max?: number;
   step?: number;
   showValue?: boolean;
+  /** Show a value bubble above the thumb while dragging */
+  showValueOnDrag?: boolean;
   valueSuffix?: string;
   disabled?: boolean;
   name?: string;
@@ -39,6 +45,8 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
   function Slider(
     {
       label,
+      helperText,
+      error = false,
       value,
       defaultValue,
       onChange,
@@ -47,6 +55,7 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
       max = 100,
       step = 1,
       showValue = false,
+      showValueOnDrag = false,
       valueSuffix = '',
       disabled = false,
       className,
@@ -61,6 +70,7 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
   ) {
     // For controlled component, use value; otherwise track internal state for display
     const [internalValue, setInternalValue] = React.useState(defaultValue ?? min);
+    const [isDragging, setIsDragging] = React.useState(false);
     const displayValue = value !== undefined ? value : internalValue;
 
     const resolvedOnChange = onChange ?? onValueChange;
@@ -70,8 +80,37 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
       resolvedOnChange?.(val);
     };
 
+    const handleDragStart = () => {
+      if (!disabled && showValueOnDrag) {
+        setIsDragging(true);
+      }
+    };
+
+    React.useEffect(() => {
+      if (!isDragging) return;
+
+      const handlePointerEnd = () => setIsDragging(false);
+      window.addEventListener('pointerup', handlePointerEnd);
+      window.addEventListener('pointercancel', handlePointerEnd);
+
+      return () => {
+        window.removeEventListener('pointerup', handlePointerEnd);
+        window.removeEventListener('pointercancel', handlePointerEnd);
+      };
+    }, [isDragging]);
+
+    React.useEffect(() => {
+      if (disabled && isDragging) {
+        setIsDragging(false);
+      }
+    }, [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>}
@@ -97,14 +136,29 @@ const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
           aria-labelledby={ariaLabelledBy}
           aria-describedby={ariaDescribedBy}
           className={styles.root}
+          onPointerDownCapture={handleDragStart}
         >
           <BaseSlider.Control className={styles.control}>
             <BaseSlider.Track className={styles.track}>
               <BaseSlider.Indicator className={styles.indicator} />
-              <BaseSlider.Thumb className={styles.thumb} />
+              <BaseSlider.Thumb
+                className={styles.thumb}
+              >
+                {showValueOnDrag && isDragging && (
+                  <span className={styles.dragValueBubble} aria-hidden="true">
+                    {displayValue}
+                    {valueSuffix}
+                  </span>
+                )}
+              </BaseSlider.Thumb>
             </BaseSlider.Track>
           </BaseSlider.Control>
         </BaseSlider.Root>
+        {helperText && (
+          <Field.Description className={helperClasses}>
+            {helperText}
+          </Field.Description>
+        )}
       </Field.Root>
     );
   }

package/src/components/Stack/index.tsx

@@ -4,7 +4,8 @@ import styles from './Stack.module.scss';
 type Direction = 'row' | 'column';
 type GapToken = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 /** Gap accepts string tokens or numbers (1-8) mapping to the spacing scale */
-type Gap = GapToken | number;
+type GapScale = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
+type Gap = GapToken | GapScale;
 
 /** Responsive value — either a single value or per-breakpoint overrides */
 export interface ResponsiveDirection {
@@ -38,7 +39,7 @@ export interface ResponsiveGap {
  * Flexbox layout component for vertical or horizontal stacking with consistent spacing.
  * @see https://usefragments.com/components/stack
  */
-export interface StackProps {
+export interface StackProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children' | 'style' | 'className'> {
   children: React.ReactNode;
   /**
    * Stack direction.
@@ -76,7 +77,7 @@ function isResponsiveGap(gap: StackProps['gap']): gap is ResponsiveGap {
   return typeof gap === 'object' && gap !== null;
 }
 
-function isNumericGap(gap: StackProps['gap']): gap is number {
+function isNumericGap(gap: StackProps['gap']): gap is GapScale {
   return typeof gap === 'number';
 }
 
@@ -93,6 +94,7 @@ const StackRoot = React.forwardRef<HTMLElement, StackProps>(
       as: Component = 'div',
       className,
       style,
+      ...htmlProps
     },
     ref
   ) {
@@ -175,7 +177,12 @@ const StackRoot = React.forwardRef<HTMLElement, StackProps>(
     }
 
     return (
-      <Component ref={ref as React.Ref<never>} className={classes} style={mergedStyle}>
+      <Component
+        {...htmlProps}
+        ref={ref as React.Ref<never>}
+        className={classes}
+        style={mergedStyle}
+      >
         {content}
       </Component>
     );
@@ -183,8 +190,8 @@ const StackRoot = React.forwardRef<HTMLElement, StackProps>(
 );
 
 // Map gap prop values to space variable numbers
-function gapToSpace(gap: Gap): string {
-  const map: Record<Gap, string> = {
+function gapToSpace(gap: GapToken): string {
+  const map: Record<GapToken, string> = {
     none: '0',
     xs: '1',
     sm: '2',

package/src/components/Table/Table.module.scss

@@ -33,7 +33,7 @@
 .sm {
   .th,
   .td {
-    padding: var(--fui-padding-item-xs, $fui-padding-item-xs) var(--fui-padding-item-md, $fui-padding-item-md);
+    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);
   }
 }
@@ -41,7 +41,7 @@
 .md {
   .th,
   .td {
-    padding: var(--fui-padding-item-xs, $fui-padding-item-xs) var(--fui-padding-item-md, $fui-padding-item-md);
+    padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
     font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   }
 }

package/src/components/Table/index.tsx

@@ -16,6 +16,10 @@ export interface TableProps extends React.HTMLAttributes<HTMLTableElement> {
   striped?: boolean;
   /** Wrap table in a bordered container */
   bordered?: boolean;
+  /** Class applied to the outer wrapper element */
+  wrapperClassName?: string;
+  /** Props applied to the outer wrapper element */
+  wrapperProps?: React.HTMLAttributes<HTMLDivElement>;
   children?: React.ReactNode;
 }
 
@@ -29,14 +33,16 @@ export interface TableCellProps extends React.TdHTMLAttributes<HTMLTableCellElem
   children?: React.ReactNode;
 }
 
-export interface TableHeaderCellProps extends React.ThHTMLAttributes<HTMLTableCellElement> {
+export interface TableHeaderCellProps extends React.ThHTMLAttributes<HTMLTableHeaderCellElement> {
   /** Scope for the header cell */
   scope?: string;
   children?: React.ReactNode;
 }
 
-export interface TableCaptionProps extends React.HTMLAttributes<HTMLTableCaptionElement> {
+export interface TableCaptionProps extends Omit<React.HTMLAttributes<HTMLTableCaptionElement>, 'hidden'> {
   /** Visually hide the caption (screen readers only) */
+  visuallyHidden?: boolean;
+  /** @deprecated Use visuallyHidden */
   hidden?: boolean;
   children?: React.ReactNode;
 }
@@ -97,10 +103,17 @@ function TableHeaderCell({ className, scope = 'col', children, ...props }: Table
   );
 }
 
-function TableCaption({ className, hidden: visuallyHidden, children, ...props }: TableCaptionProps) {
+function TableCaption({
+  className,
+  visuallyHidden,
+  hidden,
+  children,
+  ...props
+}: TableCaptionProps) {
+  const useVisuallyHidden = visuallyHidden ?? hidden;
   return (
     <caption
-      className={[visuallyHidden ? styles.captionHidden : styles.caption, className].filter(Boolean).join(' ')}
+      className={[useVisuallyHidden ? styles.captionHidden : styles.caption, className].filter(Boolean).join(' ')}
       {...props}
     >
       {children}
@@ -116,6 +129,8 @@ function TableRoot({
   size = 'md',
   striped = false,
   bordered = false,
+  wrapperClassName,
+  wrapperProps,
   className,
   children,
   ...htmlProps
@@ -130,7 +145,10 @@ function TableRoot({
     .join(' ');
 
   return (
-    <div className={[styles.wrapper, bordered && styles.bordered].filter(Boolean).join(' ')}>
+    <div
+      {...wrapperProps}
+      className={[styles.wrapper, bordered && styles.bordered, wrapperProps?.className, wrapperClassName].filter(Boolean).join(' ')}
+    >
       <table className={tableClasses} {...htmlProps}>
         {children}
       </table>

package/src/components/TableOfContents/index.tsx

@@ -38,12 +38,13 @@ function TableOfContentsRoot({
   title = 'On This Page',
   hideTitle = false,
   className,
+  'aria-label': ariaLabel,
   ...htmlProps
 }: TableOfContentsProps) {
   const classes = [styles.root, className].filter(Boolean).join(' ');
 
   return (
-    <nav aria-label={label} className={classes} {...htmlProps}>
+    <nav {...htmlProps} aria-label={ariaLabel ?? label} className={classes}>
       {!hideTitle && (
         <Text as="p" variant="section-label" className={styles.title}>
           {title}
@@ -63,6 +64,7 @@ function TableOfContentsItem({
   indent = false,
   className,
   onClick,
+  href: _href,
   ...htmlProps
 }: TableOfContentsItemProps) {
   const linkClasses = [
@@ -73,23 +75,25 @@ function TableOfContentsItem({
   ].filter(Boolean).join(' ');
 
   const handleClick = (e: React.MouseEvent<HTMLAnchorElement>) => {
+    onClick?.(e);
+    if (e.defaultPrevented) return;
+
     e.preventDefault();
     const el = document.getElementById(id);
     if (el) {
       el.scrollIntoView({ behavior: 'smooth' });
-      history.replaceState(null, '', `#${id}`);
+      window.history.replaceState(null, '', `#${id}`);
     }
-    onClick?.(e);
   };
 
   return (
     <li className={styles.item}>
       <a
+        {...htmlProps}
         href={`#${id}`}
         className={linkClasses}
         onClick={handleClick}
-        aria-current={active ? 'true' : undefined}
-        {...htmlProps}
+        aria-current={active ? 'location' : undefined}
       >
         {children}
       </a>

package/src/components/Tabs/Tabs.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 // Root container
 .root {
@@ -7,7 +7,7 @@
   flex-direction: column;
   font-family: var(--fui-font-sans, $fui-font-sans);
 
-  &[data-orientation='vertical'] {
+  &[data-orientation="vertical"] {
     flex-direction: row;
   }
 }
@@ -21,7 +21,7 @@
   border-bottom: 1px solid var(--fui-border, $fui-border);
   padding: 0 var(--fui-space-1, $fui-space-1);
 
-  &[data-orientation='vertical'] {
+  &[data-orientation="vertical"] {
     flex-direction: column;
     align-items: stretch;
     border-bottom: none;
@@ -55,7 +55,7 @@
   align-items: center;
   justify-content: center;
   gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-padding-item-xs, $fui-padding-item-xs) var(--fui-padding-item-md, $fui-padding-item-md);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
   font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   color: var(--fui-text-secondary, $fui-text-secondary);
@@ -80,7 +80,7 @@
 .tabUnderline {
   border-radius: 0;
   margin-bottom: -1px;
-  padding-bottom: calc(var(--fui-padding-item-xs, $fui-padding-item-xs) + 1px);
+  padding-bottom: calc(var(--fui-space-1, $fui-space-1) + 1px);
 
   &:hover:not([data-disabled]) {
     background-color: transparent;
@@ -122,7 +122,7 @@
     width var(--fui-transition-fast, $fui-transition-fast),
     transform var(--fui-transition-fast, $fui-transition-fast);
 
-  [data-orientation='vertical'] & {
+  [data-orientation="vertical"] & {
     bottom: auto;
     left: auto;
     right: 0;
@@ -135,7 +135,7 @@
 
 // Tab panel content
 .panel {
-  padding: var(--fui-padding-item-lg, $fui-padding-item-lg) 0;
+  padding: var(--fui-space-2, $fui-space-2) 0;
   outline: none;
 
   &[data-hidden] {

package/src/components/Tabs/index.tsx

@@ -25,6 +25,9 @@ export interface TabsProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'd
   /** Tab layout direction.
    * @default "horizontal" */
   orientation?: 'horizontal' | 'vertical';
+  /** Tab list visual style (default for Tabs.List).
+   * @default "underline" */
+  variant?: 'underline' | 'pills';
 }
 
 export interface TabsListProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -65,39 +68,44 @@ function TabsRoot({
   value,
   onValueChange,
   orientation = 'horizontal',
+  variant = 'underline',
   className,
   ...htmlProps
 }: TabsProps) {
   const classes = [styles.root, className].filter(Boolean).join(' ');
 
   return (
-    <BaseTabs.Root
-      {...htmlProps}
-      defaultValue={defaultValue}
-      value={value}
-      onValueChange={onValueChange}
-      orientation={orientation}
-      className={classes}
-    >
-      {children}
-    </BaseTabs.Root>
+    <TabsVariantContext.Provider value={variant}>
+      <BaseTabs.Root
+        {...htmlProps}
+        defaultValue={defaultValue}
+        value={value}
+        onValueChange={onValueChange}
+        orientation={orientation}
+        className={classes}
+      >
+        {children}
+      </BaseTabs.Root>
+    </TabsVariantContext.Provider>
   );
 }
 
 function TabsList({
   children,
-  variant = 'underline',
+  variant,
   className,
   ...htmlProps
 }: TabsListProps) {
-  const variantClass = variant === 'pills' ? styles.listPills : styles.listUnderline;
+  const rootVariant = React.useContext(TabsVariantContext);
+  const resolvedVariant = variant ?? rootVariant;
+  const variantClass = resolvedVariant === 'pills' ? styles.listPills : styles.listUnderline;
   const classes = [styles.list, variantClass, className].filter(Boolean).join(' ');
 
   return (
-    <TabsVariantContext.Provider value={variant}>
+    <TabsVariantContext.Provider value={resolvedVariant}>
       <BaseTabs.List {...htmlProps} className={classes}>
         {children}
-        {variant === 'underline' && <BaseTabs.Indicator className={styles.indicator} />}
+        {resolvedVariant === 'underline' && <BaseTabs.Indicator className={styles.indicator} />}
       </BaseTabs.List>
     </TabsVariantContext.Provider>
   );

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;
+  }
 }