@fragments-sdk/ui 0.11.1 → 0.13.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.11.1",
+  "version": "0.13.0",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -230,7 +230,7 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@fragments-sdk/cli": "0.9.1"
+    "@fragments-sdk/cli": "0.10.1"
   },
   "files": [
     "src",

package/src/components/Accordion/Accordion.test.tsx

@@ -148,6 +148,22 @@ describe('Accordion', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'false');
   });
 
+  it('emits undefined when a single collapsible accordion fully closes', async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    renderAccordion({
+      type: 'single',
+      collapsible: true,
+      defaultValue: 'one',
+      onValueChange,
+    });
+
+    await user.click(screen.getByRole('button', { name: /item one/i }));
+
+    expect(onValueChange).toHaveBeenCalledWith(undefined);
+  });
+
   it('non-collapsible single type prevents full collapse', async () => {
     const user = userEvent.setup();
     renderAccordion({ type: 'single', collapsible: false, defaultValue: 'one' });
@@ -160,6 +176,23 @@ describe('Accordion', () => {
     expect(trigger).toHaveAttribute('aria-expanded', 'true');
   });
 
+  it('forwards html props to trigger and content', async () => {
+    const user = userEvent.setup();
+    render(
+      <Accordion>
+        <Accordion.Item value="one">
+          <Accordion.Trigger data-testid="trigger" data-track="accordion-trigger">Item One</Accordion.Trigger>
+          <Accordion.Content data-testid="content" aria-label="Accordion panel">Content One</Accordion.Content>
+        </Accordion.Item>
+      </Accordion>
+    );
+
+    await user.click(screen.getByTestId('trigger'));
+
+    expect(screen.getByTestId('trigger')).toHaveAttribute('data-track', 'accordion-trigger');
+    expect(screen.getByTestId('content')).toHaveAttribute('aria-label', 'Accordion panel');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = renderAccordion({ defaultValue: 'one' });
     await expectNoA11yViolations(container, {

package/src/components/Accordion/index.tsx

@@ -19,7 +19,7 @@ export interface AccordionProps extends Omit<React.HTMLAttributes<HTMLDivElement
   /** Default value for uncontrolled usage */
   defaultValue?: AccordionValue;
   /** Callback when value changes */
-  onValueChange?: (value: AccordionValue) => void;
+  onValueChange?: (value: AccordionValue | undefined) => void;
   /** Whether items can be fully collapsed (only for type="single") */
   collapsible?: boolean;
   /**
@@ -137,7 +137,7 @@ function AccordionRoot({
     }
 
     if (onValueChange) {
-      onValueChange(type === 'single' ? (newItems[0] ?? '') : newItems);
+      onValueChange(type === 'single' ? newItems[0] : newItems);
     }
   }, [type, currentOpenItems, collapsible, controlledOpenItems, onValueChange]);
 
@@ -186,11 +186,15 @@ function AccordionItem({
 function AccordionTrigger({
   children,
   className,
+  onClick,
+  ...htmlProps
 }: AccordionTriggerProps) {
   const { toggle, headingLevel } = useAccordionContext();
   const { value, isOpen, disabled, triggerId, contentId } = useAccordionItemContext();
 
-  const handleClick = () => {
+  const handleClick = (event: React.MouseEvent<HTMLButtonElement>) => {
+    onClick?.(event);
+    if (event.defaultPrevented) return;
     if (!disabled) {
       toggle(value);
     }
@@ -204,6 +208,7 @@ function AccordionTrigger({
   return (
     <HeadingTag className={styles.heading}>
       <BaseCollapsible.Trigger
+        {...htmlProps}
         id={triggerId}
         className={classes}
         onClick={handleClick}
@@ -237,6 +242,7 @@ function AccordionTrigger({
 function AccordionContent({
   children,
   className,
+  ...htmlProps
 }: AccordionContentProps) {
   const { isOpen, triggerId, contentId } = useAccordionItemContext();
 
@@ -244,6 +250,7 @@ function AccordionContent({
 
   return (
     <BaseCollapsible.Panel
+      {...htmlProps}
       id={contentId}
       className={classes}
       data-state={isOpen ? 'open' : 'closed'}

package/src/components/Alert/index.tsx

@@ -10,8 +10,15 @@ import styles from './Alert.module.scss';
 
 export type AlertSeverity = 'info' | 'success' | 'warning' | 'error';
 
+/**
+ * Alert for contextual feedback messages (info, success, warning, error).
+ * @see https://usefragments.com/components/alert
+ */
 export interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
+  /** Alert severity level. Controls color and default icon.
+   * @default "info"
+   * @see https://usefragments.com/components/alert#variants */
   severity?: AlertSeverity;
 }
 

package/src/components/Avatar/index.tsx

@@ -9,6 +9,10 @@ import styles from './Avatar.module.scss';
 
 export type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
 
+/**
+ * Avatar for user photos, initials, or placeholder icons.
+ * @see https://usefragments.com/components/avatar
+ */
 export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'color'> {
   /** Image source URL */
   src?: string;

package/src/components/Badge/Badge.fragment.tsx

@@ -50,7 +50,7 @@ export default defineFragment({
     variant: {
       type: 'enum',
       description: 'Visual style indicating severity or category',
-      values: ['default', 'success', 'warning', 'error', 'info'],
+      values: ['default', 'success', 'warning', 'error', 'info', 'outline'],
       default: 'default',
     },
     size: {
@@ -82,7 +82,7 @@ export default defineFragment({
   contract: {
     propsSummary: [
       'children: ReactNode - badge label (required)',
-      'variant: default|success|warning|error|info - visual style',
+      'variant: default|success|warning|error|info|outline - visual style',
       'size: sm|md - badge size',
       'dot: boolean - show status dot indicator',
       'onRemove: () => void - makes badge removable',
@@ -147,6 +147,14 @@ import { Stack } from '@/components/Stack';
         </Stack>
       ),
     },
+    {
+      name: 'Outline',
+      description: 'Minimal bordered badge for neutral emphasis',
+      code: `import { Badge } from '@/components/Badge';
+
+<Badge variant="outline">Outline</Badge>`,
+      render: () => <Badge variant="outline">Outline</Badge>,
+    },
     {
       name: 'Small Size',
       description: 'Compact badges for dense UIs',

package/src/components/Badge/index.tsx

@@ -4,12 +4,24 @@ import * as React from 'react';
 import { Button as BaseButton } from '@base-ui/react/button';
 import styles from './Badge.module.scss';
 
+/**
+ * Badge for status indicators, labels, and counts.
+ * @see https://usefragments.com/components/badge
+ */
 export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   children: React.ReactNode;
+  /** Visual style variant.
+   * @default "default"
+   * @see https://usefragments.com/components/badge#variants */
   variant?: 'default' | 'success' | 'warning' | 'error' | 'info' | 'outline';
+  /** Badge size.
+   * @default "md" */
   size?: 'sm' | 'md' | 'lg';
+  /** Show a status dot before the label */
   dot?: boolean;
+  /** Icon element rendered before the label */
   icon?: React.ReactNode;
+  /** Makes the badge removable. Called when dismiss button is clicked. */
   onRemove?: () => void;
 }
 

package/src/components/Button/Button.fragment.tsx

@@ -46,7 +46,7 @@ export default defineFragment({
     },
     variant: {
       type: 'enum',
-      values: ['primary', 'secondary', 'ghost', 'danger'],
+      values: ['primary', 'secondary', 'ghost', 'danger', 'outlined', 'outline'],
       default: 'primary',
       description: 'Visual style variant',
       constraints: ['Only one primary button per context'],
@@ -63,6 +63,11 @@ export default defineFragment({
       default: 'button',
       description: 'Render as a native button or anchor element',
     },
+    asChild: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Merge button styling onto child element (e.g. Next.js Link)',
+    },
     icon: {
       type: 'boolean',
       default: 'false',
@@ -95,7 +100,7 @@ export default defineFragment({
 
   contract: {
     propsSummary: [
-      'variant: primary|secondary|ghost|danger (default: primary)',
+      'variant: primary|secondary|ghost|danger|outlined|outline (default: primary)',
       'size: sm|md|lg (default: md)',
       'disabled: boolean - disables interaction',
       'type: button|submit|reset (default: button)',
@@ -140,6 +145,11 @@ export default defineFragment({
       description: 'Destructive action requiring attention',
       render: () => <Button variant="danger">Delete Item</Button>,
     },
+    {
+      name: 'Outline',
+      description: 'Bordered button with transparent background',
+      render: () => <Button variant="outline">View Details</Button>,
+    },
     {
       name: 'Sizes',
       description: 'Available size options',

package/src/components/Button/Button.test.tsx

@@ -46,6 +46,22 @@ describe('Button', () => {
     expect(ref).toHaveBeenCalled();
   });
 
+  it('resolves variant="outline" to "outlined"', () => {
+    render(<Button variant="outline">Outline</Button>);
+    expect(screen.getByRole('button')).toHaveClass('outlined');
+  });
+
+  it('renders as child element when asChild is true', () => {
+    render(
+      <Button asChild>
+        <a href="/test">Link Button</a>
+      </Button>
+    );
+    const link = screen.getByRole('link', { name: 'Link Button' });
+    expect(link).toHaveAttribute('href', '/test');
+    expect(link).toHaveClass('button');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<Button>Accessible</Button>);
     await expectNoA11yViolations(container);

package/src/components/Button/index.tsx

@@ -4,14 +4,27 @@ import * as React from 'react';
 import { Button as BaseButton } from '@base-ui/react/button';
 import styles from './Button.module.scss';
 
+/**
+ * Button props.
+ * @see https://usefragments.com/components/button
+ */
 type ButtonBaseProps = {
   children: React.ReactNode;
-  variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'outlined';
+  /** Visual style variant. `"outline"` is an alias for `"outlined"`.
+   * @default "primary"
+   * @see https://usefragments.com/components/button#variants */
+  variant?: 'primary' | 'secondary' | 'ghost' | 'danger' | 'outlined' | 'outline';
+  /** Button size.
+   * @default "md"
+   * @see https://usefragments.com/components/button#sizes */
   size?: 'sm' | 'md' | 'lg';
   /** Render as icon-only button (square aspect ratio) */
   icon?: boolean;
   /** Make button full width of container */
   fullWidth?: boolean;
+  /** Merge props onto child element instead of rendering a button. Useful for composition with Link components.
+   * @see https://usefragments.com/components/button#aschild */
+  asChild?: boolean;
 };
 
 // Button as native button element
@@ -36,14 +49,18 @@ const ButtonRoot = React.forwardRef<
 >(function Button(props, ref) {
   const {
     children,
-    variant = 'primary',
+    variant: variantProp = 'primary',
     size = 'md',
     icon = false,
     fullWidth = false,
+    asChild = false,
     className,
     ...rest
   } = props;
 
+  // Resolve alias: "outline" → "outlined"
+  const variant = variantProp === 'outline' ? 'outlined' : variantProp;
+
   const classNames = [
     styles.button,
     styles[size],
@@ -55,6 +72,14 @@ const ButtonRoot = React.forwardRef<
     .filter(Boolean)
     .join(' ');
 
+  // asChild: merge button styling onto child element (e.g. Next.js Link)
+  if (asChild && React.isValidElement(children)) {
+    return React.cloneElement(children as React.ReactElement<Record<string, unknown>>, {
+      className: [classNames, (children.props as Record<string, unknown>).className].filter(Boolean).join(' '),
+      ref,
+    });
+  }
+
   // Render as anchor
   if (props.as === 'a') {
     const { as: _as, ...anchorProps } = rest as ButtonAsAnchorProps & { as?: 'a' };

package/src/components/Card/Card.fragment.tsx

@@ -44,7 +44,7 @@ export default defineFragment({
     },
     variant: {
       type: 'enum',
-      values: ['default', 'outlined', 'elevated'],
+      values: ['default', 'outlined', 'outline', 'elevated'],
       default: 'default',
       description: 'Visual style of the card surface',
       constraints: ['Use "elevated" sparingly to maintain visual hierarchy'],
@@ -76,7 +76,7 @@ export default defineFragment({
 
   contract: {
     propsSummary: [
-      'variant: default|outlined|elevated (default: default)',
+      'variant: default|outlined|outline|elevated (default: default)',
       'padding: none|sm|md|lg (default: md)',
       'onClick: () => void - makes card interactive',
       'Sub-components: Card.Header, Card.Title, Card.Description, Card.Body, Card.Footer',
@@ -130,6 +130,18 @@ export default defineFragment({
         </Card>
       ),
     },
+    {
+      name: 'Outline',
+      description: 'Card with border, using the "outline" alias for "outlined"',
+      render: () => (
+        <Card variant="outline">
+          <Card.Header>
+            <Card.Title>Outline Card</Card.Title>
+          </Card.Header>
+          <Card.Body>Uses the Radix/Shadcn-style alias.</Card.Body>
+        </Card>
+      ),
+    },
     {
       name: 'Elevated',
       description: 'Card with prominent shadow for emphasis',

package/src/components/Card/Card.test.tsx

@@ -57,6 +57,11 @@ describe('Card', () => {
     expect(screen.getByRole('button')).toHaveClass('interactive');
   });
 
+  it('resolves variant="outline" to "outlined"', () => {
+    render(<Card variant="outline">Content</Card>);
+    expect(screen.getByRole('article')).toHaveClass('outlined');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(
       <Card>

package/src/components/Card/index.tsx

@@ -7,10 +7,20 @@ import styles from './Card.module.scss';
 // Types
 // ============================================
 
+/**
+ * Card container for grouping related content.
+ * @see https://usefragments.com/components/card
+ */
 export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick'> {
   children: React.ReactNode;
-  variant?: 'default' | 'outlined' | 'elevated';
+  /** Visual style variant. `"outline"` is an alias for `"outlined"`.
+   * @default "default"
+   * @see https://usefragments.com/components/card#variants */
+  variant?: 'default' | 'outlined' | 'outline' | 'elevated';
+  /** Inner padding.
+   * @default "md" */
   padding?: 'none' | 'sm' | 'md' | 'lg';
+  /** Makes the card interactive (clickable) */
   onClick?: () => void;
 }
 
@@ -71,7 +81,7 @@ const paddingMap = {
 
 function CardRoot({
   children,
-  variant = 'default',
+  variant: variantProp = 'default',
   padding = 'md',
   onClick,
   className,
@@ -80,6 +90,9 @@ function CardRoot({
   'aria-describedby': ariaDescribedBy,
   ...htmlProps
 }: CardProps) {
+  // Resolve alias: "outline" → "outlined"
+  const variant = variantProp === 'outline' ? 'outlined' : variantProp;
+
   const isInteractive = !!onClick;
 
   const classes = [

package/src/components/Checkbox/index.tsx

@@ -8,6 +8,10 @@ import styles from './Checkbox.module.scss';
 // Types
 // ============================================
 
+/**
+ * Checkbox for boolean or indeterminate selections in forms.
+ * @see https://usefragments.com/components/checkbox
+ */
 export interface CheckboxProps extends Omit<React.HTMLAttributes<HTMLLabelElement>, 'onChange' | 'defaultChecked'> {
   /** Whether the checkbox is checked */
   checked?: boolean;
@@ -21,7 +25,8 @@ export interface CheckboxProps extends Omit<React.HTMLAttributes<HTMLLabelElemen
   disabled?: boolean;
   /** Whether the checkbox is required */
   required?: boolean;
-  /** Size variant */
+  /** Size variant.
+   * @default "md" */
   size?: 'sm' | 'md' | 'lg';
   /** Label text */
   label?: string;

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

@@ -50,7 +50,7 @@ export default defineFragment({
     variant: {
       type: 'enum',
       description: 'Visual style variant',
-      values: ['filled', 'outlined', 'soft'],
+      values: ['filled', 'outlined', 'outline', 'soft'],
       default: 'filled',
     },
     size: {
@@ -91,7 +91,7 @@ export default defineFragment({
   contract: {
     propsSummary: [
       'children: ReactNode - chip label (required)',
-      'variant: filled|outlined|soft - visual style',
+      'variant: filled|outlined|outline|soft - visual style',
       'size: sm|md - chip size',
       'selected: boolean - selection state',
       'icon/avatar: ReactNode - leading visual',
@@ -113,6 +113,16 @@ export default defineFragment({
       description: 'Basic filled chip',
       render: () => <Chip>Default</Chip>,
     },
+    {
+      name: 'Outline',
+      description: 'Chip with border using the "outline" alias for "outlined"',
+      render: () => (
+        <div style={{ display: 'flex', gap: '8px' }}>
+          <Chip variant="outline">Outline</Chip>
+          <Chip variant="outline" selected>Outline Selected</Chip>
+        </div>
+      ),
+    },
     {
       name: 'Selected',
       description: 'Chip in selected state across variants',

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

@@ -43,6 +43,11 @@ describe('Chip', () => {
     expect(handleClick).toHaveBeenCalledTimes(1);
   });
 
+  it('resolves variant="outline" to "outlined"', () => {
+    render(<Chip variant="outline">Outline</Chip>);
+    expect(screen.getByRole('button', { name: 'Outline' })).toHaveClass('outlined');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<Chip>Accessible chip</Chip>);
     await expectNoA11yViolations(container);

package/src/components/Chip/index.tsx

@@ -3,11 +3,18 @@
 import * as React from 'react';
 import styles from './Chip.module.scss';
 
+/**
+ * Chip for selections, filters, and tags. Use with Chip.Group for multi-select.
+ * @see https://usefragments.com/components/chip
+ */
 export interface ChipProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
   children: React.ReactNode;
-  /** Visual style variant */
-  variant?: 'filled' | 'outlined' | 'soft';
-  /** Size of the chip */
+  /** Visual style variant. `"outline"` is an alias for `"outlined"`.
+   * @default "filled"
+   * @see https://usefragments.com/components/chip#variants */
+  variant?: 'filled' | 'outlined' | 'outline' | 'soft';
+  /** Chip size.
+   * @default "md" */
   size?: 'sm' | 'md' | 'lg';
   /** Whether the chip is selected */
   selected?: boolean;
@@ -36,7 +43,7 @@ const ChipBase = React.forwardRef<HTMLButtonElement, ChipProps>(
   function Chip(
     {
       children,
-      variant = 'filled',
+      variant: variantProp = 'filled',
       size = 'md',
       selected = false,
       disabled = false,
@@ -50,6 +57,9 @@ const ChipBase = React.forwardRef<HTMLButtonElement, ChipProps>(
     },
     ref
   ) {
+    // Resolve alias: "outline" → "outlined"
+    const variant = variantProp === 'outline' ? 'outlined' : variantProp;
+
     const classes = [
       styles.chip,
       styles[size],

package/src/components/CodeBlock/index.tsx

@@ -35,7 +35,9 @@ import "../../styles/globals.scss";
 export type CodeBlockLanguage =
   | "tsx"
   | "typescript"
+  | "ts"
   | "javascript"
+  | "js"
   | "jsx"
   | "bash"
   | "shell"
@@ -64,7 +66,15 @@ export type CodeBlockLanguage =
   | "sql"
   | "graphql"
   | "diff"
-  | "plaintext";
+  | "plaintext"
+  | "text";
+
+/** Resolves language aliases to their canonical Shiki names */
+const LANGUAGE_ALIASES: Partial<Record<CodeBlockLanguage, string>> = {
+  ts: "typescript",
+  js: "javascript",
+  text: "plaintext",
+};
 
 /** Available syntax highlighting themes */
 export type CodeBlockTheme =
@@ -591,7 +601,8 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
       }
 
       try {
-        const html = await _codeToHtml(visibleCode, { lang: language, theme });
+        const resolvedLang = LANGUAGE_ALIASES[language] || language;
+        const html = await _codeToHtml(visibleCode, { lang: resolvedLang, theme });
         return processShikiHtml(html, {
           showLineNumbers,
           startLineNumber,

package/src/components/Collapsible/Collapsible.test.tsx

@@ -96,6 +96,47 @@ describe('Collapsible', () => {
     expect(screen.queryByText('Collapsible content here')).not.toBeInTheDocument();
   });
 
+  it('composes child handlers when trigger uses asChild', async () => {
+    const user = userEvent.setup();
+    const childClick = vi.fn();
+    const childKeyDown = vi.fn();
+
+    render(
+      <Collapsible>
+        <Collapsible.Trigger asChild>
+          <button onClick={childClick} onKeyDown={childKeyDown}>Toggle</button>
+        </Collapsible.Trigger>
+        <Collapsible.Content>Collapsible content here</Collapsible.Content>
+      </Collapsible>
+    );
+
+    const trigger = screen.getByRole('button', { name: /toggle/i });
+    await user.click(trigger);
+    expect(childClick).toHaveBeenCalled();
+    expect(screen.getByText('Collapsible content here')).toBeInTheDocument();
+
+    await user.keyboard('{Enter}');
+    expect(childKeyDown).toHaveBeenCalled();
+  });
+
+  it('forwards html props to root, trigger, and content', async () => {
+    const user = userEvent.setup();
+    render(
+      <Collapsible data-testid="root" data-track="collapsible-root">
+        <Collapsible.Trigger data-testid="trigger" aria-label="Toggle section">Toggle</Collapsible.Trigger>
+        <Collapsible.Content data-testid="content" data-panel="details">
+          Collapsible content here
+        </Collapsible.Content>
+      </Collapsible>
+    );
+
+    await user.click(screen.getByTestId('trigger'));
+
+    expect(screen.getByTestId('root')).toHaveAttribute('data-track', 'collapsible-root');
+    expect(screen.getByTestId('trigger')).toHaveAttribute('aria-label', 'Toggle section');
+    expect(screen.getByTestId('content')).toHaveAttribute('data-panel', 'details');
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = renderCollapsible({ defaultOpen: true });
     await expectNoA11yViolations(container);