Skip to content

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

TypeScript

feat(docsite): move Theming into its own component tab, wrap tables in Card (#4948)

Kenton Quatman27d139ff9695
diff --git a/apps/docsite/src/__tests__/theming-helpers.test.ts b/apps/docsite/src/__tests__/theming-helpers.test.ts
index 9fb679822e..c4c4444ded 100644
--- a/apps/docsite/src/__tests__/theming-helpers.test.ts
+++ b/apps/docsite/src/__tests__/theming-helpers.test.ts
@@ -12,6 +12,7 @@ import {
targetPropValues,
buildDefineThemeExample,
publicVars,
+ hasThemingContent,
} from '../components/component-detail/themingHelpers';
describe('theming helpers — configKey', () => {
@@ -130,6 +131,40 @@ describe('theming helpers — publicVars', () => {
});
});
+describe('theming helpers — hasThemingContent', () => {
+ it('is false for a null theming doc', () => {
+ expect(hasThemingContent(null)).toBe(false);
+ });
+
+ it('is false when there are no targets and no public vars', () => {
+ expect(hasThemingContent({targets: []})).toBe(false);
+ expect(
+ hasThemingContent({
+ targets: [],
+ vars: [
+ {name: '--_private', description: 'x', default: '0', private: true},
+ {name: '--derived', description: 'y', default: '0', derived: true},
+ ],
+ }),
+ ).toBe(false);
+ });
+
+ it('is true when the component has at least one theme target', () => {
+ expect(hasThemingContent({targets: [{className: 'astryx-button'}]})).toBe(
+ true,
+ );
+ });
+
+ it('is true when the component exposes a public CSS variable', () => {
+ expect(
+ hasThemingContent({
+ targets: [],
+ vars: [{name: '--button-gap', description: 'x', default: '8px'}],
+ }),
+ ).toBe(true);
+ });
+});
+
describe('theming section — canary gating', () => {
const source = readFileSync(
join(
@@ -146,4 +181,39 @@ describe('theming section — canary gating', () => {
it('shows an experimental notice about the theming API', () => {
expect(source).toMatch(/theming API is experimental/i);
});
+
+ it('wraps both theming tables in a Card, like sibling doc tables', () => {
+ // Both the desktop <Table> and the mobile hand-rolled layout for each of
+ // the two tables (targets + CSS vars) render inside a <Card>. Four Card
+ // open tags total; a bare <Table> outside a Card would regress the
+ // consistency this test guards.
+ const cardOpenTags = source.match(/<Card[\s>]/g) ?? [];
+ expect(cardOpenTags.length).toBe(4);
+ expect(source).not.toMatch(/\)\s*;\s*}\s*\n\s*return \(\s*<Table/);
+ });
+});
+
+describe('theming tab — component detail wiring', () => {
+ const source = readFileSync(
+ join(
+ dirname(fileURLToPath(import.meta.url)),
+ '../components/component-detail/ComponentDetailClient.tsx',
+ ),
+ 'utf8',
+ );
+
+ it('renders a dedicated Theming tab', () => {
+ expect(source).toMatch(/<Tab value="theming" label="Theming" \/>/);
+ });
+
+ it('only mounts the Theming tab when there is themeable content', () => {
+ expect(source).toContain('hasThemingContent(comp.theming)');
+ expect(source).toContain("CURRENT_TARGET === 'canary'");
+ });
+
+ it('renders the Theming section in the theming tab, not Overview', () => {
+ expect(source).toMatch(
+ /tab === 'theming' && comp\.theming && \(\s*<Theming/,
+ );
+ });
});
diff --git a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
index 45ac50fae2..e8609ce571 100644
--- a/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
+++ b/apps/docsite/src/components/component-detail/ComponentDetailClient.tsx
@@ -25,6 +25,8 @@ import {
useInteractiveState,
} from './InteractivePreview';
import {hasInteractivePlayground} from './interactiveState';
+import {hasThemingContent} from './themingHelpers';
+import {CURRENT_TARGET} from '../../lib/docsVersions';
import {PlaygroundPropsTable} from './PlaygroundPropsTable';
import {PropsTable} from './PropsTable';
import type {ComponentEntry} from '../../generated/componentRegistry';
@@ -119,10 +121,6 @@ function OverviewContent({
<PropsTable props={comp.props} heading="Props" />
)}
- {!isHook && comp.theming && (
- <Theming theming={comp.theming} props={comp.props} />
- )}
-
{(exampleRegistry[comp.name] || []).length > 0 && (
<>
<VStack gap={4}>
@@ -156,8 +154,21 @@ function ComponentDetailInner({
const hasShowcase = comp.name in showcaseRegistry;
const hasPlayground = hasInteractivePlayground(comp);
+ // Theming lives in its own tab, shown only on the canary line (where the
+ // experimental theming API is documented) and only when the component has
+ // themeable targets or CSS variables — never an empty tab.
+ const hasThemingTab =
+ CURRENT_TARGET === 'canary' && hasThemingContent(comp.theming);
+ const hasTabs = hasPlayground || hasThemingTab;
- const tab = searchParams.get('tab') ?? 'overview';
+ const requestedTab = searchParams.get('tab') ?? 'overview';
+ // Clamp to a tab that actually exists for this component so a stale or
+ // hand-edited `?tab=` never lands on a blank panel.
+ const tab =
+ (requestedTab === 'properties' && hasPlayground) ||
+ (requestedTab === 'theming' && hasThemingTab)
+ ? requestedTab
+ : 'overview';
const setTab = (value: string) => {
trackNavigate({
page: 'components',
@@ -196,11 +207,12 @@ function ComponentDetailInner({
</Text>
</VStack>
- {hasPlayground ? (
+ {hasTabs ? (
<>
<TabList value={tab} onChange={setTab} hasDivider>
<Tab value="overview" label="Overview" />
- <Tab value="properties" label="Properties" />
+ {hasPlayground && <Tab value="properties" label="Properties" />}
+ {hasThemingTab && <Tab value="theming" label="Theming" />}
</TabList>
{tab === 'overview' && (
@@ -213,7 +225,7 @@ function ComponentDetailInner({
/>
)}
- {tab === 'properties' && (
+ {tab === 'properties' && hasPlayground && (
<VStack gap={4}>
<div {...stylex.props(styles.previewStage)}>
<InteractivePreviewStage
@@ -247,6 +259,10 @@ function ComponentDetailInner({
)}
</VStack>
)}
+
+ {tab === 'theming' && comp.theming && (
+ <Theming theming={comp.theming} props={comp.props} />
+ )}
</>
) : (
<>
diff --git a/apps/docsite/src/components/component-detail/Theming.tsx b/apps/docsite/src/components/component-detail/Theming.tsx
index 29f4abd361..a0e65ac438 100644
--- a/apps/docsite/src/components/component-detail/Theming.tsx
+++ b/apps/docsite/src/components/component-detail/Theming.tsx
@@ -5,11 +5,12 @@
/**
* @file Theming.tsx
* @input A component's `theming` doc (targets, vars, derived) + its props.
- * @output Renders the component detail page's "Theming" section: a table of
+ * @output Renders the component detail page's "Theming" tab: a table of
* theme targets shown as the keys they take in a `defineTheme` `components`
* config, a copyable `defineTheme` example, and a table of themeable CSS
* variables.
- * @position Component detail Overview; sibling to PropsTable / BestPractices.
+ * @position Component detail "Theming" tab body. Mirrors the Overview tab's
+ * layout — a bare VStack of display-3 sections, no wrapping Section.
*
* Data shaping lives in ./themingHelpers (unit-tested); this file is the view.
*/
@@ -17,9 +18,9 @@
import {Fragment} from 'react';
import {Heading, Text} from '@astryxdesign/core/Text';
import {VStack} from '@astryxdesign/core/Layout';
-import {Section} from '@astryxdesign/core/Section';
import {Table, pixel} from '@astryxdesign/core/Table';
import {Banner} from '@astryxdesign/core/Banner';
+import {Card} from '@astryxdesign/core/Card';
import {useMediaQuery} from '@astryxdesign/core/hooks';
import {Divider} from '@astryxdesign/core';
import {CodeExampleBlock} from '../CodeExampleBlock';
@@ -49,41 +50,43 @@ function TargetsTable({targets, props}: TargetsTableProps) {
if (isMobile) {
return (
- <VStack gap={0}>
- {targets.map(target => {
- const dataAttrs = targetDataAttributes(target);
- const propValues = targetPropValues(target, props);
- const states = target.states ?? [];
- return (
- <Fragment key={target.className}>
- <Divider />
- <VStack gap={1} style={{paddingBlock: 8}}>
- <Text type="code" weight="bold">
- {configKey(target)}
- </Text>
- <Text type="code" color="secondary">
- .{target.className}
- </Text>
- {dataAttrs.length > 0 && (
- <Text type="supporting" color="secondary">
- Data attrs: {dataAttrs.map(a => `[${a}]`).join(', ')}
+ <Card>
+ <VStack gap={0}>
+ {targets.map(target => {
+ const dataAttrs = targetDataAttributes(target);
+ const propValues = targetPropValues(target, props);
+ const states = target.states ?? [];
+ return (
+ <Fragment key={target.className}>
+ <Divider />
+ <VStack gap={1} style={{paddingBlock: 8}}>
+ <Text type="code" weight="bold">
+ {configKey(target)}
</Text>
- )}
- {propValues.length > 0 && (
- <Text type="supporting" color="secondary">
- Props: {propValues.join(', ')}
+ <Text type="code" color="secondary">
+ .{target.className}
</Text>
- )}
- {states.length > 0 && (
- <Text type="supporting" color="secondary">
- States: {states.join(', ')}
- </Text>
- )}
- </VStack>
- </Fragment>
- );
- })}
- </VStack>
+ {dataAttrs.length > 0 && (
+ <Text type="supporting" color="secondary">
+ Data attrs: {dataAttrs.map(a => `[${a}]`).join(', ')}
+ </Text>
+ )}
+ {propValues.length > 0 && (
+ <Text type="supporting" color="secondary">
+ Props: {propValues.join(', ')}
+ </Text>
+ )}
+ {states.length > 0 && (
+ <Text type="supporting" color="secondary">
+ States: {states.join(', ')}
+ </Text>
+ )}
+ </VStack>
+ </Fragment>
+ );
+ })}
+ </VStack>
+ </Card>
);
}
@@ -96,76 +99,81 @@ function TargetsTable({targets, props}: TargetsTableProps) {
})) as Record<string, unknown>[];
return (
- <Table
- data={data}
- columns={[
- {
- key: 'key',
- header: 'Config key',
- width: pixel(180),
- renderCell: (item: Record<string, unknown>) => (
- <Text type="code" weight="bold" style={{whiteSpace: 'nowrap'}}>
- {item.key as string}
- </Text>
- ),
- },
- {
- key: 'className',
- header: 'Class',
- width: pixel(200),
- renderCell: (item: Record<string, unknown>) => (
- <Text type="code" color="secondary" style={{whiteSpace: 'nowrap'}}>
- .{item.className as string}
- </Text>
- ),
- },
- {
- key: 'dataAttrs',
- header: 'Data attributes',
- width: pixel(220),
- renderCell: (item: Record<string, unknown>) => {
- const attrs = item.dataAttrs as string[];
- return attrs.length > 0 ? (
- <Text type="code" color="secondary">
- {attrs.map(a => `[${a}]`).join(', ')}
+ <Card>
+ <Table
+ data={data}
+ columns={[
+ {
+ key: 'key',
+ header: 'Config key',
+ width: pixel(180),
+ renderCell: (item: Record<string, unknown>) => (
+ <Text type="code" weight="bold" style={{whiteSpace: 'nowrap'}}>
+ {item.key as string}
</Text>
- ) : (
- <Text color="secondary">—</Text>
- );
+ ),
},
- },
- {
- key: 'props',
- header: 'Props',
- renderCell: (item: Record<string, unknown>) => {
- const values = item.props as string[];
- return values.length > 0 ? (
- <Text type="code" color="secondary">
- {values.join(', ')}
+ {
+ key: 'className',
+ header: 'Class',
+ width: pixel(200),
+ renderCell: (item: Record<string, unknown>) => (
+ <Text
+ type="code"
+ color="secondary"
+ style={{whiteSpace: 'nowrap'}}>
+ .{item.className as string}
</Text>
- ) : (
- <Text color="secondary">—</Text>
- );
+ ),
},
- },
- {
- key: 'states',
- header: 'States',
- renderCell: (item: Record<string, unknown>) => {
- const values = item.states as string[];
- return values.length > 0 ? (
- <Text type="code" color="secondary">
- {values.join(', ')}
- </Text>
- ) : (
- <Text color="secondary">—</Text>
- );
+ {
+ key: 'dataAttrs',
+ header: 'Data attributes',
+ width: pixel(220),
+ renderCell: (item: Record<string, unknown>) => {
+ const attrs = item.dataAttrs as string[];
+ return attrs.length > 0 ? (
+ <Text type="code" color="secondary">
+ {attrs.map(a => `[${a}]`).join(', ')}
+ </Text>
+ ) : (
+ <Text color="secondary">—</Text>
+ );
+ },
+ },
+ {
+ key: 'props',
+ header: 'Props',
+ renderCell: (item: Record<string, unknown>) => {
+ const values = item.props as string[];
+ return values.length > 0 ? (
+ <Text type="code" color="secondary">
+ {values.join(', ')}
+ </Text>
+ ) : (
+ <Text color="secondary">—</Text>
+ );
+ },
+ },
+ {
+ key: 'states',
+ header: 'States',
+ renderCell: (item: Record<string, unknown>) => {
+ const values = item.states as string[];
+ return values.length > 0 ? (
+ <Text type="code" color="secondary">
+ {values.join(', ')}
+ </Text>
+ ) : (
+ <Text color="secondary">—</Text>
+ );
+ },
},
- },
- ]}
- density="spacious"
- dividers="rows"
- />
+ ]}
+ density="spacious"
+ dividers="rows"
+ />
+ </Card>
);
}
@@ -178,26 +186,28 @@ function CssVarsTable({vars}: CssVarsTableProps) {
if (isMobile) {
return (
- <VStack gap={0}>
- {vars.map(v => (
- <Fragment key={v.name}>
- <Divider />
- <VStack gap={1} style={{paddingBlock: 8}}>
- <Text type="code" weight="bold">
- {v.name}
- </Text>
- <Text type="code" color="secondary">
- {v.default}
- </Text>
- {v.description && (
- <MarkdownText type="body" color="secondary">
- {v.description}
- </MarkdownText>
- )}
- </VStack>
- </Fragment>
- ))}
- </VStack>
+ <Card>
+ <VStack gap={0}>
+ {vars.map(v => (
+ <Fragment key={v.name}>
+ <Divider />
+ <VStack gap={1} style={{paddingBlock: 8}}>
+ <Text type="code" weight="bold">
+ {v.name}
+ </Text>
+ <Text type="code" color="secondary">
+ {v.default}
+ </Text>
+ {v.description && (
+ <MarkdownText type="body" color="secondary">
+ {v.description}
+ </MarkdownText>
+ )}
+ </VStack>
+ </Fragment>
+ ))}
+ </VStack>
+ </Card>
);
}
@@ -208,42 +218,44 @@ function CssVarsTable({vars}: CssVarsTableProps) {
})) as Record<string, unknown>[];
return (
- <Table
- data={data}
- columns={[
- {
- key: 'name',
- header: 'CSS variable',
- width: pixel(240),
- renderCell: (item: Record<string, unknown>) => (
- <Text type="code" weight="bold" style={{whiteSpace: 'nowrap'}}>
- {item.name as string}
- </Text>
- ),
- },
- {
- key: 'default',
- header: 'Default',
- width: pixel(220),
- renderCell: (item: Record<string, unknown>) => (
- <Text type="code" color="secondary">
- {item.default as string}
- </Text>
- ),
- },
- {
- key: 'description',
- header: 'Description',
- renderCell: (item: Record<string, unknown>) => (
- <MarkdownText type="body">
- {item.description as string}
- </MarkdownText>
- ),
- },
- ]}
- density="spacious"
- dividers="rows"
- />
+ <Card>
+ <Table
+ data={data}
+ columns={[
+ {
+ key: 'name',
+ header: 'CSS variable',
+ width: pixel(240),
+ renderCell: (item: Record<string, unknown>) => (
+ <Text type="code" weight="bold" style={{whiteSpace: 'nowrap'}}>
+ {item.name as string}
+ </Text>
+ ),
+ },
+ {
+ key: 'default',
+ header: 'Default',
+ width: pixel(220),
+ renderCell: (item: Record<string, unknown>) => (
+ <Text type="code" color="secondary">
+ {item.default as string}
+ </Text>
+ ),
+ },
+ {
+ key: 'description',
+ header: 'Description',
+ renderCell: (item: Record<string, unknown>) => (
+ <MarkdownText type="body">
+ {item.description as string}
+ </MarkdownText>
+ ),
+ },
+ ]}
+ density="spacious"
+ dividers="rows"
+ />
+ </Card>
);
}
@@ -270,58 +282,57 @@ export function Theming({theming, props}: ThemingProps) {
const example = hasTargets ? buildDefineThemeExample(theming) : '';
return (
- <Section>
+ <VStack gap={8}>
<VStack gap={4}>
- <VStack gap={2}>
+ <Banner
+ container="card"
+ status="warning"
+ title="Experimental"
+ description="The theming API is experimental and not yet guaranteed — targets, keys, and CSS variables may change while we harden the theme system."
+ />
+ <Text type="large" weight="normal">
+ Restyle this component with a <Text type="code">defineTheme</Text>{' '}
+ config. Target the component through the keys below, or override the
+ CSS variables it exposes.
+ </Text>
+ </VStack>
+
+ {hasTargets && (
+ <VStack gap={4}>
<Heading level={2} type="display-3">
- Theming
+ Theme targets
</Heading>
- <Banner
- container="card"
- status="warning"
- title="Experimental"
- description="The theming API is experimental and not yet guaranteed — targets, keys, and CSS variables may change while we harden the theme system."
- />
- <Text type="large" weight="normal">
- Restyle this component with a <Text type="code">defineTheme</Text>{' '}
- config. Target the component through the keys below, or override the
- CSS variables it exposes.
+ <Text color="secondary">
+ Each target is a key in the <Text type="code">components</Text> map
+ of <Text type="code">defineTheme</Text>. Scope styles to a prop or
+ state with a <Text type="code">prop:value</Text> or state key; use{' '}
+ <Text type="code">base</Text> for all instances.
</Text>
+ <TargetsTable targets={theming.targets} props={props} />
+ {example && (
+ <CodeExampleBlock
+ code={example}
+ language="ts"
+ width="100%"
+ hasCopyButton
+ />
+ )}
</VStack>
+ )}
- {hasTargets && (
- <VStack gap={3}>
- <Heading level={3}>Theme targets</Heading>
- <Text color="secondary">
- Each target is a key in the <Text type="code">components</Text>{' '}
- map of <Text type="code">defineTheme</Text>. Scope styles to a
- prop or state with a <Text type="code">prop:value</Text> or state
- key; use <Text type="code">base</Text> for all instances.
- </Text>
- <TargetsTable targets={theming.targets} props={props} />
- {example && (
- <CodeExampleBlock
- code={example}
- language="ts"
- width="100%"
- hasCopyButton
- />
- )}
- </VStack>
- )}
-
- {hasVars && (
- <VStack gap={3}>
- <Heading level={3}>Themeable CSS variables</Heading>
- <Text color="secondary">
- Additional custom properties this component reads. Override them
- in a <Text type="code">base</Text> block of the component's{' '}
- <Text type="code">defineTheme</Text> config.
- </Text>
- <CssVarsTable vars={vars} />
- </VStack>
- )}
- </VStack>
- </Section>
+ {hasVars && (
+ <VStack gap={4}>
+ <Heading level={2} type="display-3">
+ Themeable CSS variables
+ </Heading>
+ <Text color="secondary">
+ Additional custom properties this component reads. Override them in
+ a <Text type="code">base</Text> block of the component's{' '}
+ <Text type="code">defineTheme</Text> config.
+ </Text>
+ <CssVarsTable vars={vars} />
+ </VStack>
+ )}
+ </VStack>
);
}
diff --git a/apps/docsite/src/components/component-detail/themingHelpers.ts b/apps/docsite/src/components/component-detail/themingHelpers.ts
index 065a540806..406a68d578 100644
--- a/apps/docsite/src/components/component-detail/themingHelpers.ts
+++ b/apps/docsite/src/components/component-detail/themingHelpers.ts
@@ -117,3 +117,16 @@ export function buildDefineThemeExample(theming: ThemingDoc): string {
export function publicVars(theming: ThemingDoc): ComponentVar[] {
return (theming.vars ?? []).filter(v => !v.private && !v.derived);
}
+
+/**
+ * Whether a component has any themeable surface worth documenting — at least
+ * one theme target or one publicly-settable CSS variable. Mirrors the render
+ * gate in Theming.tsx so the "Theming" tab is only shown when the panel would
+ * have content.
+ */
+export function hasThemingContent(theming: ThemingDoc | null): boolean {
+ if (!theming) {
+ return false;
+ }
+ return theming.targets.length > 0 || publicVars(theming).length > 0;
+}