@fragments-sdk/ui 0.11.0 → 0.12.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.11.0",
+  "version": "0.12.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.0"
+    "@fragments-sdk/cli": "0.10.0"
   },
   "files": [
     "src",

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/AppShell/AppShell.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 // ============================================
 // AppShell Root - CSS Grid Layout
@@ -20,8 +20,8 @@
   // header  header  header
   // sidebar main    aside
   grid-template-areas:
-    'header header header'
-    'sidebar main aside';
+    "header header header"
+    "sidebar main aside";
   grid-template-columns:
     var(--appshell-sidebar-width, 240px)
     1fr
@@ -36,9 +36,9 @@
   // Mobile: single column layout
   @include below-md {
     grid-template-areas:
-      'header'
-      'main'
-      'aside';
+      "header"
+      "main"
+      "aside";
     grid-template-columns: 1fr;
     grid-template-rows:
       var(--appshell-header-height, 56px)
@@ -53,14 +53,14 @@
 // sidebar main   aside
 .sidebarLayout {
   grid-template-areas:
-    'sidebar header header'
-    'sidebar main aside';
+    "sidebar header header"
+    "sidebar main aside";
 
   @include below-md {
     grid-template-areas:
-      'header'
-      'main'
-      'aside';
+      "header"
+      "main"
+      "aside";
     grid-template-columns: 1fr;
   }
 }
@@ -157,7 +157,6 @@
   min-height: 0; // Allow shrinking in grid
   min-width: 0; // Prevent overflow
   background-color: var(--fui-bg-primary, $fui-bg-primary);
-  overflow-x: hidden;
 }
 
 // Main content in sidebar-floating layout — elevated card effect

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

@@ -9,19 +9,23 @@ import { useState, useCallback, useEffect, useMemo } from "react";
 let _codeToHtml:
   | ((code: string, options: { lang: string; theme: string }) => Promise<string>)
   | null = null;
-let _shikiLoaded = false;
+let _shikiLoadPromise: Promise<void> | null = null;
 let _shikiFailed = false;
 
-function loadShikiDeps() {
-  if (_shikiLoaded) return;
-  _shikiLoaded = true;
-  try {
-    // eslint-disable-next-line @typescript-eslint/no-require-imports
-    const shiki = require("shiki");
-    _codeToHtml = shiki.codeToHtml;
-  } catch {
-    _shikiFailed = true;
+async function loadShikiDeps() {
+  if (_codeToHtml) return;
+  if (_shikiFailed) return;
+  if (!_shikiLoadPromise) {
+    _shikiLoadPromise = (async () => {
+      try {
+        const shiki = await import("shiki");
+        _codeToHtml = shiki.codeToHtml;
+      } catch {
+        _shikiFailed = true;
+      }
+    })();
   }
+  await _shikiLoadPromise;
 }
 import { TabsRoot, TabsList, Tab, TabsPanel } from "../Tabs";
 import { Button } from "../Button";
@@ -31,7 +35,9 @@ import "../../styles/globals.scss";
 export type CodeBlockLanguage =
   | "tsx"
   | "typescript"
+  | "ts"
   | "javascript"
+  | "js"
   | "jsx"
   | "bash"
   | "shell"
@@ -60,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 =
@@ -572,7 +586,7 @@ const CodeBlockBase = React.forwardRef<HTMLDivElement, CodeBlockProps>(function
     setHighlight((prev) => ({ ...prev, loading: true }));
 
     const run = async () => {
-      loadShikiDeps();
+      await loadShikiDeps();
 
       const fallbackHtml = `<pre class="shiki"><code>${escapeHtml(visibleCode)}</code></pre>`;
 
@@ -587,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/Dialog/index.tsx

@@ -8,16 +8,28 @@ import styles from './Dialog.module.scss';
 // Types
 // ============================================
 
+/**
+ * Modal dialog overlay for confirmations, forms, and focused tasks.
+ * @see https://usefragments.com/components/dialog
+ */
 export interface DialogProps {
   children: React.ReactNode;
+  /** Controlled open state */
   open?: boolean;
+  /** Default open state */
   defaultOpen?: boolean;
+  /** Called when open state changes */
   onOpenChange?: (open: boolean) => void;
+  /** Whether the dialog blocks interaction with the rest of the page.
+   * @default true */
   modal?: boolean;
 }
 
 export interface DialogContentProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
+  /** Dialog width.
+   * @default "md"
+   * @see https://usefragments.com/components/dialog#sizes */
   size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
 }
 

package/src/components/Drawer/index.tsx

@@ -8,18 +8,34 @@ import styles from './Drawer.module.scss';
 // Types
 // ============================================
 
+/**
+ * Slide-in panel for navigation, forms, or supplementary content.
+ * @see https://usefragments.com/components/drawer
+ */
 export interface DrawerProps {
   children: React.ReactNode;
+  /** Controlled open state */
   open?: boolean;
+  /** Default open state */
   defaultOpen?: boolean;
+  /** Called when open state changes */
   onOpenChange?: (open: boolean) => void;
+  /** Whether the drawer blocks interaction with the rest of the page.
+   * @default true */
   modal?: boolean;
 }
 
 export interface DrawerContentProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
+  /** Which edge the drawer slides from.
+   * @default "right" */
   side?: 'left' | 'right' | 'top' | 'bottom';
+  /** Drawer width (for left/right) or height (for top/bottom).
+   * @default "md"
+   * @see https://usefragments.com/components/drawer#sizes */
   size?: 'sm' | 'md' | 'lg' | 'xl' | 'full';
+  /** Whether to show the backdrop overlay (default: true). Set to false for non-modal bottom panels. */
+  backdrop?: boolean;
 }
 
 export interface DrawerTriggerProps {
@@ -127,6 +143,7 @@ function DrawerContent({
   children,
   side = 'right',
   size = 'md',
+  backdrop = true,
   className,
   ...htmlProps
 }: DrawerContentProps) {
@@ -141,7 +158,7 @@ function DrawerContent({
 
   return (
     <BaseDialog.Portal>
-      <BaseDialog.Backdrop className={styles.backdrop} />
+      {backdrop && <BaseDialog.Backdrop className={styles.backdrop} />}
       <BaseDialog.Popup initialFocus {...htmlProps} data-side={side} className={popupClasses}>
         {children}
       </BaseDialog.Popup>