@fragments-sdk/ui 0.13.0 → 0.14.0

package/src/components/ToggleGroup/ToggleGroup.fragment.tsx

@@ -1,5 +1,5 @@
 import React from "react";
-import { defineFragment } from "@fragments-sdk/cli/core";
+import { defineFragment } from "@fragments-sdk/core";
 import { ToggleGroup } from ".";
 
 function DefaultExample() {
@@ -30,7 +30,7 @@ function OutlineExample() {
   const [value, setValue] = React.useState("day");
 
   return (
-    <ToggleGroup value={value} onChange={setValue} variant="outline">
+    <ToggleGroup value={value} onChange={setValue} variant="outlined">
       <ToggleGroup.Item value="day">Day</ToggleGroup.Item>
       <ToggleGroup.Item value="week">Week</ToggleGroup.Item>
       <ToggleGroup.Item value="month">Month</ToggleGroup.Item>
@@ -141,7 +141,7 @@ export default defineFragment({
       "Ensure adequate touch targets on mobile",
     ],
     accessibility: [
-      'Uses role="group" for semantic grouping',
+      'Uses role="radiogroup" for single-selection semantics',
       'Each item has role="radio" with aria-checked',
       "Keyboard navigable with Tab and arrow keys",
       "Focus visible on active item",
@@ -152,7 +152,10 @@ export default defineFragment({
     value: {
       type: "string",
       description: "Currently selected value",
-      required: true,
+    },
+    defaultValue: {
+      type: "string",
+      description: "Initial selected value (uncontrolled)",
     },
     onChange: {
       type: "function",
@@ -170,7 +173,7 @@ export default defineFragment({
     variant: {
       type: "enum",
       description: "Visual style",
-      values: ["default", "pills", "outline"],
+      values: ["default", "pills", "outline", "outlined"],
       default: "default",
     },
     size: {
@@ -185,6 +188,12 @@ export default defineFragment({
       values: ["none", "xs", "sm"],
       default: "xs",
     },
+    selectionMode: {
+      type: "enum",
+      description: "Selection behavior",
+      values: ["single"],
+      default: "single",
+    },
   },
 
   relations: [
@@ -199,12 +208,14 @@ export default defineFragment({
 
   contract: {
     propsSummary: [
-      "value: string - selected value (required)",
+      "value?: string - controlled selected value",
+      "defaultValue?: string - initial selected value (uncontrolled)",
       "onChange: (value: string) => void - change handler (or onValueChange)",
       "children: ToggleGroup.Item[] - toggle items",
-      "variant: default|pills|outline - visual style",
+      "variant: default|pills|outline|outlined - visual style (outlined aliases outline)",
       "size: sm|md - size variant",
       "gap: none|xs|sm - spacing",
+      "selectionMode: single (default: single)",
     ],
     scenarioTags: ["forms.selection", "input.toggle", "control.fragmented"],
     a11yRules: ["A11Y_GROUP_ROLE", "A11Y_KEYBOARD_ACCESSIBLE"],
@@ -234,13 +245,27 @@ export default defineFragment({
     {
       name: "Outline Variant",
       description: "Outlined toggle buttons",
-      code: `<ToggleGroup value={value} onChange={setValue} variant="outline">
+      code: `<ToggleGroup value={value} onChange={setValue} variant="outlined">
   <ToggleGroup.Item value="day">Day</ToggleGroup.Item>
   <ToggleGroup.Item value="week">Week</ToggleGroup.Item>
   <ToggleGroup.Item value="month">Month</ToggleGroup.Item>
 </ToggleGroup>`,
       render: () => <OutlineExample />,
     },
+    {
+      name: "Uncontrolled",
+      description: "Use defaultValue for simple single-select state",
+      code: `<ToggleGroup defaultValue="list">
+  <ToggleGroup.Item value="grid">Grid</ToggleGroup.Item>
+  <ToggleGroup.Item value="list">List</ToggleGroup.Item>
+</ToggleGroup>`,
+      render: () => (
+        <ToggleGroup defaultValue="list">
+          <ToggleGroup.Item value="grid">Grid</ToggleGroup.Item>
+          <ToggleGroup.Item value="list">List</ToggleGroup.Item>
+        </ToggleGroup>
+      ),
+    },
     {
       name: "Sizes",
       description: "Different size variants",

package/src/components/ToggleGroup/ToggleGroup.module.scss

@@ -12,7 +12,7 @@
 
 // Gap variants
 .gap-xs {
-  gap: 2px;
+  gap: calc(var(--fui-space-px, $fui-space-px) * 2);
 }
 
 .gap-sm {
@@ -26,8 +26,8 @@
 .default {
   background-color: var(--fui-bg-secondary, $fui-bg-secondary);
   border-radius: var(--fui-radius-md, $fui-radius-md);
-  padding: 2px;
-  gap: 2px;
+  padding: calc(var(--fui-space-px, $fui-space-px) * 2);
+  gap: calc(var(--fui-space-px, $fui-space-px) * 2);
 
   .item {
     background-color: transparent;

package/src/components/ToggleGroup/index.tsx

@@ -13,7 +13,9 @@ import styles from './ToggleGroup.module.scss';
  */
 export interface ToggleGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange'> {
   /** Current selected value */
-  value: string;
+  value?: string;
+  /** Default selected value (uncontrolled) */
+  defaultValue?: string;
   /** Callback when selection changes */
   onChange?: (value: string) => void;
   /** Alias for onChange (Radix convention) */
@@ -23,12 +25,15 @@ export interface ToggleGroupProps extends Omit<React.HTMLAttributes<HTMLDivEleme
   /** Visual variant.
    * @default "default"
    * @see https://usefragments.com/components/togglegroup#variants */
-  variant?: 'default' | 'pills' | 'outline';
+  variant?: 'default' | 'pills' | 'outline' | 'outlined';
   /** Size.
    * @default "md" */
   size?: 'sm' | 'md' | 'lg';
   /** Gap between items (for pills/outline variants) */
   gap?: 'none' | 'xs' | 'sm';
+  /** Selection mode for this control. Currently only single-select is supported.
+   * @default "single" */
+  selectionMode?: 'single';
 }
 
 export interface ToggleGroupItemProps extends Omit<React.HTMLAttributes<HTMLButtonElement>, 'onClick'> {
@@ -71,19 +76,30 @@ function useToggleGroupContext() {
 
 function ToggleGroupRoot({
   value,
+  defaultValue,
   onChange,
   onValueChange,
   children,
   variant = 'default',
   size = 'md',
   gap = 'xs',
+  selectionMode = 'single',
   className,
   ...htmlProps
 }: ToggleGroupProps) {
-  const resolvedOnChange = onChange ?? onValueChange ?? (() => {});
+  const normalizedVariant = variant === 'outlined' ? 'outline' : variant;
+  const [internalValue, setInternalValue] = React.useState(defaultValue ?? '');
+  const isControlled = value !== undefined;
+  const currentValue = isControlled ? value ?? '' : internalValue;
+  const emitChange = React.useCallback((nextValue: string) => {
+    if (!isControlled) {
+      setInternalValue(nextValue);
+    }
+    (onChange ?? onValueChange)?.(nextValue);
+  }, [isControlled, onChange, onValueChange]);
   const classes = [
     styles.group,
-    styles[variant],
+    styles[normalizedVariant],
     styles[`size-${size}`],
     gap !== 'none' && styles[`gap-${gap}`],
     className,
@@ -97,13 +113,13 @@ function ToggleGroupRoot({
   );
   const firstEnabledValue = childItems.find((item) => !item.props.disabled)?.props.value ?? null;
   const hasFocusableSelection = childItems.some(
-    (item) => !item.props.disabled && item.props.value === value
+    (item) => !item.props.disabled && item.props.value === currentValue
   );
 
   const contextValue: ToggleGroupContextValue = {
-    value,
-    onChange: resolvedOnChange,
-    variant,
+    value: currentValue,
+    onChange: emitChange,
+    variant: normalizedVariant,
     size,
     hasFocusableSelection,
     firstEnabledValue,
@@ -111,7 +127,11 @@ function ToggleGroupRoot({
 
   return (
     <ToggleGroupContext.Provider value={contextValue}>
-      <div {...htmlProps} role="radiogroup" className={classes}>
+      <div
+        {...htmlProps}
+        role={selectionMode === 'single' ? 'radiogroup' : 'radiogroup'}
+        className={classes}
+      >
         {children}
       </div>
     </ToggleGroupContext.Provider>

package/src/components/Tooltip/Tooltip.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Tooltip } from '.';
 import { Button } from '../Button';
 
@@ -33,6 +33,7 @@ export default defineFragment({
       'Use sentence case, no period for single sentences',
       'Avoid duplicating visible label text',
       'Consider mobile users who cannot hover',
+      'Use contentProps for tooltip popup attributes/styling; top-level HTML attrs are applied to the popup for backward compatibility',
     ],
     accessibility: [
       'Accessible via focus as well as hover',
@@ -102,6 +103,10 @@ export default defineFragment({
       type: 'function',
       description: 'Callback when open state changes',
     },
+    contentProps: {
+      type: 'object',
+      description: 'Props forwarded to the tooltip popup element (preferred way to pass popup attrs/className/style)',
+    },
   },
 
   relations: [
@@ -115,6 +120,7 @@ export default defineFragment({
       'side: top|bottom|left|right - position',
       'delay: number - show delay in ms (default: 400)',
       'arrow: boolean - show arrow (default: true)',
+      'contentProps: HTMLAttributes<HTMLDivElement> - popup element props',
     ],
     scenarioTags: [
       'help.tooltip',
@@ -172,5 +178,14 @@ export default defineFragment({
         </Tooltip>
       ),
     },
+    {
+      name: 'With Content Props',
+      description: 'Pass popup attributes/styling using contentProps',
+      render: () => (
+        <Tooltip content="Custom popup attrs" contentProps={{ id: 'custom-tooltip-popup' }}>
+          <Button variant="secondary">Hover me</Button>
+        </Tooltip>
+      ),
+    },
   ],
 });

package/src/components/Tooltip/Tooltip.module.scss

@@ -11,7 +11,7 @@
 .popup {
   @include text-base;
 
-  padding: var(--fui-padding-item-xs) var(--fui-padding-item-sm);
+  padding: var(--fui-space-1) var(--fui-space-2);
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   line-height: var(--fui-line-height-tight, $fui-line-height-tight);
   // Tooltips use inverted colors - always dark bg with light text

package/src/components/Tooltip/index.tsx

@@ -36,6 +36,8 @@ export interface TooltipProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   defaultOpen?: boolean;
   /** Callback when open state changes */
   onOpenChange?: (open: boolean) => void;
+  /** Explicit props for the tooltip popup element (preferred over top-level HTMLAttributes for clarity) */
+  contentProps?: React.HTMLAttributes<HTMLDivElement>;
 }
 
 export interface TooltipProviderProps {
@@ -81,7 +83,9 @@ function TooltipRoot({
   open,
   defaultOpen,
   onOpenChange,
+  contentProps,
   className,
+  style,
   ...htmlProps
 }: TooltipProps) {
   const hasExternalProvider = React.useContext(TooltipProviderContext);
@@ -113,6 +117,12 @@ function TooltipRoot({
     return children;
   }
 
+  const {
+    className: contentClassName,
+    style: contentStyle,
+    ...contentHtmlProps
+  } = contentProps ?? {};
+
   const tooltipNode = (
     <BaseTooltip.Root
       open={open}
@@ -127,7 +137,12 @@ function TooltipRoot({
           sideOffset={sideOffset}
           className={styles.positioner}
         >
-          <BaseTooltip.Popup {...htmlProps} className={[styles.popup, className].filter(Boolean).join(' ')}>
+          <BaseTooltip.Popup
+            {...htmlProps}
+            {...contentHtmlProps}
+            className={[styles.popup, className, contentClassName].filter(Boolean).join(' ')}
+            style={{ ...(style ?? {}), ...(contentStyle ?? {}) }}
+          >
             {content}
             {arrow && <BaseTooltip.Arrow className={styles.arrow} />}
           </BaseTooltip.Popup>

package/src/components/VisuallyHidden/VisuallyHidden.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { VisuallyHidden } from '.';
 
 export default defineFragment({
@@ -32,6 +32,7 @@ export default defineFragment({
       'Keep hidden text concise but descriptive',
       'Test with screen readers to verify announcements',
       'Don\'t overuse; visible text is often better',
+      'VisuallyHidden forwards DOM props and className to the rendered element',
     ],
     accessibility: [
       'Content is announced by screen readers',
@@ -64,6 +65,7 @@ export default defineFragment({
     propsSummary: [
       'children: ReactNode - hidden text (required)',
       'as: span|div - HTML element',
+      'Forwards standard DOM props (id, aria-*, data-*, className, handlers)',
     ],
     scenarioTags: [
       'accessibility.label',

package/src/components/VisuallyHidden/VisuallyHidden.test.tsx

@@ -28,4 +28,16 @@ describe('VisuallyHidden', () => {
     const { container } = render(<VisuallyHidden>Accessible hidden text</VisuallyHidden>);
     await expectNoA11yViolations(container);
   });
+
+  it('forwards DOM props and composes className', () => {
+    render(
+      <VisuallyHidden data-testid="vh" id="vh-id" className="extra">
+        Hidden
+      </VisuallyHidden>
+    );
+    const el = screen.getByTestId('vh');
+    expect(el).toHaveAttribute('id', 'vh-id');
+    expect(el).toHaveClass('visuallyHidden');
+    expect(el).toHaveClass('extra');
+  });
 });

package/src/components/VisuallyHidden/index.tsx

@@ -1,7 +1,7 @@
 import * as React from 'react';
 import styles from './VisuallyHidden.module.scss';
 
-export interface VisuallyHiddenProps {
+export interface VisuallyHiddenProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** HTML element to render */
   as?: 'span' | 'div';
@@ -19,9 +19,13 @@ export interface VisuallyHiddenProps {
  * </Button>
  */
 const VisuallyHiddenRoot = React.forwardRef<HTMLElement, VisuallyHiddenProps>(
-  function VisuallyHidden({ children, as: Component = 'span' }, ref) {
+  function VisuallyHidden({ children, as: Component = 'span', className, ...htmlProps }, ref) {
     return (
-      <Component ref={ref as React.Ref<never>} className={styles.visuallyHidden}>
+      <Component
+        ref={ref as React.Ref<never>}
+        {...htmlProps}
+        className={[styles.visuallyHidden, className].filter(Boolean).join(' ')}
+      >
         {children}
       </Component>
     );

package/src/index.ts

@@ -30,8 +30,6 @@ export {
 export {
   Switch,
   type SwitchProps,
-  Switch as Toggle,
-  type SwitchProps as ToggleProps,
 } from './components/Switch';
 export {
   Alert,
@@ -665,3 +663,6 @@ export {
   type ShortcutName,
   type UseKeyboardShortcutOptions,
 } from './utils/keyboard-shortcuts';
+
+// Legacy aliases (deprecated)
+export { Switch as Toggle, type SwitchProps as ToggleProps } from './components/Switch';

package/src/tokens/_computed.scss

@@ -24,9 +24,8 @@ $_palette: palettes.get-palette(seeds.$fui-neutral);
 $_density: density.get-density(seeds.$fui-density);
 $_radius: radius.get-radius-style(seeds.$fui-radius-style);
 
-// Derive spacing and padding from density
+// Derive spacing from density
 $_spacing: density.derive-spacing($_density);
-$_padding: density.derive-padding($_density);
 
 // --------------------------------------------
 // Computed: Base Configuration
@@ -52,23 +51,6 @@ $computed-space-8: map.get($_spacing, 8);
 $computed-space-10: map.get($_spacing, 10);
 $computed-space-12: map.get($_spacing, 12);
 
-// --------------------------------------------
-// Computed: Density Padding
-// --------------------------------------------
-
-$computed-padding-container-sm: map.get($_padding, container-sm);
-$computed-padding-container-md: map.get($_padding, container-md);
-$computed-padding-container-lg: map.get($_padding, container-lg);
-$computed-padding-container-xl: map.get($_padding, container-xl);
-$computed-padding-inline-xs: map.get($_padding, inline-xs);
-$computed-padding-inline-sm: map.get($_padding, inline-sm);
-$computed-padding-inline-md: map.get($_padding, inline-md);
-$computed-padding-inline-lg: map.get($_padding, inline-lg);
-$computed-padding-item-xs: map.get($_padding, item-xs);
-$computed-padding-item-sm: map.get($_padding, item-sm);
-$computed-padding-item-md: map.get($_padding, item-md);
-$computed-padding-item-lg: map.get($_padding, item-lg);
-
 // --------------------------------------------
 // Computed: Border Radius
 // --------------------------------------------

package/src/tokens/_density.scss

@@ -163,48 +163,6 @@ $densities: (
   );
 }
 
-/// Derive container padding from density
-/// @param {Map} $density - A density configuration map
-/// @return {Map} Padding tokens
-@function derive-padding($density) {
-  $base: map.get($density, base-unit);
-  $font-size: map.get($density, base-font-size);
-  $unit-rem: math.div($base, $font-size) * 1rem;
-
-  @return (
-    // Container padding: Cards, Dialogs, Popovers
-    container-sm: $unit-rem * 3,
-    // 3 units
-    container-md: $unit-rem * 4,
-    // 4 units
-    container-lg: $unit-rem * 6,
-
-    // 6 units
-    // Inline padding: Alerts, Toasts
-    inline-xs: $unit-rem * 1,
-    // 1 unit
-    inline-sm: $unit-rem * 2,
-    // 2 units
-    inline-md: $unit-rem * 3,
-    // 3 units
-    inline-lg: $unit-rem * 4,
-
-    // 4 units
-    // Container padding (extended)
-    container-xl: $unit-rem * 8,
-
-    // 8 units
-    // Item padding: Accordion, Tabs, Menu items
-    item-xs: $unit-rem * 1,
-    // 1 unit
-    item-sm: $unit-rem * 2,
-    // 2 units
-    item-md: $unit-rem * 3,
-    // 3 units
-    item-lg: $unit-rem * 4 // 4 units
-  );
-}
-
 /// Convert pixel value to rem based on density
 /// @param {Map} $density - A density configuration map
 /// @param {Number} $px - Pixel value to convert

package/src/tokens/_mixins.scss

@@ -182,6 +182,10 @@
 /// @param {String} $size - Size variant: 'sm', 'md', or 'lg'
 /// @param {String} $component - Component type: 'button', 'input', or 'select'
 @mixin control-size($size, $component: 'button') {
+  // Global accessibility floor: component-specific height tokens may be customized,
+  // but controls should not shrink below the minimum target size.
+  min-height: var(--fui-target-size-min, #{$fui-target-size-min});
+
   @if $size == 'sm' {
     @if $component == 'input' {
       height: var(--fui-input-height-sm, #{$fui-input-height-sm});