An open source design system that's fully customizable and agent ready
TypeScript
fix(rtl-audit): D1 does not judge a chevron that points along the block axis (#9295)
Cindy Zhanga3503f826844
diff --git a/.github/scripts/rtl-audit-coverage.test.mjs b/.github/scripts/rtl-audit-coverage.test.mjsindex 9b477b5f90..243a51ecd2 100644--- a/.github/scripts/rtl-audit-coverage.test.mjs+++ b/.github/scripts/rtl-audit-coverage.test.mjs@@ -20,6 +20,10 @@ import {classifyLogicalInlinePair,collectDirectionalDecorations,filterStoryRoutesByPackages,+ glyphRendersOnBlockAxis,+ d1GlyphKey,+ d1PairKey,+ isUnchangedBlockAxisPair,finishFiniteAnimations,orderD1StoryCandidates,resolveD1Applicability,@@ -1016,6 +1020,106 @@ describe('finishFiniteAnimations', () => {});});+describe('glyphRendersOnBlockAxis', () => {+ // CSS matrix(a, b, c, d) order: rotate(90deg) is [0, 1, -1, 0].+ const identity = [1, 0, 0, 1];+ const mirror = [-1, 0, 0, 1];+ const quarterTurn = [0, 1, -1, 0];+ const mirroredQuarterTurn = [0, 1, 1, 0]; // scaleX(-1) . rotate(90deg)+ const negativeQuarterTurn = [0, -1, 1, 0]; // rotate(-90deg)++ it('keeps an unrotated chevron on the inline axis, mirrored or not', () => {+ expect(glyphRendersOnBlockAxis('right', identity)).toBe(false);+ expect(glyphRendersOnBlockAxis('right', mirror)).toBe(false);+ expect(glyphRendersOnBlockAxis('left', identity)).toBe(false);+ expect(glyphRendersOnBlockAxis('left', mirror)).toBe(false);+ });++ it('puts a chevron turned a quarter either way on the block axis', () => {+ expect(glyphRendersOnBlockAxis('right', quarterTurn)).toBe(true);+ expect(glyphRendersOnBlockAxis('right', mirroredQuarterTurn)).toBe(true);+ expect(glyphRendersOnBlockAxis('right', negativeQuarterTurn)).toBe(true);+ expect(glyphRendersOnBlockAxis('left', quarterTurn)).toBe(true);+ });++ it('keeps a half-turned chevron on the inline axis', () => {+ expect(glyphRendersOnBlockAxis('right', [-1, 0, 0, -1])).toBe(false);+ });++ it('ignores a glyph with no horizontal direction or no matrix', () => {+ expect(glyphRendersOnBlockAxis(null, quarterTurn)).toBe(false);+ expect(glyphRendersOnBlockAxis('right', undefined)).toBe(false);+ });+});++describe('isUnchangedBlockAxisPair', () => {+ const down = {dir: 'right', matrix: [0, 1, -1, 0]}; // rotate(90deg)+ const up = {dir: 'right', matrix: [0, -1, 1, 0]}; // rotate(-90deg)+ const mirroredDown = {dir: 'right', matrix: [0, 1, 1, 0]};+ const right = {dir: 'right', matrix: [1, 0, 0, 1]};++ it('leaves an expanded chevron that points down in both directions', () => {+ expect(isUnchangedBlockAxisPair(down, down)).toBe(true);+ expect(isUnchangedBlockAxisPair(down, mirroredDown)).toBe(true);+ });++ it('judges a chevron that points down in LTR and up in RTL', () => {+ expect(isUnchangedBlockAxisPair(down, up)).toBe(false);+ });++ it('judges a pair that is horizontal on either side or missing', () => {+ expect(isUnchangedBlockAxisPair(right, right)).toBe(false);+ expect(isUnchangedBlockAxisPair(down, right)).toBe(false);+ expect(isUnchangedBlockAxisPair(down, undefined)).toBe(false);+ });+});++describe('d1GlyphKey', () => {+ const path = 'm9 18 6-6-6-6';+ const expanded = [0, 1, -1, 0]; // rotate(90deg): points down+ const collapsed = [1, 0, 0, 1]; // points right, never mirrored++ it('keeps an expanded and a collapsed copy of one chevron apart', () => {+ expect(d1GlyphKey('right', path, expanded)).not.toBe(+ d1GlyphKey('right', path, collapsed),+ );+ });++ it('still merges repeated copies on the same axis', () => {+ expect(d1GlyphKey('right', path, collapsed)).toBe(+ d1GlyphKey('right', path, [1, 0, 0, 1]),+ );+ });++ it('leaves the collapsed copy judged when it never mirrors', () => {+ // The expanded copy is unjudged; the collapsed copy, kept separately,+ // is still a pair D1 judges (and fails, since RTL equals LTR).+ const down = {dir: 'right', matrix: expanded};+ const right = {dir: 'right', matrix: collapsed};+ expect(isUnchangedBlockAxisPair(down, down)).toBe(true);+ expect(isUnchangedBlockAxisPair(right, right)).toBe(false);+ });+});++describe('d1PairKey', () => {+ const collapsed = {dir: 'right', aria: 'Toggle Docs', matrix: [1, 0, 0, 1]};+ const expanded = {dir: 'right', aria: 'Toggle Docs', matrix: [0, 1, -1, 0]};++ it('pairs a collapsed and an expanded chevron under one label apart', () => {+ expect(d1PairKey(collapsed, 0)).not.toBe(d1PairKey(expanded, 1));+ });++ it('pairs the same labelled glyph across directions', () => {+ const mirrored = {...collapsed, matrix: [-1, 0, 0, 1]};+ expect(d1PairKey(collapsed, 0)).toBe(d1PairKey(mirrored, 3));+ });++ it('falls back to position for an unlabelled glyph', () => {+ const bare = {dir: 'right', aria: '', matrix: [1, 0, 0, 1]};+ expect(d1PairKey(bare, 2)).toBe('idx:2::inline');+ });+});+describe('resolveFilterRoutes (filters resolve through the Storybook index)', () => {// Core/Resizable's stories route to `core/resizable`, which no public// component is called; ResizeHandle, the folder's export, has no title anddiff --git a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs b/apps/storybook/rtl-audit/rtl-audit-coverage.mjsindex 5493dba3ef..2bdb937076 100644--- a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs+++ b/apps/storybook/rtl-audit/rtl-audit-coverage.mjs@@ -588,6 +588,74 @@ export function finishFiniteAnimations(doc) {return finished;}+/**+ * Does a left- or right-pointing glyph render pointing up or down? `matrix` is+ * the glyph's composed 2x2 transform (CSS `matrix(a, b, c, d)` order). A+ * chevron rotated a quarter turn (a disclosure's expanded state) points along+ * the block axis, which is direction-neutral (`design:bidirectionality` DR5),+ * so its mirroring is not a D1 question even though its path reads as+ * horizontal (`architecture:rtl-audit-evidence` INV12: applicability follows+ * the glyph's semantic role, not its source shape).+ */+export function glyphRendersOnBlockAxis(dir, matrix) {+ if ((dir !== 'left' && dir !== 'right') || !Array.isArray(matrix)) {+ return false;+ }+ const sign = dir === 'right' ? 1 : -1;+ // The tip's direction is the matrix applied to (±1, 0): its first column.+ const dx = sign * matrix[0];+ const dy = sign * matrix[1];+ return Math.abs(dy) > Math.abs(dx);+}++/**+ * The key D1's detector dedupes glyphs by: direction, path, and the axis the+ * glyph renders on. A repeated glyph (many tree rows) is reported once, but an+ * expanded copy (pointing down) and a collapsed copy (pointing sideways) of+ * the same chevron stay separate, so an unjudged expanded copy cannot hide a+ * collapsed one that fails to mirror. Runs in the page: keep it+ * self-contained apart from glyphRendersOnBlockAxis.+ */+export function d1GlyphKey(dir, pathSig, matrix) {+ const axis = glyphRendersOnBlockAxis(dir, matrix) ? 'block' : 'inline';+ return dir + '::' + pathSig + '::' + axis;+}++/**+ * The key D1 pairs an LTR glyph with its RTL counterpart by: the enclosing+ * control's accessible label when it has one, else the glyph's position, plus+ * the axis it renders on. A collapsed and an expanded chevron under one label+ * (a tree toggle) are then judged as separate pairs, so an unjudged expanded+ * copy cannot stand in for a collapsed copy that never mirrors.+ */+export function d1PairKey(glyph, index) {+ const axis = glyphRendersOnBlockAxis(glyph.dir, glyph.matrix)+ ? 'block'+ : 'inline';+ const label = glyph.aria && glyph.aria.trim();+ return (label ? 'aria:' + label : 'idx:' + index) + '::' + axis;+}++/**+ * Is this LTR/RTL pair one D1 leaves unjudged: a horizontal glyph that renders+ * pointing the SAME way along the block axis in both directions (an expanded+ * disclosure, down in both)? A glyph that points down in LTR and up in RTL+ * changed direction, which DR5 forbids, so it stays judged.+ */+export function isUnchangedBlockAxisPair(ltr, rtl) {+ if (+ !ltr ||+ !rtl ||+ !glyphRendersOnBlockAxis(ltr.dir, ltr.matrix) ||+ !glyphRendersOnBlockAxis(rtl.dir, rtl.matrix)+ ) {+ return false;+ }+ // The vertical component of each tip: positive is down in CSS.+ const tipY = glyph => (glyph.dir === 'right' ? 1 : -1) * glyph.matrix[1];+ return Math.sign(tipY(ltr)) === Math.sign(tipY(rtl));+}+/** Classify one stable LTR/RTL contextual-decoration pair. */export function classifyDirectionalDecorationPair(ltr, rtl) {if (!ltr || !rtl) {diff --git a/apps/storybook/rtl-audit/rtl-audit.mjs b/apps/storybook/rtl-audit/rtl-audit.mjsindex a380de414f..93f7f2fd70 100644--- a/apps/storybook/rtl-audit/rtl-audit.mjs+++ b/apps/storybook/rtl-audit/rtl-audit.mjs@@ -68,6 +68,10 @@ import {filterStoryRoutesByPackages,resolveFilterRoutes,finishFiniteAnimations,+ d1GlyphKey,+ d1PairKey,+ glyphRendersOnBlockAxis,+ isUnchangedBlockAxisPair,orderD1StoryCandidates,resolveD1Applicability,validateStoryRtlAuditParameters,@@ -375,6 +379,8 @@ async function iconPath(page, sel) {// Ambiguous glyphs are treated as NON-DIRECTIONAL (err toward not flagging).const DETECTOR = /* js */ `(() => {+ const glyphRendersOnBlockAxis = ${glyphRendersOnBlockAxis.toString()};+ const d1GlyphKey = ${d1GlyphKey.toString()};// Known directional path signatures (whitespace-normalized, lowercased).const LEFT_PATHS = new Set(['m15 6l-6 6 6 6', // core defaultIcons chevronLeft@@ -469,14 +475,15 @@ const DETECTOR = /* js */ `// icon has a real box and IS scanned.const box = svg.getBoundingClientRect();if (box.width < 1 || box.height < 1) continue;- // dedupe by (direction + path signature) so a repeated glyph (e.g. many- // tree rows) is reported once- const key = dir + '::' + dcat;+ // dedupe by (direction + path signature + rendered axis) so a repeated+ // glyph (e.g. many tree rows) is reported once, while an expanded copy and+ // a collapsed copy of one chevron are both kept+ const matrix = composedMatrixFor(svg);+ const key = d1GlyphKey(dir, dcat, matrix);if (seenPaths.has(key)) continue;seenPaths.add(key);const btn = svg.closest('button,[role=button],a');const aria = btn ? (btn.getAttribute('aria-label') || '') : '';- const matrix = composedMatrixFor(svg);const flip =Math.abs(matrix[0] + 1) < 0.01 && Math.abs(matrix[1]) < 0.01 &&Math.abs(matrix[2]) < 0.01 && Math.abs(matrix[3] - 1) < 0.01;@@ -749,7 +756,7 @@ async function autoD1(// Pair LTR<->RTL directional icons by aria-context (fallback: positional// index) and evaluate EACH pair, so a two-button name-swap (prev/next) is// seen per-button rather than washed out by a global multiset.- const keyOf = (i, idx) => (i.aria && i.aria.trim() ? 'aria:' + i.aria.trim() : 'idx:' + idx);+ const keyOf = d1PairKey;const ltrBy = new Map();ltr.forEach((i, idx) => ltrBy.set(keyOf(i, idx), i));const rtlBy = new Map();@@ -760,6 +767,7 @@ async function autoD1(let anyUnhandled = false; // at least one directional icon neither flips nor swapslet anyDoubleFlip = false;const perIcon = [];+ let blockAxisOnly = 0; // unmirrored glyphs that point up or down in both directionsfor (const k of keys) {const L = ltrBy.get(k), R = rtlBy.get(k);// transform-mirror: the glyph's COMPOSED transform under RTL equals its LTR@@ -780,6 +788,17 @@ async function autoD1(const doubleFlip =L && R && L.flip && R.flip &&L.matrix.every((v, i) => Math.abs(v - R.matrix[i]) < 0.01);+ // A horizontal glyph turned a quarter turn (an expanded disclosure) points+ // up or down. Pointing the same way along the block axis in BOTH+ // directions, it carries no inline meaning (DR5): leaving it unmirrored is+ // correct, so it is not judged. One that flips between down and up is+ // still judged; a mirrored one renders the same and counts as handled.+ const blockAxis = !mirrored && !swapped && isUnchangedBlockAxisPair(L, R);+ if (blockAxis) {+ blockAxisOnly++;+ perIcon.push({icon: k, ltrDir: L.dir, rtlDir: R.dir, ltrMatrix: L.matrix, rtlMatrix: R.matrix, blockAxis: true});+ continue;+ }if (mirrored || swapped) anyMirrored = true;else if (doubleFlip) { anyDoubleFlip = true; anyUnhandled = true; }else anyUnhandled = true;@@ -789,7 +808,10 @@ async function autoD1(// A component is RTL-ready for D1 iff EVERY directional icon is handled// (flips or swaps) and none double-flips. Any unhandled directional icon =>// not-RTL (the "shipped without RTL handling" signal).- if (!anyUnhandled && anyMirrored) {+ if (!anyUnhandled && !anyMirrored && blockAxisOnly > 0) {+ card.verdict = 'N-A';+ card.notes.push('every directional glyph points along the block axis in both directions (rotated a quarter turn)');+ } else if (!anyUnhandled && anyMirrored) {card.verdict = 'pass';card.notes.push('every directional icon mirrors (transform-flip and/or name-swap)');} else if (anyDoubleFlip) {@@ -797,7 +819,7 @@ async function autoD1(card.notes.push('double-flip: a directional icon is flipped in BOTH LTR and RTL (nets to no mirror)');} else {card.verdict = 'fail';- const bad = perIcon.filter(p => !p.mirrored && !p.swapped).map(p => p.icon);+ const bad = perIcon.filter(p => !p.blockAxis && !p.mirrored && !p.swapped).map(p => p.icon);card.notes.push(`directional glyph never mirrors: ${bad.join(', ')}`);}card.perIcon = perIcon;diff --git a/apps/storybook/rtl-audit/targets.json b/apps/storybook/rtl-audit/targets.jsonindex dfaa53799d..3f089ec4e2 100644--- a/apps/storybook/rtl-audit/targets.json+++ b/apps/storybook/rtl-audit/targets.json@@ -615,6 +615,15 @@"next": ".astryx-command-palette-footer > span:last-child"}},+ {+ "component": "DiffViewer",+ "storyId": "lab-diffviewer--character-highlight",+ "dims": ["D2"],+ "selectors": {+ "prev": ".astryx-diff-viewer-path",+ "next": ".astryx-diff-viewer-header span:text-is(\"+10\")"+ }+ },{"component": "DrawerHeader","storyId": "core-drawerheader--audit",