@fragments-sdk/ui 0.13.0 → 0.15.1

package/src/components/VisuallyHidden/VisuallyHidden.fragment.tsx

@@ -1,134 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
-import { VisuallyHidden } from '.';
-
-export default defineFragment({
-  component: VisuallyHidden,
-
-  meta: {
-    name: 'VisuallyHidden',
-    description: 'Hides content visually while keeping it accessible to screen readers. Essential for accessible icon-only buttons and supplementary text.',
-    category: 'navigation',
-    status: 'stable',
-    tags: ['accessibility', 'a11y', 'screen-reader', 'hidden', 'sr-only'],
-    since: '0.1.0',
-  },
-
-  usage: {
-    when: [
-      'Providing accessible labels for icon-only buttons',
-      'Adding context that screen readers need but sighted users don\'t',
-      'Hiding decorative content while providing text alternatives',
-      'Skip links for keyboard navigation',
-    ],
-    whenNot: [
-      'Hiding content from everyone (use display: none or conditional render)',
-      'Content that should be visible on focus (use focus-visible styles)',
-      'Temporarily hidden content (use proper ARIA attributes)',
-      'Lazy-loaded content (use suspense or loading states)',
-    ],
-    guidelines: [
-      'Always use with icon-only interactive elements',
-      'Keep hidden text concise but descriptive',
-      'Test with screen readers to verify announcements',
-      'Don\'t overuse; visible text is often better',
-    ],
-    accessibility: [
-      'Content is announced by screen readers',
-      'Content is focusable if interactive elements are inside',
-      'Essential for WCAG 2.1 compliance with icon-only controls',
-      'Must convey equivalent information to visual content',
-    ],
-  },
-
-  props: {
-    children: {
-      type: 'node',
-      description: 'Content to hide visually',
-      required: true,
-    },
-    as: {
-      type: 'enum',
-      description: 'HTML element to render',
-      values: ['span', 'div'],
-      default: 'span',
-    },
-  },
-
-  relations: [
-    { component: 'Button', relationship: 'child', note: 'Use inside icon-only buttons for accessible labels' },
-    { component: 'Icon', relationship: 'sibling', note: 'Pair with icons to provide text alternatives' },
-  ],
-
-  contract: {
-    propsSummary: [
-      'children: ReactNode - hidden text (required)',
-      'as: span|div - HTML element',
-    ],
-    scenarioTags: [
-      'accessibility.label',
-      'utility.hidden',
-      'screen-reader.text',
-    ],
-    a11yRules: ['A11Y_SR_ONLY', 'A11Y_ICON_LABEL'],
-  },
-
-  variants: [
-    {
-      name: 'Icon Button Label',
-      description: 'Accessible label for icon-only button',
-      render: () => (
-        <button style={{
-          display: 'inline-flex',
-          alignItems: 'center',
-          justifyContent: 'center',
-          width: '40px',
-          height: '40px',
-          border: '1px solid var(--fui-border-default)',
-          borderRadius: '8px',
-          background: 'var(--fui-color-surface-primary)',
-          cursor: 'pointer'
-        }}>
-          <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2">
-            <path d="M21 21l-6-6m2-5a7 7 0 11-14 0 7 7 0 0114 0z" />
-          </svg>
-          <VisuallyHidden>Search</VisuallyHidden>
-        </button>
-      ),
-    },
-    {
-      name: 'Supplementary Text',
-      description: 'Additional context for screen readers',
-      render: () => (
-        <a href="#" style={{ color: 'var(--fui-color-accent)' }}>
-          Read more
-          <VisuallyHidden> about our accessibility features</VisuallyHidden>
-        </a>
-      ),
-    },
-    {
-      name: 'Skip Link',
-      description: 'Navigation aid that becomes visible on focus',
-      render: () => (
-        <div>
-          <VisuallyHidden as="div">
-            <a
-              href="#main-content"
-              style={{
-                position: 'absolute',
-                padding: '8px 16px',
-                background: 'var(--fui-color-accent)',
-                color: 'white'
-              }}
-            >
-              Skip to main content
-            </a>
-          </VisuallyHidden>
-          <p style={{ color: 'var(--fui-color-text-tertiary)', fontSize: '14px' }}>
-            (Screen reader only: "Skip to main content" link)
-          </p>
-        </div>
-      ),
-    },
-  ],
-});

package/src/components/VisuallyHidden/VisuallyHidden.test.tsx

@@ -1,31 +0,0 @@
-import { describe, it, expect, vi } from 'vitest';
-import { render, screen, expectNoA11yViolations } from '../../test/utils';
-import { VisuallyHidden } from './index';
-
-describe('VisuallyHidden', () => {
-  it('renders content that is accessible to screen readers', () => {
-    render(<VisuallyHidden>Hidden label</VisuallyHidden>);
-    expect(screen.getByText('Hidden label')).toBeInTheDocument();
-  });
-
-  it('applies visually hidden class', () => {
-    render(<VisuallyHidden>Hidden</VisuallyHidden>);
-    expect(screen.getByText('Hidden')).toHaveClass('visuallyHidden');
-  });
-
-  it('renders as a different element via "as" prop', () => {
-    render(<VisuallyHidden as="div">Hidden</VisuallyHidden>);
-    expect(screen.getByText('Hidden').tagName).toBe('DIV');
-  });
-
-  it('forwards ref', () => {
-    const ref = vi.fn();
-    render(<VisuallyHidden ref={ref}>Hidden</VisuallyHidden>);
-    expect(ref).toHaveBeenCalled();
-  });
-
-  it('has no accessibility violations', async () => {
-    const { container } = render(<VisuallyHidden>Accessible hidden text</VisuallyHidden>);
-    await expectNoA11yViolations(container);
-  });
-});

package/src/components/compound-pattern.test.ts

@@ -1,40 +0,0 @@
-import { readdirSync, readFileSync, statSync } from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { describe, expect, it } from 'vitest';
-
-const COMPONENTS_DIR = path.dirname(fileURLToPath(import.meta.url));
-
-// Accept Object.assign(...) and typed static assignment patterns (e.g. Grid.Item = ...).
-const COMPOUND_EXPORT_PATTERN = /Object\.assign\s*\(|\(\s*[A-Za-z0-9_]+\s+as\s+[A-Za-z0-9_]+\s*\)\.[A-Z][A-Za-z0-9_]*\s*=/;
-
-describe('component export pattern', () => {
-  it('keeps component exports compound across the UI library', () => {
-    const componentDirs = readdirSync(COMPONENTS_DIR).filter((entry) => {
-      const fullPath = path.join(COMPONENTS_DIR, entry);
-      return statSync(fullPath).isDirectory();
-    });
-
-    const offenders: string[] = [];
-
-    for (const componentDir of componentDirs) {
-      const indexFilePath = path.join(COMPONENTS_DIR, componentDir, 'index.tsx');
-
-      let source: string | null = null;
-      try {
-        source = readFileSync(indexFilePath, 'utf8');
-      } catch {
-        // Skip directories without an index.tsx entrypoint.
-      }
-
-      if (source && !COMPOUND_EXPORT_PATTERN.test(source)) {
-        offenders.push(componentDir);
-      }
-    }
-
-    expect(
-      offenders,
-      `Expected every component to use a compound export pattern. Missing in: ${offenders.join(', ')}`
-    ).toEqual([]);
-  });
-});

package/src/test/setup.ts

@@ -1,74 +0,0 @@
-import '@testing-library/jest-dom/vitest';
-import { expect } from 'vitest';
-import * as matchers from 'vitest-axe/matchers';
-
-expect.extend(matchers);
-
-// Polyfill ResizeObserver for Base UI components in jsdom
-global.ResizeObserver = class ResizeObserver {
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-};
-
-// Polyfill IntersectionObserver for components that use it
-global.IntersectionObserver = class IntersectionObserver {
-  readonly root: Element | null = null;
-  readonly rootMargin: string = '';
-  readonly thresholds: ReadonlyArray<number> = [];
-
-  constructor() {
-    this.root = null;
-    this.rootMargin = '';
-    this.thresholds = [];
-  }
-
-  observe() {}
-  unobserve() {}
-  disconnect() {}
-  takeRecords(): IntersectionObserverEntry[] {
-    return [];
-  }
-};
-
-// Polyfill scrollIntoView for jsdom environments where it is undefined.
-if (!Element.prototype.scrollIntoView) {
-  Element.prototype.scrollIntoView = function scrollIntoView() {};
-}
-
-// axe-core may query canvas APIs for contrast checks; provide a minimal no-op context.
-Object.defineProperty(HTMLCanvasElement.prototype, 'getContext', {
-  configurable: true,
-  value: () => ({
-    fillRect() {},
-    clearRect() {},
-    getImageData() {
-      return { data: new Uint8ClampedArray(4) };
-    },
-    putImageData() {},
-    createImageData() {
-      return [];
-    },
-    setTransform() {},
-    drawImage() {},
-    save() {},
-    fillText() {},
-    restore() {},
-    beginPath() {},
-    moveTo() {},
-    lineTo() {},
-    closePath() {},
-    stroke() {},
-    translate() {},
-    scale() {},
-    rotate() {},
-    arc() {},
-    fill() {},
-    measureText() {
-      return { width: 0 };
-    },
-    transform() {},
-    rect() {},
-    clip() {},
-  }),
-});

package/src/test/utils.tsx

@@ -1,71 +0,0 @@
-export { render, screen, within, act, waitFor } from '@testing-library/react';
-export { default as userEvent } from '@testing-library/user-event';
-import { expect } from 'vitest';
-import { axe } from 'vitest-axe';
-
-const DEFAULT_DISABLED_RULES = ['page-has-heading-one', 'region'] as const;
-
-type AxeRules = NonNullable<Parameters<typeof axe>[1]>['rules'];
-
-export interface A11yAssertOptions {
-  /**
-   * Explicit root for axe scan. Defaults to document body to include portals.
-   */
-  root?: Element;
-  /**
-   * When true (default), audit document body instead of the render container.
-   */
-  includeDocumentBody?: boolean;
-  /**
-   * Rules to disable in addition to defaults.
-   */
-  disabledRules?: string[];
-  /**
-   * Optional axe rule overrides.
-   */
-  rules?: AxeRules;
-}
-
-function buildRulesConfig(options: A11yAssertOptions): AxeRules {
-  const disabledRuleIds = [
-    ...DEFAULT_DISABLED_RULES,
-    ...(options.disabledRules ?? []),
-  ];
-
-  const disabledRules = disabledRuleIds.reduce<AxeRules>((rules, id) => {
-    rules[id] = { enabled: false };
-    return rules;
-  }, {});
-
-  return {
-    ...disabledRules,
-    ...(options.rules ?? {}),
-  };
-}
-
-export async function runA11yAudit(
-  container: Element,
-  options: A11yAssertOptions = {},
-) {
-  const includeDocumentBody = options.includeDocumentBody ?? true;
-  const auditRoot = options.root
-    ?? (includeDocumentBody ? container.ownerDocument.body : container);
-
-  return axe(auditRoot, {
-    rules: buildRulesConfig(options),
-  });
-}
-
-/**
- * Asserts that rendered UI has no axe-core accessibility violations.
- *
- * By default this audits `document.body` so portaled overlays (Dialog, Menu,
- * Select, Tooltip, etc.) are included in the scan.
- */
-export async function expectNoA11yViolations(
-  container: Element,
-  options: A11yAssertOptions = {},
-) {
-  const results = await runA11yAudit(container, options);
-  expect(results).toHaveNoViolations();
-}

package/src/tokens/_index.scss

@@ -1,41 +0,0 @@
-// ============================================
-// @fragments-sdk/ui Design Tokens Index
-// ============================================
-//
-// This module exports the complete token system.
-// Import with: @use '@fragments-sdk/ui/tokens';
-//
-// SEED-BASED CONFIGURATION:
-// Set seed variables before importing to customize your theme.
-// See _seeds.scss for available options.
-//
-// Example:
-//   $fui-brand: #0066ff;
-//   $fui-neutral: "steel";
-//   @use '@fragments-sdk/ui/tokens';
-//
-// ============================================
-
-// Forward seed configuration (for users to override)
-@forward 'seeds';
-
-// Forward palette definitions (for advanced customization)
-@forward 'palettes';
-
-// Forward density scales
-@forward 'density';
-
-// Forward radius styles
-@forward 'radius';
-
-// Forward derivation functions (for advanced users)
-@forward 'derive';
-
-// Forward computed values (internal use)
-@forward 'computed';
-
-// Forward main variables (includes all token definitions)
-@forward 'variables';
-
-// Forward mixins
-@forward 'mixins';

package/src/utils/a11y.test.tsx

@@ -1,79 +0,0 @@
-import { describe, it, expect } from 'vitest';
-import { render, screen, expectNoA11yViolations } from '../test/utils';
-import { handleArrowNavigation, VisuallyHidden } from './a11y';
-
-describe('handleArrowNavigation', () => {
-  const items = ['a', 'b', 'c'];
-
-  function makeEvent(key: string): React.KeyboardEvent {
-    return { key, preventDefault: () => {} } as unknown as React.KeyboardEvent;
-  }
-
-  it('moves down with ArrowDown in vertical orientation', () => {
-    expect(handleArrowNavigation(makeEvent('ArrowDown'), items, 0, { orientation: 'vertical' })).toBe(1);
-  });
-
-  it('moves up with ArrowUp in vertical orientation', () => {
-    expect(handleArrowNavigation(makeEvent('ArrowUp'), items, 1, { orientation: 'vertical' })).toBe(0);
-  });
-
-  it('ignores ArrowDown in horizontal orientation', () => {
-    expect(handleArrowNavigation(makeEvent('ArrowDown'), items, 0, { orientation: 'horizontal' })).toBeUndefined();
-  });
-
-  it('moves right with ArrowRight in horizontal orientation', () => {
-    expect(handleArrowNavigation(makeEvent('ArrowRight'), items, 0, { orientation: 'horizontal' })).toBe(1);
-  });
-
-  it('loops from last to first when loop is enabled', () => {
-    expect(handleArrowNavigation(makeEvent('ArrowDown'), items, 2, { orientation: 'vertical', loop: true })).toBe(0);
-  });
-
-  it('clamps at boundary when loop is disabled', () => {
-    expect(handleArrowNavigation(makeEvent('ArrowDown'), items, 2, { orientation: 'vertical', loop: false })).toBe(2);
-  });
-
-  it('navigates to first item on Home', () => {
-    expect(handleArrowNavigation(makeEvent('Home'), items, 2)).toBe(0);
-  });
-
-  it('navigates to last item on End', () => {
-    expect(handleArrowNavigation(makeEvent('End'), items, 0)).toBe(2);
-  });
-
-  it('handles both orientation (vertical + horizontal keys)', () => {
-    expect(handleArrowNavigation(makeEvent('ArrowDown'), items, 0, { orientation: 'both' })).toBe(1);
-    expect(handleArrowNavigation(makeEvent('ArrowRight'), items, 0, { orientation: 'both' })).toBe(1);
-  });
-
-  it('returns undefined for unrelated keys', () => {
-    expect(handleArrowNavigation(makeEvent('Enter'), items, 0)).toBeUndefined();
-  });
-});
-
-describe('VisuallyHidden (utils)', () => {
-  it('hides content visually with inline styles', () => {
-    render(<VisuallyHidden>SR only</VisuallyHidden>);
-    const el = screen.getByText('SR only');
-    expect(el.style.position).toBe('absolute');
-    expect(el.style.width).toBe('1px');
-    expect(el.style.height).toBe('1px');
-    expect(el.style.overflow).toBe('hidden');
-  });
-
-  it('does not apply hidden styles when focusable', () => {
-    render(<VisuallyHidden focusable>Skip link</VisuallyHidden>);
-    const el = screen.getByText('Skip link');
-    expect(el.style.position).not.toBe('absolute');
-  });
-
-  it('sets data-visually-hidden attribute when not focusable', () => {
-    render(<VisuallyHidden>Hidden</VisuallyHidden>);
-    expect(screen.getByText('Hidden')).toHaveAttribute('data-visually-hidden', 'true');
-  });
-
-  it('has no accessibility violations', async () => {
-    const { container } = render(<VisuallyHidden>Accessible</VisuallyHidden>);
-    await expectNoA11yViolations(container);
-  });
-});