Skip to content

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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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