Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

test(storybook): run the story-tree check where Storybook is built, and bring the tree back to its shape (#8509)

Christopher Chedeaud29fe0f64b7a
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 35edae2d68..7799bfdebf 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -1014,6 +1014,12 @@ jobs:
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
run: node scripts/verify-exports.mjs
+ # The story-tree check reads the built index and skips without one, so it
+ # runs here, where Storybook was just built (apps/storybook/README.md).
+ - name: Check the story tree
+ if: needs.check-scope.outputs.docsite_only != 'true' && needs.check-scope.outputs.spec_only != 'true' && needs.check-scope.outputs.tooling_only != 'true'
+ run: pnpm exec vitest run --project node apps/storybook/.storybook/story-tree.test.ts
+
- name: Stamp Storybook source revision
if: steps.scope.outputs.docsite_only != 'true' && steps.scope.outputs.spec_only != 'true' && steps.scope.outputs.tooling_only != 'true'
run: git rev-parse HEAD > apps/storybook/dist/astryx-build-sha.txt
diff --git a/apps/storybook/.storybook/story-tree.test.ts b/apps/storybook/.storybook/story-tree.test.ts
index 9b817db08c..35ee52c1e6 100644
--- a/apps/storybook/.storybook/story-tree.test.ts
+++ b/apps/storybook/.storybook/story-tree.test.ts
@@ -7,6 +7,8 @@
* <Package>/<Component>/(Default | Theme Sheet | …)
* <Package>/Hooks/<hook>
* <Package>/Themes/<theme feature>
+ * <Package>/Internationalization/<page>
+ * A11y/<pattern or component>
* ```
*
* Conventions that live only in a README drift: `Hooks/useClipboard` and
@@ -16,7 +18,9 @@
* source appears to say.
*
* Requires a built Storybook; skips itself when there is none, because a
- * fresh clone has no dist and this must not be the test that fails there.
+ * fresh clone has no dist and this must not be the test that fails there. CI
+ * runs it in `build-storybook`, right after the build, so a title outside the
+ * shape fails the pull request that adds it.
*/
import fs from 'node:fs';
@@ -31,8 +35,16 @@ const INDEX = path.join(ROOT, 'dist', 'index.json');
/** The packages a story can ship from. Not categories — packages. */
const PACKAGES = ['Core', 'Lab', 'Charts', 'Vega', 'RichText'];
+/**
+ * The root of the accessibility contract fixtures: test fixtures the a11y
+ * audit and its browser specs open by story id, not component docs. Compared
+ * without case: Storybook ids lowercase titles, so `A11y/` and `a11y/` already
+ * share ids.
+ */
+const FIXTURE_ROOT = 'a11y';
+
/** Groups that are deliberately not components. */
-const NON_COMPONENT_GROUPS = ['Hooks', 'Themes'];
+const NON_COMPONENT_GROUPS = ['Hooks', 'Themes', 'Internationalization'];
type StoryIndex = {entries: Record<string, {title: string}>};
@@ -53,10 +65,14 @@ describe.skipIf(!built)('story tree shape', () => {
});
it('files every story under a package, never a category', () => {
- const stray = titles.filter(
- title => !PACKAGES.includes(title.split('/')[0]),
- );
- expect(stray, `not under one of ${PACKAGES.join(', ')}`).toEqual([]);
+ const stray = titles.filter(title => {
+ const root = title.split('/')[0];
+ return !PACKAGES.includes(root) && root.toLowerCase() !== FIXTURE_ROOT;
+ });
+ expect(
+ stray,
+ `not under one of ${PACKAGES.join(', ')}, or A11y/ for a11y fixtures`,
+ ).toEqual([]);
});
it('keeps hooks under <Package>/Hooks/, not beside components', () => {
@@ -95,13 +111,15 @@ describe.skipIf(!built)('story tree shape', () => {
});
it('never nests a component deeper than <Package>/<Component>', () => {
- // Charts/Chrome/* and Lab/3DChart/* are deliberate sub-grouping; anything
- // else three deep is a story name that leaked into the title.
+ // Charts/Chrome/*, Lab/3DChart/* and Lab/ChartTheming/* (one feature in
+ // four renderers) are deliberate sub-grouping; anything else three deep is
+ // a story name that leaked into the title.
const allowedGroups = [
...NON_COMPONENT_GROUPS,
'Chrome',
'3DChart',
'Chart Interactions',
+ 'ChartTheming',
];
const tooDeep = titles.filter(title => {
const segments = title.split('/');
diff --git a/apps/storybook/README.md b/apps/storybook/README.md
index aafeaeb0cd..a52e45e78b 100644
--- a/apps/storybook/README.md
+++ b/apps/storybook/README.md
@@ -13,6 +13,8 @@ find it:
<Package>/<Component>/(Default | Theme Sheet | …)
<Package>/Hooks/<hook>
<Package>/Themes/<theme feature>
+<Package>/Internationalization/<page>
+A11y/<pattern or component>
```
- **`<Package>`** is `Core`, `Lab`, `Charts`, `Vega` or `RichText` — the package
@@ -28,6 +30,15 @@ find it:
- **Hooks and theme-level features are not components** and do not sit beside
them. Icon and indicator registries, `MediaTheme`, `CodeTheme` and the like
live under `Themes/`.
+- **An internationalization page** checks one locale behavior across several
+ components, such as dates in Calendar, DateInput and Timestamp, so it sits in
+ its package's `Internationalization/` group rather than beside one component.
+- **Accessibility contract fixtures live under `A11y/`.** They are test
+ fixtures the a11y audit and its browser specs open by story id, not component
+ docs. Storybook ids lowercase titles, so `A11y/` and `a11y/` share ids, and
+ the check accepts both.
+- `.storybook/story-tree.test.ts` checks this shape against the built index,
+ and CI runs it in `build-storybook` right after the build.
### A Theme Sheet must not pin its own theme
diff --git a/apps/storybook/stories/DateLocaleConsistency.stories.tsx b/apps/storybook/stories/DateLocaleConsistency.stories.tsx
index bbdd448feb..49bc896ab6 100644
--- a/apps/storybook/stories/DateLocaleConsistency.stories.tsx
+++ b/apps/storybook/stories/DateLocaleConsistency.stories.tsx
@@ -21,7 +21,7 @@ import {Timestamp} from '@astryxdesign/core/Timestamp';
import {spacingVars} from '@astryxdesign/core/theme/tokens.stylex';
const meta = {
- title: 'Foundations/Internationalization/Date consistency',
+ title: 'Core/Internationalization/Date consistency',
parameters: {
layout: 'padded',
},
diff --git a/apps/storybook/stories/IconSizeTheming.stories.tsx b/apps/storybook/stories/IconSizeTheming.stories.tsx
index b75c2cda02..00951db330 100644
--- a/apps/storybook/stories/IconSizeTheming.stories.tsx
+++ b/apps/storybook/stories/IconSizeTheming.stories.tsx
@@ -182,7 +182,9 @@ function Columns({render}: {render: () => React.ReactNode}) {
// =============================================================================
const meta: Meta = {
- title: 'Core/Icon/Size Theming',
+ title: 'Core/Themes/Icon Size',
+ // The ids the visual baseline keys these stories by, from their earlier title.
+ id: 'core-icon-size-theming',
tags: ['autodocs'],
parameters: {
docs: {
diff --git a/apps/storybook/stories/MarkdownHeadingLinks.stories.tsx b/apps/storybook/stories/MarkdownHeadingLinks.stories.tsx
index 5cc58d2eb4..3ed3b000df 100644
--- a/apps/storybook/stories/MarkdownHeadingLinks.stories.tsx
+++ b/apps/storybook/stories/MarkdownHeadingLinks.stories.tsx
@@ -15,7 +15,7 @@ const styles = stylex.create({
});
const meta: Meta<typeof Markdown> = {
- title: 'Core/Markdown/Plugins/Heading links',
+ title: 'Core/Markdown',
component: Markdown,
};
@@ -60,7 +60,7 @@ const compactPlugins = [
createMarkdownHeadingLinks({headingIdPrefix: 'heading-links-compact'}),
];
-export const Overview: Story = {
+export const HeadingLinks: Story = {
name: 'Heading links',
parameters: {
docs: {
diff --git a/apps/storybook/stories/SideNavCollapseOwnership.stories.tsx b/apps/storybook/stories/SideNavCollapseOwnership.stories.tsx
index 696e2882a1..9626c3018d 100644
--- a/apps/storybook/stories/SideNavCollapseOwnership.stories.tsx
+++ b/apps/storybook/stories/SideNavCollapseOwnership.stories.tsx
@@ -12,7 +12,7 @@ import {CubeIcon, FolderIcon, HomeIcon} from '@heroicons/react/24/outline';
import {HomeIcon as HomeIconSolid} from '@heroicons/react/24/solid';
const meta: Meta<typeof SideNav> = {
- title: 'Core/SideNav/Collapse Ownership',
+ title: 'Core/SideNav',
component: SideNav,
parameters: {layout: 'centered'},
decorators: [
@@ -27,7 +27,8 @@ const meta: Meta<typeof SideNav> = {
export default meta;
type Story = StoryObj<typeof SideNav>;
-export const Acceptance: Story = {
+export const CollapseOwnership: Story = {
+ name: 'Collapse ownership',
args: {
collapsible: true,
resizable: {
diff --git a/packages/core/src/Markdown/plugins/headingLinks.a11y.chromium.spec.ts b/packages/core/src/Markdown/plugins/headingLinks.a11y.chromium.spec.ts
index 49f6a59097..261119325c 100644
--- a/packages/core/src/Markdown/plugins/headingLinks.a11y.chromium.spec.ts
+++ b/packages/core/src/Markdown/plugins/headingLinks.a11y.chromium.spec.ts
@@ -21,7 +21,7 @@ import {
type StaticServer,
} from '@astryxdesign/a11y-spec/storybook';
-const STORY = 'core-markdown-plugins-heading-links--overview';
+const STORY = 'core-markdown--heading-links';
const OUTPUT = path.resolve('test-results/markdown-heading-links');
const GEOMETRY_TOLERANCE_PX = 1;
let storybook: StaticServer;