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.mjsindex 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.mjsindex 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.mjsnew file mode 100644index 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.tsxindex 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.mdindex 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 chevronwithout 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. thediff --git a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs b/apps/storybook/rtl-audit/rtl-audit-coverage.mjsindex 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.mjsindex 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.tsnew file mode 100644index 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.tsxindex 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-basedlayer classification (only elements fully contained within a larger