Skip to content

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.tsx
index 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
+ <TransferList
label="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"
hasSelectAll
hasClear
- 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
+ <TransferList
label="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}
hasSelectAll
hasClear
- 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
+ <TransferList
label="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"
hasSelectAll
hasClear
- 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.tsx
new file mode 100644
index 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.mjs
index 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.mjs
index 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.mjs
index 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.tsx
index 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.tsx
index 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(
<div
ref={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>