An open source design system that's fully customizable and agent ready
TypeScript
feat(lab): bring the TransferList primitive inside the audits (#5223)
Ernest95f5b3525b5c
diff --git a/apps/storybook/stories/TransferList.stories.tsx b/apps/storybook/stories/TransferList.stories.tsxindex 7e6f08e907..8386407e89 100644--- a/apps/storybook/stories/TransferList.stories.tsx+++ b/apps/storybook/stories/TransferList.stories.tsx@@ -2,18 +2,26 @@/*** @file TransferList.stories.tsx- * @input TransferListSelector option data, commit behavior, and advanced Core selector and table primitives- * @output Storybook examples for immediate/staged selectors plus advanced TransferList composition+ * @input TransferList option data plus advanced Core selector and table primitives+ * @output Storybook examples for the TransferList composition primitive* @position Lab Storybook documentation and visual validation*- * SYNC: When selector commit behavior or TransferList interaction changes, update source, docs, and tests.+ * Covers the primitive directly rather than through TransferListSelector. The+ * two surfaces are documented separately because a Storybook title maps to one+ * component, and the accessibility audit derives the component it audits from+ * that title — a primitive shown only inside the wrapper's stories is never+ * audited under its own name.+ *+ * SYNC: When TransferList interaction or panel copy changes, update source,+ * docs, and tests.*/import {useEffect, useRef, useState, type SVGProps} from 'react';import type {Meta, StoryObj} from '@storybook/react';import * as stylex from '@stylexjs/stylex';-import {TransferList, TransferListSelector} from '@astryxdesign/lab';-import type {TransferListOption, TransferListProps} from '@astryxdesign/lab';+import {TransferList} from '@astryxdesign/lab';+import type {TransferListOption} from '@astryxdesign/lab';+import {Theme} from '@astryxdesign/core';import {Button} from '@astryxdesign/core/Button';import {ComplexSelector} from '@astryxdesign/core/ComplexSelector';import {Divider} from '@astryxdesign/core/Divider';@@ -37,6 +45,8 @@ import {radiusVars,spacingVars,} from '@astryxdesign/core/theme/tokens.stylex';+import {neutralTheme} from '@astryxdesign/theme-neutral';+function PlusIcon(props: SVGProps<SVGSVGElement>) {return (<svg@@ -100,22 +110,34 @@ const styles = stylex.create({paddingBlock: spacingVars['--spacing-3'],paddingInline: spacingVars['--spacing-3'],},+ stack: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-6'],+ },+ themePane: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-3'],+ padding: spacingVars['--spacing-4'],+ borderRadius: radiusVars['--radius-element'],+ // Must be a token, not a literal: the pane's whole job is to render the+ // surface each nested Theme resolves to, so a hardcoded colour would sit+ // under text that follows the theme and fail contrast in one of the modes.+ backgroundColor: colorVars['--color-background-body'],+ },});-const meta: Meta<typeof TransferListSelector> = {- title: 'Lab/TransferListSelector',- component: TransferListSelector,+const meta: Meta<typeof TransferList> = {+ title: 'Lab/TransferList',+ component: TransferList,tags: ['autodocs'],parameters: {layout: 'centered',},decorators: [Story => (- <div- style={{- width: 'min(900px, calc(100vw - 64px))',- minHeight: 480,- }}>+ <div style={{width: 'min(760px, calc(100vw - 64px))'}}><Story /></div>),@@ -136,83 +158,44 @@ const BASIC_OPTIONS: ReadonlyArray<TransferListOption<string>> = [label: 'Owner',description: 'Person responsible for the record',},- {- value: 'status',- label: 'Status',- description: 'Current workflow state',- },- {- value: 'priority',- label: 'Priority',- description: 'Relative urgency',- },- {- value: 'team',- label: 'Team',- description: 'Owning team',- },+ {value: 'status', label: 'Status', description: 'Current workflow state'},+ {value: 'priority', label: 'Priority', description: 'Relative urgency'},+ {value: 'team', label: 'Team', description: 'Owning team'},{value: 'updated',label: 'Last updated',description: 'Most recent change time',},- {- value: 'created',- label: 'Created',- description: 'Original creation time',- },+ {value: 'created', label: 'Created', description: 'Original creation time'},];-const BASIC_DESCRIPTION =- 'Choose which fields appear. Changes take effect immediately, and drag reorder commits on release.';--const BASIC_TRANSFER_LIST_PROPS = {- label: 'Visible fields',- options: BASIC_OPTIONS,- selectedLabel: 'Visible fields',- availableLabel: 'Available fields',- hasSelectAll: true,- hasClear: true,-} satisfies Omit<TransferListProps<string>, 'value' | 'onChange'>;-function DefaultExample() {- const defaults = ['name', 'owner', 'status'];- const [value, setValue] = useState<readonly string[]>(defaults);+ const [value, setValue] = useState<readonly string[]>([+ 'name',+ 'owner',+ 'status',+ ]);return (- <TransferListSelector- {...BASIC_TRANSFER_LIST_PROPS}- description={BASIC_DESCRIPTION}+ <TransferList+ label="Visible fields"+ description="Move fields between the panels. The selected order is the display order."+ options={BASIC_OPTIONS}value={value}onChange={setValue}- triggerLabel={`${value.length} visible fields`}+ selectedLabel="Visible fields"+ availableLabel="Available fields"+ hasSelectAll+ hasClear/>);}+/** The primitive rendered inline, without the selector's popover. */export const Default: Story = {render: () => <DefaultExample />,};-function StagedChangesExample() {- const defaults = ['name', 'owner', 'status'];- const [value, setValue] = useState<readonly string[]>(defaults);- return (- <TransferListSelector- {...BASIC_TRANSFER_LIST_PROPS}- description="Review the complete field selection before applying it."- value={value}- onChange={setValue}- commitBehavior="staged"- triggerLabel={`${value.length} visible fields`}- />- );-}--export const StagedChanges: Story = {- render: () => <StagedChangesExample />,-};--const GROUPED_OPTIONS: ReadonlyArray<TransferListOption<string>> = [+const LOCKED_OPTIONS: ReadonlyArray<TransferListOption<string>> = [{value: 'name',label: 'Name',@@ -230,12 +213,7 @@ const GROUPED_OPTIONS: ReadonlyArray<TransferListOption<string>> = [isTransferDisabled: true,disabledMessage: 'Owner must remain visible but can be reordered.',},- {- value: 'team',- label: 'Team',- description: 'Owning team',- group: 'Identity',- },+ {value: 'team', label: 'Team', description: 'Owning team', group: 'Identity'},{value: 'status',label: 'Status',@@ -251,48 +229,43 @@ const GROUPED_OPTIONS: ReadonlyArray<TransferListOption<string>> = [description: 'Relative urgency',group: 'Planning',},- {- value: 'due',- label: 'Due date',- description: 'Planned completion date',- group: 'Planning',- },{value: 'updated',label: 'Last updated',description: 'Most recent change time',group: 'Activity',},- {- value: 'created',- label: 'Created',- description: 'Original creation time',- group: 'Activity',- },];-function GroupedAndLockedExample() {- const defaults = ['name', 'owner', 'status', 'updated'];- const [value, setValue] = useState<readonly string[]>(defaults);-+function LockedExample() {+ const [value, setValue] = useState<readonly string[]>([+ 'name',+ 'owner',+ 'status',+ 'updated',+ ]);return (- <TransferListSelector+ <TransferListlabel="Record fields"- description="Fields are grouped by purpose. Removal and reordering constraints can be applied independently."- options={GROUPED_OPTIONS}+ description="Transfer and reorder are constrained per option, so a field can be locked in place without being locked in the list."+ options={LOCKED_OPTIONS}value={value}onChange={setValue}selectedLabel="Shown"availableLabel="Hidden"hasSelectAllhasClear- triggerLabel={`${value.length} shown fields`}/>);}-export const GroupedAndLocked: Story = {- render: () => <GroupedAndLockedExample />,+/**+ * TransferList has no component-wide disabled state. Availability is decided+ * per option, and the two constraints are independent: `isTransferDisabled`+ * pins an option to its panel, `isReorderDisabled` pins it to its position.+ */+export const Locked: Story = {+ render: () => <LockedExample />,};function UnorderedExample() {@@ -301,11 +274,10 @@ function UnorderedExample() {'priority','team',]);-return (- <TransferListSelector+ <TransferListlabel="Included filters"- description="Use an unordered transfer list when selection matters but display order does not."+ description="With reordering off the selected panel loses its drag handles and keyboard reorder."options={BASIC_OPTIONS}value={value}onChange={setValue}@@ -314,44 +286,15 @@ function UnorderedExample() {isReorderable={false}hasSelectAllhasClear- triggerLabel={`${value.length} included filters`}/>);}+/** `isReorderable={false}` for selections where order carries no meaning. */export const Unordered: Story = {render: () => <UnorderedExample />,};-function NarrowContainerExample() {- const [value, setValue] = useState<readonly string[]>([- 'name',- 'owner',- 'status',- ]);- return (- <TransferListSelector- label="Mobile field settings"- description="The two panels stack when horizontal space is limited."- options={BASIC_OPTIONS}- value={value}- onChange={setValue}- triggerLabel={`${value.length} visible fields`}- width="min(360px, calc(100vw - 32px))"- placement="below"- selectedLabel="Visible"- availableLabel="Available"- isReorderable={false}- hasSelectAll- hasClear- />- );-}--export const NarrowContainer: Story = {- render: () => <NarrowContainerExample />,-};-const LARGE_POOL_OPTIONS: ReadonlyArray<TransferListOption<string>> =Array.from({length: 200}, (_, index) => {const number = index + 1;@@ -363,15 +306,14 @@ const LARGE_POOL_OPTIONS: ReadonlyArray<TransferListOption<string>> =};});-function LargePoolExample() {+function SearchableExample() {const [value, setValue] = useState<readonly string[]>(LARGE_POOL_OPTIONS.slice(0, 12).map(option => option.value),);-return (- <TransferListSelector+ <TransferListlabel="Report fields"- description="Search a pool of 200 options while preserving the chosen display order."+ description="One search field filters both panels across a pool of 200 grouped options."options={LARGE_POOL_OPTIONS}value={value}onChange={setValue}@@ -381,13 +323,99 @@ function LargePoolExample() {searchPlaceholder="Search 200 fields"hasSelectAllhasClear- triggerLabel={`${value.length} report fields`}/>);}-export const LargePool: Story = {- render: () => <LargePoolExample />,+/** `hasSearch` over a large grouped pool, exercising both panels at volume. */+export const Searchable: Story = {+ render: () => <SearchableExample />,+};++function EmptyExample() {+ const [value, setValue] = useState<readonly string[]>([]);+ return (+ <TransferList+ label="Visible fields"+ description="Nothing is selected yet, so the selected panel carries its own empty copy."+ options={BASIC_OPTIONS}+ value={value}+ onChange={setValue}+ selectedLabel="Visible fields"+ availableLabel="Available fields"+ selectedEmptyText="No fields are visible yet. Add one from the right."+ availableEmptyText="Every field is already visible."+ hasSelectAll+ hasClear+ />+ );+}++function NoResultsExample() {+ const [value, setValue] = useState<readonly string[]>(['name']);+ return (+ <TransferList+ label="Report fields"+ description="A query that matches nothing replaces both panels with the no-results copy."+ options={BASIC_OPTIONS}+ value={value}+ onChange={setValue}+ selectedLabel="In report"+ availableLabel="Available"+ hasSearch+ searchLabel="Search report fields"+ searchPlaceholder="Try a term that matches nothing"+ noResultsText="No field matches that search."+ />+ );+}++/**+ * The three empty surfaces are distinct: an empty selection, an exhausted+ * available pool, and a search that matches nothing each need their own copy.+ */+export const Empty: Story = {+ render: () => (+ <div {...stylex.props(styles.stack)}>+ <EmptyExample />+ <Divider />+ <NoResultsExample />+ </div>+ ),+};++/** The same list pinned to light and dark, including a nested override. */+export const ThemeMatrix: Story = {+ render: () => (+ <div {...stylex.props(styles.stack)}>+ <Theme theme={neutralTheme} mode="light">+ <div {...stylex.props(styles.themePane)}>+ <Text weight="bold">Light</Text>+ <DefaultExample />+ </div>+ </Theme>+ <Theme theme={neutralTheme} mode="dark">+ <div {...stylex.props(styles.themePane)}>+ <Text weight="bold">Dark</Text>+ <DefaultExample />+ <Theme theme={neutralTheme} mode="light">+ <div {...stylex.props(styles.themePane)}>+ <Text weight="bold">Light nested inside dark</Text>+ <LockedExample />+ </div>+ </Theme>+ </div>+ </Theme>+ </div>+ ),+ parameters: {+ docs: {+ description: {+ story:+ 'Pins both modes into one frame so a theme regression is visible without toggling the toolbar, and nests a light theme inside a dark one to confirm the panels read their colours from the nearest provider rather than the document root.',+ },+ },+ },};interface ProjectRow extends Record<string, unknown> {@@ -738,4 +766,11 @@ function TableColumnSettingsExample() {export const TableColumnSettings: Story = {name: 'Advanced: Table column settings',render: () => <TableColumnSettingsExample />,+ decorators: [+ Story => (+ <div style={{width: 'min(1100px, calc(100vw - 64px))', minHeight: 480}}>+ <Story />+ </div>+ ),+ ],};diff --git a/apps/storybook/stories/TransferListSelector.stories.tsx b/apps/storybook/stories/TransferListSelector.stories.tsxnew file mode 100644index 0000000000..568827d6a8--- /dev/null+++ b/apps/storybook/stories/TransferListSelector.stories.tsx@@ -0,0 +1,308 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.++/**+ * @file TransferListSelector.stories.tsx+ * @input TransferListSelector option data and commit behavior+ * @output Storybook examples for the popover-backed immediate and staged selectors+ * @position Lab Storybook documentation and visual validation+ *+ * Covers the selector wrapper only. The TransferList primitive it hosts has its+ * own story file: a Storybook title maps to exactly one component, and the+ * accessibility audit resolves the component it audits from that title, so a+ * primitive documented under the wrapper's title is invisible to the gate.+ *+ * SYNC: When selector commit behavior changes, update source, docs, and tests.+ */++import {useState} from 'react';+import type {Meta, StoryObj} from '@storybook/react';+import {TransferListSelector} from '@astryxdesign/lab';+import type {TransferListOption, TransferListProps} from '@astryxdesign/lab';++const meta: Meta<typeof TransferListSelector> = {+ title: 'Lab/TransferListSelector',+ component: TransferListSelector,+ tags: ['autodocs'],+ parameters: {+ layout: 'centered',+ },+ decorators: [+ Story => (+ <div+ style={{+ width: 'min(900px, calc(100vw - 64px))',+ minHeight: 480,+ }}>+ <Story />+ </div>+ ),+ ],+};++export default meta;+type Story = StoryObj<typeof meta>;++const BASIC_OPTIONS: ReadonlyArray<TransferListOption<string>> = [+ {+ value: 'name',+ label: 'Name',+ description: 'Primary display name for the record',+ },+ {+ value: 'owner',+ label: 'Owner',+ description: 'Person responsible for the record',+ },+ {+ value: 'status',+ label: 'Status',+ description: 'Current workflow state',+ },+ {+ value: 'priority',+ label: 'Priority',+ description: 'Relative urgency',+ },+ {+ value: 'team',+ label: 'Team',+ description: 'Owning team',+ },+ {+ value: 'updated',+ label: 'Last updated',+ description: 'Most recent change time',+ },+ {+ value: 'created',+ label: 'Created',+ description: 'Original creation time',+ },+];++const BASIC_DESCRIPTION =+ 'Choose which fields appear. Changes take effect immediately, and drag reorder commits on release.';++const BASIC_TRANSFER_LIST_PROPS = {+ label: 'Visible fields',+ options: BASIC_OPTIONS,+ selectedLabel: 'Visible fields',+ availableLabel: 'Available fields',+ hasSelectAll: true,+ hasClear: true,+} satisfies Omit<TransferListProps<string>, 'value' | 'onChange'>;++function DefaultExample() {+ const defaults = ['name', 'owner', 'status'];+ const [value, setValue] = useState<readonly string[]>(defaults);+ return (+ <TransferListSelector+ {...BASIC_TRANSFER_LIST_PROPS}+ description={BASIC_DESCRIPTION}+ value={value}+ onChange={setValue}+ triggerLabel={`${value.length} visible fields`}+ />+ );+}++export const Default: Story = {+ render: () => <DefaultExample />,+};++function StagedChangesExample() {+ const defaults = ['name', 'owner', 'status'];+ const [value, setValue] = useState<readonly string[]>(defaults);+ return (+ <TransferListSelector+ {...BASIC_TRANSFER_LIST_PROPS}+ description="Review the complete field selection before applying it."+ value={value}+ onChange={setValue}+ commitBehavior="staged"+ triggerLabel={`${value.length} visible fields`}+ />+ );+}++export const StagedChanges: Story = {+ render: () => <StagedChangesExample />,+};++const GROUPED_OPTIONS: ReadonlyArray<TransferListOption<string>> = [+ {+ value: 'name',+ label: 'Name',+ description: 'Required identity field',+ group: 'Identity',+ isTransferDisabled: true,+ isReorderDisabled: true,+ disabledMessage: 'Name is required and fixed in position.',+ },+ {+ value: 'owner',+ label: 'Owner',+ description: 'Person responsible for the work',+ group: 'Identity',+ isTransferDisabled: true,+ disabledMessage: 'Owner must remain visible but can be reordered.',+ },+ {+ value: 'team',+ label: 'Team',+ description: 'Owning team',+ group: 'Identity',+ },+ {+ value: 'status',+ label: 'Status',+ description: 'Current workflow state',+ group: 'Planning',+ isReorderDisabled: true,+ disabledMessage:+ 'Status can be hidden but its current position is fixed while selected.',+ },+ {+ value: 'priority',+ label: 'Priority',+ description: 'Relative urgency',+ group: 'Planning',+ },+ {+ value: 'due',+ label: 'Due date',+ description: 'Planned completion date',+ group: 'Planning',+ },+ {+ value: 'updated',+ label: 'Last updated',+ description: 'Most recent change time',+ group: 'Activity',+ },+ {+ value: 'created',+ label: 'Created',+ description: 'Original creation time',+ group: 'Activity',+ },+];++function GroupedAndLockedExample() {+ const defaults = ['name', 'owner', 'status', 'updated'];+ const [value, setValue] = useState<readonly string[]>(defaults);++ return (+ <TransferListSelector+ label="Record fields"+ description="Fields are grouped by purpose. Removal and reordering constraints can be applied independently."+ options={GROUPED_OPTIONS}+ value={value}+ onChange={setValue}+ selectedLabel="Shown"+ availableLabel="Hidden"+ hasSelectAll+ hasClear+ triggerLabel={`${value.length} shown fields`}+ />+ );+}++export const GroupedAndLocked: Story = {+ render: () => <GroupedAndLockedExample />,+};++function UnorderedExample() {+ const [value, setValue] = useState<readonly string[]>([+ 'status',+ 'priority',+ 'team',+ ]);++ return (+ <TransferListSelector+ label="Included filters"+ description="Use an unordered transfer list when selection matters but display order does not."+ options={BASIC_OPTIONS}+ value={value}+ onChange={setValue}+ selectedLabel="Included"+ availableLabel="Not included"+ isReorderable={false}+ hasSelectAll+ hasClear+ triggerLabel={`${value.length} included filters`}+ />+ );+}++export const Unordered: Story = {+ render: () => <UnorderedExample />,+};++function NarrowContainerExample() {+ const [value, setValue] = useState<readonly string[]>([+ 'name',+ 'owner',+ 'status',+ ]);+ return (+ <TransferListSelector+ label="Mobile field settings"+ description="The two panels stack when horizontal space is limited."+ options={BASIC_OPTIONS}+ value={value}+ onChange={setValue}+ triggerLabel={`${value.length} visible fields`}+ width="min(360px, calc(100vw - 32px))"+ placement="below"+ selectedLabel="Visible"+ availableLabel="Available"+ isReorderable={false}+ hasSelectAll+ hasClear+ />+ );+}++export const NarrowContainer: Story = {+ render: () => <NarrowContainerExample />,+};++const LARGE_POOL_OPTIONS: ReadonlyArray<TransferListOption<string>> =+ Array.from({length: 200}, (_, index) => {+ const number = index + 1;+ return {+ value: `field-${number}`,+ label: `Field ${String(number).padStart(3, '0')}`,+ description: `Configurable field ${number}`,+ group: `Group ${Math.floor(index / 40) + 1}`,+ };+ });++function LargePoolExample() {+ const [value, setValue] = useState<readonly string[]>(+ LARGE_POOL_OPTIONS.slice(0, 12).map(option => option.value),+ );++ return (+ <TransferListSelector+ label="Report fields"+ description="Search a pool of 200 options while preserving the chosen display order."+ options={LARGE_POOL_OPTIONS}+ value={value}+ onChange={setValue}+ selectedLabel="In report"+ availableLabel="Available"+ hasSearch+ searchPlaceholder="Search 200 fields"+ hasSelectAll+ hasClear+ triggerLabel={`${value.length} report fields`}+ />+ );+}++export const LargePool: Story = {+ render: () => <LargePoolExample />,+};diff --git a/internal/lab-readiness/audit.test.mjs b/internal/lab-readiness/audit.test.mjsindex 96d9c1326f..e38a214587 100644--- a/internal/lab-readiness/audit.test.mjs+++ b/internal/lab-readiness/audit.test.mjs@@ -132,6 +132,55 @@ describe('automated derivation', () => {expect(derived.stateCoverage.note).toMatch(/isDisabled.*no test/);});+ it('asks for an edge-case story only for states the props expose', () => {+ scaffold({+ 'packages/lab/src/Widget/Widget.tsx':+ "import {Text} from '@astryxdesign/core/Text';\n" ++ 'export interface WidgetProps { isDisabled?: boolean; isLoading?: boolean }\n' ++ 'export function Widget() { return <Text />; }\n',+ 'apps/storybook/stories/Widget.stories.tsx':+ "const meta = {title: 'Lab/Widget'};\n" ++ 'export const Default: Story = {};\n' ++ 'export const ThemeMatrix: Story = {};\n',+ });+ const derived = deriveChecks(root, candidate);+ expect(derived.edgeCases.state).not.toBe('passed');+ expect(derived.edgeCases.note).toMatch(/disabled/);+ expect(derived.edgeCases.note).toMatch(/loading/);+ // Nothing in the props implies an empty state, so it must not be demanded.+ expect(derived.edgeCases.note).not.toMatch(/empty/);+ });++ it('owes no edge-case story when the component exposes no such state', () => {+ // The rubric describes the API; it must never pressure someone into adding+ // an isLoading prop that nothing needs just to turn a check green.+ scaffold({+ 'apps/storybook/stories/Widget.stories.tsx':+ "const meta = {title: 'Lab/Widget'};\n" ++ 'export const Default: Story = {};\n' ++ 'export const Disabled: Story = {};\n' ++ 'export const ThemeMatrix: Story = {};\n',+ });+ const derived = deriveChecks(root, candidate);+ expect(derived.edgeCases.state).toBe('passed');+ expect(derived.edgeCases.note).toMatch(/none is owed a story/);+ });++ it('asks for an empty story when the component renders an EmptyState', () => {+ scaffold({+ 'packages/lab/src/Widget/Widget.tsx':+ "import {EmptyState} from '@astryxdesign/core/EmptyState';\n" ++ 'export function Widget() { return <EmptyState />; }\n',+ 'apps/storybook/stories/Widget.stories.tsx':+ "const meta = {title: 'Lab/Widget'};\n" ++ 'export const Default: Story = {};\n' ++ 'export const ThemeMatrix: Story = {};\n',+ });+ const derived = deriveChecks(root, candidate);+ expect(derived.edgeCases.state).not.toBe('passed');+ expect(derived.edgeCases.note).toMatch(/empty/);+ });+it('accepts a locally defined SVG glyph', () => {// Core defines glyphs this way in Avatar, Thumbnail, and Indicator, so a// raw <svg> is idiomatic rather than a finding.diff --git a/internal/lab-readiness/automated.mjs b/internal/lab-readiness/automated.mjsindex 33cf90ac34..20e40b939b 100644--- a/internal/lab-readiness/automated.mjs+++ b/internal/lab-readiness/automated.mjs@@ -503,17 +503,39 @@ export function deriveChecks(repoRoot, candidate) {}{+ // Which edge cases are worth a story depends on the component, not on a+ // fixed list. Demanding a "loading" story from a component with no loading+ // state invites someone to invent the prop to clear the check, which is+ // backwards: the rubric should describe the API, never drive it. So the+ // expectation is read off the prop surface.const names = storyExports(stories).join(' ');- const missing = ['empty', 'loading', 'disabled'].filter(+ const expected = [];+ if (/\bisDisabled\??:/.test(source)) {+ expected.push('disabled');+ }+ if (/\bisLoading\??:/.test(source)) {+ expected.push('loading');+ }+ // An empty state is a rendering decision rather than a prop, so look for+ // either the copy props that configure one or the primitive that draws it.+ if (/\bEmptyState\b/.test(source) || /\w*[eE]mptyText\??:/.test(source)) {+ expected.push('empty');+ }+ const missing = expected.filter(kind => !new RegExp(kind, 'i').test(names),);add('edgeCases',verdict(missing),- missing.length === 0- ? 'Empty, loading, and disabled cases each have a dedicated story.'- : `No dedicated story for: ${missing.join(', ')}.`,- [ev(`Story names: ${names || 'none'}.`, p.stories)],+ expected.length === 0+ ? 'No empty, loading, or disabled state is exposed, so none is owed a story.'+ : missing.length === 0+ ? `Each state this component exposes (${expected.join(', ')}) has a dedicated story.`+ : `No dedicated story for: ${missing.join(', ')}.`,+ [+ ev(`Story names: ${names || 'none'}.`, p.stories),+ ev(`Edge cases the prop surface implies: ${expected.join(', ') || 'none'}.`, p.source),+ ],);}diff --git a/packages/lab/src/TransferList/TransferList.doc.mjs b/packages/lab/src/TransferList/TransferList.doc.mjsindex 421da01e23..4ed9e35494 100644--- a/packages/lab/src/TransferList/TransferList.doc.mjs+++ b/packages/lab/src/TransferList/TransferList.doc.mjs@@ -482,6 +482,29 @@ export const docs = {},],},+ // Mirrors the themeProps() calls in TransferList.tsx. `astryx theme build`+ // reads this inventory to learn which visual props a target can vary on, so+ // a target missing here cannot be themed even though it carries the class.+ theming: {+ targets: [+ {+ className: 'astryx-transfer-list',+ visualProps: [],+ },+ {+ className: 'astryx-transfer-list-collection',+ visualProps: [],+ },+ {+ className: 'astryx-transfer-list-panel',+ visualProps: ['side'],+ },+ {+ className: 'astryx-transfer-list-item',+ visualProps: ['side', 'state'],+ },+ ],+ },examples: [{label: 'Default immediate selector',diff --git a/packages/lab/src/TransferList/TransferList.test.tsx b/packages/lab/src/TransferList/TransferList.test.tsxindex 1fef237a4c..0861df28fc 100644--- a/packages/lab/src/TransferList/TransferList.test.tsx+++ b/packages/lab/src/TransferList/TransferList.test.tsx@@ -496,7 +496,7 @@ describe('TransferList', () => {});describe('pointer reordering', () => {- it('mounts the drag preview in the nearest top-layer container', () => {+ it('promotes the drag preview to the top layer from inside a popover host', () => {const {container} = render(<div data-testid="popover-host" popover="auto"><ControlledTransferList initialValue={['name', 'owner', 'status']} />@@ -521,7 +521,13 @@ describe('TransferList', () => {const preview = document.querySelector<HTMLElement>('[data-transfer-list-drag-preview]',);- expect(preview?.parentElement).toBe(screen.getByTestId('popover-host'));+ // The ghost reaches the top layer through its host's popover attribute+ // rather than by being relocated into an ancestor. That keeps it painted+ // above this popover host while it still inherits the host's theme+ // variables, which a portal to document.body would have dropped.+ const layer = preview?.parentElement ?? null;+ expect(layer).toHaveAttribute('popover');+ expect(screen.getByTestId('popover-host')).toContainElement(layer);});it('keeps rows stationary, locks X, follows pointer Y, and commits once', () => {@@ -560,9 +566,10 @@ describe('TransferList', () => {expect(getComputedStyle(preview!).opacity).toBe('0.5');expect(preview).toHaveAttribute('aria-hidden', 'true');expect(preview).toHaveTextContent('Owner');- expect(preview!.style.getPropertyValue('--x-transform')).toBe(- 'translate3d(0px, 40px, 0)',- );+ // Placement lives on the layer as fixed insets. The coordinates come+ // from getBoundingClientRect, so reading them as viewport insets is what+ // keeps the ghost under the pointer once the page has been scrolled.+ expect(preview!.parentElement).toHaveStyle({top: '40px', left: '0px'});expect(container.querySelector('[data-transfer-list-drop-target]'),).not.toBeInTheDocument();@@ -573,9 +580,7 @@ describe('TransferList', () => {clientY: 5,});- expect(preview!.style.getPropertyValue('--x-transform')).toBe(- 'translate3d(0px, -5px, 0)',- );+ expect(preview!.parentElement).toHaveStyle({top: '-5px', left: '0px'});expect([...container.querySelectorAll<HTMLElement>('[data-transfer-list-row]'),]).toEqual(rows);@@ -596,9 +601,7 @@ describe('TransferList', () => {clientY: 115,});- expect(preview!.style.getPropertyValue('--x-transform')).toBe(- 'translate3d(0px, 105px, 0)',- );+ expect(preview!.parentElement).toHaveStyle({top: '105px', left: '0px'});expect(rows[0]).not.toHaveAttribute('data-transfer-list-drop-target');expect(rows[2]).toHaveAttribute('data-transfer-list-drop-target',@@ -655,11 +658,12 @@ describe('TransferList', () => {expect(document.querySelector('[data-transfer-list-drag-preview]'),).toBeInTheDocument();+ // A horizontal-only gesture must not move the ghost off the row it came+ // from: the drag is locked to the Y axis.expect(- document- .querySelector<HTMLElement>('[data-transfer-list-drag-preview]')- ?.style.getPropertyValue('--x-transform'),- ).toBe('translate3d(0px, 0px, 0)');+ document.querySelector<HTMLElement>('[data-transfer-list-drag-preview]')+ ?.parentElement,+ ).toHaveStyle({top: '0px', left: '0px'});expect(container.querySelector('[data-transfer-list-drop-target]'),).not.toBeInTheDocument();diff --git a/packages/lab/src/TransferList/TransferList.tsx b/packages/lab/src/TransferList/TransferList.tsxindex c07ba80f30..2a447e16a7 100644--- a/packages/lab/src/TransferList/TransferList.tsx+++ b/packages/lab/src/TransferList/TransferList.tsx@@ -17,6 +17,7 @@import {Fragment,useCallback,+ useEffect,useId,useLayoutEffect,useMemo,@@ -27,12 +28,13 @@ import {type ReactNode,} from 'react';import * as stylex from '@stylexjs/stylex';-import {createPortal, flushSync} from 'react-dom';+import {flushSync} from 'react-dom';import type {BaseProps} from '@astryxdesign/core';import {Button} from '@astryxdesign/core/Button';import {Icon} from '@astryxdesign/core/Icon';import {IconButton} from '@astryxdesign/core/IconButton';import {Item} from '@astryxdesign/core/Item';+import {useLayer} from '@astryxdesign/core/Layer';import {List} from '@astryxdesign/core/List';import {Text} from '@astryxdesign/core/Text';import {TextInput} from '@astryxdesign/core/TextInput';@@ -345,10 +347,10 @@ const styles = stylex.create({});const dynamicStyles = stylex.create({- dragPreview: (x: number, y: number, width: number) => ({- width,- transform: `translate3d(${x}px, ${y}px, 0)`,- }),+ // Only the width is dynamic here. The layer owns the placement: it reads the+ // same viewport coordinates as `position: fixed` insets, which is what+ // getBoundingClientRect gives us.+ dragPreview: (width: number) => ({width}),});function moveItem<T>(@@ -435,6 +437,11 @@ export function TransferList<T extends string = string>({const availablePanelRef = useRef<HTMLDivElement | null>(null);const selectedRowRefs = useRef(new Map<T, HTMLElement>());const dragPreviewRef = useRef<HTMLDivElement | null>(null);+ // The ghost that follows the pointer is a layer, not a portal into body.+ // Its coordinates come from getBoundingClientRect, so they are viewport+ // relative; the top layer is the only host that reads them that way from+ // any scroll position and still paints above a Popover or open dialog.+ const dragPreviewLayer = useLayer({mode: 'fixed'});const currentValueRef = useRef<readonly T[]>(value);const reorderSessionRef = useRef<ReorderSession<T> | null>(null);const suppressClickRef = useRef(false);@@ -1010,11 +1017,15 @@ export function TransferList<T extends string = string>({width: reorderSession.previewWidth,}: null;- const dragPreviewPortalTarget =- typeof document === 'undefined'- ? null- : (rootRef.current?.closest<HTMLElement>('[popover], dialog[open]') ??- document.body);+ const isDraggingPreview = dragPreviewPosition != null;+ const {show: showDragPreview, hide: hideDragPreview} = dragPreviewLayer;+ useEffect(() => {+ if (!isDraggingPreview) {+ return undefined;+ }+ showDragPreview();+ return hideDragPreview;+ }, [isDraggingPreview, showDragPreview, hideDragPreview]);const reorderControl = (option: TransferListOption<T>) => {if (!isReorderable) {@@ -1304,8 +1315,8 @@ export function TransferList<T extends string = string>({</div></div></div>- {dragPreviewPosition != null && dragPreviewPortalTarget != null- ? createPortal(+ {dragPreviewPosition != null+ ? dragPreviewLayer.render(<divref={dragPreviewRef}aria-hidden="true"@@ -1313,14 +1324,10 @@ export function TransferList<T extends string = string>({{...stylex.props(reorderStyles.preview,styles.dragPreviewContainer,- dynamicStyles.dragPreview(- dragPreviewPosition.x,- dragPreviewPosition.y,- dragPreviewPosition.width,- ),+ dynamicStyles.dragPreview(dragPreviewPosition.width),)}/>,- dragPreviewPortalTarget,+ {x: dragPreviewPosition.x, y: dragPreviewPosition.y},): null}</div>