@fragments-sdk/ui 0.14.0 → 0.15.1

package/src/components/Tooltip/Tooltip.fragment.tsx

@@ -1,191 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/core';
-import { Tooltip } from '.';
-import { Button } from '../Button';
-
-export default defineFragment({
-  component: Tooltip,
-
-  meta: {
-    name: 'Tooltip',
-    description: 'Contextual help text that appears on hover or focus. Perfect for explaining icons, truncated text, or providing additional context.',
-    category: 'feedback',
-    status: 'stable',
-    tags: ['tooltip', 'hint', 'help', 'hover', 'contextual'],
-    since: '0.1.0',
-  },
-
-  usage: {
-    when: [
-      'Explaining icon-only buttons',
-      'Showing full text for truncated content',
-      'Providing keyboard shortcuts',
-      'Brief contextual help that fits in one line',
-    ],
-    whenNot: [
-      'Long-form help content (use Popover)',
-      'Critical information users must see (use Alert)',
-      'Interactive content (use Popover or Menu)',
-      'Mobile-primary interfaces (tooltips require hover)',
-    ],
-    guidelines: [
-      'Keep tooltip text concise (under 80 characters)',
-      'Use sentence case, no period for single sentences',
-      'Avoid duplicating visible label text',
-      'Consider mobile users who cannot hover',
-      'Use contentProps for tooltip popup attributes/styling; top-level HTML attrs are applied to the popup for backward compatibility',
-    ],
-    accessibility: [
-      'Accessible via focus as well as hover',
-      'Uses role="tooltip" with proper aria association',
-      'Delay prevents tooltips from appearing during navigation',
-    ],
-  },
-
-  props: {
-    children: {
-      type: 'element',
-      description: 'The element that triggers the tooltip',
-      required: true,
-    },
-    content: {
-      type: 'node',
-      description: 'Content to display in the tooltip',
-      required: true,
-    },
-    side: {
-      type: 'enum',
-      description: 'Which side to show the tooltip',
-      values: ['top', 'bottom', 'left', 'right'],
-      default: 'top',
-    },
-    align: {
-      type: 'enum',
-      description: 'Alignment along the side',
-      values: ['start', 'center', 'end'],
-      default: 'center',
-    },
-    sideOffset: {
-      type: 'number',
-      description: 'Distance from trigger in pixels',
-      default: '6',
-    },
-    delay: {
-      type: 'number',
-      description: 'Delay before showing (ms)',
-      default: '400',
-    },
-    closeDelay: {
-      type: 'number',
-      description: 'Delay before hiding (ms)',
-      default: '0',
-    },
-    arrow: {
-      type: 'boolean',
-      description: 'Show arrow pointing to trigger',
-      default: 'true',
-    },
-    disabled: {
-      type: 'boolean',
-      description: 'Disable the tooltip',
-      default: 'false',
-    },
-    open: {
-      type: 'boolean',
-      description: 'Controlled open state',
-    },
-    defaultOpen: {
-      type: 'boolean',
-      description: 'Default open state',
-      default: 'false',
-    },
-    onOpenChange: {
-      type: 'function',
-      description: 'Callback when open state changes',
-    },
-    contentProps: {
-      type: 'object',
-      description: 'Props forwarded to the tooltip popup element (preferred way to pass popup attrs/className/style)',
-    },
-  },
-
-  relations: [
-    { component: 'Popover', relationship: 'alternative', note: 'Use Popover for interactive or longer content' },
-    { component: 'Alert', relationship: 'alternative', note: 'Use Alert for critical information that must be visible' },
-  ],
-
-  contract: {
-    propsSummary: [
-      'content: ReactNode - tooltip content',
-      'side: top|bottom|left|right - position',
-      'delay: number - show delay in ms (default: 400)',
-      'arrow: boolean - show arrow (default: true)',
-      'contentProps: HTMLAttributes<HTMLDivElement> - popup element props',
-    ],
-    scenarioTags: [
-      'help.tooltip',
-      'content.hint',
-      'action.explain',
-    ],
-    a11yRules: ['A11Y_TOOLTIP_FOCUS', 'A11Y_TOOLTIP_ROLE'],
-  },
-
-  variants: [
-    {
-      name: 'Default',
-      description: 'Basic tooltip on hover',
-      render: () => (
-        <Tooltip content="Save your changes">
-          <Button>Save</Button>
-        </Tooltip>
-      ),
-    },
-    {
-      name: 'Positions',
-      description: 'Tooltips on different sides',
-      render: () => (
-        <div style={{ display: 'flex', gap: '16px', padding: '40px' }}>
-          <Tooltip content="Top tooltip" side="top">
-            <Button variant="secondary">Top</Button>
-          </Tooltip>
-          <Tooltip content="Bottom tooltip" side="bottom">
-            <Button variant="secondary">Bottom</Button>
-          </Tooltip>
-          <Tooltip content="Left tooltip" side="left">
-            <Button variant="secondary">Left</Button>
-          </Tooltip>
-          <Tooltip content="Right tooltip" side="right">
-            <Button variant="secondary">Right</Button>
-          </Tooltip>
-        </div>
-      ),
-    },
-    {
-      name: 'With Shortcut',
-      description: 'Tooltip showing keyboard shortcut',
-      render: () => (
-        <Tooltip content="Undo (Ctrl+Z)">
-          <Button variant="ghost">Undo</Button>
-        </Tooltip>
-      ),
-    },
-    {
-      name: 'No Arrow',
-      description: 'Tooltip without arrow',
-      render: () => (
-        <Tooltip content="Clean tooltip" arrow={false}>
-          <Button variant="secondary">Hover me</Button>
-        </Tooltip>
-      ),
-    },
-    {
-      name: 'With Content Props',
-      description: 'Pass popup attributes/styling using contentProps',
-      render: () => (
-        <Tooltip content="Custom popup attrs" contentProps={{ id: 'custom-tooltip-popup' }}>
-          <Button variant="secondary">Hover me</Button>
-        </Tooltip>
-      ),
-    },
-  ],
-});

package/src/components/Tooltip/Tooltip.test.tsx

@@ -1,124 +0,0 @@
-import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
-import { render, screen, userEvent, waitFor, act, expectNoA11yViolations } from '../../test/utils';
-import { Tooltip } from './index';
-
-describe('Tooltip', () => {
-  beforeEach(() => {
-    vi.useFakeTimers({ shouldAdvanceTime: true });
-  });
-
-  afterEach(() => {
-    vi.useRealTimers();
-  });
-
-  it('shows tooltip content on hover', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    render(
-      <Tooltip content="Tooltip text" delay={0}>
-        <button>Hover me</button>
-      </Tooltip>
-    );
-
-    await user.hover(screen.getByRole('button', { name: /hover me/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText('Tooltip text')).toBeInTheDocument();
-    });
-  });
-
-  it('hides tooltip on unhover', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    render(
-      <Tooltip content="Tooltip text" delay={0}>
-        <button>Hover me</button>
-      </Tooltip>
-    );
-
-    await user.hover(screen.getByRole('button', { name: /hover me/i }));
-    await waitFor(() => {
-      expect(screen.getByText('Tooltip text')).toBeInTheDocument();
-    });
-
-    await user.unhover(screen.getByRole('button', { name: /hover me/i }));
-    await waitFor(() => {
-      expect(screen.queryByText('Tooltip text')).not.toBeInTheDocument();
-    });
-  });
-
-  it('respects delay prop', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    render(
-      <Tooltip content="Delayed tooltip" delay={500}>
-        <button>Hover me</button>
-      </Tooltip>
-    );
-
-    await user.hover(screen.getByRole('button', { name: /hover me/i }));
-
-    // Tooltip should not be visible immediately
-    expect(screen.queryByText('Delayed tooltip')).not.toBeInTheDocument();
-
-    // Advance timers past the delay
-    await act(async () => {
-      vi.advanceTimersByTime(600);
-    });
-
-    await waitFor(() => {
-      expect(screen.getByText('Delayed tooltip')).toBeInTheDocument();
-    });
-  });
-
-  it('does not render when disabled', () => {
-    render(
-      <Tooltip content="Hidden tooltip" disabled>
-        <button>No tooltip</button>
-      </Tooltip>
-    );
-
-    // The trigger should just render the child directly
-    expect(screen.getByRole('button', { name: /no tooltip/i })).toBeInTheDocument();
-  });
-
-  it('supports controlled open state', async () => {
-    render(
-      <Tooltip content="Controlled tooltip" open={true} delay={0}>
-        <button>Trigger</button>
-      </Tooltip>
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('Controlled tooltip')).toBeInTheDocument();
-    });
-  });
-
-  it('respects shared Tooltip.Provider delay settings', async () => {
-    const user = userEvent.setup({ advanceTimers: vi.advanceTimersByTime });
-    render(
-      <Tooltip.Provider delay={0}>
-        <Tooltip content="Provider tooltip">
-          <button>Provider Trigger</button>
-        </Tooltip>
-      </Tooltip.Provider>
-    );
-
-    await user.hover(screen.getByRole('button', { name: /provider trigger/i }));
-
-    await waitFor(() => {
-      expect(screen.getByText('Provider tooltip')).toBeInTheDocument();
-    });
-  });
-
-  it('has no accessibility violations when open', async () => {
-    const { container } = render(
-      <Tooltip content="Accessible tooltip" open={true} delay={0}>
-        <button>Trigger</button>
-      </Tooltip>
-    );
-
-    await waitFor(() => {
-      expect(screen.getByText('Accessible tooltip')).toBeInTheDocument();
-    });
-
-    await expectNoA11yViolations(container);
-  });
-});

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

@@ -1,136 +0,0 @@
-import React from 'react';
-import { defineFragment } from '@fragments-sdk/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',
-      'VisuallyHidden forwards DOM props and className to the rendered element',
-    ],
-    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',
-      'Forwards standard DOM props (id, aria-*, data-*, className, handlers)',
-    ],
-    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,43 +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);
-  });
-
-  it('forwards DOM props and composes className', () => {
-    render(
-      <VisuallyHidden data-testid="vh" id="vh-id" className="extra">
-        Hidden
-      </VisuallyHidden>
-    );
-    const el = screen.getByTestId('vh');
-    expect(el).toHaveAttribute('id', 'vh-id');
-    expect(el).toHaveClass('visuallyHidden');
-    expect(el).toHaveClass('extra');
-  });
-});

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();
-}