@astryxdesign/core 0.1.4-canary.fd7ab46 → 0.1.4

package/src/SizeContext/SizeContext.test.tsx

@@ -1,226 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file SizeContext.test.tsx
- * @input Uses vitest, @testing-library/react, SizeContext module
- * @output Characterization tests for SizeContext / useSize / SizeProvider
- * @position Testing; validates the size-cascade resolution contract
- *
- * SYNC: When SizeContext.ts changes, update tests to match new behavior
- */
-
-import {describe, it, expect} from 'vitest';
-import {renderHook, render, screen} from '@testing-library/react';
-import {createElement, type ReactNode} from 'react';
-import {
-  SizeContext,
-  SizeProvider,
-  useSize,
-  type ElementSize,
-} from './SizeContext';
-
-/**
- * Wrap children in a SizeProvider set to `size`. Passing `null` mimics
- * "no container is providing a size".
- */
-function withProvider(size: ElementSize | null) {
-  return function Wrapper({children}: {children: ReactNode}) {
-    return <SizeProvider value={size}>{children}</SizeProvider>;
-  };
-}
-
-describe('SizeContext', () => {
-  describe('context identity', () => {
-    it('defaults to null when read outside any provider', () => {
-      const {result} = renderHook(() => useSize());
-      // No provider + no prop + no explicit default → the 'md' fallback.
-      expect(result.current).toBe('md');
-    });
-
-    it('exposes a displayName for devtools', () => {
-      expect(SizeContext.displayName).toBe('SizeContext');
-    });
-
-    it('SizeProvider is the context Provider itself', () => {
-      expect(SizeProvider).toBe(SizeContext.Provider);
-    });
-  });
-
-  describe('useSize — resolution priority', () => {
-    it('returns the default "md" with no prop and no provider', () => {
-      const {result} = renderHook(() => useSize());
-      expect(result.current).toBe('md');
-    });
-
-    it('honors an explicit defaultSize when neither prop nor context is set', () => {
-      const {result} = renderHook(() => useSize(undefined, 'lg'));
-      expect(result.current).toBe('lg');
-    });
-
-    it('returns the explicit size prop when provided', () => {
-      const {result} = renderHook(() => useSize('sm'));
-      expect(result.current).toBe('sm');
-    });
-
-    it('prop wins over the explicit default', () => {
-      const {result} = renderHook(() => useSize('sm', 'lg'));
-      expect(result.current).toBe('sm');
-    });
-
-    it('inherits the size from an enclosing provider when no prop is passed', () => {
-      const {result} = renderHook(() => useSize(), {
-        wrapper: withProvider('lg'),
-      });
-      expect(result.current).toBe('lg');
-    });
-
-    it('prop wins over the inherited provider size', () => {
-      const {result} = renderHook(() => useSize('sm'), {
-        wrapper: withProvider('lg'),
-      });
-      expect(result.current).toBe('sm');
-    });
-
-    it('inherited context wins over the explicit default fallback', () => {
-      const {result} = renderHook(() => useSize(undefined, 'sm'), {
-        wrapper: withProvider('lg'),
-      });
-      expect(result.current).toBe('lg');
-    });
-
-    it('falls back to default when the provider value is explicitly null', () => {
-      const {result} = renderHook(() => useSize(undefined, 'sm'), {
-        wrapper: withProvider(null),
-      });
-      expect(result.current).toBe('sm');
-    });
-
-    it('falls back to "md" when provider is null and no default is given', () => {
-      const {result} = renderHook(() => useSize(), {
-        wrapper: withProvider(null),
-      });
-      expect(result.current).toBe('md');
-    });
-  });
-
-  describe('useSize — every standard ElementSize resolves', () => {
-    const sizes: ElementSize[] = ['sm', 'md', 'lg'];
-
-    it.each(sizes)('resolves explicit prop "%s"', size => {
-      const {result} = renderHook(() => useSize(size));
-      expect(result.current).toBe(size);
-    });
-
-    it.each(sizes)('resolves inherited provider "%s"', size => {
-      const {result} = renderHook(() => useSize(), {
-        wrapper: withProvider(size),
-      });
-      expect(result.current).toBe(size);
-    });
-  });
-
-  describe('useSize — nested providers', () => {
-    it('resolves to the nearest provider', () => {
-      function Nested({children}: {children: ReactNode}) {
-        return (
-          <SizeProvider value="sm">
-            <SizeProvider value="lg">{children}</SizeProvider>
-          </SizeProvider>
-        );
-      }
-      const {result} = renderHook(() => useSize(), {wrapper: Nested});
-      expect(result.current).toBe('lg');
-    });
-
-    it('a prop still overrides the nearest provider', () => {
-      function Nested({children}: {children: ReactNode}) {
-        return (
-          <SizeProvider value="sm">
-            <SizeProvider value="lg">{children}</SizeProvider>
-          </SizeProvider>
-        );
-      }
-      const {result} = renderHook(() => useSize('md'), {wrapper: Nested});
-      expect(result.current).toBe('md');
-    });
-  });
-
-  describe('useSize — generic (non-ElementSize) values', () => {
-    it('supports a custom string union via the type parameter', () => {
-      type Custom = 'compact' | 'comfortable';
-      const {result} = renderHook(() =>
-        useSize<Custom>('compact', 'comfortable'),
-      );
-      expect(result.current).toBe('compact');
-    });
-
-    it('returns the custom default when no prop is given', () => {
-      type Custom = 'compact' | 'comfortable';
-      const {result} = renderHook(() =>
-        useSize<Custom>(undefined, 'comfortable'),
-      );
-      expect(result.current).toBe('comfortable');
-    });
-
-    it('empty-string prop is a real value and does NOT fall through to default', () => {
-      // '' ?? x === '' because nullish coalescing only catches null/undefined.
-      const {result} = renderHook(() => useSize('' as ElementSize, 'lg'));
-      expect(result.current).toBe('');
-    });
-  });
-
-  describe('integration — components consuming the cascade', () => {
-    function SizedProbe({size}: {size?: ElementSize}) {
-      const resolved = useSize(size);
-      return <span data-testid="probe">{resolved}</span>;
-    }
-
-    it('a child with no size prop reads the container size', () => {
-      render(
-        <SizeProvider value="lg">
-          <SizedProbe />
-        </SizeProvider>,
-      );
-      expect(screen.getByTestId('probe')).toHaveTextContent('lg');
-    });
-
-    it('sibling children resolve independently against the same provider', () => {
-      render(
-        <SizeProvider value="lg">
-          <span data-testid="a">
-            <SizedProbe />
-          </span>
-          <span data-testid="b">
-            <SizedProbe size="sm" />
-          </span>
-        </SizeProvider>,
-      );
-      expect(screen.getByTestId('a')).toHaveTextContent('lg');
-      expect(screen.getByTestId('b')).toHaveTextContent('sm');
-    });
-
-    it('re-renders with the new size when the provider value changes', () => {
-      const {rerender} = render(
-        <SizeProvider value="sm">
-          <SizedProbe />
-        </SizeProvider>,
-      );
-      expect(screen.getByTestId('probe')).toHaveTextContent('sm');
-
-      rerender(
-        <SizeProvider value="lg">
-          <SizedProbe />
-        </SizeProvider>,
-      );
-      expect(screen.getByTestId('probe')).toHaveTextContent('lg');
-    });
-
-    it('works with createElement (no JSX) call form', () => {
-      const {result} = renderHook(() => useSize(), {
-        wrapper: ({children}: {children: ReactNode}) =>
-          createElement(SizeProvider, {value: 'sm'}, children),
-      });
-      expect(result.current).toBe('sm');
-    });
-  });
-});

package/src/__tests__/TestIcon.tsx

@@ -1,26 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file TestIcon.tsx
- * @input Standard SVG props
- * @output A minimal SVG React component for tests
- * @position Test fixture; a stand-in external SVG icon for Icon component-mode tests
- *
- * A trivial SVG component used by tests that need to pass a custom SVG icon to
- * `Icon` (component mode) or component `*Icon` props. It forwards all standard
- * SVG props and its ref so tests exercising prop/ref forwarding behave the same
- * as a real third-party icon component.
- */
-
-import React, {type SVGProps} from 'react';
-
-export function TestIcon({
-  ref,
-  ...props
-}: SVGProps<SVGSVGElement> & {ref?: React.Ref<SVGSVGElement>}) {
-  return (
-    <svg ref={ref} viewBox="0 0 24 24" {...props}>
-      <path d="M4 4h16v16H4z" />
-    </svg>
-  );
-}

package/src/__tests__/fastRoleQueries.ts

@@ -1,66 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/**
- * @file fastRoleQueries.ts
- * @input Uses @testing-library/react screen, dom-accessibility-api
- * @output getButton/queryButton — role+name lookups that stay O(match) in jsdom
- * @position Shared test helper; imported by component tests that render large
- *   always-mounted button collections (Calendar month grids)
- *
- * RTL's getByRole('button', {name}) computes the accessible name of EVERY
- * role candidate before filtering, and each computation consults jsdom's slow
- * getComputedStyle (~5ms per node). The date components keep a month grid of
- * ~35–85 role=button nodes mounted — visible in Calendar's case, inside the
- * closed popover for the *Input components — so a single trigger lookup cost
- * ~450ms and dominated those suites' runtime (DateRangeInput: 34s for 34
- * tests before this helper existed).
- *
- * These helpers keep RTL's exact name algorithm (dom-accessibility-api is the
- * library RTL uses internally) but:
- *   - collect candidates with {hidden: true}, skipping the per-node
- *     getComputedStyle visibility checks, and
- *   - inject a constant "visible" style stub into the name computation —
- *     names only consult display/visibility, and under {hidden: true}
- *     semantics visibility must not exclude candidates anyway.
- *
- * Trade-off vs getByRole: first match wins — no tree-wide uniqueness check.
- *
- * SYNC: When modified, update this header.
- */
-
-import {screen} from '@testing-library/react';
-import {computeAccessibleName} from 'dom-accessibility-api';
-
-// The name algorithm only reads getPropertyValue (for display/visibility/
-// content), so a Pick is all we need to type honestly — no object-literal
-// cast. The widening to CSSStyleDeclaration happens at the call site, where
-// getComputedStyle's signature demands the full type.
-const visibleStyleStub: Pick<CSSStyleDeclaration, 'getPropertyValue'> = {
-  getPropertyValue: prop =>
-    prop === 'display' ? 'block' : prop === 'visibility' ? 'visible' : '',
-};
-
-function matchesName(el: Element, name: string | RegExp): boolean {
-  const accessibleName = computeAccessibleName(el, {
-    getComputedStyle: () => visibleStyleStub as CSSStyleDeclaration,
-  });
-  return typeof name === 'string'
-    ? accessibleName === name
-    : name.test(accessibleName);
-}
-
-export function queryButton(name: string | RegExp): HTMLElement | null {
-  return (
-    screen
-      .queryAllByRole('button', {hidden: true})
-      .find(el => matchesName(el, name)) ?? null
-  );
-}
-
-export function getButton(name: string | RegExp): HTMLElement {
-  const el = queryButton(name);
-  if (!el) {
-    throw new Error(`Unable to find a role=button named ${String(name)}`);
-  }
-  return el;
-}

package/src/docPropReferences.test.ts

@@ -1,178 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/* eslint-disable @typescript-eslint/no-require-imports */
-/**
- * @file Guards doc prose against docs/source prop mismatches (#3360).
- *
- * Scans every {Name}.doc.mjs for prose phrases like "the foo prop on Bar"
- * and verifies the referenced prop is documented on the referenced
- * component. Doc prose is LLM training signal: a reference to a prop that
- * doesn't exist steers codegen toward hallucinated APIs (#3360 shipped a
- * bullet pointing at a nonexistent CodeBlock syntaxTheme prop).
- *
- * A reference to a missing prop is allowed only when the same string
- * explicitly negates it ("no such prop exists" / "does not exist"), the
- * corrective-bullet pattern used to counter known hallucinations.
- */
-
-import {describe, it, expect} from 'vitest';
-import {readdirSync} from 'node:fs';
-import {join, relative} from 'node:path';
-
-const SRC_DIR = __dirname;
-
-type DocModule = {
-  docs?: {
-    name?: string;
-    props?: {name: string}[];
-    components?: {name?: string; props?: {name: string}[]}[];
-  };
-};
-
-/**
- * Props intentionally omitted from doc props[]: PropDoc in docs-types.ts
- * says to skip internal/styling props, so prose may reference them even
- * though no doc lists them.
- */
-const UNIVERSAL_PROPS = new Set([
-  'xstyle',
-  'className',
-  'style',
-  'ref',
-  'data-testid',
-]);
-
-/**
- * Matches prose like "the foo prop on Bar", "foo prop of Bar", and
- * conjunction targets: "foo prop on Bar or Baz". Group 1 is the prop
- * (camelCase, lowercase first letter), group 2 the component name list.
- */
-const PROP_REF_PATTERN =
-  /\b([a-z][A-Za-z0-9]*) prop (?:on|of) (?:the )?([A-Z][A-Za-z0-9]*(?:(?:,(?: and| or)?| and| or) [A-Z][A-Za-z0-9]*)*)/g;
-
-/** A same-string negation marks the reference as a deliberate counter-signal. */
-const NEGATION_PATTERN = /no such prop|does not exist|doesn't exist/i;
-
-function findDocFiles(dir: string): string[] {
-  const files: string[] = [];
-  for (const entry of readdirSync(dir, {withFileTypes: true})) {
-    const full = join(dir, entry.name);
-    if (entry.isDirectory()) {
-      files.push(...findDocFiles(full));
-    } else if (entry.name.endsWith('.doc.mjs')) {
-      files.push(full);
-    }
-  }
-  return files;
-}
-
-/** Collect every string value reachable from a doc module export. */
-function collectStrings(value: unknown, out: string[]): void {
-  if (typeof value === 'string') {
-    out.push(value);
-  } else if (Array.isArray(value)) {
-    for (const item of value) {
-      collectStrings(item, out);
-    }
-  } else if (value && typeof value === 'object') {
-    for (const item of Object.values(value)) {
-      collectStrings(item, out);
-    }
-  }
-}
-
-const docFiles = findDocFiles(SRC_DIR);
-
-// Component name → documented prop names, from every doc file's props[]
-// (single and sub-component docs) and inline components[] entries.
-const documentedProps = new Map<string, Set<string>>();
-for (const file of docFiles) {
-  const mod = require(file) as DocModule;
-  const docs = mod.docs;
-  if (!docs) {
-    continue;
-  }
-  const entries = [
-    {name: docs.name, props: docs.props},
-    ...(docs.components || []),
-  ];
-  for (const {name, props} of entries) {
-    if (!name || !Array.isArray(props)) {
-      continue;
-    }
-    const set = documentedProps.get(name) || new Set<string>();
-    for (const prop of props) {
-      set.add(prop.name);
-    }
-    documentedProps.set(name, set);
-  }
-}
-
-interface Violation {
-  file: string;
-  component: string;
-  prop: string;
-  excerpt: string;
-}
-
-function findViolations(): Violation[] {
-  const violations: Violation[] = [];
-  for (const file of docFiles) {
-    const strings: string[] = [];
-    collectStrings(require(file), strings);
-    for (const text of strings) {
-      let match;
-      while ((match = PROP_REF_PATTERN.exec(text)) !== null) {
-        const [, prop, componentList] = match;
-        if (UNIVERSAL_PROPS.has(prop) || NEGATION_PATTERN.test(text)) {
-          continue;
-        }
-        for (const component of componentList.split(
-          /,(?: and| or)?| and | or /,
-        )) {
-          const name = component.trim();
-          if (!name) {
-            continue;
-          }
-          const known = documentedProps.get(name);
-          if (known && !known.has(prop)) {
-            violations.push({
-              file: relative(SRC_DIR, file),
-              component: name,
-              prop,
-              excerpt: text.slice(
-                Math.max(0, match.index - 40),
-                match.index + match[0].length + 20,
-              ),
-            });
-          }
-        }
-      }
-    }
-  }
-  return violations;
-}
-
-describe('doc prose prop references', () => {
-  it('sanity: discovers doc files and documented components', () => {
-    expect(docFiles.length).toBeGreaterThan(0);
-    expect(documentedProps.size).toBeGreaterThan(0);
-  });
-
-  it('every "X prop on Y" reference names a documented prop of Y', () => {
-    const violations = findViolations();
-    expect(
-      violations,
-      violations
-        .map(
-          v =>
-            `${v.file} references prop "${v.prop}" on ${v.component}, ` +
-            `which does not document it (…${v.excerpt}…). Either the prop ` +
-            `doesn't exist (fix the prose; negate with "no such prop ` +
-            `exists" if countering a known hallucination) or it exists in ` +
-            `source but is missing from the component's doc props[] (add it).`,
-        )
-        .join('\n'),
-    ).toEqual([]);
-  });
-});

package/src/hooks/useHotkeys.doc.mjs

@@ -1,52 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-/** @type {import('../docs-types').HookDoc} */
-export const docs = {
-  name: 'useHotkeys',
-  displayName: 'useHotkeys',
-  keywords: ['hotkey', 'shortcut', 'keyboard', 'keydown', 'command', 'palette', 'mod', 'cmd', 'ctrl', 'kbd'],
-  params: [
-    {
-      name: 'hotkeys',
-      type: 'Hotkey[]',
-      description:
-        'Shortcut registrations. Each entry: `{ keys, onPress, allowInInputs?, isDisabled? }`. `keys` is a "+"-separated combo like "mod+k", "shift+/", "escape" — "mod" is ⌘ on macOS and Ctrl elsewhere. `onPress` receives the KeyboardEvent after preventDefault(). `allowInInputs` (default false) lets the hotkey fire while typing in inputs/textareas/selects/contenteditable. `isDisabled` temporarily disables the entry.',
-      required: true,
-    },
-  ],
-  returns: [],
-  usage: {
-    description:
-      'Registers global keyboard shortcuts with a single window keydown listener per hook instance. Handlers live in a ref, so re-renders never re-subscribe. Skips events from typing targets (input, textarea, select, contenteditable) unless allowInInputs, skips defaultPrevented events, and calls preventDefault() on match. SSR-safe.',
-    bestPractices: [
-      { guidance: true, description: 'Use for app-level shortcuts like command palettes (mod+k), help overlays (shift+/), and navigation keys.' },
-      { guidance: true, description: 'Pair with the Kbd component to display the same combo you register — both resolve "mod" per platform identically.' },
-      { guidance: true, description: 'Use isDisabled to suspend shortcuts while a modal or wizard owns the keyboard, instead of unmounting the hook.' },
-      { guidance: false, description: 'Use for focus-scoped keyboard navigation inside a widget; use useListFocus or useGridFocus instead.' },
-    ],
-  },
-  relatedComponents: ['Kbd'],
-  relatedHooks: ['useListFocus', 'useGridFocus'],
-  importPath: '@astryxdesign/core/hooks',
-  category: 'interaction',
-};
-
-/** @type {import('../docs-types').HookTranslationDoc} */
-export const docsDense = {
-  description:
-    'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref — re-renders never re-subscribe. Skips typing targets (input/textarea/select/contenteditable) unless allowInInputs, skips defaultPrevented, preventDefault() on match. "mod" = ⌘ on macOS, Ctrl elsewhere. SSR-safe.',
-  paramDescriptions: {
-    hotkeys:
-      'array of { keys, onPress, allowInInputs?, isDisabled? }. keys = "+"-separated combo ("mod+k", "shift+/", "escape").',
-  },
-  usage: {
-    description:
-      'Global keyboard shortcuts w/ one window keydown listener per hook instance. Handlers kept in ref — re-renders never re-subscribe. Skips typing targets unless allowInInputs, skips defaultPrevented, preventDefault() on match. SSR-safe.',
-    bestPractices: [
-      { guidance: true, description: 'Use for app-level shortcuts: command palettes (mod+k), help overlays (shift+/), navigation keys.' },
-      { guidance: true, description: 'Pair w/ Kbd component to display same combo registered — both resolve "mod" per platform identically.' },
-      { guidance: true, description: 'Use isDisabled to suspend shortcuts while modal/wizard owns keyboard, instead of unmounting hook.' },
-      { guidance: false, description: 'Use for focus-scoped keyboard nav inside widget; use useListFocus / useGridFocus instead.' },
-    ],
-  },
-};