@fragments-sdk/ui 0.8.8 → 0.9.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.8.8",
+  "version": "0.9.0",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -113,7 +113,7 @@
     "@tanstack/react-table": "^8.21.3",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@fragments-sdk/cli": "0.7.14"
+    "@fragments-sdk/cli": "0.7.15"
   },
   "files": [
     "src",

package/src/components/Accordion/Accordion.module.scss

@@ -38,7 +38,7 @@
   align-items: center;
   justify-content: space-between;
   width: 100%;
-  padding: var(--fui-padding-item-xs, $fui-padding-item-xs) 0;
+  padding: var(--fui-padding-item-sm, $fui-padding-item-sm) 0;
   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-primary, $fui-text-primary);

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

@@ -71,7 +71,6 @@ describe('Accordion', () => {
   });
 
   it('links trigger aria-controls to content id', async () => {
-    const user = userEvent.setup();
     renderAccordion({ defaultValue: 'one' });
 
     const trigger = screen.getByRole('button', { name: /item one/i });
@@ -110,7 +109,7 @@ describe('Accordion', () => {
 
   it('supports controlled value prop', async () => {
     const onValueChange = vi.fn();
-    const { rerender } = render(
+    render(
       <Accordion value="one" onValueChange={onValueChange}>
         <Accordion.Item value="one">
           <Accordion.Trigger>Item One</Accordion.Trigger>

package/src/components/Avatar/Avatar.fragment.tsx

@@ -62,6 +62,10 @@ export default defineFragment({
       default: 'md',
       description: 'Size variant',
     },
+    customSize: {
+      type: 'string',
+      description: 'Custom avatar size (number in px or CSS size string like "2.25rem"), overrides size width/height',
+    },
     shape: {
       type: 'enum',
       values: ['circle', 'square'],
@@ -72,6 +76,10 @@ export default defineFragment({
       type: 'string',
       description: 'Custom background color for fallback avatar',
     },
+    imageStyle: {
+      type: 'string',
+      description: 'Inline style object applied to the underlying image element',
+    },
   },
 
   relations: [
@@ -87,6 +95,8 @@ export default defineFragment({
       'src: string - image URL',
       'name: string - used for initials fallback',
       'size: xs|sm|md|lg|xl (default: md)',
+      'customSize: number|string - custom size override',
+      'imageStyle: CSSProperties - inline image styling',
       'shape: circle|square (default: circle)',
     ],
     scenarioTags: [
@@ -150,6 +160,14 @@ import { Stack } from '@/components/Stack';
         </Stack>
       ),
     },
+    {
+      name: 'Custom Size',
+      description: 'Set an exact avatar size',
+      code: `import { Avatar } from '@/components/Avatar';
+
+<Avatar name="Conan McNicholl" customSize={36} />`,
+      render: () => <Avatar name="Conan McNicholl" customSize={36} />,
+    },
     {
       name: 'Square Shape',
       description: 'Square variant for app icons or brands',

package/src/components/Avatar/Avatar.test.tsx

@@ -33,6 +33,24 @@ describe('Avatar', () => {
     expect(screen.getByText('+2')).toBeInTheDocument();
   });
 
+  it('applies a custom avatar size when customSize is provided', () => {
+    render(<Avatar name="Jane Doe" customSize={36} data-testid="avatar" />);
+    const avatar = screen.getByTestId('avatar');
+    expect(avatar).toHaveStyle({ width: '36px', height: '36px' });
+  });
+
+  it('applies imageStyle to the avatar image element', () => {
+    render(
+      <Avatar
+        src="https://example.com/photo.jpg"
+        alt="Jane Doe"
+        imageStyle={{ objectPosition: 'center 24%', transform: 'scale(1.4)' }}
+      />
+    );
+    const img = screen.getByRole('img');
+    expect(img).toHaveStyle({ objectPosition: 'center 24%', transform: 'scale(1.4)' });
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = render(<Avatar name="Jane Doe" />);
     await expectNoA11yViolations(container);

package/src/components/Avatar/index.tsx

@@ -22,10 +22,14 @@ export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   name?: string;
   /** Size variant */
   size?: AvatarSize;
+  /** Custom avatar size (overrides size width/height) */
+  customSize?: number | string;
   /** Shape variant */
   shape?: 'circle' | 'square';
   /** Custom background color for fallback */
   color?: string;
+  /** Inline style for the underlying image element */
+  imageStyle?: React.CSSProperties;
 }
 
 export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -103,8 +107,10 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
       initials,
       name,
       size = 'md',
+      customSize,
       shape = 'circle',
       color,
+      imageStyle,
       className,
       style: styleProp,
       ...htmlProps
@@ -137,6 +143,15 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
     ].filter(Boolean).join(' ');
 
     const style: React.CSSProperties = { ...styleProp };
+    if (customSize !== undefined) {
+      const resolvedSize = typeof customSize === 'number' ? `${customSize}px` : customSize;
+      style.width = resolvedSize;
+      style.height = resolvedSize;
+      if (style.fontSize === undefined) {
+        style.fontSize = `calc(${resolvedSize} * 0.4)`;
+      }
+    }
+
     if (showFallback && fallbackColor) {
       style.backgroundColor = fallbackColor;
       const textColor = getContrastTextColor(fallbackColor);
@@ -162,6 +177,7 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
             alt={alt}
             className={styles.image}
             onError={() => setImageError(true)}
+            style={{ ...imageStyle }}
           />
         )}
         {showFallback && displayInitials && (

package/src/components/Badge/index.tsx

@@ -1,3 +1,5 @@
+'use client';
+
 import * as React from 'react';
 import { Button as BaseButton } from '@base-ui/react/button';
 import styles from './Badge.module.scss';

package/src/components/BentoGrid/BentoGrid.fragment.tsx

@@ -0,0 +1,147 @@
+import React from 'react';
+import { defineFragment } from '@fragments-sdk/cli/core';
+import { BentoGrid } from '.';
+
+export default defineFragment({
+  component: BentoGrid,
+
+  meta: {
+    name: 'BentoGrid',
+    description: 'Asymmetric grid layout with responsive spans and built-in surface styling for bento-style feature sections',
+    category: 'layout',
+    status: 'stable',
+    tags: ['bento', 'grid', 'layout', 'responsive', 'feature-grid', 'asymmetric'],
+  },
+
+  usage: {
+    when: [
+      'Asymmetric feature grids with hero + supporting items',
+      'Dashboard overviews where cards have different visual weight',
+      'Marketing pages with mixed-size content blocks',
+      'Any layout where items need per-breakpoint column/row spans',
+    ],
+    whenNot: [
+      'Uniform grids where all items are the same size (use Grid)',
+      'Form layouts with labeled fields (use Grid)',
+      'Simple stacked content (use Stack)',
+    ],
+    guidelines: [
+      'Use colSpan/rowSpan with responsive objects for layouts that adapt across breakpoints',
+      'The hero item typically uses colSpan={2} rowSpan={2} at lg and above',
+      'Items include built-in surface styling — no need to wrap children in Card',
+      'Grid auto-collapses: 3→2 columns below lg, all→1 column below sm',
+    ],
+    accessibility: [
+      'Grid is purely visual — it does not affect reading order or semantics',
+      'Ensure logical source order matches visual order for screen readers',
+      'Hover effects are disabled when prefers-reduced-motion is set',
+      'Border thickness increases in prefers-contrast: more mode',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'BentoGrid.Item children',
+    },
+    columns: {
+      type: 'enum',
+      values: ['2', '3', '4'],
+      default: '3',
+      description: 'Number of columns — auto-collapses responsively (3→2→1)',
+    },
+    gap: {
+      type: 'enum',
+      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+      default: 'md',
+      description: 'Gap between grid items, mapped to spacing tokens',
+    },
+  },
+
+  relations: [
+    {
+      component: 'Grid',
+      relationship: 'alternative',
+      note: 'Use Grid for uniform layouts; BentoGrid for asymmetric spans with built-in surfaces',
+    },
+    {
+      component: 'Card',
+      relationship: 'sibling',
+      note: 'BentoGrid.Item has built-in surface styling similar to Card',
+    },
+  ],
+
+  contract: {
+    propsSummary: [
+      'columns: 2|3|4 (default: 3) — auto-collapses responsively',
+      'gap: none|xs|sm|md|lg|xl (default: md)',
+      'BentoGrid.Item colSpan: 1|2|3 | { base, sm, md, lg, xl }',
+      'BentoGrid.Item rowSpan: 1|2|3 | { base, sm, md, lg, xl }',
+    ],
+    scenarioTags: [
+      'layout.bento',
+      'layout.asymmetric',
+      'layout.responsive',
+      'pattern.feature-grid',
+      'pattern.dashboard',
+      'pattern.marketing',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic 3-column uniform bento grid',
+      render: () => (
+        <BentoGrid columns={3} gap="md">
+          <BentoGrid.Item>Item 1</BentoGrid.Item>
+          <BentoGrid.Item>Item 2</BentoGrid.Item>
+          <BentoGrid.Item>Item 3</BentoGrid.Item>
+          <BentoGrid.Item>Item 4</BentoGrid.Item>
+          <BentoGrid.Item>Item 5</BentoGrid.Item>
+          <BentoGrid.Item>Item 6</BentoGrid.Item>
+        </BentoGrid>
+      ),
+    },
+    {
+      name: 'Hero Layout',
+      description: '2×2 hero item with 4 supporting items in a 3-column grid',
+      render: () => (
+        <BentoGrid columns={3} gap="md">
+          <BentoGrid.Item colSpan={{ base: 1, lg: 2 }} rowSpan={{ base: 1, lg: 2 }}>
+            Hero content
+          </BentoGrid.Item>
+          <BentoGrid.Item>Item 2</BentoGrid.Item>
+          <BentoGrid.Item>Item 3</BentoGrid.Item>
+          <BentoGrid.Item>Item 4</BentoGrid.Item>
+          <BentoGrid.Item>Item 5</BentoGrid.Item>
+        </BentoGrid>
+      ),
+    },
+    {
+      name: 'Two Column',
+      description: '2-column bento with a wide item',
+      render: () => (
+        <BentoGrid columns={2} gap="md">
+          <BentoGrid.Item>Item 1</BentoGrid.Item>
+          <BentoGrid.Item>Item 2</BentoGrid.Item>
+          <BentoGrid.Item colSpan={2}>Wide item</BentoGrid.Item>
+          <BentoGrid.Item>Item 4</BentoGrid.Item>
+          <BentoGrid.Item>Item 5</BentoGrid.Item>
+        </BentoGrid>
+      ),
+    },
+    {
+      name: 'Full-Width Banner',
+      description: '3-column grid with a full-width item spanning all columns',
+      render: () => (
+        <BentoGrid columns={3} gap="md">
+          <BentoGrid.Item>Item 1</BentoGrid.Item>
+          <BentoGrid.Item>Item 2</BentoGrid.Item>
+          <BentoGrid.Item>Item 3</BentoGrid.Item>
+          <BentoGrid.Item colSpan={3}>Full-width banner</BentoGrid.Item>
+        </BentoGrid>
+      ),
+    },
+  ],
+});

package/src/components/BentoGrid/BentoGrid.module.scss

@@ -0,0 +1,123 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// BentoGrid Container
+// ============================================
+
+.grid {
+  display: grid;
+  width: 100%;
+  grid-auto-flow: dense;
+}
+
+// ============================================
+// Column counts
+// ============================================
+
+.columns2 { grid-template-columns: repeat(2, 1fr); }
+.columns3 { grid-template-columns: repeat(3, 1fr); }
+.columns4 { grid-template-columns: repeat(4, 1fr); }
+
+// ============================================
+// Responsive collapse
+// ============================================
+
+@include below-lg {
+  .columns3,
+  .columns4 {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+@include below-sm {
+  .columns2,
+  .columns3,
+  .columns4 {
+    grid-template-columns: 1fr;
+  }
+}
+
+// ============================================
+// Gap
+// ============================================
+
+.gapNone { gap: 0; }
+.gapXs   { gap: var(--fui-space-1, $fui-space-1); }
+.gapSm   { gap: var(--fui-space-2, $fui-space-2); }
+.gapMd   { gap: var(--fui-space-4, $fui-space-4); }
+.gapLg   { gap: var(--fui-space-6, $fui-space-6); }
+.gapXl   { gap: var(--fui-space-8, $fui-space-8); }
+
+// ============================================
+// BentoGrid Item
+// ============================================
+
+.item {
+  @include surface-elevated;
+
+  min-width: 0;
+  padding: var(--fui-padding-container-md, $fui-padding-container-md);
+  transition:
+    box-shadow var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    border-color: var(--fui-border-strong, $fui-border-strong);
+    box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+    transform: translateY(-2px);
+  }
+
+  // ---- Responsive span cascade ----
+  --_col-span: var(--bento-col-span, 1);
+  --_row-span: var(--bento-row-span, 1);
+
+  grid-column: span var(--_col-span);
+  grid-row: span var(--_row-span);
+
+  @include breakpoint-sm {
+    --_col-span: var(--bento-col-span-sm, var(--bento-col-span, 1));
+    --_row-span: var(--bento-row-span-sm, var(--bento-row-span, 1));
+  }
+
+  @include breakpoint-md {
+    --_col-span: var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)));
+    --_row-span: var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)));
+  }
+
+  @include breakpoint-lg {
+    --_col-span: var(--bento-col-span-lg, var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1))));
+    --_row-span: var(--bento-row-span-lg, var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1))));
+  }
+
+  @include breakpoint-xl {
+    --_col-span: var(--bento-col-span-xl, var(--bento-col-span-lg, var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)))));
+    --_row-span: var(--bento-row-span-xl, var(--bento-row-span-lg, var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)))));
+  }
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .item {
+    transition: none;
+
+    &:hover {
+      transform: none;
+    }
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .item {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+}

package/src/components/BentoGrid/BentoGrid.test.tsx

@@ -0,0 +1,140 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
+import { BentoGrid } from './index';
+
+describe('BentoGrid', () => {
+  it('renders children', () => {
+    render(
+      <BentoGrid>
+        <BentoGrid.Item>Item 1</BentoGrid.Item>
+        <BentoGrid.Item>Item 2</BentoGrid.Item>
+      </BentoGrid>
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+    expect(screen.getByText('Item 2')).toBeInTheDocument();
+  });
+
+  it('applies default columns3 class', () => {
+    const { container } = render(<BentoGrid>Content</BentoGrid>);
+    expect(container.firstChild).toHaveClass('columns3');
+  });
+
+  it('applies columns2 class', () => {
+    const { container } = render(<BentoGrid columns={2}>Content</BentoGrid>);
+    expect(container.firstChild).toHaveClass('columns2');
+  });
+
+  it('applies columns4 class', () => {
+    const { container } = render(<BentoGrid columns={4}>Content</BentoGrid>);
+    expect(container.firstChild).toHaveClass('columns4');
+  });
+
+  it('applies default gapMd class', () => {
+    const { container } = render(<BentoGrid>Content</BentoGrid>);
+    expect(container.firstChild).toHaveClass('gapMd');
+  });
+
+  it('applies gap classes', () => {
+    const { container } = render(<BentoGrid gap="lg">Content</BentoGrid>);
+    expect(container.firstChild).toHaveClass('gapLg');
+  });
+
+  it('sets CSS custom properties for simple colSpan', () => {
+    const { container } = render(
+      <BentoGrid>
+        <BentoGrid.Item colSpan={2}>Wide</BentoGrid.Item>
+      </BentoGrid>
+    );
+    const item = container.querySelector('[class*="item"]') as HTMLElement;
+    expect(item.style.getPropertyValue('--bento-col-span')).toBe('2');
+  });
+
+  it('sets CSS custom properties for simple rowSpan', () => {
+    const { container } = render(
+      <BentoGrid>
+        <BentoGrid.Item rowSpan={2}>Tall</BentoGrid.Item>
+      </BentoGrid>
+    );
+    const item = container.querySelector('[class*="item"]') as HTMLElement;
+    expect(item.style.getPropertyValue('--bento-row-span')).toBe('2');
+  });
+
+  it('sets per-breakpoint CSS custom properties for responsive colSpan', () => {
+    const { container } = render(
+      <BentoGrid>
+        <BentoGrid.Item colSpan={{ base: 1, lg: 2 }}>Responsive</BentoGrid.Item>
+      </BentoGrid>
+    );
+    const item = container.querySelector('[class*="item"]') as HTMLElement;
+    // base=1 should not set --bento-col-span (only values > 1)
+    expect(item.style.getPropertyValue('--bento-col-span')).toBe('');
+    expect(item.style.getPropertyValue('--bento-col-span-lg')).toBe('2');
+  });
+
+  it('sets per-breakpoint CSS custom properties for responsive rowSpan', () => {
+    const { container } = render(
+      <BentoGrid>
+        <BentoGrid.Item rowSpan={{ base: 1, md: 2, xl: 3 }}>Responsive</BentoGrid.Item>
+      </BentoGrid>
+    );
+    const item = container.querySelector('[class*="item"]') as HTMLElement;
+    expect(item.style.getPropertyValue('--bento-row-span')).toBe('');
+    expect(item.style.getPropertyValue('--bento-row-span-md')).toBe('2');
+    expect(item.style.getPropertyValue('--bento-row-span-xl')).toBe('3');
+  });
+
+  it('does not set vars for default span value (1)', () => {
+    const { container } = render(
+      <BentoGrid>
+        <BentoGrid.Item colSpan={1} rowSpan={1}>Default</BentoGrid.Item>
+      </BentoGrid>
+    );
+    const item = container.querySelector('[class*="item"]') as HTMLElement;
+    expect(item.style.getPropertyValue('--bento-col-span')).toBe('');
+    expect(item.style.getPropertyValue('--bento-row-span')).toBe('');
+  });
+
+  it('forwards ref on root', () => {
+    const ref = vi.fn();
+    render(<BentoGrid ref={ref}>Content</BentoGrid>);
+    expect(ref).toHaveBeenCalled();
+  });
+
+  it('forwards ref on item', () => {
+    const ref = vi.fn();
+    render(
+      <BentoGrid>
+        <BentoGrid.Item ref={ref}>Content</BentoGrid.Item>
+      </BentoGrid>
+    );
+    expect(ref).toHaveBeenCalled();
+  });
+
+  it('accepts className on root', () => {
+    const { container } = render(<BentoGrid className="custom-root">Content</BentoGrid>);
+    expect(container.firstChild).toHaveClass('custom-root');
+  });
+
+  it('accepts className on item', () => {
+    const { container } = render(
+      <BentoGrid>
+        <BentoGrid.Item className="custom-item">Content</BentoGrid.Item>
+      </BentoGrid>
+    );
+    const item = container.querySelector('.custom-item');
+    expect(item).toBeInTheDocument();
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = render(
+      <BentoGrid columns={3}>
+        <BentoGrid.Item colSpan={2} rowSpan={2}>Hero</BentoGrid.Item>
+        <BentoGrid.Item>Item 2</BentoGrid.Item>
+        <BentoGrid.Item>Item 3</BentoGrid.Item>
+        <BentoGrid.Item>Item 4</BentoGrid.Item>
+        <BentoGrid.Item>Item 5</BentoGrid.Item>
+      </BentoGrid>
+    );
+    await expectNoA11yViolations(container);
+  });
+});