Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(rtl): make fixture applicability order-independent (#7489)

nynexman44649e0591af2072
diff --git a/.github/scripts/rtl-audit-coverage.test.mjs b/.github/scripts/rtl-audit-coverage.test.mjs
index 1692ca43a0..66544f5937 100644
--- a/.github/scripts/rtl-audit-coverage.test.mjs
+++ b/.github/scripts/rtl-audit-coverage.test.mjs
@@ -13,14 +13,19 @@ import {
AUDITED_STORY_PREFIXES,
buildAuditedComponentRoster,
buildComponentCoverage,
+ buildD1Target,
buildStoryComponentRoutes,
classifyDirectionalDecorationPair,
classifyLogicalGroupedCorners,
classifyLogicalInlinePair,
collectDirectionalDecorations,
filterStoryRoutesByPackages,
+ orderD1StoryCandidates,
+ resolveD1Applicability,
storyIdsForComponentFilters,
unresolvedComponentFilters,
+ validateStoryRtlAuditParameters,
+ withD1CompletionIdentity,
} from '../../apps/storybook/rtl-audit/rtl-audit-coverage.mjs';
const {
@@ -116,6 +121,168 @@ describe('classifyDirectionalDecorationPair', () => {
});
});
+describe('D1 story applicability', () => {
+ const defaultStory = {
+ id: 'lab-svgicon--default',
+ importPath: './stories/SVGIcon.stories.tsx',
+ sourceOrder: 10,
+ };
+ const registryFixture = {
+ id: 'lab-svgicon--default-registry-icons',
+ importPath: './stories/SVGIconRegistry.stories.tsx',
+ sourceOrder: 10,
+ };
+
+ it.each([
+ [registryFixture, defaultStory],
+ [defaultStory, registryFixture],
+ ])(
+ 'selects the same representative when Storybook order changes',
+ (...stories) => {
+ expect(orderD1StoryCandidates(stories).map(story => story.id)).toEqual([
+ defaultStory.id,
+ registryFixture.id,
+ ]);
+ },
+ );
+
+ it('preserves source export order for stories in one file', () => {
+ const later = {
+ id: 'core-example--later',
+ importPath: './stories/Example.stories.tsx',
+ sourceOrder: 200,
+ };
+ const earlier = {...later, id: 'core-example--earlier', sourceOrder: 100};
+ expect(orderD1StoryCandidates([later, earlier])).toEqual([earlier, later]);
+ });
+
+ it('discloses exclusions ordered after the selected representative', () => {
+ const rationale =
+ 'Reference glyphs preserve caller-supplied geometry as data.';
+ const resolved = resolveD1Applicability(
+ 'lab/SVGIcon',
+ [registryFixture, defaultStory],
+ new Map([
+ [defaultStory.id, {}],
+ [registryFixture.id, {D1: {applicable: false, reason: rationale}}],
+ ]),
+ );
+
+ expect(resolved.selectedCandidate).toEqual(defaultStory);
+ expect(resolved.declaredExclusions).toEqual([
+ {
+ component: 'lab/SVGIcon',
+ storyId: registryFixture.id,
+ dimension: 'D1',
+ reason: rationale,
+ },
+ ]);
+ });
+
+ it('fails closed when one candidate has no resolved metadata', () => {
+ expect(() =>
+ resolveD1Applicability(
+ 'lab/SVGIcon',
+ [defaultStory, registryFixture],
+ new Map([[defaultStory.id, {}]]),
+ ),
+ ).toThrow(
+ `${registryFixture.id} resolved rtlAudit metadata was not collected`,
+ );
+ });
+
+ it('keeps completion identity stable when metadata selects another candidate', () => {
+ const excludedFirst = {
+ ...registryFixture,
+ importPath: './stories/ASVGIconRegistry.stories.tsx',
+ };
+ const target = buildD1Target('lab/SVGIcon', [defaultStory, excludedFirst]);
+ const completed = withD1CompletionIdentity(
+ {
+ component: 'lab/SVGIcon',
+ storyId: defaultStory.id,
+ verdict: 'N-A',
+ skippedStories: [
+ {storyId: excludedFirst.id, reason: 'Reference fixture.'},
+ ],
+ },
+ target.id,
+ );
+
+ expect(target).toMatchObject({
+ comp: 'lab/SVGIcon',
+ id: excludedFirst.id,
+ });
+ expect(completed).toMatchObject({
+ component: 'lab/SVGIcon',
+ storyId: excludedFirst.id,
+ selectedStoryId: defaultStory.id,
+ });
+ expect(`${target.comp}::${target.id}`).toBe(
+ `${completed.component}::${completed.storyId}`,
+ );
+ });
+
+ it('keeps all-excluded completion identity non-null and deterministic', () => {
+ const target = buildD1Target('lab/SVGIcon', [
+ registryFixture,
+ defaultStory,
+ ]);
+ const completed = withD1CompletionIdentity(
+ {
+ component: 'lab/SVGIcon',
+ storyId: null,
+ verdict: 'N-A',
+ skippedStories: [
+ {storyId: defaultStory.id, reason: 'First fixture.'},
+ {storyId: registryFixture.id, reason: 'Second fixture.'},
+ ],
+ },
+ target.id,
+ );
+
+ expect(completed.storyId).toBe(defaultStory.id);
+ expect(completed).not.toHaveProperty('selectedStoryId');
+ expect(`${target.comp}::${target.id}`).toBe(
+ `${completed.component}::${completed.storyId}`,
+ );
+ });
+
+ it('requires a reason for a story-level D1 exclusion', () => {
+ expect(
+ validateStoryRtlAuditParameters(
+ {
+ D1: {
+ applicable: false,
+ reason: ' Reference glyphs preserve caller-supplied geometry. ',
+ },
+ },
+ registryFixture.id,
+ ),
+ ).toEqual({
+ D1: {
+ applicable: false,
+ reason: 'Reference glyphs preserve caller-supplied geometry.',
+ },
+ });
+ expect(() =>
+ validateStoryRtlAuditParameters(
+ {D1: {applicable: false, reason: ' '}},
+ registryFixture.id,
+ ),
+ ).toThrow('needs a non-empty reason');
+ });
+
+ it('rejects mistyped dimensions instead of silently ignoring them', () => {
+ expect(() =>
+ validateStoryRtlAuditParameters(
+ {D7: {applicable: false, reason: 'Typo.'}},
+ registryFixture.id,
+ ),
+ ).toThrow('unknown dimension D7');
+ });
+});
+
function logicalMeasurement(overrides = {}) {
return {
count: 1,
diff --git a/.github/scripts/rtl-scorecard-summary.mjs b/.github/scripts/rtl-scorecard-summary.mjs
index 8940c741a1..797b6cda35 100644
--- a/.github/scripts/rtl-scorecard-summary.mjs
+++ b/.github/scripts/rtl-scorecard-summary.mjs
@@ -3,8 +3,10 @@
/**
* @file Markdown scorecard for one package's RTL audit report.
- * @input --report <rtl-audit-report.json> --scope <audited components label>
- * @output The job-summary section, on stdout.
+ * @input --report <rtl-audit-report.json> --scope <audited components label>,
+ * including any declared D1 exclusions.
+ * @output The job-summary section on stdout, with review-facing exclusion
+ * disclosure.
* @position Shared by the pr-rtl package legs and the sharded-package merge
* job, so a joined report reads exactly like a single run's.
*/
@@ -18,6 +20,11 @@ const arg = name => {
};
const reportPath = arg('report') ?? 'rtl-audit-report.json';
const scope = arg('scope') ?? '';
+const markdownCell = value =>
+ String(value ?? '')
+ .replaceAll('|', '\\|')
+ .replace(/\s+/g, ' ')
+ .trim();
const lines = [
'## RTL semantic audit',
@@ -63,6 +70,21 @@ if (!fs.existsSync(reportPath)) {
.map(x => x.component);
out.push(`RTL-ready (D1 pass): ${passes.join(', ') || '—'}.`);
out.push('');
+ const declaredD1Exclusions = r.declaredD1Exclusions ?? [];
+ out.push('### Declared D1 exclusions (human review required)');
+ out.push('');
+ if (declaredD1Exclusions.length > 0) {
+ out.push('| Component | Story | Dimension | Rationale |');
+ out.push('|-----------|-------|-----------|-----------|');
+ for (const exclusion of declaredD1Exclusions) {
+ out.push(
+ `| ${markdownCell(exclusion.component)} | ${markdownCell(exclusion.storyId)} | ${markdownCell(exclusion.dimension)} | ${markdownCell(exclusion.reason)} |`,
+ );
+ }
+ } else {
+ out.push('_No declared D1 exclusions in this audit scope._');
+ }
+ out.push('');
const pm = r.positionalMirror;
if (pm) {
out.push('### Positional-mirror (D5, all scoped stories)');
diff --git a/.github/scripts/rtl-scorecard-summary.test.mjs b/.github/scripts/rtl-scorecard-summary.test.mjs
new file mode 100644
index 0000000000..c2c0a2233a
--- /dev/null
+++ b/.github/scripts/rtl-scorecard-summary.test.mjs
@@ -0,0 +1,90 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Review-facing RTL scorecard disclosure tests.
+ * @input Audit reports with declared D1 exclusions.
+ * @output Markdown that names every exclusion and its rationale.
+ * @position INV16 regression coverage for rtl-scorecard-summary.mjs.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {spawnSync} from 'node:child_process';
+import {afterEach, describe, expect, it} from 'vitest';
+
+const SCRIPT = path.resolve('.github/scripts/rtl-scorecard-summary.mjs');
+const dirs = [];
+
+afterEach(() => {
+ for (const dir of dirs.splice(0)) {
+ fs.rmSync(dir, {recursive: true, force: true});
+ }
+});
+
+function runSummary(report) {
+ const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'rtl-scorecard-summary-'));
+ dirs.push(dir);
+ const reportPath = path.join(dir, 'report.json');
+ fs.writeFileSync(reportPath, JSON.stringify(report));
+ return spawnSync(
+ process.execPath,
+ [SCRIPT, '--report', reportPath, '--scope', 'lab/SVGIcon'],
+ {encoding: 'utf8'},
+ );
+}
+
+function reportWith(exclusions) {
+ return {
+ declaredD1Exclusions: exclusions,
+ autoDiscovery: {
+ total: 1,
+ pass: 0,
+ fail: 0,
+ na: 1,
+ surprises: [],
+ results: [
+ {
+ component: 'lab/SVGIcon',
+ storyId: 'lab-svgicon--default',
+ verdict: 'N-A',
+ },
+ ],
+ },
+ curated: {results: []},
+ };
+}
+
+describe('RTL scorecard D1 exclusion disclosure', () => {
+ it('lists every declared exclusion, including a non-representative story', () => {
+ const result = runSummary(
+ reportWith([
+ {
+ component: 'lab/SVGIcon',
+ storyId: 'lab-svgicon--default-registry-icons',
+ dimension: 'D1',
+ reason:
+ 'The samples are caller-supplied data, not directional controls.',
+ },
+ {
+ component: 'lab/SVGIcon',
+ storyId: 'lab-svgicon--inherited-reference',
+ dimension: 'D1',
+ reason: 'Inherited fixture | rationale.\nReviewed as data.',
+ },
+ ]),
+ );
+
+ expect(result.status).toBe(0);
+ expect(result.stdout).toContain(
+ '### Declared D1 exclusions (human review required)',
+ );
+ expect(result.stdout).toContain(
+ '| lab/SVGIcon | lab-svgicon--default-registry-icons | D1 | The samples are caller-supplied data, not directional controls. |',
+ );
+ expect(result.stdout).toContain(
+ '| lab/SVGIcon | lab-svgicon--inherited-reference | D1 | Inherited fixture \\| rationale. Reviewed as data. |',
+ );
+ expect(result.stdout).toContain('RTL-ready (D1 pass): —.');
+ });
+});
diff --git a/apps/storybook/.storybook/preview.tsx b/apps/storybook/.storybook/preview.tsx
index 4561ef54e8..7ea55825c0 100644
--- a/apps/storybook/.storybook/preview.tsx
+++ b/apps/storybook/.storybook/preview.tsx
@@ -2,6 +2,7 @@
import type {Preview, Decorator} from '@storybook/react';
import * as React from 'react';
+import type {RtlAuditParameters} from '../rtl-audit/story-parameters';
import {
Theme,
LayerProvider,
@@ -101,6 +102,22 @@ const withTheme: Decorator = (Story, context) => {
);
};
+const withRtlAuditMetadata: Decorator = (Story, context) => {
+ const rtlAudit = context.parameters.rtlAudit as
+ RtlAuditParameters | undefined;
+ React.useEffect(() => {
+ const root = document.getElementById('storybook-root');
+ if (root == null) {
+ return;
+ }
+ root.dataset.astryxRtlAudit = JSON.stringify(rtlAudit ?? {});
+ return () => {
+ delete root.dataset.astryxRtlAudit;
+ };
+ }, [rtlAudit]);
+ return <Story />;
+};
+
const preview: Preview = {
parameters: {
controls: {
@@ -164,7 +181,7 @@ const preview: Preview = {
colorMode: 'light',
direction: 'ltr',
},
- decorators: [withTheme],
+ decorators: [withTheme, withRtlAuditMetadata],
};
export default preview;
diff --git a/apps/storybook/rtl-audit/README.md b/apps/storybook/rtl-audit/README.md
index 342cd7d039..a71043ed46 100644
--- a/apps/storybook/rtl-audit/README.md
+++ b/apps/storybook/rtl-audit/README.md
@@ -74,6 +74,33 @@ Directional-icon mirroring. For each audited story it:
This is the broad safety net: a component that lands a directional chevron
without RTL support shows up as a not-RTL finding automatically.
+D1 selects one representative per component by stable story source-file and
+export order, rather than depending on generated `index.json` object order. A
+reference fixture that intentionally preserves caller-supplied directional
+glyph geometry may opt out of D1 only, with a colocated rationale:
+
+```ts
+import {rtlAuditParameters} from '../rtl-audit/story-parameters';
+
+export const ReferenceFixture: StoryObj = {
+ parameters: rtlAuditParameters({
+ D1: {
+ applicable: false,
+ reason: 'The samples are caller-supplied data, not directional controls.',
+ },
+ }),
+};
+```
+
+The audit validates the rendered, resolved Storybook parameters for every
+in-scope story before choosing the D1 representative. Story-level parameters
+therefore override meta-level defaults through normal Storybook precedence.
+`applicable: false` without a nonempty reason is an error, and D5 and D6
+continue scanning the same story. The JSON report and Markdown scorecard list
+every declared D1 exclusion with its component, story ID, dimension, and
+rationale—even when an earlier applicable story is selected—so a human reviewer
+can confirm the fixture is data rather than a directional control or cue.
+
#### Interaction-revealed icons (popovers, dialogs, menus)
Many directional icons live inside content that is closed by default — e.g. the
diff --git a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs b/apps/storybook/rtl-audit/rtl-audit-coverage.mjs
index 29ae0a350f..a9f5935590 100644
--- a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs
+++ b/apps/storybook/rtl-audit/rtl-audit-coverage.mjs
@@ -2,11 +2,13 @@
/**
* @file Shared RTL coverage and directional-decoration helpers.
- * @input Rendered DOM decorations, canonical package rosters, Storybook routes,
- * curated targets, and D1/D5/D6/curated audit results.
- * @output Audited package/story routing, contextual decoration candidates,
- * component-filter reconciliation, and per-component measured / verified-N-A /
- * coverage-gap classifications.
+ * @input Rendered DOM decorations, canonical package rosters, Storybook routes
+ * and source/export metadata, typed story-level applicability, curated targets,
+ * and D1/D5/D6/curated audit results.
+ * @output Audited package/story routing, stable D1 targets, applicability and
+ * exclusion disclosure, contextual decoration candidates, component-filter
+ * reconciliation, and per-component measured / verified-N-A / coverage-gap
+ * classifications.
* @position Pure support layer for rtl-audit.mjs and its unit tests.
*/
@@ -19,15 +21,14 @@ export const AUDITED_STORY_PREFIXES = Object.freeze([
...new Set(COMPONENT_PACKAGES.flatMap(pkg => pkg.storyPrefixes)),
]);
-function packageForStoryId(
- storyId,
- packageNames = AUDITED_PACKAGE_NAMES,
-) {
- return COMPONENT_PACKAGES.find(
- pkg =>
- packageNames.includes(pkg.name) &&
- pkg.storyPrefixes.some(prefix => storyId.startsWith(prefix)),
- )?.name ?? null;
+function packageForStoryId(storyId, packageNames = AUDITED_PACKAGE_NAMES) {
+ return (
+ COMPONENT_PACKAGES.find(
+ pkg =>
+ packageNames.includes(pkg.name) &&
+ pkg.storyPrefixes.some(prefix => storyId.startsWith(prefix)),
+ )?.name ?? null
+ );
}
function pascalCase(value) {
@@ -63,16 +64,19 @@ function componentsFromStoryTitle(
(publicComponentsByPackage[packageName] ?? [])
.filter(component => candidates.has(component))
.map(component => `${packageName}/${component}`);
- const namespacePackages = COMPONENT_PACKAGES
- .filter(pkg => pkg.storyNamespaces.includes(namespace))
+ const namespacePackages = COMPONENT_PACKAGES.filter(pkg =>
+ pkg.storyNamespaces.includes(namespace),
+ )
.map(pkg => pkg.name)
.filter(packageName => packageName in publicComponentsByPackage);
- const eligiblePackages = namespacePackages.length > 0
- ? namespacePackages
- : Object.keys(publicComponentsByPackage);
- const preferred = preferredPackage && eligiblePackages.includes(preferredPackage)
- ? matchesIn(preferredPackage)
- : [];
+ const eligiblePackages =
+ namespacePackages.length > 0
+ ? namespacePackages
+ : Object.keys(publicComponentsByPackage);
+ const preferred =
+ preferredPackage && eligiblePackages.includes(preferredPackage)
+ ? matchesIn(preferredPackage)
+ : [];
if (preferred.length > 0) return preferred;
return eligiblePackages
.filter(packageName => packageName !== preferredPackage)
@@ -95,8 +99,8 @@ export function componentFromStoryId(
const exact = publicComponents.find(
component => component.toLowerCase() === normalized,
);
- const fallback = exact ??
- (publicComponents.includes('Chart') ? 'Chart' : segment);
+ const fallback =
+ exact ?? (publicComponents.includes('Chart') ? 'Chart' : segment);
return `${packageName}/${fallback}`;
}
@@ -118,9 +122,7 @@ export function componentFromTarget(
return declared;
}
const packageName = packageForStoryId(target.storyId, packageNames);
- return packageName
- ? `${packageName}/${declared}`
- : `unknown/${declared}`;
+ return packageName ? `${packageName}/${declared}` : `unknown/${declared}`;
}
/**
@@ -151,21 +153,18 @@ export function buildStoryComponentRoutes({
return normalizedStories.flatMap(story => {
const packageName = packageForStoryId(story.id, packageNames);
const explicitComponents = aliases.get(story.id) ?? [];
- const titleComponents = explicitComponents.length === 0
- ? componentsFromStoryTitle(
- story.title,
- packageName,
- publicComponentsByPackage,
- )
- : [];
+ const titleComponents =
+ explicitComponents.length === 0
+ ? componentsFromStoryTitle(
+ story.title,
+ packageName,
+ publicComponentsByPackage,
+ )
+ : [];
const components = [...explicitComponents, ...titleComponents];
if (components.length === 0) {
components.push(
- componentFromStoryId(
- story.id,
- packageNames,
- publicComponentsByPackage,
- ),
+ componentFromStoryId(story.id, packageNames, publicComponentsByPackage),
);
}
return Array.from(
@@ -217,6 +216,125 @@ export function storyIdsForComponentFilters(routes, filters) {
];
}
+/**
+ * Keep D1 representative selection stable when Storybook changes index order.
+ * Story source-file and export order preserve the repository's existing choice;
+ * the story id is the deterministic fallback.
+ */
+export function orderD1StoryCandidates(candidates) {
+ return [...candidates].sort(
+ (left, right) =>
+ (left.importPath ?? '').localeCompare(right.importPath ?? '') ||
+ (left.sourceOrder ?? Number.MAX_SAFE_INTEGER) -
+ (right.sourceOrder ?? Number.MAX_SAFE_INTEGER) ||
+ left.id.localeCompare(right.id),
+ );
+}
+
+/** Build one stable D1 scan target from a component's ordered candidates. */
+export function buildD1Target(comp, candidates) {
+ const orderedCandidates = orderD1StoryCandidates(candidates);
+ if (orderedCandidates.length === 0) {
+ throw new Error(`${comp} has no D1 story candidates`);
+ }
+ return {
+ comp,
+ id: orderedCandidates[0].id,
+ candidates: orderedCandidates,
+ };
+}
+
+/**
+ * Select the first applicable D1 story while disclosing every explicit
+ * exclusion, including exclusions ordered after the selected representative.
+ */
+export function resolveD1Applicability(
+ component,
+ candidates,
+ parametersByStoryId,
+) {
+ let selectedCandidate = null;
+ const declaredExclusions = [];
+ for (const candidate of orderD1StoryCandidates(candidates)) {
+ if (!parametersByStoryId.has(candidate.id)) {
+ throw new Error(
+ `${candidate.id} resolved rtlAudit metadata was not collected`,
+ );
+ }
+ const parameters = parametersByStoryId.get(candidate.id);
+ if (parameters.D1?.applicable === false) {
+ declaredExclusions.push({
+ component,
+ storyId: candidate.id,
+ dimension: 'D1',
+ reason: parameters.D1.reason,
+ });
+ } else if (selectedCandidate == null) {
+ selectedCandidate = candidate;
+ }
+ }
+ return {selectedCandidate, declaredExclusions};
+}
+
+/**
+ * Preserve the planned D1 identity even when metadata selects another story or
+ * excludes every candidate. Keep the rendered story separately for evidence.
+ */
+export function withD1CompletionIdentity(result, plannedStoryId) {
+ const selectedStoryId = result.storyId;
+ return {
+ ...result,
+ storyId: plannedStoryId,
+ ...(selectedStoryId && selectedStoryId !== plannedStoryId
+ ? {selectedStoryId}
+ : {}),
+ };
+}
+
+const STORY_RTL_AUDIT_DIMENSIONS = new Set(['D1']);
+
+/** Validate resolved Storybook RTL-audit applicability metadata. */
+export function validateStoryRtlAuditParameters(value, storyId) {
+ if (value == null) return {};
+ if (typeof value !== 'object' || Array.isArray(value)) {
+ throw new Error(`${storyId} rtlAudit metadata must be an object`);
+ }
+
+ const result = {};
+ for (const [dimension, applicability] of Object.entries(value)) {
+ if (!STORY_RTL_AUDIT_DIMENSIONS.has(dimension)) {
+ throw new Error(`${storyId} rtlAudit has unknown dimension ${dimension}`);
+ }
+ if (
+ applicability == null ||
+ typeof applicability !== 'object' ||
+ Array.isArray(applicability) ||
+ typeof applicability.applicable !== 'boolean'
+ ) {
+ throw new Error(
+ `${storyId} rtlAudit.${dimension} must declare applicable as a boolean`,
+ );
+ }
+ const reason = applicability.reason;
+ if (reason != null && typeof reason !== 'string') {
+ throw new Error(
+ `${storyId} rtlAudit.${dimension}.reason must be a string`,
+ );
+ }
+ const trimmedReason = reason?.trim();
+ if (applicability.applicable === false && !trimmedReason) {
+ throw new Error(
+ `${storyId} rtlAudit.${dimension} applicable=false needs a non-empty reason`,
+ );
+ }
+ result[dimension] = {
+ applicable: applicability.applicable,
+ ...(trimmedReason ? {reason: trimmedReason} : {}),
+ };
+ }
+ return result;
+}
+
/** Selected owners for which the canonical Storybook route has no story. */
export function unresolvedComponentFilters(routes, filters) {
return filters.filter(
@@ -608,8 +726,8 @@ export function classifyLogicalGroupedCorners(
Number.isFinite(box.height) &&
box.width > 0 &&
box.height > 0 &&
- ['topLeft', 'topRight', 'bottomRight', 'bottomLeft'].every(
- corner => Number.isFinite(box.corners?.[corner]),
+ ['topLeft', 'topRight', 'bottomRight', 'bottomLeft'].every(corner =>
+ Number.isFinite(box.corners?.[corner]),
),
),
) ||
@@ -630,8 +748,7 @@ export function classifyLogicalGroupedCorners(
: 'right';
const oppositeSide = physicalSide === 'left' ? 'right' : 'left';
const sideTop = physicalSide === 'left' ? 'topLeft' : 'topRight';
- const sideBottom =
- physicalSide === 'left' ? 'bottomLeft' : 'bottomRight';
+ const sideBottom = physicalSide === 'left' ? 'bottomLeft' : 'bottomRight';
const oppositeTop = oppositeSide === 'left' ? 'topLeft' : 'topRight';
const oppositeBottom =
oppositeSide === 'left' ? 'bottomLeft' : 'bottomRight';
diff --git a/apps/storybook/rtl-audit/rtl-audit.mjs b/apps/storybook/rtl-audit/rtl-audit.mjs
index 0e90a3a06a..40c1fbaa4a 100644
--- a/apps/storybook/rtl-audit/rtl-audit.mjs
+++ b/apps/storybook/rtl-audit/rtl-audit.mjs
@@ -24,16 +24,17 @@
* the geometry/behavior dims that genuinely need hand-written selectors.
* (C) APPLICABILITY: every component is measured, explicitly verified N/A,
* or reported as a coverage gap. An all-N/A result is never called clean.
- * @input --storybook-dir <path> --output <file> [--targets <path>]
+ * @input Resolved Storybook `rtlAudit` parameters plus --storybook-dir <path>
+ * --output <file> [--targets <path>]
* [--verified-not-applicable <path>] [--filter <csv>] [--packages <csv>]
* [--auto-only] [--curated-only]
* [--shard <i>/<n> --shard-output <file>] audit every n-th planned item and
* write only those cards; [--merge-shards <dir>] build the report from a
* complete shard set without a browser (rtl-audit-shards.mjs).
- * @output JSON scorecard: D1/D5/D6 auto verdicts, curated D2/D3/D4/D7/D8/D9
- * results, exact planned/completed scan counts, a component coverage
- * rollup, and the worker pages replaced after a failed story
- * (`pageRecoveries`). Mirrors the pr-a11y accessibility-audit harness.
+ * @output JSON scorecard: D1/D5/D6 auto verdicts, declared D1 exclusions,
+ * curated D2/D3/D4/D7/D8/D9 results, exact planned/completed scan counts, a
+ * component coverage rollup, and the worker pages replaced after a failed
+ * story (`pageRecoveries`). Mirrors the pr-a11y accessibility-audit harness.
* @position internal test harness; run by the soft-gated `pr-rtl` CI job and
* locally via `pnpm -F @astryxdesign/storybook rtl-audit`.
*
@@ -57,6 +58,7 @@ import {
AUDITED_STORY_PREFIXES,
buildAuditedComponentRoster,
buildComponentCoverage,
+ buildD1Target,
buildStoryComponentRoutes,
classifyLogicalGroupedCorners,
classifyLogicalInlinePair,
@@ -64,6 +66,10 @@ import {
componentFromTarget,
evaluateDirectionalDecorations,
filterStoryRoutesByPackages,
+ orderD1StoryCandidates,
+ resolveD1Applicability,
+ validateStoryRtlAuditParameters,
+ withD1CompletionIdentity,
} from './rtl-audit-coverage.mjs';
import {
createCuratedPages,
@@ -211,6 +217,26 @@ async function settle(page) {
await page.waitForTimeout(200);
}
+async function readStoryRtlAuditParameters(page, storyId) {
+ const marker = page.locator('[data-astryx-rtl-audit]').first();
+ await marker
+ .waitFor({state: 'attached', timeout: 5000})
+ .catch(() => {
+ throw new Error(`${storyId} rtlAudit metadata was not rendered`);
+ });
+ const raw = await marker.getAttribute('data-astryx-rtl-audit');
+ if (raw == null) {
+ throw new Error(`${storyId} rtlAudit metadata was not rendered`);
+ }
+ let parsed;
+ try {
+ parsed = JSON.parse(raw);
+ } catch {
+ throw new Error(`${storyId} rtlAudit metadata is not valid JSON`);
+ }
+ return validateStoryRtlAuditParameters(parsed, storyId);
+}
+
async function doSetup(page, t) {
if (t?.setup?.args) {
await page
@@ -680,12 +706,24 @@ async function autoPositionalAndDecorations(page, port, storyId, component) {
}
// Auto-discovery D1 for one story: compare LTR vs RTL directional-icon flip.
-async function autoD1(page, port, storyId, component) {
+async function autoD1(
+ page,
+ port,
+ storyId,
+ component,
+ {ltrMeasurement: premeasuredLtr = null} = {},
+) {
const card = {component, storyId, dim: 'D1', verdict: 'N-A', notes: [], icons: 0};
- await page.goto(storyUrl(port, storyId, false), {waitUntil: 'domcontentloaded'});
- await settle(page);
- const revealedL = await revealInteractionGated(page);
- const ltr = await detectDirectionalIcons(page);
+ let ltrMeasurement = premeasuredLtr;
+ if (ltrMeasurement == null) {
+ await page.goto(storyUrl(port, storyId, false), {waitUntil: 'domcontentloaded'});
+ await settle(page);
+ ltrMeasurement = {
+ revealed: await revealInteractionGated(page),
+ icons: await detectDirectionalIcons(page),
+ };
+ }
+ const {revealed: revealedL, icons: ltr} = ltrMeasurement;
await page.goto(storyUrl(port, storyId, true), {waitUntil: 'domcontentloaded'});
await settle(page);
const revealedR = await revealInteractionGated(page);
@@ -759,6 +797,71 @@ async function autoD1(page, port, storyId, component) {
return card;
}
+async function autoD1ForComponent(page, port, candidates, component) {
+ const orderedCandidates = orderD1StoryCandidates(candidates);
+ const parametersByStoryId = new Map();
+ let selectedLtr = null;
+ for (const candidate of orderedCandidates) {
+ await page.goto(storyUrl(port, candidate.id, false), {
+ waitUntil: 'domcontentloaded',
+ });
+ await settle(page);
+ const parameters = await readStoryRtlAuditParameters(page, candidate.id);
+ parametersByStoryId.set(candidate.id, parameters);
+ if (
+ selectedLtr == null &&
+ parameters.D1?.applicable !== false
+ ) {
+ selectedLtr = {
+ storyId: candidate.id,
+ revealed: await revealInteractionGated(page),
+ icons: await detectDirectionalIcons(page),
+ };
+ }
+ }
+
+ const {selectedCandidate, declaredExclusions} = resolveD1Applicability(
+ component,
+ orderedCandidates,
+ parametersByStoryId,
+ );
+ const skippedStories = declaredExclusions.map(({storyId, reason}) => ({
+ storyId,
+ reason,
+ }));
+ if (selectedCandidate != null) {
+ if (selectedLtr?.storyId !== selectedCandidate.id) {
+ throw new Error(
+ `${component} D1 selected story did not retain its LTR measurement`,
+ );
+ }
+ const card = await autoD1(page, port, selectedCandidate.id, component, {
+ ltrMeasurement: {
+ revealed: selectedLtr.revealed,
+ icons: selectedLtr.icons,
+ },
+ });
+ card.skippedStories = skippedStories;
+ card.declaredD1Exclusions = declaredExclusions;
+ if (skippedStories.length > 0) {
+ card.notes.unshift(
+ `skipped ${skippedStories.length} fixture(s) explicitly not applicable to D1`,
+ );
+ }
+ return card;
+ }
+ return {
+ component,
+ storyId: null,
+ dim: 'D1',
+ verdict: 'N-A',
+ notes: ['every candidate story is explicitly not applicable to D1'],
+ icons: 0,
+ skippedStories,
+ declaredD1Exclusions: declaredExclusions,
+ };
+}
+
// ===========================================================================
// CURATED precision dims (D2/D3/D4/D7/D8/D9) — hand selectors from targets.json
// ===========================================================================
@@ -1045,6 +1148,38 @@ async function scoreCurated(pages, port, t) {
}
// ---------------------------------------------------------------------------
+const STORY_SOURCE_ROOT = path.resolve(PROJECT_ROOT, 'apps/storybook');
+const storySourceCache = new Map();
+
+function storySourceOrder(entry) {
+ const importPath = entry?.importPath ?? '';
+ const exportName = entry?.exportName ?? '';
+ const sourcePath = path.resolve(
+ STORY_SOURCE_ROOT,
+ importPath.replace(/^\.\//, ''),
+ );
+ if (
+ !sourcePath.startsWith(`${STORY_SOURCE_ROOT}${path.sep}`) ||
+ !exportName
+ ) {
+ return Number.MAX_SAFE_INTEGER;
+ }
+ let source = storySourceCache.get(sourcePath);
+ if (source == null) {
+ try {
+ source = fs.readFileSync(sourcePath, 'utf8');
+ } catch {
+ source = '';
+ }
+ storySourceCache.set(sourcePath, source);
+ }
+ const escaped = exportName.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+ return (
+ new RegExp(`export\\s+(?:const|function)\\s+${escaped}\\b`).exec(source)
+ ?.index ?? Number.MAX_SAFE_INTEGER
+ );
+}
+
function matchesFilter(component) {
const normalized = component.toLowerCase();
const name = normalized.split('/').at(-1) ?? normalized;
@@ -1135,17 +1270,24 @@ async function cleanupRuntime() {
filters: FILTER,
});
- // The audit's plan: D1 runs one representative story per component (extra
- // stories add little D1 signal); D5 (positional-mirror) and D6 run over
- // EVERY story — a positioned bug can be story-specific (only a `withStatus`
- // variant mounts the offending element), so they do not collapse to one per
- // component; curated targets add the behaviour and geometry dims.
+ // The audit's plan: D1 uses one deterministic representative story per
+ // component. Repository story-file/export order preserves the existing
+ // representative while remaining independent of index.json object order.
+ // Fixtures may opt out with typed rtlAudit metadata. D5 (positional-mirror)
+ // and D6 still run over EVERY story because those bugs can be story-specific;
+ // curated targets add the behaviour and geometry dims.
const perComponent = new Map();
for (const {component, id} of scopedStoryRoutes) {
- if (!perComponent.has(component)) perComponent.set(component, id);
+ if (!perComponent.has(component)) perComponent.set(component, []);
+ perComponent.get(component).push({
+ id,
+ importPath: entries[id]?.importPath ?? '',
+ sourceOrder: storySourceOrder(entries[id]),
+ });
}
- const d1Targets = [...perComponent]
- .map(([component, id]) => ({comp: component, id}));
+ const d1Targets = [...perComponent].map(([component, candidates]) =>
+ buildD1Target(component, candidates),
+ );
const storyTargets = scopedStoryRoutes.map(({id, component}) => ({id, comp: component}));
const curatedTargets = [];
for (const t of targets) {
@@ -1228,12 +1370,17 @@ async function cleanupRuntime() {
if (!CURATED_ONLY) {
const d1Positions = mine(d1Targets);
const d1Cards = await mapPool(d1Positions.map(position => d1Targets[position]), pool, {
- scan: async ({comp, id}, workerPage) => {
- const card = await autoD1(workerPage, port, id, comp);
+ scan: async ({comp, id, candidates}, workerPage) => {
+ const card = await autoD1ForComponent(
+ workerPage,
+ port,
+ candidates,
+ comp,
+ );
if (card.verdict !== 'N-A') {
console.error(`AUTO ${card.verdict.toUpperCase().padEnd(4)} ${comp.padEnd(24)} icons=${card.icons}`);
}
- return card;
+ return withD1CompletionIdentity(card, id);
},
onError: ({comp, id}, e) => {
console.error(`AUTO ERROR ${comp}: ${String(e).slice(0, 120)}`);
@@ -1343,6 +1490,14 @@ async function cleanupRuntime() {
const surprises = autoFails;
const pmFails = pmResults.filter(r => r.verdict === 'fail' || r.verdict === 'ERROR');
const decorationFails = decorationResults.filter(r => r.verdict === 'fail' || r.verdict === 'ERROR');
+ const declaredD1Exclusions = autoResults
+ .flatMap(result => result.declaredD1Exclusions ?? [])
+ .sort(
+ (left, right) =>
+ left.component.localeCompare(right.component) ||
+ left.storyId.localeCompare(right.storyId) ||
+ left.dimension.localeCompare(right.dimension),
+ );
const report = {
generatedAt: new Date().toISOString(),
scope: {
@@ -1379,6 +1534,7 @@ async function cleanupRuntime() {
// keeps its ERROR result; the record shows the stories after it ran on a
// fresh page.
pageRecoveries,
+ declaredD1Exclusions,
autoDiscovery: {
total: autoResults.length,
applicable: autoResults.filter(r => r.verdict !== 'N-A').length,
diff --git a/apps/storybook/rtl-audit/story-parameters.ts b/apps/storybook/rtl-audit/story-parameters.ts
new file mode 100644
index 0000000000..ebf42b3c7a
--- /dev/null
+++ b/apps/storybook/rtl-audit/story-parameters.ts
@@ -0,0 +1,24 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Typed Storybook parameters for per-dimension RTL audit applicability.
+ * @input A story's dimension-specific applicability and rationale.
+ * @output Storybook's `{rtlAudit: ...}` parameter shape.
+ * @position Authoring boundary between story fixtures and the external RTL audit.
+ */
+
+/** Whether an RTL audit dimension applies to a Storybook story. */
+export type RtlAuditApplicability =
+ {applicable: true; reason?: string} | {applicable: false; reason: string};
+
+/** Storybook parameters consumed by the rendered RTL audit. */
+export type RtlAuditParameters = {
+ D1?: RtlAuditApplicability;
+};
+
+/** Type-check RTL audit parameters while preserving Storybook's parameter shape. */
+export function rtlAuditParameters(rtlAudit: RtlAuditParameters): {
+ rtlAudit: RtlAuditParameters;
+} {
+ return {rtlAudit};
+}
diff --git a/apps/storybook/stories/SVGIconRegistry.stories.tsx b/apps/storybook/stories/SVGIconRegistry.stories.tsx
index 715d46fdea..666f0d6b2c 100644
--- a/apps/storybook/stories/SVGIconRegistry.stories.tsx
+++ b/apps/storybook/stories/SVGIconRegistry.stories.tsx
@@ -17,6 +17,7 @@ import {
} from '@astryxdesign/lab';
import {Stack, Text} from '@astryxdesign/core';
import {defaultIcons} from '../../../packages/core/src/Icon/defaultIcons';
+import {rtlAuditParameters} from '../rtl-audit/story-parameters';
// =============================================================================
// Bounding box utilities
@@ -226,7 +227,8 @@ function jsxSvgToIconDef(
// =============================================================================
const meta: Meta = {
- title: 'Lab/SVGIconRegistry',
+ title: 'Lab/SVGIcon',
+ component: SVGIcon,
};
export default meta;
@@ -239,6 +241,13 @@ const VARIATIONS: SVGIconVariation[] = [
];
export const DefaultRegistryIcons: StoryObj = {
+ parameters: rtlAuditParameters({
+ D1: {
+ applicable: false,
+ reason:
+ 'This reference fixture preserves caller-supplied left and right glyph geometry; the samples are data, not directional controls.',
+ },
+ }),
render: () => {
const converted: Array<{name: string; def: SVGIconDef}> = [];
for (const [name, jsx] of Object.entries(defaultIcons)) {
@@ -250,9 +259,7 @@ export const DefaultRegistryIcons: StoryObj = {
return (
<Stack direction="vertical" gap={3}>
- <Text type="large">
- Default Registry Icons \u2192 SVGIcon System
- </Text>
+ <Text type="large">Default Registry Icons \u2192 SVGIcon System</Text>
<Text type="supporting">
{converted.length} icons auto-converted. Heuristic: containment-based
layer classification (only elements fully contained within a larger