An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] EmptyState: remove blank optional-slot gaps (#7654)
Cindy Zhange2909cf48e4b
diff --git a/.changeset/empty-state-nonrendering-slots.md b/.changeset/empty-state-nonrendering-slots.mdnew file mode 100644index 0000000000..c2f3627dbd--- /dev/null+++ b/.changeset/empty-state-nonrendering-slots.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[fix] `EmptyState` no longer leaves blank icon or action spacing when those optional slots receive a boolean or an empty string. An empty description also omits its theme target. The docs now describe configurable heading levels and map the container anatomy to the public theme target.++@cixzhangdiff --git a/apps/storybook/rtl-audit/verified-not-applicable.json b/apps/storybook/rtl-audit/verified-not-applicable.jsonindex dc2cdcd95f..46757ed8f9 100644--- a/apps/storybook/rtl-audit/verified-not-applicable.json+++ b/apps/storybook/rtl-audit/verified-not-applicable.json@@ -16,6 +16,10 @@"component": "core/Field","reason": "The Core/Field stories use block-flow labels, controls, descriptions, and status text without directional icons, side-specific placement, order, scrolling, dragging, overlays, or keyboard behavior."},+ {+ "component": "core/EmptyState",+ "reason": "EmptyState is a centered block-flow status region. Its icon, text group, and action group stack only on the block axis; spacing is block-axis or logical, and text is centered. The component owns no directional glyph, contextual separator, side-specific placement or ordering, horizontal scrolling or dragging, overlay, or directional keyboard behavior. Caller-supplied icons and action controls retain their own RTL ownership."+ },{"component": "core/FieldStatus","reason": "FieldStatus uses block-flow message layout and logical padding and corner radii. Its status glyphs are non-directional, and it has no side-specific placement, order, scrolling, dragging, overlays, or directional keyboard behavior."diff --git a/apps/storybook/stories/EmptyState.stories.tsx b/apps/storybook/stories/EmptyState.stories.tsxindex 92f159962d..34abb7ca0f 100644--- a/apps/storybook/stories/EmptyState.stories.tsx+++ b/apps/storybook/stories/EmptyState.stories.tsx@@ -40,6 +40,15 @@ export const TitleOnly: Story = {},};+export const NonRenderingOptionalSlots: Story = {+ args: {+ title: 'Nothing here yet',+ description: '',+ icon: false,+ actions: '',+ },+};+export const WithIcon: Story = {args: {icon: <span style={{fontSize: '48px'}}>📭</span>,diff --git a/packages/core/src/EmptyState/EmptyState.doc.mjs b/packages/core/src/EmptyState/EmptyState.doc.mjsindex 1fcd7a7e9e..d0f75308e4 100644--- a/packages/core/src/EmptyState/EmptyState.doc.mjs+++ b/packages/core/src/EmptyState/EmptyState.doc.mjs@@ -12,7 +12,7 @@ export const docs = {name: 'title',type: 'string',description:- 'Primary message rendered as an <h3> heading inside the empty state.',+ 'Primary message rendered as the configured heading level inside the empty state.',required: true,},{@@ -81,6 +81,7 @@ export const docs = {{ guidance: false, description: 'Use an EmptyState for error messages that require immediate action; use a Banner instead.' },],anatomy: [+ {name: 'Container', required: true, description: 'The centered status region that owns spacing, reading order, and the compact layout variant.'},{name: 'Icon', required: false, description: 'A visual cue above the title that reinforces the context, like a search icon for no results.'},{name: 'Title', required: true, description: 'Primary message explaining what is empty: "No projects yet" not "No data".'},{name: 'Description', required: false, description: 'Additional context explaining why it is empty or what the user can do.'},@@ -98,7 +99,7 @@ export const docsZh = {name: 'title',type: 'string',description:- '在空状态内部渲染为 <h3> 标题的主要信息。',+ '在空状态内部按配置的标题级别渲染主要信息。',required: true,},{diff --git a/packages/core/src/EmptyState/EmptyState.spec.md b/packages/core/src/EmptyState/EmptyState.spec.mdnew file mode 100644index 0000000000..f03b9d4580--- /dev/null+++ b/packages/core/src/EmptyState/EmptyState.spec.md@@ -0,0 +1,189 @@+---+schema_version: 3+template_version: 7+kind: component+id: component:EmptyState+authority: draft+archive_reason: null+superseded_by: null+approved_by: null+approved_at: null+owners: [cixzhang]+review_triggers: [public-api, behavior, layout, theming, accessibility, testing]+verified_by:+ [+ packages/core/src/EmptyState/EmptyState.test.tsx,+ 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-020/FR1, spec:AST-029/FR3]+---++# 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 status region; 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 | Callers supply content and actions, select heading semantics, and may compose supported root props and styling. No additional setup is required. |+| Compatibility/readiness | The released default is preserved. This draft observes shipped behavior plus the narrow scalar-slot remediation; it adds no API, default, or compatibility promise. |+| 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+- Compatibility class: observational and additive documentation; runtime remediation removes wrappers for nullish, boolean, and empty-string optional values+- Controlled/uncontrolled behavior: not applicable+- Migration decision: none++Consumer migration instructions belong in consumer docs and release notes.++## Ownership boundary++**Owns**++- the status-region 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++Draft requirements identify their basis so observed code is not mistaken for an+intentional decision. A `current` contract contains no unresolved rows.++| ID | Candidate invariant | Basis | Draft review state |+| --- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ | ------------------ |+| FR1 | The component MUST render one status-region root containing the icon, text group, and actions in that reading order when present. | Current implementation and consumer docs; WCAG 2.2 SC 1.3.2 and SC 4.1.3 | verify |+| 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 | verify |+| 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 | verify |+| 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 | verify |+| FR5 | Root DOM/data/ARIA/event props, ref, `className`, `style`, and `xstyle` MUST reach and compose on the status-region root. | `architecture:public-component-api` INV5–INV8 | verify |+| 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 | verify |++### 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 | status 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; component-owned `role="status"` remains authoritative.++### Performance and resources++- **PR1 — Render-only surface.** EmptyState owns no retained state, listener,+ observer, timer, or external resource.++## 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 — Status exposure.** The root exposes the empty message as a status region+ without moving focus; 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–FR4, AR1–3 | focused DOM tests plus required exact-head accessibility evidence | title only, all slots, absent/shallow-empty slots | order, heading, status, or decorative treatment regresses | `audit:EmptyState/a11y` |+| FR5, ORD1 | focused root composition tests plus shared API guards | DOM/data/event/style inputs, ref, root target | accepted input is dropped or component semantics/styles are replaced | `audit:EmptyState/api` |+| FR6 | compact target/DOM tests plus required exact-head rendered evidence | default and compact, wide and narrow | compact state, spacing, or action direction no longer applies | `audit:EmptyState/layout` |+| PR1 | source review | every render path | a retained resource appears without a named owner | `audit:EmptyState/code` |++## Decision log++No component-local decision is approved in this draft.++## 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.diff --git a/packages/core/src/EmptyState/EmptyState.test.tsx b/packages/core/src/EmptyState/EmptyState.test.tsxindex 88933a6c24..e473394bc7 100644--- a/packages/core/src/EmptyState/EmptyState.test.tsx+++ b/packages/core/src/EmptyState/EmptyState.test.tsx@@ -1,7 +1,8 @@// Copyright (c) Meta Platforms, Inc. and affiliates.-import {describe, it, expect} from 'vitest';-import {render, screen} from '@testing-library/react';+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';@@ -11,6 +12,12 @@ function generateThemeTestCSS(theme: Parameters<typeof generateThemeCSS>[0]) {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" />);@@ -52,7 +59,7 @@ describe('EmptyState', () => {/>,);expect(screen.getByText('Try adjusting your search.')).toBeInTheDocument();- // Description renders as <div> (never <p>) so block content composes safely.+ // Description keeps its stable target element instead of paragraph semantics.expect(screen.getByText('Try adjusting your search.').tagName).toBe('DIV');});@@ -132,6 +139,70 @@ describe('EmptyState', () => {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 = screen.getByRole('status');+ 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 and keeps component semantics authoritative', () => {+ 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('status');+ 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+ />,+ );++ const root = screen.getByRole('status');+ 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(<EmptyStatediff --git a/packages/core/src/EmptyState/EmptyState.tsx b/packages/core/src/EmptyState/EmptyState.tsxindex 1fec136e78..7675cf5043 100644--- a/packages/core/src/EmptyState/EmptyState.tsx+++ b/packages/core/src/EmptyState/EmptyState.tsx@@ -23,7 +23,7 @@ import {typeScaleVars,} from '../theme/tokens.stylex';import type {BaseProps} from '../BaseProps';-import {mergeProps} from '../utils';+import {isRenderable, mergeProps} from '../utils';import {themeProps} from '../utils/themeProps';const styles = stylex.create({@@ -169,7 +169,7 @@ export function EmptyState({className,style,)}>- {icon != null && <div aria-hidden="true">{icon}</div>}+ {isRenderable(icon) && <div aria-hidden="true">{icon}</div>}<div {...stylex.props(styles.textGroup)}>{createElement(HeadingTag,@@ -181,11 +181,7 @@ export function EmptyState({),title,)}- {description != null && (- // Rendered as <div> (not <p>): description accepts ReactNode and a- // <p> cannot legally contain block children, which causes hydration- // mismatches. The StyleX style sets margin: 0, so appearance is- // unchanged.+ {isRenderable(description) && (<div{...mergeProps(themeProps('empty-state-description', {@@ -200,7 +196,7 @@ export function EmptyState({</div>)}</div>- {actions != null && (+ {isRenderable(actions) && (<div{...stylex.props(styles.actions, isCompact && styles.actionsCompact)}>{actions}