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.tsindex 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.tsxindex 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.tsxindex 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.tsindex 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;+}