Skip to content

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.mjs
index 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 and
diff --git a/apps/storybook/rtl-audit/rtl-audit-coverage.mjs b/apps/storybook/rtl-audit/rtl-audit-coverage.mjs
index 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.mjs
index 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 swaps
let anyDoubleFlip = false;
const perIcon = [];
+ let blockAxisOnly = 0; // unmirrored glyphs that point up or down in both directions
for (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.json
index 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",