An open source design system that's fully customizable and agent ready
TypeScript
[Component Audit] Heading: outline levels and styling precedence are pinned, and every prop is documented (#9328)
Cindy Zhangd1e5cc4bbd9a
diff --git a/.changeset/heading-audit-docs.md b/.changeset/heading-audit-docs.mdnew file mode 100644index 0000000000..a865ea249a--- /dev/null+++ b/.changeset/heading-audit-docs.md@@ -0,0 +1,7 @@+---+'@astryxdesign/core': patch+---++[docs] Heading: document the `xstyle`, `className`, `style`, and `ref` props, including that a `maxLines` above 1 replaces any `WebkitLineClamp` passed in `style`.++@cixzhangdiff --git a/apps/storybook/stories/Heading.stories.tsx b/apps/storybook/stories/Heading.stories.tsxindex 6b8903bb2d..17b09a4e14 100644--- a/apps/storybook/stories/Heading.stories.tsx+++ b/apps/storybook/stories/Heading.stories.tsx@@ -1,8 +1,22 @@// Copyright (c) Meta Platforms, Inc. and affiliates.import type {Meta, StoryObj} from '@storybook/react';+import * as stylex from '@stylexjs/stylex';import {Heading} from '@astryxdesign/core/Heading';import {Text} from '@astryxdesign/core/Text';+import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';++const auditStyles = stylex.create({+ column: {+ display: 'flex',+ flexDirection: 'column',+ gap: spacingVars['--spacing-4'],+ boxSizing: 'border-box',+ inlineSize: '100%',+ maxInlineSize: 360,+ minInlineSize: 0,+ },+});const meta: Meta<typeof Heading> = {title: 'Core/Heading',@@ -356,3 +370,71 @@ export const CardGrid: Story = {</div>),};++// =============================================================================+// Audit matrix+// =============================================================================++/**+ * Bounded browser fixture for the Heading contract: outline levels, display+ * types and weight, color, logical alignment, both truncation modes, and a+ * long unbroken token, in one 360px column.+ */+export const AuditMatrix: Story = {+ parameters: {layout: 'padded'},+ render: () => (+ <div {...stylex.props(auditStyles.column)}>+ <Heading data-audit-case="level-2" level={2}>+ Level two section+ </Heading>+ <Heading data-audit-case="outline-equal" level={3} accessibilityLevel={3}>+ Matching outline level+ </Heading>+ <Heading+ data-audit-case="outline-override"+ level={2}+ accessibilityLevel={4}>+ Drawn as two, outlined as four+ </Heading>+ <Heading data-audit-case="display-1" level={2} type="display-1">+ Display one+ </Heading>+ <Heading data-audit-case="display-2" level={2} type="display-2">+ Display two+ </Heading>+ <Heading data-audit-case="display-3" level={2} type="display-3">+ Display three+ </Heading>+ <Heading+ data-audit-case="display-weight"+ level={2}+ type="display-2"+ weight="bold">+ Display two, bold+ </Heading>+ <Heading data-audit-case="secondary" level={3} color="secondary">+ Secondary heading+ </Heading>+ <Heading data-audit-case="justify-center" level={4} justify="center">+ Centered heading+ </Heading>+ <Heading data-audit-case="justify-end" level={4} justify="end">+ End-aligned heading+ </Heading>+ <Heading data-audit-case="truncate-1" level={3} maxLines={1}>+ A single-line heading that is far too long for this column+ </Heading>+ <Heading+ data-audit-case="truncate-2"+ level={3}+ maxLines={2}+ hasTruncateTooltip="below">+ A two-line heading that keeps going well past its second line so the+ clamp has something to cut+ </Heading>+ <Heading data-audit-case="long-token" level={3}>+ Report_2026_quarterly_revenue_by_region_and_product_line_final+ </Heading>+ </div>+ ),+};diff --git a/packages/core/src/Heading/Heading.test.tsx b/packages/core/src/Heading/Heading.test.tsxindex 78c8769c02..7989fdc784 100644--- a/packages/core/src/Heading/Heading.test.tsx+++ b/packages/core/src/Heading/Heading.test.tsx@@ -5,10 +5,18 @@* Tests for Heading component*/-import {render, screen} from '@testing-library/react';+import * as stylex from '@stylexjs/stylex';+import {typeScaleVars} from '../theme/tokens.stylex';+import {act, render, screen} from '@testing-library/react';import {describe, it, expect, vi} from 'vitest';import {Heading} from './Heading';+const headingStyles = stylex.create({+ // Overrides a property Heading's own level styles set, so the consumer+ // value survives only when xstyle merges after them.+ consumer: {fontSize: typeScaleVars['--text-heading-1-size']},+});+declare module './index' {interface HeadingTypeMap {hero: true;@@ -326,3 +334,104 @@ describe('Heading maxLines without a truncation tooltip', () => {expect(reads).toBeGreaterThan(0);});});++function restoreProperty(+ proto: HTMLElement,+ name: 'scrollWidth' | 'offsetWidth',+ descriptor: PropertyDescriptor | undefined,+) {+ if (descriptor) {+ Object.defineProperty(proto, name, descriptor);+ } else {+ Reflect.deleteProperty(proto, name);+ }+}++describe('Heading outline, passthrough, and styling-input precedence', () => {+ it('adds no aria-level when accessibilityLevel equals level', () => {+ render(+ <Heading level={3} accessibilityLevel={3}>+ Matching outline+ </Heading>,+ );+ const element = screen.getByRole('heading', {name: 'Matching outline'});+ expect(element.tagName).toBe('H3');+ expect(element).not.toHaveAttribute('aria-level');+ });++ it('lets a caller aria-level win over the derived one', () => {+ render(+ <Heading level={2} accessibilityLevel={3} aria-level={4}>+ Caller outline+ </Heading>,+ );+ expect(+ screen.getByRole('heading', {name: 'Caller outline'}),+ ).toHaveAttribute('aria-level', '4');+ });++ it('merges className and xstyle after its own styles', () => {+ render(+ <Heading+ level={2}+ className="consumer-heading"+ xstyle={headingStyles.consumer}>+ Styled heading+ </Heading>,+ );+ const consumerClasses = (+ stylex.props(headingStyles.consumer).className ?? ''+ )+ .split(' ')+ .filter(Boolean);+ expect(consumerClasses.length).toBeGreaterThan(0);+ expect(screen.getByRole('heading', {name: 'Styled heading'})).toHaveClass(+ 'astryx-heading',+ 'consumer-heading',+ ...consumerClasses,+ );+ });++ it('applies the line clamp after the caller style and keeps the rest of it', () => {+ render(+ <Heading+ level={2}+ maxLines={3}+ style={{WebkitLineClamp: 5, opacity: 0.5}}>+ Clamped heading+ </Heading>,+ );+ const element = screen.getByRole('heading', {name: 'Clamped heading'});+ expect(element.style.webkitLineClamp).toBe('3');+ expect(element.style.opacity).toBe('0.5');+ });++ it('keeps the full text in the heading and adds no native title when truncated', async () => {+ const proto = HTMLElement.prototype;+ const scrollWidth = Object.getOwnPropertyDescriptor(proto, 'scrollWidth');+ const offsetWidth = Object.getOwnPropertyDescriptor(proto, 'offsetWidth');+ Object.defineProperty(proto, 'scrollWidth', {+ configurable: true,+ get: () => 500,+ });+ Object.defineProperty(proto, 'offsetWidth', {+ configurable: true,+ get: () => 100,+ });+ try {+ render(+ <Heading level={2} maxLines={1}>+ A heading far wider than its column+ </Heading>,+ );+ await act(async () => {});+ const element = screen.getByRole('heading', {+ name: 'A heading far wider than its column',+ });+ expect(element).not.toHaveAttribute('title');+ } finally {+ restoreProperty(proto, 'scrollWidth', scrollWidth);+ restoreProperty(proto, 'offsetWidth', offsetWidth);+ }+ });+});diff --git a/packages/core/src/Heading/Heading.tsx b/packages/core/src/Heading/Heading.tsxindex 74d621ea69..564490a3a8 100644--- a/packages/core/src/Heading/Heading.tsx+++ b/packages/core/src/Heading/Heading.tsx@@ -9,10 +9,12 @@* @position Core implementation; lives in own Heading/ dir, re-exported by Text/** SYNC: When modified, update these files to stay in sync:- * - /packages/core/src/Text/Text.doc.mjs (props table, features, implementation notes)+ * - /packages/core/src/Text/Heading.doc.mjs (props table, theming target)+ * - /packages/core/src/Text/Text.doc.mjs (shared truncation and tooltip guidance)* - /packages/core/src/Heading/Heading.test.tsx (tests for new/changed behavior)- * - /packages/core/src/Text/index.ts (exports if types change)- * - /apps/storybook/stories/Text.stories.tsx (storybook stories)+ * - /packages/core/src/Heading/index.ts (exports if types change)+ * - /packages/core/src/Text/index.ts (re-exports if types change)+ * - /apps/storybook/stories/Heading.stories.tsx (storybook stories)* - /packages/cli/assets/templates/blocks/components/Heading/ (showcase blocks)* - /packages/cli/assets/templates/blocks/components/Text/ (showcase blocks)*/diff --git a/packages/core/src/Heading/__tests__/HeadingAudit.a11y.chromium.spec.ts b/packages/core/src/Heading/__tests__/HeadingAudit.a11y.chromium.spec.tsnew file mode 100644index 0000000000..cc57cb320d--- /dev/null+++ b/packages/core/src/Heading/__tests__/HeadingAudit.a11y.chromium.spec.ts@@ -0,0 +1,626 @@+// Copyright (c) Meta Platforms, Inc. and affiliates.+// @pr-a11y audit Heading++/**+ * @file HeadingAudit.a11y.chromium.spec.ts+ * @input Exact-head Heading audit matrix across themes, modes, direction, and viewport+ * @output Screenshots and fail-closed sensor receipts for the Heading whole-component audit+ * @position Component-owned Night Watch browser evidence; CI runs it only for a Heading audit pull request+ */++import {createHash} from 'node:crypto';+import {execFileSync} from 'node:child_process';+import * as fs from 'node:fs';+import * as path from 'node:path';+import {expect, test, type Page} from '@playwright/test';+import {holdMotionStill} from '@astryxdesign/a11y-spec/chromium';+import {+ DEFAULT_STORYBOOK_DIR,+ serveStorybook,+ type StaticServer,+} from '@astryxdesign/a11y-spec/storybook';++const OUTPUT = path.resolve('heading-audit-evidence');+const STORY_ID = 'core-heading--audit-matrix';+const WIDE = {width: 1024, height: 1100};+const NARROW = {width: 320, height: 1400};++type Mode = 'light' | 'dark';+type Direction = 'ltr' | 'rtl';+type Theme = 'neutral' | 'butter';++type AuditCase = {+ key: string;+ mode: Mode;+ direction: Direction;+ theme: Theme;+ viewport: {width: number; height: number};+};++type AuditReceipt = {+ passed: boolean;+ expected: Record<string, unknown>;+ failures: string[];+};++const EXPECTED_CASES = [+ 'level-2',+ 'outline-equal',+ 'outline-override',+ 'display-1',+ 'display-2',+ 'display-3',+ 'display-weight',+ 'secondary',+ 'justify-center',+ 'justify-end',+ 'truncate-1',+ 'truncate-2',+ 'long-token',+];++// Element and accessible level each case must expose (AR1, AR2).+const OUTLINE: Record<string, {tag: string; level: number}> = {+ 'level-2': {tag: 'H2', level: 2},+ 'outline-equal': {tag: 'H3', level: 3},+ 'outline-override': {tag: 'H2', level: 4},+ 'display-1': {tag: 'H2', level: 2},+ 'display-2': {tag: 'H2', level: 2},+ 'display-3': {tag: 'H2', level: 2},+ 'display-weight': {tag: 'H2', level: 2},+ secondary: {tag: 'H3', level: 3},+ 'justify-center': {tag: 'H4', level: 4},+ 'justify-end': {tag: 'H4', level: 4},+ 'truncate-1': {tag: 'H3', level: 3},+ 'truncate-2': {tag: 'H3', level: 3},+ 'long-token': {tag: 'H3', level: 3},+};++const cases: AuditCase[] = [];+function addPair(+ key: string,+ options: Partial<Omit<AuditCase, 'key' | 'mode'>> = {},+) {+ for (const mode of ['light', 'dark'] as const) {+ cases.push({+ key: `${key}-${mode}`,+ mode,+ direction: options.direction ?? 'ltr',+ theme: options.theme ?? 'neutral',+ viewport: options.viewport ?? WIDE,+ });+ }+}++addPair('default');+addPair('custom-theme', {theme: 'butter'});+addPair('rtl', {direction: 'rtl'});+addPair('narrow', {viewport: NARROW});++test.describe.configure({mode: 'serial', retries: 0});+let server: StaticServer;+let checkoutSha: string;+let storybookSha: string;++function storyUrl(item: AuditCase) {+ return `${server.origin}/iframe.html?id=${STORY_ID}&viewMode=story&globals=colorMode:${item.mode};astryxTheme:${item.theme};direction:${item.direction}`;+}++async function settle(page: Page) {+ await holdMotionStill(page);+ await page.evaluate(async () => document.fonts.ready);+ await page.evaluate(+ async () =>+ new Promise<void>(resolve =>+ requestAnimationFrame(() => requestAnimationFrame(() => resolve())),+ ),+ );+ await page.waitForTimeout(40);+}++async function observe(page: Page) {+ return page.evaluate((expectedCases: string[]) => {+ type Rgba = {r: number; g: number; b: number; a: number};+ function parseColor(color: string): Rgba | null {+ const match = color.match(/rgba?\(([^)]+)\)/);+ if (!match) {+ return null;+ }+ const [r, g, b, a = 1] = match[1]+ .split(/[\s,/]+/)+ .filter(Boolean)+ .map(Number);+ return {r, g, b, a};+ }+ function over(top: Rgba, bottom: Rgba): Rgba {+ return {+ r: top.r * top.a + bottom.r * (1 - top.a),+ g: top.g * top.a + bottom.g * (1 - top.a),+ b: top.b * top.a + bottom.b * (1 - top.a),+ a: 1,+ };+ }+ // The painted backdrop behind an element: every translucent ancestor+ // fill down to the first opaque one (or a white canvas when none is).+ function backdrop(element: Element): Rgba {+ const layers: Rgba[] = [];+ for (+ let node: Element | null = element;+ node != null;+ node = node.parentElement+ ) {+ const color = parseColor(getComputedStyle(node).backgroundColor);+ if (color != null && color.a > 0) {+ layers.push(color);+ if (color.a >= 1) {+ break;+ }+ }+ }+ let result: Rgba = {r: 255, g: 255, b: 255, a: 1};+ for (const layer of layers.reverse()) {+ result = over(layer, result);+ }+ return result;+ }+ function luminance({r, g, b}: Rgba): number {+ const [lr, lg, lb] = [r, g, b].map(channel => {+ const c = channel / 255;+ return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;+ });+ return 0.2126 * lr + 0.7152 * lg + 0.0722 * lb;+ }+ function contrast(element: Element): number | null {+ const fg = parseColor(getComputedStyle(element).color);+ if (fg == null) {+ return null;+ }+ const bg = backdrop(element);+ const a = luminance(over(fg, bg));+ const b = luminance(bg);+ const [hi, lo] = a > b ? [a, b] : [b, a];+ return Math.round(((hi + 0.05) / (lo + 0.05)) * 100) / 100;+ }+ const round = (value: number) => Math.round(value * 10) / 10;++ const headings = Array.from(+ document.querySelectorAll<HTMLElement>('[data-audit-case]'),+ ).map(heading => {+ const style = getComputedStyle(heading);+ const rect = heading.getBoundingClientRect();+ const column = heading.parentElement?.getBoundingClientRect() ?? null;+ const fontSize = Number.parseFloat(style.fontSize);+ const lineHeight = Number.parseFloat(style.lineHeight);+ return {+ auditCase: heading.getAttribute('data-audit-case'),+ tagName: heading.tagName,+ ariaLevel: heading.getAttribute('aria-level'),+ title: heading.getAttribute('title'),+ hasTarget: heading.classList.contains('astryx-heading'),+ dataLevel: heading.getAttribute('data-level'),+ dataType: heading.getAttribute('data-type'),+ dataWeight: heading.getAttribute('data-weight'),+ dataColor: heading.getAttribute('data-color'),+ tabIndex: heading.tabIndex,+ text: heading.textContent,+ fontSize,+ fontWeight: Number.parseFloat(style.fontWeight),+ lineHeight: Number.isFinite(lineHeight) ? lineHeight : null,+ textAlign: style.textAlign,+ direction: style.direction,+ whiteSpace: style.whiteSpace,+ textOverflow: style.textOverflow,+ lineClamp: style.webkitLineClamp,+ display: style.display,+ scrollWidth: heading.scrollWidth,+ clientWidth: heading.clientWidth,+ scrollHeight: heading.scrollHeight,+ clientHeight: heading.clientHeight,+ contrast: contrast(heading),+ color: style.color,+ geometry: {+ x: round(rect.x),+ y: round(rect.y),+ width: round(rect.width),+ height: round(rect.height),+ },+ escapesColumn:+ column != null &&+ (rect.left < column.left - 1 || rect.right > column.right + 1),+ };+ });+ const root = document.querySelector<HTMLElement>('[data-audit-case]');+ return {+ theme: document+ .querySelector('[data-astryx-theme]')+ ?.getAttribute('data-astryx-theme'),+ mode: document.documentElement.getAttribute('data-theme'),+ direction: root ? getComputedStyle(root).direction : null,+ viewport: {width: innerWidth, height: innerHeight},+ dpr: devicePixelRatio,+ reducedMotion: matchMedia('(prefers-reduced-motion: reduce)').matches,+ documentOverflow: document.documentElement.scrollWidth > innerWidth + 1,+ fonts: document.fonts.status,+ runningAnimations: document+ .getAnimations()+ .filter(animation => animation.playState === 'running').length,+ storybookError:+ document.querySelector('.sb-show-errordisplay') != null ||+ document.body.classList.contains('sb-show-errordisplay'),+ cases: headings.map(heading => heading.auditCase),+ expectedCases,+ headings,+ };+ }, EXPECTED_CASES);+}++type AxNode = {+ role?: {value?: string};+ backendDOMNodeId?: number;+ properties?: {name: string; value?: {value?: unknown}}[];+};++/** Heading level per audit case, read from Chromium's accessibility tree. */+async function axHeadingLevels(page: Page): Promise<Record<string, number>> {+ const cdp = await page.context().newCDPSession(page);+ try {+ await cdp.send('DOM.getDocument', {depth: 0});+ const {nodes} = (await cdp.send('Accessibility.getFullAXTree')) as {+ nodes: AxNode[];+ };+ const levels: Record<string, number> = {};+ for (const node of nodes) {+ if (node.role?.value !== 'heading' || node.backendDOMNodeId == null) {+ continue;+ }+ const {object} = await cdp.send('DOM.resolveNode', {+ backendNodeId: node.backendDOMNodeId,+ });+ if (object.objectId == null) {+ continue;+ }+ const {result} = await cdp.send('Runtime.callFunctionOn', {+ objectId: object.objectId,+ functionDeclaration:+ 'function () { return this.getAttribute("data-audit-case"); }',+ returnByValue: true,+ });+ const id = result.value as string | null;+ const level = node.properties?.find(property => property.name === 'level')+ ?.value?.value;+ if (id != null && typeof level === 'number') {+ levels[id] = level;+ }+ }+ return levels;+ } finally {+ await cdp.detach();+ }+}++test.beforeAll(async () => {+ fs.rmSync(OUTPUT, {recursive: true, force: true});+ fs.mkdirSync(OUTPUT, {recursive: true});+ checkoutSha = execFileSync('git', ['rev-parse', 'HEAD'], {+ encoding: 'utf8',+ }).trim();+ const expected = process.env.ASTRYX_HEAD_SHA;+ if (expected && expected !== checkoutSha) {+ throw new Error(+ `checkout ${checkoutSha} does not match expected head ${expected}`,+ );+ }+ server = await serveStorybook(+ process.env.ASTRYX_STORYBOOK_DIR ?? DEFAULT_STORYBOOK_DIR,+ );+ const response = await fetch(`${server.origin}/astryx-build-sha.txt`);+ if (!response.ok) {+ throw new Error(`Storybook build has no SHA stamp (${response.status})`);+ }+ storybookSha = (await response.text()).trim();+ if (storybookSha !== checkoutSha) {+ throw new Error(+ `Storybook ${storybookSha} does not match checkout ${checkoutSha}`,+ );+ }+});++test.afterAll(async () => {+ await server?.close();+});++for (const item of cases) {+ test(item.key, async ({browser}) => {+ const context = await browser.newContext({+ viewport: item.viewport,+ deviceScaleFactor: 1,+ colorScheme: item.mode,+ reducedMotion: 'reduce',+ });+ const page = await context.newPage();+ const pageErrors: string[] = [];+ page.on('pageerror', error => pageErrors.push(String(error)));+ await page.goto(storyUrl(item), {waitUntil: 'load'});+ await page.locator('#storybook-root').waitFor();+ await expect(page.locator('[data-audit-case]')).toHaveCount(+ EXPECTED_CASES.length,+ );++ await settle(page);+ const first = await observe(page);+ await page.waitForTimeout(100);+ await settle(page);+ const observed = await observe(page);+ const geometryStable =+ JSON.stringify(first.headings.map(heading => heading.geometry)) ===+ JSON.stringify(observed.headings.map(heading => heading.geometry));++ const failures: string[] = [];+ const check = (condition: boolean, message: string) => {+ if (!condition) {+ failures.push(message);+ }+ };+ check(storybookSha === checkoutSha, 'storybook build mismatch');+ check(pageErrors.length === 0, `page errors: ${pageErrors.join(' | ')}`);+ check(!observed.storybookError, 'storybook error display');+ check(observed.theme === item.theme, `theme ${observed.theme}`);+ check(observed.mode === item.mode, `mode ${observed.mode}`);+ check(+ observed.direction === item.direction,+ `direction ${observed.direction}`,+ );+ check(+ observed.viewport.width === item.viewport.width &&+ observed.viewport.height === item.viewport.height,+ 'viewport mismatch',+ );+ check(observed.dpr === 1, `dpr ${observed.dpr}`);+ check(observed.reducedMotion, 'reduced motion not applied');+ check(observed.fonts === 'loaded', `fonts ${observed.fonts}`);+ check(observed.runningAnimations === 0, 'animations still running');+ check(geometryStable, 'geometry changed between samples');+ check(+ JSON.stringify(observed.cases) === JSON.stringify(EXPECTED_CASES),+ `cases ${observed.cases.join(',')}`,+ );++ const byCase = Object.fromEntries(+ observed.headings.map(heading => [heading.auditCase, heading]),+ );++ // AR1, AR2: role and level as Chromium's accessibility tree exposes them,+ // not the DOM tag alone. Playwright's role queries prefer the native+ // h1-h6 level over aria-level, so they cannot observe the override.+ const exposedLevels = await axHeadingLevels(page);+ for (const [id, outline] of Object.entries(OUTLINE)) {+ const heading = byCase[id];+ check(heading != null, `${id}: missing`);+ if (heading == null) {+ continue;+ }+ check(+ heading.tagName === outline.tag,+ `${id}: renders ${heading.tagName}`,+ );+ check(+ exposedLevels[id] === outline.level,+ `${id}: accessibility tree level ${exposedLevels[id]} is not ${outline.level}`,+ );+ check(heading.hasTarget, `${id}: no astryx-heading target`);+ check(+ heading.dataLevel === outline.tag.slice(1),+ `${id}: data-level ${heading.dataLevel}`,+ );+ check(heading.title == null, `${id}: native title ${heading.title}`);+ }+ check(+ byCase['outline-equal']?.ariaLevel == null,+ 'outline-equal: carries aria-level although it matches level',+ );+ check(+ byCase['outline-override']?.ariaLevel === '4',+ 'outline-override: aria-level is not 4',+ );++ // FR2, ORD1, ORD2: display types replace the level scale in order; an+ // explicit bold weight is reflected and is heavier than the type's default.+ const d1 = byCase['display-1'];+ const d2 = byCase['display-2'];+ const d3 = byCase['display-3'];+ const dw = byCase['display-weight'];+ if (d1 && d2 && d3 && dw) {+ check(+ d1.fontSize > d2.fontSize && d2.fontSize > d3.fontSize,+ `display scale order ${d1.fontSize} > ${d2.fontSize} > ${d3.fontSize}`,+ );+ for (const [id, heading] of [+ ['display-1', d1],+ ['display-2', d2],+ ['display-3', d3],+ ] as const) {+ check(heading.dataType === id, `${id}: data-type ${heading.dataType}`);+ }+ check(dw.dataWeight === 'bold', `display-weight: data-weight`);+ check(+ dw.fontWeight > d2.fontWeight,+ `display-weight: ${dw.fontWeight} not heavier than display-2 ${d2.fontWeight}`,+ );+ check(+ dw.fontSize === d2.fontSize,+ `display-weight: size ${dw.fontSize} differs from display-2 ${d2.fontSize}`,+ );+ }+ check(byCase.secondary?.dataColor === 'secondary', 'secondary: data-color');++ // FR3: logical alignment.+ check(+ byCase['justify-center']?.textAlign === 'center',+ `justify-center: ${byCase['justify-center']?.textAlign}`,+ );+ check(+ byCase['justify-end']?.textAlign === 'end',+ `justify-end: ${byCase['justify-end']?.textAlign}`,+ );++ // FR4: one clipped line with an ellipsis; a two-line clamp.+ const t1 = byCase['truncate-1'];+ if (t1) {+ check(+ t1.whiteSpace === 'nowrap',+ `truncate-1: white-space ${t1.whiteSpace}`,+ );+ check(+ t1.textOverflow === 'ellipsis',+ `truncate-1: text-overflow ${t1.textOverflow}`,+ );+ check(t1.scrollWidth > t1.clientWidth, 'truncate-1: not truncated');+ }+ const t2 = byCase['truncate-2'];+ if (t2) {+ check(t2.lineClamp === '2', `truncate-2: line clamp ${t2.lineClamp}`);+ check(t2.scrollHeight > t2.clientHeight + 1, 'truncate-2: not clamped');+ check(t2.lineHeight != null, 'truncate-2: line height not measurable');+ if (t2.lineHeight != null) {+ check(+ Math.abs(t2.geometry.height - 2 * t2.lineHeight) <= 2,+ `truncate-2: height ${t2.geometry.height} is not two lines`,+ );+ }+ }++ // WCAG 2.2 SC 1.4.3 against the composited backdrop; large text is at+ // least 24px, or 18.66px at weight 700 and above.+ for (const heading of observed.headings) {+ const id = heading.auditCase ?? 'unknown';+ const isLarge =+ heading.fontSize >= 24 ||+ (heading.fontSize >= 18.66 && heading.fontWeight >= 700);+ const threshold = isLarge ? 3 : 4.5;+ check(+ heading.contrast != null && heading.contrast >= threshold,+ `${id}: contrast ${heading.contrast} below ${threshold}`,+ );+ check(heading.direction === item.direction, `${id}: direction`);+ if (id !== 'long-token') {+ check(!heading.escapesColumn, `${id}: escapes its column`);+ }+ }++ const png = await page.screenshot({animations: 'disabled', fullPage: true});+ check(png.length > 1000, 'screenshot is empty');++ // FR4 pointer path: hovering the clipped heading shows its full text.+ const fullText = t1?.text ?? '';+ await page.locator('[data-audit-case="truncate-1"]').hover();+ const tooltip = page.getByRole('tooltip').filter({hasText: fullText});+ const tooltipOnHover = await tooltip+ .waitFor({state: 'visible', timeout: 3000})+ .then(() => true)+ .catch(() => false);+ check(tooltipOnHover, 'truncate-1: hover shows no full-text tooltip');+ await page.mouse.move(0, 0);++ // FR4 keyboard path: recorded, not asserted. The contract lists this as+ // an implementation gap (the heading is not focusable).+ await page.evaluate(() =>+ (document.activeElement as HTMLElement | null)?.blur(),+ );+ let keyboardReachesTruncatedHeading = false;+ for (let step = 0; step < 20; step += 1) {+ await page.keyboard.press('Tab');+ const focused = await page.evaluate(+ () => document.activeElement?.getAttribute('data-audit-case') ?? null,+ );+ if (focused === 'truncate-1') {+ keyboardReachesTruncatedHeading = true;+ break;+ }+ }++ const longToken = byCase['long-token'];+ const image = `${item.key}.png`;+ const receipt = {+ schemaVersion: 1,+ expected: {+ build: checkoutSha,+ storyId: STORY_ID,+ mode: item.mode,+ direction: item.direction,+ theme: item.theme,+ viewport: item.viewport,+ cases: EXPECTED_CASES,+ outline: OUTLINE,+ truncation:+ 'truncate-1 clips one line with an ellipsis and shows its full text on hover; truncate-2 clamps two lines; no native title',+ },+ observed: {+ build: storybookSha,+ ...observed,+ geometryStable,+ pageErrors,+ tooltipOnHover,+ accessibilityTreeLevels: exposedLevels,+ },+ observations: {+ keyboardReachesTruncatedHeading,+ longToken: longToken+ ? {+ overflowsItsBox: longToken.scrollWidth > longToken.clientWidth,+ escapesColumn: longToken.escapesColumn,+ documentOverflow: observed.documentOverflow,+ }+ : null,+ },+ image: {+ file: image,+ sha256: createHash('sha256').update(png).digest('hex'),+ width: png.readUInt32BE(16),+ height: png.readUInt32BE(20),+ },+ failures,+ passed: failures.length === 0,+ };+ fs.writeFileSync(path.join(OUTPUT, image), png);+ fs.writeFileSync(+ path.join(OUTPUT, `${item.key}.sensors.json`),+ `${JSON.stringify(receipt, null, 2)}\n`,+ );+ await context.close();+ });+}++test('manifest is complete', async () => {+ const receiptFiles = fs+ .readdirSync(OUTPUT)+ .filter(file => file.endsWith('.sensors.json'));+ const receipts = receiptFiles.map(+ (file): AuditReceipt =>+ JSON.parse(+ fs.readFileSync(path.join(OUTPUT, file), 'utf8'),+ ) as AuditReceipt,+ );+ fs.writeFileSync(+ path.join(OUTPUT, 'manifest.json'),+ `${JSON.stringify(+ {+ schemaVersion: 1,+ component: 'core/Heading',+ build: checkoutSha,+ frames: cases.map(item => ({+ key: item.key,+ image: `${item.key}.png`,+ receipt: `${item.key}.sensors.json`,+ })),+ },+ null,+ 2,+ )}\n`,+ );+ expect(receiptFiles).toHaveLength(cases.length);+ expect(+ receipts+ .filter(receipt => !receipt.passed)+ .map(receipt => ({frame: receipt.expected, failures: receipt.failures})),+ ).toEqual([]);+});diff --git a/packages/core/src/Text/Heading.doc.mjs b/packages/core/src/Text/Heading.doc.mjsindex daf20cdd25..a3fc3b9bd9 100644--- a/packages/core/src/Text/Heading.doc.mjs+++ b/packages/core/src/Text/Heading.doc.mjs@@ -111,6 +111,28 @@ export const docs = {type: 'string',description: 'HTML id attribute.',},+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ 'StyleX styles applied to the heading element. Must be a stylex.create() value: not an inline style object like style={{}}.',+ },+ {+ name: 'className',+ type: 'string',+ description: 'CSS class name applied to the heading element.',+ },+ {+ name: 'style',+ type: 'React.CSSProperties',+ description:+ 'Inline styles applied to the heading element. When `maxLines` is above 1, its line clamp replaces any `WebkitLineClamp` in `style`.',+ },+ {+ name: 'ref',+ type: 'React.Ref<HTMLHeadingElement>',+ description: 'Ref forwarded to the heading element.',+ },],};@@ -212,6 +234,28 @@ export const docsZh = {type: 'string',description: 'HTML id 属性。',},+ {+ name: 'xstyle',+ type: 'StyleXStyles',+ description:+ '应用于标题元素的 StyleX 样式。必须是 stylex.create() 的值,而不是 style={{}} 这样的内联样式对象。',+ },+ {+ name: 'className',+ type: 'string',+ description: '应用于标题元素的 CSS 类名。',+ },+ {+ name: 'style',+ type: 'React.CSSProperties',+ description:+ '应用于标题元素的内联样式。当 `maxLines` 大于 1 时,其行数截断会替换 `style` 中的 `WebkitLineClamp`。',+ },+ {+ name: 'ref',+ type: 'React.Ref<HTMLHeadingElement>',+ description: '转发到标题元素的 Ref。',+ },],};@@ -244,5 +288,10 @@ export const docsDense = {hasCapsize: 'Optical alignment via text-box-trim; forces block display.',hasStrikethrough: 'Strikethrough text decoration.',id: 'HTML id attribute.',+ xstyle: 'StyleX styles on the heading; stylex.create() value only.',+ className: 'CSS class on the heading.',+ style:+ 'inline styles on the heading; with maxLines>1 the line clamp replaces WebkitLineClamp.',+ ref: 'ref to the heading element.',},};