@fragments-sdk/ui 0.8.6 → 0.8.8

package/src/components/Menu/index.tsx

@@ -37,6 +37,8 @@ export interface MenuItemProps {
   className?: string;
   icon?: React.ReactNode;
   shortcut?: string;
+  /** When passed, renders a check indicator. `true` shows a checkmark, `false` reserves space. */
+  checked?: boolean;
 }
 
 export interface MenuCheckboxItemProps {
@@ -76,25 +78,39 @@ export interface MenuSeparatorProps {
   className?: string;
 }
 
+export interface MenuSubmenuProps {
+  children: React.ReactNode;
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+
+export interface MenuSubmenuTriggerProps {
+  children: React.ReactNode;
+  disabled?: boolean;
+  className?: string;
+  icon?: React.ReactNode;
+}
+
 // ============================================
 // Icons
 // ============================================
 
-function CheckIcon() {
+function CheckmarkIcon() {
   return (
     <svg
       xmlns="http://www.w3.org/2000/svg"
-      width="12"
-      height="12"
+      width="14"
+      height="14"
       viewBox="0 0 24 24"
       fill="none"
       stroke="currentColor"
-      strokeWidth="3"
+      strokeWidth={3}
       strokeLinecap="round"
       strokeLinejoin="round"
       aria-hidden="true"
     >
-      <polyline points="20 6 9 17 4 12" />
+      <path d="M5 13l4 4L19 7" />
     </svg>
   );
 }
@@ -187,7 +203,9 @@ function MenuItem({
   className,
   icon,
   shortcut,
+  checked,
 }: MenuItemProps) {
+  const hasChecked = checked !== undefined;
   const classes = [
     styles.item,
     danger && styles.itemDanger,
@@ -200,6 +218,11 @@ function MenuItem({
       onClick={onSelect}
       className={classes}
     >
+      {hasChecked && (
+        <span className={styles.checkIndicator}>
+          {checked ? <CheckmarkIcon /> : null}
+        </span>
+      )}
       {icon && <span className={styles.itemIcon}>{icon}</span>}
       <span className={styles.itemLabel}>{children}</span>
       {shortcut && <span className={styles.itemShortcut}>{shortcut}</span>}
@@ -209,26 +232,38 @@ function MenuItem({
 
 function MenuCheckboxItem({
   children,
-  checked,
+  checked: checkedProp,
   defaultChecked,
   onCheckedChange,
   disabled,
   className,
 }: MenuCheckboxItemProps) {
+  const isControlled = checkedProp !== undefined;
+  const [internalChecked, setInternalChecked] = React.useState(defaultChecked ?? false);
+  const visualChecked = isControlled ? checkedProp : internalChecked;
+
+  const handleCheckedChange = React.useCallback(
+    (value: boolean) => {
+      if (!isControlled) setInternalChecked(value);
+      onCheckedChange?.(value);
+    },
+    [isControlled, onCheckedChange],
+  );
+
   const classes = [styles.item, styles.checkboxItem, className]
     .filter(Boolean)
     .join(' ');
 
   return (
     <BaseMenu.CheckboxItem
-      checked={checked}
+      checked={checkedProp}
       defaultChecked={defaultChecked}
-      onCheckedChange={onCheckedChange}
+      onCheckedChange={handleCheckedChange}
       disabled={disabled}
       className={classes}
     >
-      <span className={styles.itemIndicator}>
-        <CheckIcon />
+      <span className={styles.checkIndicator}>
+        {visualChecked ? <CheckmarkIcon /> : null}
       </span>
       <span className={styles.itemLabel}>{children}</span>
     </BaseMenu.CheckboxItem>
@@ -264,7 +299,7 @@ function MenuRadioItem({
 
   return (
     <BaseMenu.RadioItem value={value} disabled={disabled} className={classes}>
-      <span className={styles.itemIndicator}>
+      <span className={styles.radioIndicator}>
         <DotIcon />
       </span>
       <span className={styles.itemLabel}>{children}</span>
@@ -287,6 +322,41 @@ function MenuSeparator({ className }: MenuSeparatorProps) {
   return <BaseMenu.Separator className={classes} />;
 }
 
+function MenuSubmenu({
+  children,
+  open,
+  defaultOpen,
+  onOpenChange,
+}: MenuSubmenuProps) {
+  return (
+    <BaseMenu.SubmenuRoot
+      open={open}
+      defaultOpen={defaultOpen}
+      onOpenChange={onOpenChange as any}
+    >
+      {children}
+    </BaseMenu.SubmenuRoot>
+  );
+}
+
+function MenuSubmenuTrigger({
+  children,
+  disabled,
+  className,
+  icon,
+}: MenuSubmenuTriggerProps) {
+  const classes = [styles.item, styles.submenuTrigger, className]
+    .filter(Boolean)
+    .join(' ');
+
+  return (
+    <BaseMenu.SubmenuTrigger disabled={disabled} className={classes}>
+      {icon && <span className={styles.itemIcon}>{icon}</span>}
+      <span className={styles.itemLabel}>{children}</span>
+    </BaseMenu.SubmenuTrigger>
+  );
+}
+
 // ============================================
 // Export compound component
 // ============================================
@@ -301,6 +371,8 @@ export const Menu = Object.assign(MenuRoot, {
   Group: MenuGroup,
   GroupLabel: MenuGroupLabel,
   Separator: MenuSeparator,
+  Submenu: MenuSubmenu,
+  SubmenuTrigger: MenuSubmenuTrigger,
 });
 
 // Re-export individual components
@@ -315,4 +387,6 @@ export {
   MenuGroup,
   MenuGroupLabel,
   MenuSeparator,
+  MenuSubmenu,
+  MenuSubmenuTrigger,
 };

package/src/components/Message/Message.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments/core';
+import { defineFragment } from '@fragments-sdk/cli/core';
 import { Message } from '.';
 
 export default defineFragment({

package/src/components/Message/Message.module.scss

@@ -36,7 +36,7 @@
 
   .content {
     background-color: var(--fui-color-accent, $fui-color-accent);
-    color: var(--fui-color-danger-text, $fui-color-danger-text);
+    color: var(--fui-text-inverse, $fui-text-inverse);
   }
 }
 
@@ -68,6 +68,7 @@
   .content {
     background-color: var(--fui-color-danger-bg, $fui-color-danger-bg);
     border: 1px solid var(--fui-color-danger, $fui-color-danger);
+    color: var(--fui-color-danger-text, $fui-color-danger-text);
   }
 }
 

package/src/components/NavigationMenu/NavigationMenu.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments/core';
+import { defineFragment } from '@fragments-sdk/cli/core';
 import { NavigationMenu } from '.';
 
 export default defineFragment({

package/src/components/Pagination/Pagination.fragment.tsx

@@ -0,0 +1,152 @@
+import React from 'react';
+import { defineFragment } from '@fragments-sdk/cli/core';
+import { Pagination } from '.';
+
+export default defineFragment({
+  component: Pagination,
+
+  meta: {
+    name: 'Pagination',
+    description: 'Page navigation for paginated data. Supports controlled/uncontrolled, page counts, and edge/sibling customization.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['pagination', 'paging', 'pages', 'navigation'],
+    since: '0.8.2',
+  },
+
+  usage: {
+    when: [
+      'Navigating through paginated data sets',
+      'Table or list pagination controls',
+      'Search results with multiple pages',
+      'Any content split across multiple pages',
+    ],
+    whenNot: [
+      'Small lists that fit on one page',
+      'Infinite scroll patterns (use IntersectionObserver)',
+      'Tab-based navigation (use Tabs)',
+      'Step-by-step wizards (use Stepper)',
+    ],
+    guidelines: [
+      'Place below the content being paginated',
+      'Use edgeCount to always show first/last pages',
+      'Use siblingCount to control how many pages surround the current page',
+      'Pair with Table component for data table pagination',
+    ],
+    accessibility: [
+      'Uses nav element with aria-label="Pagination"',
+      'aria-current="page" marks the active page',
+      'Previous/Next buttons have descriptive aria-labels',
+      'Disabled buttons at boundaries prevent invalid navigation',
+    ],
+  },
+
+  props: {
+    totalPages: {
+      type: 'number',
+      description: 'Total number of pages',
+      required: true,
+    },
+    page: {
+      type: 'number',
+      description: 'Controlled current page (1-indexed)',
+    },
+    defaultPage: {
+      type: 'number',
+      description: 'Default page (uncontrolled)',
+      default: '1',
+    },
+    onPageChange: {
+      type: 'function',
+      description: 'Called when page changes',
+    },
+    edgeCount: {
+      type: 'number',
+      description: 'Number of pages shown at edges',
+      default: '1',
+    },
+    siblingCount: {
+      type: 'number',
+      description: 'Number of pages shown around current',
+      default: '1',
+    },
+  },
+
+  relations: [
+    { component: 'Table', relationship: 'sibling', note: 'Commonly paired for table pagination' },
+    { component: 'Listbox', relationship: 'alternative', note: 'Use Listbox for small sets of options' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'totalPages: number - total page count (required)',
+      'page: number - controlled current page (1-indexed)',
+      'defaultPage: number - initial page (default: 1)',
+      'onPageChange: (page) => void - page change handler',
+      'edgeCount: number - pages at edges (default: 1)',
+      'siblingCount: number - pages around current (default: 1)',
+    ],
+    scenarioTags: [
+      'navigation.pagination',
+      'data.table',
+      'search.results',
+    ],
+    a11yRules: ['A11Y_NAV_LABEL', 'A11Y_CURRENT_PAGE'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Previous', 'Next', 'Items', 'Item', 'Ellipsis'],
+    requiredChildren: ['Items'],
+    commonPatterns: [
+      '<Pagination totalPages={totalPages} page={currentPage} onPageChange={setPage}><Pagination.Previous /><Pagination.Items /><Pagination.Next /></Pagination>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic pagination with 10 pages',
+      render: () => (
+        <Pagination totalPages={10} defaultPage={1}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+    {
+      name: 'With Edge Pages',
+      description: 'Shows 2 pages at each edge',
+      render: () => (
+        <Pagination totalPages={20} defaultPage={10} edgeCount={2} siblingCount={1}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+    {
+      name: 'Compact',
+      description: 'No siblings, minimal display',
+      render: () => (
+        <Pagination totalPages={20} defaultPage={10} siblingCount={0}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+    {
+      name: 'Controlled',
+      description: 'Controlled pagination at page 3',
+      render: () => (
+        <Pagination totalPages={5} page={3}>
+          <Pagination.Previous />
+          <Pagination.Items />
+          <Pagination.Next />
+        </Pagination>
+      ),
+    },
+  ],
+});

package/src/components/Pagination/Pagination.module.scss

@@ -0,0 +1,109 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// ============================================
+// Navigation wrapper
+// ============================================
+
+.pagination {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+// ============================================
+// List container
+// ============================================
+
+.list {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, 0.25rem);
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+// ============================================
+// Page item button
+// ============================================
+
+.item {
+  @include button-reset;
+  @include text-base;
+
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2rem;
+  height: 2rem;
+  padding: 0 var(--fui-space-2, 0.5rem);
+  border-radius: var(--fui-radius-md, 0.375rem);
+  font-size: var(--fui-font-size-sm, 0.875rem);
+  font-weight: var(--fui-font-weight-medium, 500);
+  color: var(--fui-text-primary);
+  cursor: pointer;
+  transition: background-color 0.1s ease, color 0.1s ease;
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-bg-hover);
+  }
+
+  &:focus-visible {
+    @include focus-ring;
+  }
+}
+
+// Active page
+.itemActive {
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-text-inverse, $fui-text-inverse);
+
+  &:hover:not(:disabled) {
+    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
+  }
+}
+
+// Disabled state (prev/next at boundaries)
+.itemDisabled {
+  opacity: 0.5;
+  cursor: not-allowed;
+  pointer-events: none;
+}
+
+// ============================================
+// Nav buttons (Previous/Next)
+// ============================================
+
+.navButton {
+  svg {
+    width: 1rem;
+    height: 1rem;
+  }
+}
+
+// ============================================
+// Ellipsis
+// ============================================
+
+.ellipsis {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  min-width: 2rem;
+  height: 2rem;
+  font-size: var(--fui-font-size-sm, 0.875rem);
+  color: var(--fui-text-secondary);
+  user-select: none;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .itemActive {
+    outline: 2px solid var(--fui-color-accent);
+    outline-offset: -2px;
+  }
+}

package/src/components/Pagination/Pagination.test.tsx

@@ -0,0 +1,171 @@
+import { describe, it, expect, vi } from 'vitest';
+import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { Pagination } from './index';
+
+function renderPagination(props: Partial<React.ComponentProps<typeof Pagination>> = {}) {
+  return render(
+    <Pagination totalPages={10} defaultPage={1} {...props}>
+      <Pagination.Previous />
+      <Pagination.Items />
+      <Pagination.Next />
+    </Pagination>
+  );
+}
+
+describe('Pagination', () => {
+  it('renders correct page range', () => {
+    renderPagination({ totalPages: 5 });
+
+    expect(screen.getByLabelText('Go to page 1')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 2')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 3')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 4')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 5')).toBeInTheDocument();
+  });
+
+  it('current page is highlighted', () => {
+    renderPagination({ defaultPage: 3, totalPages: 5 });
+
+    const page3 = screen.getByLabelText('Go to page 3');
+    expect(page3).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('click page changes selection', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    renderPagination({ totalPages: 5, onPageChange });
+
+    await user.click(screen.getByLabelText('Go to page 3'));
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
+
+  it('Previous/Next buttons work', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    renderPagination({ totalPages: 5, defaultPage: 3, onPageChange });
+
+    await user.click(screen.getByLabelText('Go to previous page'));
+    expect(onPageChange).toHaveBeenCalledWith(2);
+
+    await user.click(screen.getByLabelText('Go to next page'));
+    // After clicking prev (now on 2), clicking next goes to 3
+    expect(onPageChange).toHaveBeenCalledWith(3);
+  });
+
+  it('Previous disabled on page 1', () => {
+    renderPagination({ defaultPage: 1, totalPages: 5 });
+
+    expect(screen.getByLabelText('Go to previous page')).toBeDisabled();
+  });
+
+  it('Next disabled on last page', () => {
+    renderPagination({ defaultPage: 5, totalPages: 5 });
+
+    expect(screen.getByLabelText('Go to next page')).toBeDisabled();
+  });
+
+  it('ellipsis renders for large ranges', () => {
+    renderPagination({ totalPages: 20, defaultPage: 10 });
+
+    const ellipses = document.querySelectorAll('[aria-hidden="true"]');
+    // Should have at least one ellipsis (excluding SVG icons)
+    const textEllipses = Array.from(ellipses).filter(
+      (el) => el.tagName !== 'svg' && el.textContent === '\u2026'
+    );
+    expect(textEllipses.length).toBeGreaterThan(0);
+  });
+
+  it('edge count customization', () => {
+    renderPagination({ totalPages: 20, defaultPage: 10, edgeCount: 2 });
+
+    // With edgeCount=2, pages 1,2 and 19,20 should show
+    expect(screen.getByLabelText('Go to page 1')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 2')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 19')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 20')).toBeInTheDocument();
+  });
+
+  it('sibling count customization', () => {
+    renderPagination({ totalPages: 20, defaultPage: 10, siblingCount: 2 });
+
+    // With siblingCount=2, pages 8,9,10,11,12 should show
+    expect(screen.getByLabelText('Go to page 8')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 9')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 10')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 11')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to page 12')).toBeInTheDocument();
+  });
+
+  it('controlled mode (page prop)', async () => {
+    const user = userEvent.setup();
+    const onPageChange = vi.fn();
+    const { rerender } = render(
+      <Pagination totalPages={5} page={3} onPageChange={onPageChange}>
+        <Pagination.Previous />
+        <Pagination.Items />
+        <Pagination.Next />
+      </Pagination>
+    );
+
+    expect(screen.getByLabelText('Go to page 3')).toHaveAttribute('aria-current', 'page');
+
+    await user.click(screen.getByLabelText('Go to page 5'));
+    expect(onPageChange).toHaveBeenCalledWith(5);
+
+    // Re-render with updated page prop
+    rerender(
+      <Pagination totalPages={5} page={5} onPageChange={onPageChange}>
+        <Pagination.Previous />
+        <Pagination.Items />
+        <Pagination.Next />
+      </Pagination>
+    );
+
+    expect(screen.getByLabelText('Go to page 5')).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('keyboard navigation (Tab between buttons)', async () => {
+    const user = userEvent.setup();
+    renderPagination({ totalPages: 3 });
+
+    const prevButton = screen.getByLabelText('Go to previous page');
+    prevButton.focus();
+
+    await user.tab();
+    // Focus should move to a page button
+    expect(document.activeElement?.getAttribute('aria-label')).toMatch(/Go to page/);
+  });
+
+  it('totalPages=0 renders empty nav', () => {
+    const { container } = renderPagination({ totalPages: 0 });
+
+    expect(container.querySelector('nav')).toBeInTheDocument();
+    expect(container.querySelector('ul')).not.toBeInTheDocument();
+  });
+
+  it('totalPages=1 renders single page, no prev/next disabled correctly', () => {
+    renderPagination({ totalPages: 1 });
+
+    expect(screen.getByLabelText('Go to page 1')).toBeInTheDocument();
+    expect(screen.getByLabelText('Go to previous page')).toBeDisabled();
+    expect(screen.getByLabelText('Go to next page')).toBeDisabled();
+  });
+
+  it('out-of-range controlled page clamps to valid range', () => {
+    render(
+      <Pagination totalPages={5} page={99}>
+        <Pagination.Previous />
+        <Pagination.Items />
+        <Pagination.Next />
+      </Pagination>
+    );
+
+    expect(screen.getByLabelText('Go to page 5')).toHaveAttribute('aria-current', 'page');
+  });
+
+  it('has no accessibility violations', async () => {
+    const { container } = renderPagination({ totalPages: 10, defaultPage: 5 });
+
+    await expectNoA11yViolations(container);
+  });
+});