An open source design system that's fully customizable and agent ready
TypeScript
fix(docsite): anatomy guard misses dark renderers; part names break mid-word (#5391)
Cindy Zhang535f32709934
diff --git a/apps/docsite/src/__tests__/anatomy-helpers.test.ts b/apps/docsite/src/__tests__/anatomy-helpers.test.tsindex 3ef2492322..4df02b7027 100644--- a/apps/docsite/src/__tests__/anatomy-helpers.test.ts+++ b/apps/docsite/src/__tests__/anatomy-helpers.test.ts@@ -1,7 +1,10 @@// Copyright (c) Meta Platforms, Inc. and affiliates.import {describe, expect, it} from 'vitest';-import {anatomyDescription} from '../components/component-detail/anatomyHelpers';+import {+ anatomyDescription,+ anatomyNameSegments,+} from '../components/component-detail/anatomyHelpers';describe('anatomy description', () => {it('marks a required element with a bold lead-in on its description', () => {@@ -42,3 +45,26 @@ describe('anatomy description', () => {).toBe('**Required:** A small indicator in the bottom-right corner.');});});++describe('anatomy name segments', () => {+ it('offers a break after a solidus, which CSS does not', () => {+ // Field: "Optional/Required" is 132px in a 108px content box and has no+ // break opportunity, so it came out as "Optional/Requ" / "ired indicator".+ expect(anatomyNameSegments('Optional/Required indicator')).toEqual([+ 'Optional/',+ 'Required indicator',+ ]);+ });++ it('leaves a name the browser can already wrap as one piece', () => {+ // A hyphen is a break opportunity, so "Scroll-to-bottom" wraps correctly.+ expect(anatomyNameSegments('Scroll-to-bottom button')).toEqual([+ 'Scroll-to-bottom button',+ ]);+ expect(anatomyNameSegments('Status dot')).toEqual(['Status dot']);+ });++ it('splits every solidus in a name', () => {+ expect(anatomyNameSegments('a/b/c')).toEqual(['a/', 'b/', 'c']);+ });+});diff --git a/apps/docsite/src/__tests__/component-detail-wiring.test.ts b/apps/docsite/src/__tests__/component-detail-wiring.test.tsindex 58113ff8ce..dc559e5595 100644--- a/apps/docsite/src/__tests__/component-detail-wiring.test.ts+++ b/apps/docsite/src/__tests__/component-detail-wiring.test.ts@@ -5,9 +5,9 @@** The `component-detail/` directory holds the internal building blocks of a* single page. Unlike `app/`, it contains no Next.js route entry points and no- * script-consumed modules, so every module in it must be reachable from an- * import — a renderer that nothing imports is dead code, and the data it was- * written to display silently never reaches the page.+ * script-consumed modules, so every module in it must be reachable from the+ * router — a renderer nothing on the page reaches is dead code, and the data it+ * was written to display silently never reaches the page.** Run: pnpm -F @astryxdesign/docsite test*/@@ -23,6 +23,7 @@ const SRC_DIR = path.resolve('..',);const DETAIL_DIR = path.join(SRC_DIR, 'components/component-detail');+const APP_DIR = path.join(SRC_DIR, 'app');const EXTENSIONS = ['.ts', '.tsx'];function walk(dir: string, out: string[] = []): string[] {@@ -63,31 +64,47 @@ function resolveRelative(fromFile: string, specifier: string): string | null {const SPECIFIER_RE = /(?:from\s*|import\(\s*|require\(\s*)['"]([^'"]+)['"]/g;-function collectImportedFiles(files: string[]): Set<string> {- const imported = new Set<string>();- for (const file of files) {+/**+ * Walk the relative-import graph out from `entries`, returning every file+ * reachable from one of them.+ *+ * Reachability, not "somebody imports it": a renderer imported only by its own+ * unit test — or only by another module the page never reaches — is still dark+ * on the page, and a guard that counted those importers would pass on it.+ */+function collectReachable(entries: string[]): Set<string> {+ const reachable = new Set<string>(entries);+ const queue = [...entries];+ while (queue.length > 0) {+ const file = queue.pop()!;const source = fs.readFileSync(file, 'utf8');for (const match of source.matchAll(SPECIFIER_RE)) {const resolved = resolveRelative(file, match[1]);- if (resolved !== null) {- imported.add(resolved);+ if (resolved !== null && !reachable.has(resolved)) {+ reachable.add(resolved);+ queue.push(resolved);}}}- return imported;+ return reachable;}describe('component detail wiring', () => {- it('imports every module in component-detail/ from somewhere', () => {+ it('reaches every module in component-detail/ from a page', () => {const detailModules = walk(DETAIL_DIR).filter(file => !file.includes('.test.'),);// Guard against a vacuous pass if the directory is ever moved or renamed.expect(detailModules.length).toBeGreaterThan(5);- const imported = collectImportedFiles(walk(SRC_DIR));+ // The Next.js router loads `app/`; everything else in `src/` is only code+ // that something under `app/` pulls in.+ const entries = walk(APP_DIR);+ expect(entries.length).toBeGreaterThan(5);++ const reachable = collectReachable(entries);const orphans = detailModules- .filter(file => !imported.has(file))+ .filter(file => !reachable.has(file)).map(file => path.relative(SRC_DIR, file)).sort();diff --git a/apps/docsite/src/components/component-detail/Anatomy.tsx b/apps/docsite/src/components/component-detail/Anatomy.tsxindex 28902ca65e..8afb84bab6 100644--- a/apps/docsite/src/components/component-detail/Anatomy.tsx+++ b/apps/docsite/src/components/component-detail/Anatomy.tsx@@ -2,6 +2,7 @@'use client';+import {Fragment} from 'react';import {Heading} from '@astryxdesign/core/Text';import {VStack} from '@astryxdesign/core/Layout';import {Section} from '@astryxdesign/core/Section';@@ -9,7 +10,7 @@ import {Table, pixel} from '@astryxdesign/core/Table';import {Card} from '@astryxdesign/core/Card';import type {AnatomyElement} from '../../generated/componentRegistry';import {MarkdownText} from '../MarkdownText';-import {anatomyDescription} from './anatomyHelpers';+import {anatomyDescription, anatomyNameSegments} from './anatomyHelpers';interface AnatomyProps {elements: AnatomyElement[];@@ -41,6 +42,15 @@ export function Anatomy({elements}: AnatomyProps) {key: 'name',header: 'Element',width: pixel(140),+ renderCell: (item: Record<string, unknown>) =>+ anatomyNameSegments(item.name as string).map(+ (segment, index) => (+ <Fragment key={index}>+ {index > 0 ? <wbr /> : null}+ {segment}+ </Fragment>+ ),+ ),},{key: 'description',diff --git a/apps/docsite/src/components/component-detail/anatomyHelpers.ts b/apps/docsite/src/components/component-detail/anatomyHelpers.tsindex 67c76a80af..8d658416d6 100644--- a/apps/docsite/src/components/component-detail/anatomyHelpers.ts+++ b/apps/docsite/src/components/component-detail/anatomyHelpers.ts@@ -18,6 +18,24 @@ import type {AnatomyElement} from '../../generated/componentRegistry';const REQUIRED_LEAD_IN = '**Required:**';+/**+ * Split a part name where the browser is allowed to wrap it but will not on+ * its own.+ *+ * The Anatomy table lays out `fixed`, so its Element column never grows to fit+ * its content: a name with no break opportunity inside the column's ~108px of+ * content box is broken inside a word instead — `Optional/Requ` / `ired+ * indicator` on Field, `Collapse/expa` / `nd toggle` on SideNav. A solidus is+ * not a break opportunity in CSS the way a hyphen is, so the renderer has to+ * offer one.+ *+ * Returns the pieces to join with `<wbr />`; a name with no solidus comes back+ * as a single piece and renders exactly as before.+ */+export function anatomyNameSegments(name: string): string[] {+ return name.split(/(?<=\/)/);+}+/*** The description to render for one anatomy element. Required elements get a* bold `Required:` lead-in rather than a separate badge column, keeping the flag