@fragments-sdk/ui 0.12.0 → 0.14.0

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/Text/Text.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Text } from '.';
 
 export default defineFragment({

package/src/components/Textarea/Textarea.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Textarea } from '.';
 
 export default defineFragment({
@@ -88,6 +88,18 @@ export default defineFragment({
       type: 'number',
       description: 'Maximum character length',
     },
+    onChange: {
+      type: 'function',
+      description: 'Called when the textarea value changes',
+    },
+    onValueChange: {
+      type: 'function',
+      description: 'Value-first change callback alias: (value: string) => void',
+    },
+    rootProps: {
+      type: 'object',
+      description: 'HTML attributes applied to the wrapper element',
+    },
   },
 
   relations: [
@@ -106,6 +118,9 @@ export default defineFragment({
       'error: boolean - error state',
       'disabled: boolean - disabled state',
       'resize: none|vertical|horizontal|both',
+      'onValueChange: (value: string) => void - value-first change callback alias',
+      'rootProps: HTMLAttributes<HTMLDivElement> - wrapper element props',
+      '...native textarea attributes are supported (readOnly, autoComplete, maxLength, onKeyDown, etc.)',
     ],
     scenarioTags: [
       'form.textarea',
@@ -175,5 +190,16 @@ export default defineFragment({
         />
       ),
     },
+    {
+      name: 'With Root Props',
+      description: 'Pass wrapper attributes/styling via rootProps',
+      render: () => (
+        <Textarea
+          label="Notes"
+          placeholder="Add notes..."
+          rootProps={{ 'data-demo': 'textarea-wrapper' }}
+        />
+      ),
+    },
   ],
 });

package/src/components/Textarea/index.tsx

@@ -1,7 +1,10 @@
 import * as React from 'react';
 import styles from './Textarea.module.scss';
 
-export interface TextareaProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'onBlur' | 'defaultValue'> {
+export interface TextareaProps extends Omit<
+  React.TextareaHTMLAttributes<HTMLTextAreaElement>,
+  'onChange' | 'onBlur' | 'className' | 'style'
+> {
   /** Controlled value */
   value?: string;
   /** Default value for uncontrolled usage */
@@ -26,6 +29,8 @@ export interface TextareaProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   helperText?: string;
   /** Called when value changes */
   onChange?: (value: string) => void;
+  /** Alias for onChange (value-first callback) */
+  onValueChange?: (value: string) => void;
   /** Called when textarea loses focus */
   onBlur?: () => void;
   /** Form field name */
@@ -40,6 +45,12 @@ export interface TextareaProps extends Omit<React.HTMLAttributes<HTMLDivElement>
   'aria-labelledby'?: string;
   /** Accessible described-by relationship */
   'aria-describedby'?: string;
+  /** Props applied to the wrapper element */
+  rootProps?: React.HTMLAttributes<HTMLDivElement>;
+  /** Wrapper class name */
+  className?: string;
+  /** Wrapper styles */
+  style?: React.CSSProperties;
 }
 
 function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
@@ -62,20 +73,26 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       label,
       helperText,
       onChange,
+      onValueChange,
       onBlur,
+      rootProps,
       className,
-      name,
+      style: wrapperStyle,
+      ...textareaProps
+    },
+    ref
+  ) {
+    const generatedId = React.useId();
+    const {
       id,
+      name,
       maxLength,
       required = false,
       'aria-label': ariaLabel,
       'aria-labelledby': ariaLabelledBy,
       'aria-describedby': ariaDescribedBy,
-      ...htmlProps
-    },
-    ref
-  ) {
-    const generatedId = React.useId();
+      ...nativeTextareaProps
+    } = textareaProps;
     const textareaId = id || generatedId;
     const labelId = label ? `${textareaId}-label` : undefined;
     const helperId = `${textareaId}-helper`;
@@ -93,16 +110,20 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
       .join(' ');
 
     // Calculate min/max height based on rows
-    const style: React.CSSProperties = {};
+    const textareaInlineStyle: React.CSSProperties = {};
     if (minRows) {
-      style.minHeight = `calc(${minRows} * 1.5em + 1.5rem)`;
+      textareaInlineStyle.minHeight = `calc(${minRows} * 1.5em + 1.5rem)`;
     }
     if (maxRows) {
-      style.maxHeight = `calc(${maxRows} * 1.5em + 1.5rem)`;
+      textareaInlineStyle.maxHeight = `calc(${maxRows} * 1.5em + 1.5rem)`;
     }
 
     return (
-      <div {...htmlProps} className={[styles.wrapper, className].filter(Boolean).join(' ')}>
+      <div
+        {...rootProps}
+        className={[styles.wrapper, rootProps?.className, className].filter(Boolean).join(' ')}
+        style={{ ...(rootProps?.style ?? {}), ...(wrapperStyle ?? {}) }}
+      >
         {label && (
           <label id={labelId} htmlFor={textareaId} className={styles.label}>
             {label}
@@ -116,6 +137,7 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
           defaultValue={defaultValue}
           placeholder={placeholder}
           rows={rows}
+          {...nativeTextareaProps}
           name={name}
           maxLength={maxLength}
           disabled={disabled}
@@ -127,10 +149,13 @@ const TextareaRoot = React.forwardRef<HTMLTextAreaElement, TextareaProps>(
             ariaDescribedBy,
             helperText ? helperId : undefined
           )}
-          onChange={(e) => onChange?.(e.target.value)}
-          onBlur={onBlur}
+          onChange={(e) => {
+            onChange?.(e.target.value);
+            onValueChange?.(e.target.value);
+          }}
+          onBlur={() => onBlur?.()}
           className={textareaClasses}
-          style={Object.keys(style).length > 0 ? style : undefined}
+          style={Object.keys(textareaInlineStyle).length > 0 ? textareaInlineStyle : undefined}
         />
         {helperText && (
           <span id={helperId} className={helperClasses}>

package/src/components/Theme/Theme.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { ThemeProvider, ThemeToggle, useTheme } from '.';
 
 // Demo component to show hook usage
@@ -43,6 +43,7 @@ export default defineFragment({
       'ThemeToggle cycles through light → dark → system',
       'Use storageKey to customize localStorage key',
       'Set attribute="class" if your CSS uses .dark class instead of data-theme',
+      'ThemeToggle forwards DOM props (id, data-*, className, handlers) to the toggle group',
     ],
     accessibility: [
       'ThemeToggle button has accessible label indicating current mode',
@@ -96,6 +97,7 @@ export default defineFragment({
       'onModeChange: (mode) => void - change handler',
       'attribute: data-theme|class - DOM theme attribute',
       'ThemeToggle size: sm|md|lg - toggle button size',
+      'ThemeToggle forwards div DOM props to the button group root',
     ],
     scenarioTags: [
       'navigation.theme',

package/src/components/Theme/Theme.test.tsx

@@ -103,6 +103,17 @@ describe('ThemeToggle', () => {
     expect(screen.getByRole('group', { name: 'Switch theme' })).toBeInTheDocument();
   });
 
+  it('forwards DOM props to the toggle group', () => {
+    render(
+      <ThemeProvider>
+        <ThemeToggle data-testid="theme-toggle" id="theme-toggle-group" />
+      </ThemeProvider>
+    );
+
+    const group = screen.getByTestId('theme-toggle');
+    expect(group).toHaveAttribute('id', 'theme-toggle-group');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(
       <ThemeProvider>

package/src/components/Theme/index.tsx

@@ -40,7 +40,7 @@ export interface UseThemeReturn {
   toggleMode: () => void;
 }
 
-export interface ThemeToggleProps {
+export interface ThemeToggleProps extends React.HTMLAttributes<HTMLDivElement> {
   /** Size of the toggle button */
   size?: 'sm' | 'md' | 'lg';
   /** Whether to include system mode option (default: false) */
@@ -51,8 +51,6 @@ export interface ThemeToggleProps {
   onValueChange?: (value: 'light' | 'dark') => void;
   /** Accessible label for the group */
   'aria-label'?: string;
-  /** Additional class name */
-  className?: string;
 }
 
 // ============================================
@@ -282,6 +280,7 @@ function ThemeToggle({
   onValueChange,
   'aria-label': ariaLabel,
   className,
+  ...htmlProps
 }: ThemeToggleProps) {
   const { mode: contextMode, setMode: setContextMode } = useTheme();
 
@@ -314,6 +313,7 @@ function ThemeToggle({
 
   return (
     <div
+      {...htmlProps}
       className={groupClasses}
       role="group"
       aria-label={label}

package/src/components/ThinkingIndicator/ThinkingIndicator.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { ThinkingIndicator } from '.';
 
 export default defineFragment({

package/src/components/ThinkingIndicator/ThinkingIndicator.module.scss

@@ -38,7 +38,7 @@
 .dots {
   display: flex;
   align-items: center;
-  gap: 4px;
+  gap: calc(var(--fui-space-px, $fui-space-px) * 4);
 }
 
 .dot {

package/src/components/Toast/Toast.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Toast, ToastProvider, useToast } from '.';
 
 // Demo component that triggers toasts
@@ -9,7 +9,7 @@ function ToastDemo() {
   return (
     <div style={{ display: 'flex', gap: 'var(--fui-space-1)', flexWrap: 'wrap' }}>
       <button
-        onClick={() => success('Success!', 'Your changes have been saved.')}
+        onClick={() => success({ title: 'Success!', description: 'Your changes have been saved.', id: 'save-success' })}
         style={{ padding: 'var(--fui-space-1) var(--fui-space-2)', borderRadius: 'var(--fui-radius-md)', border: '1px solid var(--fui-color-success)', background: 'var(--fui-color-success-bg)', color: 'var(--fui-color-success)', cursor: 'pointer' }}
       >
         Success Toast
@@ -75,6 +75,7 @@ export default defineFragment({
       'Auto-dismiss after reasonable duration (3-5s)',
       'Allow manual dismissal for longer messages',
       'Limit number of simultaneous toasts',
+      'useToast() variant helpers accept either (title, description?) or an options object for action/duration/id',
     ],
     accessibility: [
       'Use role="alert" for important messages',
@@ -142,6 +143,8 @@ export default defineFragment({
       'variant: default|success|error|warning|info',
       'duration: number - ms before auto-dismiss',
       'action: { label, onClick } - optional action',
+      'ToastInput (useToast): optional id for deterministic creation/replacement flows',
+      'useToast().success/error/warning/info: (title, description?) or ({ title, description, action, duration, id })',
     ],
     scenarioTags: [
       'feedback.success',
@@ -158,7 +161,7 @@ export default defineFragment({
   variants: [
     {
       name: 'Default',
-      description: 'Interactive toast demo - click buttons to trigger toasts',
+      description: 'Interactive toast demo - click buttons to trigger toasts (includes helper object syntax example)',
       render: () => <ToastDemoWrapper />,
     },
     {

package/src/components/Toast/Toast.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 // ============================================
 // Toast Container
@@ -63,8 +63,8 @@
 .toast {
   display: flex;
   align-items: flex-start;
-  gap: var(--fui-space-3, $fui-space-3);
-  padding: var(--fui-padding-inline-sm, $fui-padding-inline-sm) var(--fui-padding-inline-md, $fui-padding-inline-md);
+  gap: var(--fui-space-1, $fui-space-1);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
   background-color: var(--fui-bg-elevated, $fui-bg-elevated);
   border: 1px solid var(--fui-border, $fui-border);
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
@@ -189,7 +189,8 @@
   }
 
   &:focus-visible {
-    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid var(--fui-focus-ring-color, $fui-focus-ring-color);
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid
+      var(--fui-focus-ring-color, $fui-focus-ring-color);
     outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
   }
 }
@@ -226,7 +227,8 @@
   }
 
   &:focus-visible {
-    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid var(--fui-focus-ring-color, $fui-focus-ring-color);
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid
+      var(--fui-focus-ring-color, $fui-focus-ring-color);
     outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
   }
 }

package/src/components/Toast/index.tsx

@@ -28,6 +28,11 @@ export interface ToastData {
   };
 }
 
+export interface ToastInput extends Omit<ToastData, 'id'> {
+  /** Optional explicit id (useful for deterministic tests / replacing a known toast) */
+  id?: string;
+}
+
 export interface ToastProps extends Omit<ToastData, 'id'>, Omit<React.HTMLAttributes<HTMLDivElement>, 'title'> {
   /** Callback when toast should be dismissed */
   onDismiss?: () => void;
@@ -50,7 +55,7 @@ export interface ToastProviderProps {
 
 interface ToastContextValue {
   toasts: ToastData[];
-  addToast: (toast: Omit<ToastData, 'id'>) => string;
+  addToast: (toast: ToastInput) => string;
   removeToast: (id: string) => void;
   clearToasts: () => void;
 }
@@ -67,25 +72,25 @@ export function useToast() {
     throw new Error('useToast must be used within a ToastProvider');
   }
 
-  const toast = React.useCallback((options: Omit<ToastData, 'id'>) => {
+  const toast = React.useCallback((options: ToastInput) => {
     return context.addToast(options);
   }, [context]);
 
-  const success = React.useCallback((title: string, description?: string) => {
-    return context.addToast({ title, description, variant: 'success' });
-  }, [context]);
-
-  const error = React.useCallback((title: string, description?: string) => {
-    return context.addToast({ title, description, variant: 'error' });
-  }, [context]);
+  const makeVariantHelper = React.useCallback(
+    (variant: ToastVariant) =>
+      (titleOrOptions: string | Omit<ToastInput, 'variant'>, description?: string) => {
+        if (typeof titleOrOptions === 'string') {
+          return context.addToast({ title: titleOrOptions, description, variant });
+        }
+        return context.addToast({ ...titleOrOptions, variant });
+      },
+    [context]
+  );
 
-  const warning = React.useCallback((title: string, description?: string) => {
-    return context.addToast({ title, description, variant: 'warning' });
-  }, [context]);
-
-  const info = React.useCallback((title: string, description?: string) => {
-    return context.addToast({ title, description, variant: 'info' });
-  }, [context]);
+  const success = React.useMemo(() => makeVariantHelper('success'), [makeVariantHelper]);
+  const error = React.useMemo(() => makeVariantHelper('error'), [makeVariantHelper]);
+  const warning = React.useMemo(() => makeVariantHelper('warning'), [makeVariantHelper]);
+  const info = React.useMemo(() => makeVariantHelper('info'), [makeVariantHelper]);
 
   return {
     toast,
@@ -292,8 +297,6 @@ function ToastContainer({
 // Toast Provider
 // ============================================
 
-let toastCounter = 0;
-
 export function ToastProvider({
   position = 'bottom-right',
   duration = 8000,
@@ -301,6 +304,7 @@ export function ToastProvider({
   children,
 }: ToastProviderProps) {
   const [toasts, setToasts] = React.useState<ToastData[]>([]);
+  const idCounterRef = React.useRef(0);
   const timeoutRef = React.useRef(new Map<string, ReturnType<typeof setTimeout>>());
   const remainingRef = React.useRef(new Map<string, number>());
   const startTimeRef = React.useRef(new Map<string, number>());
@@ -332,8 +336,8 @@ export function ToastProvider({
     [clearRemovalTimer]
   );
 
-  const addToast = React.useCallback((toast: Omit<ToastData, 'id'>) => {
-    const id = `toast-${++toastCounter}`;
+  const addToast = React.useCallback((toast: ToastInput) => {
+    const id = toast.id ?? `toast-${++idCounterRef.current}`;
     const toastDuration = toast.duration ?? (toast.action ? 0 : duration);
 
     setToasts((prev) => {

package/src/components/Toggle/Toggle.fragment.tsx

@@ -1,5 +1,5 @@
 import React, { useState } from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Switch } from '.';
 
 // Stateful wrapper for interactive demos