@astryxdesign/core 0.7.6-canary.f73623d → 0.7.6-canary.f77aaf2

package/src/EmptyState/EmptyState.spec.md

@@ -1,203 +0,0 @@
----
-schema_version: 3
-template_version: 7
-kind: component
-id: component:EmptyState
-authority: current
-archive_reason: null
-superseded_by: null
-approved_by: cixzhang
-approved_at: 2026-10-31
-owners: [cixzhang]
-review_triggers: [public-api, behavior, layout, theming, accessibility, testing]
-verified_by:
-  [
-    packages/core/src/EmptyState/EmptyState.test.tsx,
-    packages/core/src/EmptyState/EmptyState.announce.test.tsx,
-    .github/visual-baseline/manifest.json,
-    scripts/check-knowledge.mjs,
-    packages/core/src/theme/themingTargets.test.ts,
-    packages/core/src/docPropReferences.test.ts,
-  ]
-modules: []
-families: []
-design_specs: []
-architecture:
-  [
-    architecture:public-component-api,
-    architecture:component-theming-surface,
-    architecture:component-test-sufficiency,
-  ]
-contributing: []
-system_specs:
-  [spec:AST-009, spec:AST-020/FR1, spec:AST-086/FR2, spec:AST-086/FR11]
----
-
-# EmptyState component contract
-
-## Contract at a glance
-
-| Area                    | Contract                                                                                                                                                                                         |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Public contract         | `EmptyState` renders a required title plus optional description, decorative icon, and caller-owned actions in one root without a live role; callers choose heading level and compact layout.     |
-| Behavior                | Null, undefined, boolean, and empty-string optional values create no slot wrapper. Rendered content follows icon, text, then actions order; compact layout reduces spacing and stacks actions.   |
-| End-user impact         | A person reaches a named empty-content message and any next action without blank gaps from shallow-empty optional values; the title fits the surrounding document outline.                       |
-| Builder impact          | None; the record describes shipped behavior.                                                                                                                                                     |
-| Compatibility/readiness | Released behavior recorded as current; no API, default, or output changes.                                                                                                                       |
-| Review checks           | Reject a missing heading, an informative icon hidden as decorative, a shallow-empty optional scalar that still changes layout, a dropped root prop/ref/style, or a theme target without anatomy. |
-| Governing rules         | `architecture:public-component-api` INV1 and INV5–INV9; `architecture:component-theming-surface` INV2–INV6; `architecture:component-test-sufficiency` INV1–INV7, INV10–INV11; WCAG 2.2.          |
-
-This table is a review projection; the body below is authoritative.
-
-## Intent
-
-`EmptyState` gives an otherwise empty content area a semantic heading, supporting
-context, optional decorative visual, and optional caller-owned next actions.
-
-## Compatibility and migration
-
-- Released default preserved: `yes` — heading level 3, default layout, no
-  live role on the root.
-- Compatibility class: records shipped behavior; no public prop, default, DOM,
-  target, or styling output changes.
-- Controlled/uncontrolled behavior: not applicable
-- Migration decision: none
-
-Consumer migration instructions belong in consumer docs and release notes.
-
-## Ownership boundary
-
-**Owns**
-
-- the root, content order, heading element, and default/compact layout;
-- hiding the icon slot from assistive technology as decorative; and
-- whether optional slots create component-owned wrappers and spacing.
-
-**Does not own / non-goals**
-
-- the message copy, icon meaning, action controls, or action behavior — those belong to the product callsite and the components it supplies;
-- page-level heading order — the caller chooses `headingLevel` for its document; or
-- error, loading, or populated-content behavior.
-
-## Public concepts
-
-| Concept        | Closed values or states | Meaning                                                                   | Availability by variant/orientation/state | Default  | Owner                  | Stability | Invalid-value behavior                                  |
-| -------------- | ----------------------- | ------------------------------------------------------------------------- | ----------------------------------------- | -------- | ---------------------- | --------- | ------------------------------------------------------- |
-| title          | string                  | The empty region's heading content.                                       | all                                       | required | `component:EmptyState` | stable    | type rejection                                          |
-| description    | string or absent        | Optional supporting context below the title.                              | all                                       | absent   | `component:EmptyState` | stable    | nullish and empty-string values omit the part           |
-| icon           | React node or absent    | Optional caller visual, exposed as decorative beside the textual message. | all                                       | absent   | product callsite       | stable    | nullish, boolean, and empty-string values omit the slot |
-| actions        | React node or absent    | Optional caller-owned next actions below the message.                     | all                                       | absent   | product callsite       | stable    | nullish, boolean, and empty-string values omit the slot |
-| heading level  | `1` through `6`         | The title's HTML heading level in the surrounding document outline.       | all                                       | `3`      | product callsite       | stable    | type rejection                                          |
-| layout variant | default, compact        | Compact reduces spacing and stacks the action slot vertically.            | all                                       | default  | `component:EmptyState` | stable    | type rejection                                          |
-
-## Behavioral and layout contract
-
-| ID  | Invariant                                                                                                                                                                               | Basis                                                                                |
-| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
-| FR1 | The component MUST render one root containing the icon, text group, and actions in that reading order when present. The component MUST NOT add a live role or `aria-live` to the root.  | Current implementation and consumer docs; `spec:AST-086` FR2; WCAG 2.2 SC 1.3.2      |
-| FR2 | The required title MUST render at the caller-selected heading level without changing the component's visual type role.                                                                  | Current implementation, tests, and consumer docs; WCAG 2.2 SC 1.3.1 and SC 2.4.6     |
-| FR3 | Null, undefined, boolean, and empty-string optional values MUST NOT create a wrapper, layout gap, or assistive-technology node; containers that are shallowly non-empty remain wrapped. | React's direct-child rendering semantics; established public optional-slot interface |
-| FR4 | The decorative icon wrapper MUST be absent when the slot is absent and hidden from assistive technology when rendered.                                                                  | Current implementation and tests; WCAG 2.2 SC 1.1.1                                  |
-| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the root.                                                                             | `architecture:public-component-api` INV5–INV8                                        |
-| FR6 | Compact layout MUST reduce component spacing and stack the actions slot while preserving content order and root semantics.                                                              | Current implementation, tests, and consumer docs                                     |
-
-### Allowed variation
-
-- **AV1 — Caller content.** Message wording, decorative artwork, and action
-  composition may vary at the product callsite.
-- **AV2 — Theme paint.** Theme-controlled paint and typography may vary through
-  the documented targets while anatomy and content order remain stable.
-
-### Representative states
-
-| State                         | Required invariant                                        | Allowed variation                      |
-| ----------------------------- | --------------------------------------------------------- | -------------------------------------- |
-| title only                    | root and selected heading level remain present            | message wording                        |
-| description                   | supporting text follows the title                         | text length and wrapping               |
-| decorative icon               | visual precedes text and is hidden from assistive tech    | artwork supplied by the caller         |
-| actions                       | caller controls follow the text group                     | one or more caller-owned controls      |
-| compact                       | reduced spacing and vertical actions preserve semantics   | theme paint and caller content         |
-| shallow-empty optional scalar | nullish, boolean, and empty-string values emit no wrapper | which optional slot receives the value |
-
-### Transformation and precedence order
-
-- **ORD1 — Root composition.** Component semantics and theme metadata combine
-  with component styles, then consumer `xstyle`, `className`, and `style` under
-  the shared merge contract. The component sets no role, so a caller's `role`
-  reaches the root unchanged.
-
-### Performance and resources
-
-- **PR1 — No resources of its own.** EmptyState holds no state, listener,
-  observer, or timer of its own; the shared announcement wrapper around its
-  text owns the observation that announces it (`spec:AST-086`).
-
-## Accessibility contract
-
-- **AR1 — Heading semantics.** The title is a heading at the caller-selected level.
-- **AR2 — Decorative visual.** The icon slot is hidden from assistive technology;
-  callers keep all necessary meaning in the title or description.
-- **AR3 — No live region; announced when it appears.** EmptyState adds no live
-  role or `aria-live` to the root and does not move focus. Rendered or changed
-  before the document finished loading (or while hydrating), it announces
-  nothing. When it appears, or its message changes, later, it announces its
-  message once through the shared polite channel (`spec:AST-086` FR2, FR11).
-  The message is the title and description, without content hidden from
-  assistive technology; action labels are not part of it. Action controls keep
-  their own names, roles, and behavior.
-
-## Design relationships
-
-No current design record governs EmptyState-specific representation. Visual
-judgment remains evidence, not product authority.
-
-### Theming anatomy
-
-<!-- anatomy-theming:v1 -->
-
-```json
-{
-  "Container": {"target": "empty-state"},
-  "Icon": {
-    "none": {
-      "reason": "intentional: caller-supplied decorative content keeps its own styling and has no component-owned paint target"
-    }
-  },
-  "Title": {"target": "empty-state-title"},
-  "Description": {"target": "empty-state-description"},
-  "Actions": {
-    "none": {
-      "reason": "intentional: caller-supplied controls keep their own component targets and behavior"
-    }
-  }
-}
-```
-
-## Family and system relationships
-
-No current family record owns EmptyState-specific behavior.
-
-## Verification map
-
-| Contract            | Verification                                                                                                                           | Representative states                                                                                                                 | Mutation or failure expectation                                                                                                                                                                                                                                                                           | Audit section              |
-| ------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- |
-| FR1, FR3, FR4, AR2  | `EmptyState.test.tsx` slot, order, decorative-icon, empty-slot, and live-role tests; stable visual baseline `core-emptystate--default` | Title only; all slots; absent and shallow-empty slots                                                                                 | A wrapper for an absent or shallow-empty slot, a changed slot order, an icon not hidden from assistive technology, or a live role on the root fails; a changed default layout comes back changed for review. Gap: no accessibility-tree check proves the hidden icon or the heading (`spec:AST-009` FR3). | `audit:EmptyState/a11y`    |
-| FR2, AR1            | `EmptyState.test.tsx` heading tests                                                                                                    | Default level 3; every level                                                                                                          | A title that is not the selected heading element fails. Gap: no check that the title keeps one type style at every heading level.                                                                                                                                                                         | `audit:EmptyState/a11y`    |
-| AR3                 | `EmptyState.announce.test.tsx`                                                                                                         | Render with the page; appear later; iframe; inside a live container; message change; server render and hydration; hidden and revealed | An announcement during load or hydration, a missing or repeated announcement when it appears or changes later, hidden text in the message, or an announcement inside a live container fails. Gap: no test asserts that focus stays where it was when EmptyState appears.                                  | `audit:EmptyState/a11y`    |
-| FR5, ORD1           | `EmptyState.test.tsx` ref, `data-testid`, and root-composition tests                                                                   | DOM, data, event, style inputs; caller role; ref                                                                                      | A dropped input, a replaced caller role, or a ref that is not a `div` fails. Gap: the ref test checks only that the ref is a `div`, not that it is the root. No test asserts that caller `xstyle` follows the component styles.                                                                           | `audit:EmptyState/api`     |
-| FR6                 | `EmptyState.test.tsx` compact and theming-target tests                                                                                 | Default and compact                                                                                                                   | A compact layout that is not reflected on the root, title, and description, or that changes slot order, fails. Gap: the reduced spacing and stacked actions have no automated check.                                                                                                                      | `audit:EmptyState/layout`  |
-| PR1                 | Source review                                                                                                                          | Every render path                                                                                                                     | Gap: no automated check fails if EmptyState adds state, a listener, or a timer of its own.                                                                                                                                                                                                                | `audit:EmptyState/code`    |
-| Theming anatomy map | `scripts/check-knowledge.mjs`; `themingTargets.test.ts`                                                                                | Consumer anatomy and current targets                                                                                                  | Missing, extra, or stale mappings fail repository validation.                                                                                                                                                                                                                                             | `audit:EmptyState/theming` |
-
-## Decision log
-
-None recorded. The record describes shipped behavior.
-
-## Open questions
-
-None.
-
-## Content boundary
-
-This file does not duplicate consumer prop tables/examples, current audit
-results, implementation steps, or family/system rules. It links to their owners.

package/src/EmptyState/EmptyState.test.tsx

@@ -1,284 +0,0 @@
-// Copyright (c) Meta Platforms, Inc. and affiliates.
-
-import {describe, it, expect, vi} from 'vitest';
-import {fireEvent, render, screen} from '@testing-library/react';
-import * as stylex from '@stylexjs/stylex';
-import {EmptyState} from './EmptyState';
-import {defineTheme} from '../theme/defineTheme';
-import {generateThemeCSS} from '../theme/generateThemeRules';
-
-function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {
-  const {prose, component} = generateThemeCSS(theme);
-  return [prose, component].filter(Boolean).join('\n\n');
-}
-
-const testStyles = stylex.create({
-  root: {
-    minWidth: '123px',
-  },
-});
-
-describe('EmptyState', () => {
-  it('renders with title', () => {
-    render(<EmptyState title="No results found" />);
-    expect(screen.getByText('No results found')).toBeInTheDocument();
-  });
-
-  it('renders title as h3 by default', () => {
-    render(<EmptyState title="No data" />);
-    const heading = screen.getByRole('heading', {name: 'No data'});
-    expect(heading).toBeInTheDocument();
-    expect(heading.tagName).toBe('H3');
-  });
-
-  it('renders custom heading level', () => {
-    render(<EmptyState title="No data" headingLevel={2} />);
-    const heading = screen.getByRole('heading', {name: 'No data'});
-    expect(heading.tagName).toBe('H2');
-  });
-
-  it('renders all heading levels', () => {
-    const levels = [1, 2, 3, 4, 5, 6] as const;
-    for (const level of levels) {
-      const {unmount} = render(
-        <EmptyState title={`Level ${level}`} headingLevel={level} />,
-      );
-      const heading = screen.getByRole('heading', {
-        name: `Level ${level}`,
-      });
-      expect(heading.tagName).toBe(`H${level}`);
-      unmount();
-    }
-  });
-
-  it('renders with description', () => {
-    render(
-      <EmptyState
-        title="No results"
-        description="Try adjusting your search."
-      />,
-    );
-    expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();
-    // Description keeps its stable target element instead of paragraph semantics.
-    expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');
-  });
-
-  it('does not render description when not provided', () => {
-    render(<EmptyState title="No results" />);
-    expect(screen.queryByText('Try adjusting your search.')).toBeNull();
-  });
-
-  it('renders with icon', () => {
-    render(
-      <EmptyState
-        title="No results"
-        icon={<span data-testid="empty-icon">📭</span>}
-      />,
-    );
-    expect(screen.getByTestId('empty-icon')).toBeInTheDocument();
-  });
-
-  it('marks icon as decorative with aria-hidden', () => {
-    render(
-      <EmptyState
-        title="No results"
-        icon={<span data-testid="empty-icon">📭</span>}
-      />,
-    );
-    const iconWrapper = screen.getByTestId('empty-icon').parentElement;
-    expect(iconWrapper).toHaveAttribute('aria-hidden', 'true');
-  });
-
-  it('does not render icon wrapper when icon is not provided', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    expect(
-      container.querySelector('[aria-hidden="true"]'),
-    ).not.toBeInTheDocument();
-  });
-
-  it('renders with actions', () => {
-    render(
-      <EmptyState
-        title="No results"
-        actions={
-          <button type="button" data-testid="action-btn">
-            Retry
-          </button>
-        }
-      />,
-    );
-    expect(screen.getByTestId('action-btn')).toBeInTheDocument();
-  });
-
-  it('does not render actions wrapper when actions is not provided', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    // Container div + text group div, but no actions wrapper
-    const divs = container.querySelectorAll('div');
-    expect(divs).toHaveLength(2); // container + text group
-  });
-
-  it('does not make the root a live region', () => {
-    const {container} = render(<EmptyState title="No results" />);
-    expect(container.querySelector('[role], [aria-live]')).toBeNull();
-  });
-
-  it('renders compact variant', () => {
-    render(<EmptyState title="No results" isCompact />);
-    expect(screen.getByText('No results')).toBeInTheDocument();
-  });
-
-  it('forwards ref', () => {
-    const ref = {current: null as HTMLDivElement | null};
-    render(<EmptyState ref={ref} title="No results" />);
-    expect(ref.current).toBeInstanceOf(HTMLDivElement);
-  });
-
-  it('spreads data-testid', () => {
-    render(<EmptyState title="No results" data-testid="empty-state" />);
-    expect(screen.getByTestId('empty-state')).toBeInTheDocument();
-  });
-
-  it('does not render empty optional slot wrappers', () => {
-    const {container} = render(
-      <EmptyState title="No results" description="" icon={false} actions="" />,
-    );
-    const root = container.firstElementChild as HTMLElement;
-    expect(root).toHaveTextContent('No results');
-    expect(root).toHaveTextContent(/^No results$/);
-    expect(root.children).toHaveLength(1);
-    expect(container.querySelector('[aria-hidden="true"]')).toBeNull();
-    expect(
-      container.querySelector('.astryx-empty-state-description'),
-    ).toBeNull();
-  });
-
-  it('composes root props, including a caller role', () => {
-    const onClick = vi.fn();
-    const expectedXstyleClass = stylex.props(testStyles.root).className;
-    if (expectedXstyleClass == null) {
-      throw new Error('Expected the test xstyle to produce a class name.');
-    }
-    render(
-      <EmptyState
-        title="No results"
-        role="region"
-        data-owner="consumer"
-        className="consumer-class"
-        style={{width: '321px'}}
-        xstyle={testStyles.root}
-        onClick={onClick}
-      />,
-    );
-
-    const root = screen.getByRole('region');
-    expect(root).toHaveClass('astryx-empty-state', 'consumer-class');
-    expect(root).toHaveClass(expectedXstyleClass);
-    expect(root).toHaveAttribute('data-owner', 'consumer');
-    expect(root).toHaveStyle({width: '321px'});
-    fireEvent.click(root);
-    expect(onClick).toHaveBeenCalledOnce();
-  });
-
-  it('reflects compact layout on the root and preserves slot order', () => {
-    render(
-      <EmptyState
-        title="No results"
-        description="Try again."
-        icon={<span data-testid="icon">Icon</span>}
-        actions={<button type="button">Retry</button>}
-        isCompact
-        data-testid="empty-state"
-      />,
-    );
-
-    const root = screen.getByTestId('empty-state');
-    expect(root).toHaveAttribute('data-variant', 'compact');
-    expect(root.children).toHaveLength(3);
-    expect(root.children[0]).toContainElement(screen.getByTestId('icon'));
-    expect(root.children[1]).toContainElement(
-      screen.getByRole('heading', {name: 'No results'}),
-    );
-    expect(root.children[2]).toContainElement(
-      screen.getByRole('button', {name: 'Retry'}),
-    );
-  });
-
-  it('renders all slots together', () => {
-    render(
-      <EmptyState
-        icon={<span data-testid="icon">🔍</span>}
-        title="No results found"
-        description="Try a different search term."
-        actions={
-          <>
-            <button type="button">Clear filters</button>
-            <button type="button">Go back</button>
-          </>
-        }
-        data-testid="full-empty-state"
-      />,
-    );
-    expect(screen.getByTestId('icon')).toBeInTheDocument();
-    expect(screen.getByText('No results found')).toBeInTheDocument();
-    expect(
-      screen.getByText('Try a different search term.'),
-    ).toBeInTheDocument();
-    expect(screen.getByText('Clear filters')).toBeInTheDocument();
-    expect(screen.getByText('Go back')).toBeInTheDocument();
-  });
-
-  describe('theming targets', () => {
-    it('puts astryx-empty-state-title on the title heading', () => {
-      render(<EmptyState title="No results" />);
-      const heading = screen.getByRole('heading', {name: 'No results'});
-      expect(heading).toHaveClass('astryx-empty-state-title');
-    });
-
-    it('puts astryx-empty-state-description on the description', () => {
-      render(
-        <EmptyState title="No results" description="Try another search." />,
-      );
-      const description = screen.getByText('Try another search.');
-      expect(description).toHaveClass('astryx-empty-state-description');
-    });
-
-    it('reflects the compact variant on the title and description targets', () => {
-      render(
-        <EmptyState
-          title="No results"
-          description="Try another search."
-          isCompact
-        />,
-      );
-      expect(screen.getByRole('heading', {name: 'No results'})).toHaveAttribute(
-        'data-variant',
-        'compact',
-      );
-      expect(screen.getByText('Try another search.')).toHaveAttribute(
-        'data-variant',
-        'compact',
-      );
-    });
-
-    it('exposes the title and description as themeable defineTheme targets', () => {
-      // jsdom can't resolve the @layer cascade, so this asserts the targets are
-      // reachable by a theme via the sanctioned defineTheme channel — replacing
-      // the structural `> div:has(> :is(h1..h6))` heading-detection selectors a
-      // consumer would otherwise need to restyle the title and description.
-      const theme = defineTheme({
-        name: 'empty-state-target-test',
-        components: {
-          'empty-state-title': {
-            base: {fontSize: 'var(--text-large-size)'},
-          },
-          'empty-state-description': {
-            base: {color: 'var(--color-text-secondary)'},
-          },
-        },
-      });
-      const css = generateThemeTestCSS(theme);
-      expect(css).toContain('.astryx-empty-state-title');
-      expect(css).toContain('.astryx-empty-state-description');
-    });
-  });
-});