@fragments-sdk/ui 0.12.0 → 0.14.0

package/src/components/Card/index.tsx

@@ -11,7 +11,7 @@ import styles from './Card.module.scss';
  * Card container for grouping related content.
  * @see https://usefragments.com/components/card
  */
-export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick'> {
+export interface CardProps extends Omit<React.HTMLAttributes<HTMLElement>, 'children'> {
   children: React.ReactNode;
   /** Visual style variant. `"outline"` is an alias for `"outlined"`.
    * @default "default"
@@ -20,8 +20,9 @@ export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'o
   /** Inner padding.
    * @default "md" */
   padding?: 'none' | 'sm' | 'md' | 'lg';
-  /** Makes the card interactive (clickable) */
-  onClick?: () => void;
+  /** Root element tag.
+   * @default "article" */
+  as?: 'article' | 'div' | 'section';
 }
 
 export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -56,14 +57,6 @@ interface CardContextValue {
 
 const CardContext = React.createContext<CardContextValue | null>(null);
 
-function useCardContext() {
-  const context = React.useContext(CardContext);
-  if (!context) {
-    throw new Error('Card compound components must be used within a Card');
-  }
-  return context;
-}
-
 // ============================================
 // Padding Map
 // ============================================
@@ -83,17 +76,15 @@ function CardRoot({
   children,
   variant: variantProp = 'default',
   padding = 'md',
-  onClick,
+  as: Component = 'article',
   className,
   style,
-  'aria-label': ariaLabel,
-  'aria-describedby': ariaDescribedBy,
   ...htmlProps
 }: CardProps) {
   // Resolve alias: "outline" → "outlined"
   const variant = variantProp === 'outline' ? 'outlined' : variantProp;
 
-  const isInteractive = !!onClick;
+  const isInteractive = typeof htmlProps.onClick === 'function';
 
   const classes = [
     styles.card,
@@ -111,35 +102,15 @@ function CardRoot({
     isInteractive,
   };
 
-  if (isInteractive) {
-    return (
-      <CardContext.Provider value={contextValue}>
-        <button
-          type="button"
-          {...(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>)}
-          onClick={onClick}
-          className={classes}
-          style={style}
-          aria-label={ariaLabel}
-          aria-describedby={ariaDescribedBy}
-        >
-          {children}
-        </button>
-      </CardContext.Provider>
-    );
-  }
-
   return (
     <CardContext.Provider value={contextValue}>
-      <article
+      <Component
         {...htmlProps}
         className={classes}
         style={style}
-        aria-label={ariaLabel}
-        aria-describedby={ariaDescribedBy}
       >
         {children}
-      </article>
+      </Component>
     </CardContext.Provider>
   );
 }
@@ -189,5 +160,4 @@ export {
   CardDescription,
   CardBody,
   CardFooter,
-  useCardContext,
 };

package/src/components/Chart/Chart.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import {
   LineChart,
   Line,
@@ -69,9 +69,10 @@ export default defineFragment({
     ],
     guidelines: [
       'Use ChartContainer to wrap recharts chart components',
-      'Define a ChartConfig to map data keys to labels and colors',
+      'Define a ChartConfig to map data keys to labels and colors (and optionally icons for custom legend/tooltip UIs)',
       'Use FUI CSS variables for colors so charts adapt to theme changes',
       'Use ChartTooltip and ChartLegend for consistent themed overlays',
+      'ChartTooltip and ChartLegend accept custom content renderers for advanced formatting',
     ],
     accessibility: [
       'Charts include recharts accessibilityLayer by default',
@@ -83,7 +84,7 @@ export default defineFragment({
   props: {
     config: {
       type: 'object',
-      description: 'ChartConfig mapping data keys to labels and colors',
+      description: 'ChartConfig mapping data keys to labels/colors (optional icon per series)',
     },
     children: {
       type: 'element',
@@ -109,6 +110,7 @@ export default defineFragment({
     propsSummary: [
       'config: ChartConfig - maps data keys to labels and theme colors',
       'children: ReactElement - recharts chart component',
+      'Chart.Tooltip / Chart.Legend support custom content renderers for advanced overlays',
     ],
     scenarioTags: [
       'display.chart',

package/src/components/Chart/Chart.module.scss

@@ -55,7 +55,7 @@
 .tooltipItems {
   display: flex;
   flex-direction: column;
-  gap: 2px;
+  gap: calc(var(--fui-space-px, $fui-space-px) * 2);
 }
 
 .tooltipItem {

package/src/components/Chart/index.tsx

@@ -13,7 +13,7 @@ export type ChartConfig = Record<
   {
     label: string;
     color: string;
-    icon?: React.ComponentType;
+    icon?: React.ComponentType<Record<string, unknown>>;
   }
 >;
 
@@ -58,8 +58,8 @@ type RechartsLegendProps = Record<string, unknown>;
 // Lazy-loaded dependencies (recharts)
 // ============================================
 
-let _RechartsTooltip: any = null;
-let _RechartsLegend: any = null;
+let _RechartsTooltip: React.ComponentType<Record<string, unknown>> | null = null;
+let _RechartsLegend: React.ComponentType<Record<string, unknown>> | null = null;
 let _chartLoaded = false;
 let _chartFailed = false;
 
@@ -69,8 +69,8 @@ function loadChartDeps() {
   try {
     // eslint-disable-next-line @typescript-eslint/no-require-imports
     const rc = require('recharts');
-    _RechartsTooltip = rc.Tooltip;
-    _RechartsLegend = rc.Legend;
+    _RechartsTooltip = rc.Tooltip as React.ComponentType<Record<string, unknown>>;
+    _RechartsLegend = rc.Legend as React.ComponentType<Record<string, unknown>>;
   } catch {
     _chartFailed = true;
   }
@@ -243,7 +243,7 @@ type ChartTooltipProps = {
   hideIndicator?: boolean;
   labelFormatter?: ChartTooltipContentProps['labelFormatter'];
   valueFormatter?: ChartTooltipContentProps['valueFormatter'];
-  content?: any;
+  content?: React.ReactNode | ((tooltipProps: Record<string, unknown>) => React.ReactNode);
   [key: string]: unknown;
 };
 
@@ -260,9 +260,9 @@ export function ChartTooltip({
 
   const defaultContent = React.useCallback(
 
-    (tooltipProps: any) => (
+    (tooltipProps: Record<string, unknown>) => (
       <ChartTooltipContent
-        {...tooltipProps}
+        {...(tooltipProps as ChartTooltipContentProps)}
         indicator={indicator}
         hideLabel={hideLabel}
         hideIndicator={hideIndicator}
@@ -330,13 +330,15 @@ export function ChartLegendContent({ payload }: ChartLegendContentProps) {
 // ============================================
 
 type ChartLegendProps = RechartsLegendProps & {
-  content?: any;
+  content?: React.ReactNode | ((legendProps: Record<string, unknown>) => React.ReactNode);
 };
 
 export function ChartLegend({ content, ...props }: ChartLegendProps) {
   loadChartDeps();
 
-  const defaultContent = (legendProps: any) => <ChartLegendContent {...legendProps} />;
+  const defaultContent = (legendProps: Record<string, unknown>) => (
+    <ChartLegendContent {...(legendProps as ChartLegendContentProps)} />
+  );
 
   if (_chartFailed || !_RechartsLegend) {
     if (_chartFailed && process.env.NODE_ENV === 'development') {

package/src/components/Checkbox/Checkbox.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 { Checkbox } from '.';
 
 // Stateful wrapper for interactive demos
@@ -59,6 +59,10 @@ export default defineFragment({
       type: 'function',
       description: 'Called when checked state changes',
     },
+    onChange: {
+      type: 'function',
+      description: 'Alias for onCheckedChange: (checked: boolean) => void',
+    },
     indeterminate: {
       type: 'boolean',
       description: 'Indeterminate state (partial selection)',
@@ -83,6 +87,14 @@ export default defineFragment({
       values: ['sm', 'md', 'lg'],
       default: 'md',
     },
+    controlClassName: {
+      type: 'string',
+      description: 'Class name for the checkbox control element (stable styling target)',
+    },
+    contentClassName: {
+      type: 'string',
+      description: 'Class name for the label/description content wrapper',
+    },
   },
 
   relations: [
@@ -94,9 +106,11 @@ export default defineFragment({
     propsSummary: [
       'checked: boolean - controlled checked state',
       'onCheckedChange: (checked) => void - change handler',
+      'onChange: (checked) => void - alias for onCheckedChange',
       'indeterminate: boolean - partial selection state',
       'label: string - checkbox label',
       'description: string - helper text',
+      'controlClassName/contentClassName - explicit styling targets for control and content',
     ],
     scenarioTags: [
       'form.checkbox',
@@ -162,5 +176,17 @@ export default defineFragment({
         </div>
       ),
     },
+    {
+      name: 'Custom Styling Targets',
+      description: 'Use explicit class targets for control vs content styling',
+      render: () => (
+        <Checkbox
+          label="Styled checkbox"
+          description="Control and content wrappers can be targeted independently"
+          controlClassName="demo-checkbox-control"
+          contentClassName="demo-checkbox-content"
+        />
+      ),
+    },
   ],
 });

package/src/components/Checkbox/Checkbox.module.scss

@@ -1,11 +1,11 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 // Wrapper for checkbox + label
 .wrapper {
   display: inline-flex;
   align-items: center;
-  gap: var(--fui-space-2, $fui-space-2);
+  gap: var(--fui-space-1, $fui-space-1);
   cursor: pointer;
   font-family: var(--fui-font-sans, $fui-font-sans);
 

package/src/components/Checkbox/index.tsx

@@ -19,6 +19,8 @@ export interface CheckboxProps extends Omit<React.HTMLAttributes<HTMLLabelElemen
   defaultChecked?: boolean;
   /** Callback when checked state changes */
   onCheckedChange?: (checked: boolean) => void;
+  /** Alias for onCheckedChange */
+  onChange?: (checked: boolean) => void;
   /** Whether the checkbox is in an indeterminate state */
   indeterminate?: boolean;
   /** Whether the checkbox is disabled */
@@ -38,6 +40,10 @@ export interface CheckboxProps extends Omit<React.HTMLAttributes<HTMLLabelElemen
   value?: string;
   /** ID for the checkbox input */
   id?: string;
+  /** Class applied directly to the checkbox control element */
+  controlClassName?: string;
+  /** Class applied to the label/description content wrapper */
+  contentClassName?: string;
   /** Accessible label for icon-only mode */
   'aria-label'?: string;
   /** Accessible labelled-by relationship for icon-only mode */
@@ -99,6 +105,7 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
       checked,
       defaultChecked,
       onCheckedChange,
+      onChange,
       indeterminate = false,
       disabled = false,
       required = false,
@@ -108,6 +115,8 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
       name,
       value,
       className,
+      controlClassName,
+      contentClassName,
       id,
       'aria-label': ariaLabel,
       'aria-labelledby': ariaLabelledBy,
@@ -125,6 +134,7 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
       styles.checkbox,
       size === 'sm' && styles.sm,
       size === 'lg' && styles.lg,
+      controlClassName,
     ].filter(Boolean).join(' ');
 
     const labelClasses = [
@@ -134,15 +144,18 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
     ].filter(Boolean).join(' ');
 
     const wrapperClasses = [styles.wrapper, className].filter(Boolean).join(' ');
+    const handleCheckedChange = onChange ?? onCheckedChange;
 
     // If no label/description, render just the checkbox
     if (!label && !description) {
+      const iconOnlyHtmlProps = htmlProps as unknown as Record<string, unknown>;
       return (
         <BaseCheckbox.Root
+          {...iconOnlyHtmlProps}
           ref={ref}
           checked={checked}
           defaultChecked={defaultChecked}
-          onCheckedChange={onCheckedChange}
+          onCheckedChange={handleCheckedChange}
           indeterminate={indeterminate}
           disabled={disabled}
           required={required}
@@ -172,7 +185,7 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
           ref={ref}
           checked={checked}
           defaultChecked={defaultChecked}
-          onCheckedChange={onCheckedChange}
+          onCheckedChange={handleCheckedChange}
           indeterminate={indeterminate}
           disabled={disabled}
           required={required}
@@ -188,7 +201,7 @@ const CheckboxRoot = React.forwardRef<HTMLButtonElement, CheckboxProps>(
             {indeterminate ? <MinusIcon /> : <CheckIcon />}
           </BaseCheckbox.Indicator>
         </BaseCheckbox.Root>
-        <div className={styles.content}>
+        <div className={[styles.content, contentClassName].filter(Boolean).join(' ')}>
           <span id={labelId} className={labelClasses}>{label}</span>
           {description && (
             <span id={descriptionId} className={styles.description}>{description}</span>

package/src/components/Chip/Chip.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Chip } from '.';
 
 export default defineFragment({
@@ -32,10 +32,11 @@ export default defineFragment({
       'Use Chip.Group for multi-select sets with shared state',
       'Use onRemove only when users should be able to dismiss the chip',
       'Pair avatar chips with user-related selections (assignees, reviewers)',
+      'Provide an explicit value on Chip when using non-string/custom JSX children inside Chip.Group',
     ],
     accessibility: [
-      'Chips use role="option" with aria-selected for selection state',
-      'Chip.Group uses role="listbox" with aria-multiselectable',
+      'Chips are buttons and use aria-pressed for selection state',
+      'Chip.Group is a grouping wrapper; add role/aria-label when needed for assistive context',
       'Remove buttons include descriptive aria-label with chip text',
       'Disabled chips are properly excluded from interaction',
     ],
@@ -97,6 +98,8 @@ export default defineFragment({
       'icon/avatar: ReactNode - leading visual',
       'onRemove: () => void - makes chip removable',
       'value: string - identifier for Chip.Group',
+      'Chip.Group forwards DOM props (id, role, aria-*, data-*, handlers)',
+      'Chip.Group: non-string chip labels should set an explicit value',
     ],
     scenarioTags: [
       'actions.filter',
@@ -166,6 +169,20 @@ export default defineFragment({
         </Chip.Group>
       ),
     },
+    {
+      name: 'Chip Group with Custom Labels',
+      description: 'Use explicit values when chip labels are custom JSX',
+      render: () => (
+        <Chip.Group aria-label="Assignees">
+          <Chip value="jane">
+            <span>Jane Doe</span>
+          </Chip>
+          <Chip value="sam">
+            <span>Sam Lee</span>
+          </Chip>
+        </Chip.Group>
+      ),
+    },
     {
       name: 'Disabled',
       description: 'Chip in disabled state',

package/src/components/Chip/Chip.test.tsx

@@ -48,6 +48,34 @@ describe('Chip', () => {
     expect(screen.getByRole('button', { name: 'Outline' })).toHaveClass('outlined');
   });
 
+  it('Chip.Group supports non-string chip children without value collisions', async () => {
+    const user = userEvent.setup();
+    render(
+      <Chip.Group>
+        <Chip><span>Alpha</span></Chip>
+        <Chip><span>Beta</span></Chip>
+      </Chip.Group>
+    );
+
+    const alpha = screen.getByRole('button', { name: 'Alpha' });
+    const beta = screen.getByRole('button', { name: 'Beta' });
+
+    await user.click(alpha);
+    await user.click(beta);
+
+    expect(alpha).toHaveAttribute('aria-pressed', 'true');
+    expect(beta).toHaveAttribute('aria-pressed', 'true');
+  });
+
+  it('Chip.Group forwards DOM props to the group root', () => {
+    render(
+      <Chip.Group data-testid="chip-group" aria-label="Filters">
+        <Chip value="one">One</Chip>
+      </Chip.Group>
+    );
+    expect(screen.getByTestId('chip-group')).toHaveAttribute('aria-label', 'Filters');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<Chip>Accessible chip</Chip>);
     await expectNoA11yViolations(container);

package/src/components/Chip/index.tsx

@@ -28,7 +28,7 @@ export interface ChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonEle
   value?: string;
 }
 
-export interface ChipGroupProps {
+export interface ChipGroupProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'onChange'> {
   children: React.ReactNode;
   /** Controlled selected values */
   value?: string[];
@@ -36,7 +36,6 @@ export interface ChipGroupProps {
   defaultValue?: string[];
   /** Called when selection changes */
   onChange?: (value: string[]) => void;
-  className?: string;
 }
 
 const ChipBase = React.forwardRef<HTMLButtonElement, ChipProps>(
@@ -126,7 +125,7 @@ const ChipBase = React.forwardRef<HTMLButtonElement, ChipProps>(
 const EMPTY_CHIP_GROUP: string[] = [];
 
 function ChipGroupInner(
-  { children, value: controlledValue, defaultValue = EMPTY_CHIP_GROUP, onChange, className }: ChipGroupProps,
+  { children, value: controlledValue, defaultValue = EMPTY_CHIP_GROUP, onChange, className, ...htmlProps }: ChipGroupProps,
   ref: React.Ref<HTMLDivElement>
 ) {
   const [internalValue, setInternalValue] = React.useState<string[]>(defaultValue);
@@ -150,10 +149,19 @@ function ChipGroupInner(
   const classes = [styles.group, className].filter(Boolean).join(' ');
 
   return (
-    <div ref={ref} className={classes}>
-      {React.Children.map(children, (child) => {
+    <div ref={ref} {...htmlProps} className={classes}>
+      {React.Children.map(children, (child, index) => {
         if (!React.isValidElement<ChipProps>(child)) return child;
-        const chipValue = child.props.value ?? (typeof child.props.children === 'string' ? child.props.children : '');
+        const chipValue = (() => {
+          if (child.props.value != null) return child.props.value;
+          if (typeof child.props.children === 'string') return child.props.children;
+          if (child.key != null) return String(child.key);
+          if (process.env.NODE_ENV !== 'production') {
+            // Non-string labels need an explicit value to avoid unstable group selection keys.
+            console.warn('Chip.Group: Chips with non-string children should provide a `value` prop.');
+          }
+          return `__chip-${index}`;
+        })();
         return React.cloneElement(child, {
           selected: currentValue.includes(chipValue),
           onClick: (e: React.MouseEvent<HTMLButtonElement>) => {

package/src/components/CodeBlock/CodeBlock.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { CodeBlock } from '.';
 
 export default defineFragment({
@@ -42,6 +42,7 @@ export default defineFragment({
       'Use collapsible for code samples that users may want to skim',
       'Choose a theme that matches your documentation style',
       'Keep code examples concise and focused',
+      'Use CodeBlock.Tabbed for multi-language snippets; tabs support controlled value/onValueChange and explicit tab values',
     ],
     accessibility: [
       'Code is presented in a semantic pre/code structure',
@@ -193,6 +194,7 @@ export default defineFragment({
       'collapsible: boolean (default: false)',
       'defaultCollapsed: boolean (default: false)',
       'collapsedLines: number (default: 5)',
+      'CodeBlock.Tabbed: tabs[] plus optional defaultTab/value/onValueChange for multi-language snippets',
     ],
     scenarioTags: [
       'documentation.code',

package/src/components/CodeBlock/CodeBlock.module.scss

@@ -31,7 +31,7 @@
   display: flex;
   align-items: center;
   justify-content: space-between;
-  padding: 0 var(--fui-padding-container-sm);
+  padding: 0 var(--fui-space-3);
   background-color: var(--fui-code-header-bg, $fui-code-header-bg);
   border-bottom: 1px solid var(--fui-code-border, $fui-code-border);
   min-height: var(--fui-input-height, $fui-input-height);
@@ -90,7 +90,7 @@
   .codeContainer :global(.shiki),
   .loading pre {
     padding-right: calc(
-      var(--fui-padding-container-md, #{$fui-padding-container-md}) +
+      var(--fui-space-4, #{$fui-space-4}) +
         var(--fui-target-size-min, #{$fui-target-size-min}) + var(--fui-space-3, #{$fui-space-3})
     );
   }
@@ -108,8 +108,8 @@
 .loading {
   pre {
     margin: 0;
-    padding: var(--fui-padding-container-sm);
-    padding-right: var(--fui-padding-container-sm);
+    padding: var(--fui-space-3);
+    padding-right: var(--fui-space-3);
     background-color: transparent !important;
     border: none !important;
     border-radius: 0 !important;
@@ -135,8 +135,8 @@
   :global(.shiki) {
     background-color: transparent !important;
     margin: 0;
-    padding: var(--fui-padding-container-sm);
-    padding-right: var(--fui-padding-container-sm);
+    padding: var(--fui-space-3);
+    padding-right: var(--fui-space-3);
     border: none !important;
     border-radius: 0 !important;
     font-family: var(--fui-font-mono, $fui-font-mono);
@@ -252,7 +252,7 @@
 
   .codeContainer :global(.shiki),
   .loading pre {
-    padding: var(--fui-padding-inline-sm) var(--fui-padding-container-sm);
+    padding: var(--fui-space-2) var(--fui-space-3);
     font-size: var(--fui-font-size-sm, $fui-font-size-sm);
     line-height: 1.5;
   }
@@ -261,7 +261,7 @@
     .codeContainer :global(.shiki),
     .loading pre {
       padding-right: calc(
-        var(--fui-padding-container-sm, #{$fui-padding-container-sm}) +
+        var(--fui-space-3, #{$fui-space-3}) +
           var(--fui-target-size-min, #{$fui-target-size-min}) + var(--fui-space-3, #{$fui-space-3})
       );
     }
@@ -298,7 +298,7 @@
   justify-content: center;
   gap: var(--fui-space-1, $fui-space-1);
   width: 100%;
-  padding: 0 var(--fui-padding-inline-sm);
+  padding: 0 var(--fui-space-2);
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   font-family: var(--fui-font-sans, $fui-font-sans);

package/src/components/CodeBlock/CodeBlock.test.tsx

@@ -121,6 +121,27 @@ describe('CodeBlock', () => {
     expect(collapseBtn).toHaveAttribute('aria-expanded', 'true');
   });
 
+  it('supports controlled tabbed mode with explicit tab values', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    render(
+      <CodeBlock.Tabbed
+        value="js"
+        onValueChange={onValueChange}
+        tabs={[
+          { label: 'Example', value: 'ts', language: 'typescript', code: 'const tsValue = 1;' },
+          { label: 'Example', value: 'js', language: 'javascript', code: 'const jsValue = 1;' },
+        ]}
+      />
+    );
+
+    expect(screen.getByText('const jsValue = 1;')).toBeInTheDocument();
+    const tabs = screen.getAllByRole('tab', { name: 'Example' });
+    await user.click(tabs[0]);
+    expect(onValueChange).toHaveBeenCalled();
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<CodeBlock code="const x = 1;" />);
     await expectNoA11yViolations(container);