An open source design system that's fully customizable and agent ready
TypeScript
docs(cli): import each Core export from the path `astryx component` prints (#7623)
Joeye26723dcfd02
diff --git a/.changeset/canonical-core-imports.md b/.changeset/canonical-core-imports.mdnew file mode 100644index 0000000000..6912534b65--- /dev/null+++ b/.changeset/canonical-core-imports.md@@ -0,0 +1,12 @@+---+'@astryxdesign/cli': patch+'@astryxdesign/core': patch+---++[docs] Docs and CLI examples import each Core export from the path `astryx component <Name>` prints.++@josephfarina++- `VStack` and `HStack` come from `@astryxdesign/core/VStack` and `@astryxdesign/core/HStack`, `Heading` from `@astryxdesign/core/Heading`, `Text` from `@astryxdesign/core/Text`, and `Theme` and `defineTheme` from `@astryxdesign/core/theme`.+- This covers the guides, the `Card` docs, the next steps `astryx init` prints, the install example `astryx theme build` prints, the wiring example `theme add` prints, the build rules, the theme-module fix `astryx doctor` prints, and the annotated theme template.+- Every path was already exported. Nothing else changes.diff --git a/packages/cli/api/build/help/help.mjs b/packages/cli/api/build/help/help.mjsindex 6a6d07ace6..d1381f0fe7 100644--- a/packages/cli/api/build/help/help.mjs+++ b/packages/cli/api/build/help/help.mjs@@ -63,7 +63,7 @@ export function buildHelp() {"Keep the template's page frame, gap, and padding values. Replace its data, copy, and sections.",'No <div>/raw HTML for layout — use VStack/HStack/Grid/Stack/Card etc.','No style={{}} — use component props, and design tokens for values.',- "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core') and import core reset.css + astryx.css.",+ "Wrap the app in <Theme theme={...}> (import {Theme} from '@astryxdesign/core/theme') and import core reset.css + astryx.css.",],related: [{diff --git a/packages/cli/api/doctor/theme-checks.mjs b/packages/cli/api/doctor/theme-checks.mjsindex f5a0bd7d67..42e8dcf1ba 100644--- a/packages/cli/api/doctor/theme-checks.mjs+++ b/packages/cli/api/doctor/theme-checks.mjs@@ -736,7 +736,7 @@ export async function checkAppThemes(cwd) {label: 'App imports the theme module',status: 'warn',message: `Could not prove that project source imports ${state.module.path}${importEvidence.parseFailures ? `; ${importEvidence.parseFailures} source file(s) could not be parsed` : ''}.`,- fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core', then render <Theme theme={themes[defaultThemeSlug]}>.`,+ fix: `Import {themes, defaultThemeSlug} from the generated module and {Theme} from '@astryxdesign/core/theme', then render <Theme theme={themes[defaultThemeSlug]}>.`,});}diff --git a/packages/cli/api/init/run/run.mjs b/packages/cli/api/init/run/run.mjsindex 6aaf318886..3f6568b2da 100644--- a/packages/cli/api/init/run/run.mjs+++ b/packages/cli/api/init/run/run.mjs@@ -50,11 +50,11 @@ export function getNextSteps(invocation) {` (run \`${invocation} doctor\` to verify)`," 2. Import base styles: import '@astryxdesign/core/reset.css'"," and import '@astryxdesign/core/astryx.css'",- " 3. Import components: import { Button } from '@astryxdesign/core'",+ " 3. Import components: import { Button } from '@astryxdesign/core/Button'",' 4. Add and wire a theme:',' npm install @astryxdesign/theme-neutral',` ${invocation} theme add neutral`,- " import { Theme } from '@astryxdesign/core'",+ " import { Theme } from '@astryxdesign/core/theme'"," import { themes, defaultThemeSlug } from './astryx-themes'",' <Theme theme={themes[defaultThemeSlug]}>...</Theme>',` Extend an imported theme to customize it. Run \`${invocation} theme eject <slug>\` only to fork source.`,diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjsindex ae50d49e25..3823063d49 100644--- a/packages/cli/api/theme/build/build.mjs+++ b/packages/cli/api/theme/build/build.mjs@@ -3093,7 +3093,7 @@ function printBuildTrailer(trailer) {logger.log(`Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):- import { Theme } from '@astryxdesign/core';+ import { Theme } from '@astryxdesign/core/theme';import { ${trailer.exportName} } from '${trailer.jsImport}';import '${trailer.cssImport}';@@ -3103,7 +3103,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours livesOr with a <link> tag:- import { Theme } from '@astryxdesign/core';+ import { Theme } from '@astryxdesign/core/theme';import { ${trailer.exportName} } from '${trailer.jsImport}';<link rel="stylesheet" href="${trailer.cssImport}" />@@ -3129,7 +3129,7 @@ export function printBatchTrailer(trailers) {logger.log(`Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):- import { Theme } from '@astryxdesign/core';+ import { Theme } from '@astryxdesign/core/theme';import { ${first.exportName} } from '${first.jsImport}';import '${first.cssImport}';@@ -3139,7 +3139,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours livesOr with a <link> tag:- import { Theme } from '@astryxdesign/core';+ import { Theme } from '@astryxdesign/core/theme';import { ${first.exportName} } from '${first.jsImport}';<link rel="stylesheet" href="${first.cssImport}" />diff --git a/packages/cli/assets/docs/README.md b/packages/cli/assets/docs/README.mdindex 4d8a96be36..8f753b09bd 100644--- a/packages/cli/assets/docs/README.md+++ b/packages/cli/assets/docs/README.md@@ -51,6 +51,16 @@ The material is usually good; the finding is placement, not quality. It goes inWorked example: a responsive-and-interaction readiness rubric is grading criteria → **Component-Audit-Rubric**, or **Component-Lifecycle** if it is a promotion gate.+## Imports in code samples++Import each Core export from the path `astryx component <Name>` prints: the+component's own entry when Core has one (`@astryxdesign/core/VStack`,+`@astryxdesign/core/Heading`), and `@astryxdesign/core/theme` for `Theme`,+`defineTheme` and the rest of the theme API. A reader copies one sample and then+reads `astryx component`, and two paths for one export read as two different+things. The no-build CDN page is the exception: its import map names only the+package root.+## Sections are read one at a time`astryx docs <topic> --index` lists a topic's sections, and readers then opendiff --git a/packages/cli/assets/docs/author-a-theme.doc.mjs b/packages/cli/assets/docs/author-a-theme.doc.mjsindex 9b7c8f5667..8b02dfce48 100644--- a/packages/cli/assets/docs/author-a-theme.doc.mjs+++ b/packages/cli/assets/docs/author-a-theme.doc.mjs@@ -120,7 +120,7 @@ export const docs = {['ocean.variants.d.ts', "(Optional) Module augmentations for custom component prop values"],]},{type: 'prose', text: 'The `__built: true` flag tells Theme to skip runtime `<style>` injection; the CSS file handles it. Load the generated CSS wherever you load the module.'},- {type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n <App />\n</Theme>"},+ {type: 'code', lang: 'tsx', label: 'Using a custom built theme', code: "import {Theme} from '@astryxdesign/core/theme';\nimport {oceanTheme} from './themes/ocean';\nimport './themes/ocean.css';\n\n<Theme theme={oceanTheme}>\n <App />\n</Theme>"},{type: 'prose', text: "After upgrading Astryx, rerun `astryx theme build` for every custom prebuilt theme. Deploy the regenerated files together. The runtime intentionally trusts `__built: true` and will not repair stale CSS from an older build. The build also warns when the theme names font families it does not load. See {@link generic:font-setup} for the full recipe."},{type: 'prose', text: 'For the runtime vs built tradeoff, see the Runtime vs Built section of {@link generic:use-a-theme}.'},],diff --git a/packages/cli/assets/docs/getting-started.doc.mjs b/packages/cli/assets/docs/getting-started.doc.mjsindex 93a9a8efc3..3c8a11bce1 100644--- a/packages/cli/assets/docs/getting-started.doc.mjs+++ b/packages/cli/assets/docs/getting-started.doc.mjs@@ -86,7 +86,7 @@ export const docs = {type: 'code',lang: 'tsx',label: 'App root',- code: `import {Theme} from '@astryxdesign/core';+ code: `import {Theme} from '@astryxdesign/core/theme';import {themes, defaultThemeSlug} from './astryx-themes';<Theme theme={themes[defaultThemeSlug]}><App /></Theme>`,@@ -119,14 +119,14 @@ import {themes, defaultThemeSlug} from './astryx-themes';content: [{type: 'prose',- text: 'Components are imported from per-category subpath entrypoints. This keeps bundles small and makes intent clear.',+ text: 'Import each component from its own entry, the path `astryx component <Name>` prints. This keeps bundles small and makes intent clear.',},{type: 'code',lang: 'tsx',label: 'app/page.tsx',code: `import {Button} from '@astryxdesign/core/Button';-import {VStack} from '@astryxdesign/core/Layout';+import {VStack} from '@astryxdesign/core/VStack';export default function Page() {return (diff --git a/packages/cli/assets/docs/theme.doc.dense.mjs b/packages/cli/assets/docs/theme.doc.dense.mjsindex 5f48c1491d..6aa26a666d 100644--- a/packages/cli/assets/docs/theme.doc.dense.mjs+++ b/packages/cli/assets/docs/theme.doc.dense.mjs@@ -9,7 +9,7 @@ export const docsDense = {section: 'Wrap your app in a theme',title: 'Quick start',content: [- {type: 'prose', text: "Install a theme, wrap in `<Theme>` (`import {Theme} from '@astryxdesign/core'`). {@link generic:use-a-theme} for full guide."},+ {type: 'prose', text: "Install a theme, wrap in `<Theme>` (`import {Theme} from '@astryxdesign/core/theme'`). {@link generic:use-a-theme} for full guide."},],},{diff --git a/packages/cli/assets/docs/theme.doc.mjs b/packages/cli/assets/docs/theme.doc.mjsindex 00b18617f0..6370536f19 100644--- a/packages/cli/assets/docs/theme.doc.mjs+++ b/packages/cli/assets/docs/theme.doc.mjs@@ -23,7 +23,7 @@ export const docs = {type: 'code',lang: 'tsx',label: 'Wire the generated module once',- code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n <Theme theme={themes[defaultThemeSlug]}>\n <YourApp />\n </Theme>\n );\n}",+ code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n <Theme theme={themes[defaultThemeSlug]}>\n <YourApp />\n </Theme>\n );\n}",},],},diff --git a/packages/cli/assets/docs/theme.doc.zh.mjs b/packages/cli/assets/docs/theme.doc.zh.mjsindex 79193d8a99..2bdd7f9e51 100644--- a/packages/cli/assets/docs/theme.doc.zh.mjs+++ b/packages/cli/assets/docs/theme.doc.zh.mjs@@ -11,7 +11,7 @@ export const docsZh = {content: [{type: 'prose',- text: "安装主题包,用 `<Theme>`(`import {Theme} from '@astryxdesign/core'`)包裹应用,选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。",+ text: "安装主题包,用 `<Theme>`(`import {Theme} from '@astryxdesign/core/theme'`)包裹应用,选择浅色或深色模式。完整指南——可用主题、集成主题、深色模式、嵌套主题和生产构建——请参阅 {@link generic:use-a-theme}。",},],},diff --git a/packages/cli/assets/docs/tree/type-scale.doc.mjs b/packages/cli/assets/docs/tree/type-scale.doc.mjsindex 127be39399..f907f9246b 100644--- a/packages/cli/assets/docs/tree/type-scale.doc.mjs+++ b/packages/cli/assets/docs/tree/type-scale.doc.mjs@@ -76,7 +76,7 @@ export const docs = {type: 'code',lang: 'tsx',label: 'Heading for document structure',- code: `import {Heading} from '@astryxdesign/core';+ code: `import {Heading} from '@astryxdesign/core/Heading';// Heading levels map to semantic tokens: level 1 → --text-heading-1-*<Heading level={1}>Page Title</Heading>@@ -96,7 +96,7 @@ export const docs = {type: 'code',lang: 'tsx',label: 'Text for body, label, and display text',- code: `import {Text} from '@astryxdesign/core';+ code: `import {Text} from '@astryxdesign/core/Text';<Text type="body">Body text at the base scale.</Text><Text type="large">Emphasized body text.</Text>@@ -121,7 +121,7 @@ export const docs = {type: 'code',lang: 'tsx',label: 'Customizing the type scale via defineTheme',- code: `import {defineTheme} from '@astryxdesign/core';+ code: `import {defineTheme} from '@astryxdesign/core/theme';// Adjust the entire ramp holistically with base and ratioconst editorialTheme = defineTheme({diff --git a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjsindex f0c9fb7b51..33e48f284b 100644--- a/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs+++ b/packages/cli/assets/docs/tree/write-the-template-file.doc.mjs@@ -91,8 +91,9 @@ npx astryx template acme-stat-card src/features/account/StatusCard.tsx`,lang: 'tsx',code: `import {Button} from '@astryxdesign/core/Button';import {Card} from '@astryxdesign/core/Card';-import {HStack, VStack} from '@astryxdesign/core/Stack';+import {HStack} from '@astryxdesign/core/HStack';import {Text} from '@astryxdesign/core/Text';+import {VStack} from '@astryxdesign/core/VStack';import {AcmeStatusCard} from '@acme/astryx-widgets/components/AcmeStatusCard';const metrics = [diff --git a/packages/cli/assets/docs/use-a-theme.doc.mjs b/packages/cli/assets/docs/use-a-theme.doc.mjsindex 6d5d48e583..2fe7cf9f7f 100644--- a/packages/cli/assets/docs/use-a-theme.doc.mjs+++ b/packages/cli/assets/docs/use-a-theme.doc.mjs@@ -25,13 +25,13 @@ export const docs = {type: 'code',lang: 'tsx',label: 'Wire the generated module once',- code: "import {Theme} from '@astryxdesign/core';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n <Theme theme={themes[defaultThemeSlug]}>\n <YourApp />\n </Theme>\n );\n}",+ code: "import {Theme} from '@astryxdesign/core/theme';\nimport {themes, defaultThemeSlug} from './astryx-themes';\n\nfunction App() {\n return (\n <Theme theme={themes[defaultThemeSlug]}>\n <YourApp />\n </Theme>\n );\n}",},{type: 'code',lang: 'tsx',label: 'Switch among added themes',- code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",+ code: "import {useState} from 'react';\nimport {Theme} from '@astryxdesign/core/theme';\nimport {themes, type ThemeSlug} from './astryx-themes';\n\nconst [slug, setSlug] = useState<ThemeSlug>('neutral');\nconst app = <Theme theme={themes[slug]}><YourApp /></Theme>;",},{type: 'prose',diff --git a/packages/cli/assets/theme.template.ts b/packages/cli/assets/theme.template.tsindex d3ff822ea2..bb8552d1a6 100644--- a/packages/cli/assets/theme.template.ts+++ b/packages/cli/assets/theme.template.ts@@ -18,7 +18,7 @@** 1. WRAP THE APP. A theme does nothing until it is provided.*- * import {Theme} from '@astryxdesign/core';+ * import {Theme} from '@astryxdesign/core/theme';* import {myTheme} from './theme';** <Theme theme={myTheme} mode="system"> // 'system' | 'light' | 'dark'diff --git a/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs b/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjsindex ef0d358778..fd0b6356ed 100644--- a/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs+++ b/packages/cli/clients/cli/commands/build-theme.batch-report.test.mjs@@ -168,7 +168,9 @@ describe('theme build report', () => {}expect(count(out, 'Install in your app')).toBe(1);expect(count(out, 'Or with a <link> tag:')).toBe(1);- expect(count(out, "import { Theme } from '@astryxdesign/core';")).toBe(2);+ expect(+ count(out, "import { Theme } from '@astryxdesign/core/theme';"),+ ).toBe(2);expect(count(out, '[note]')).toBe(1);expect(count(out, 'note: Font')).toBe(0);expect(count(out, 'fonts.googleapis.com/css2')).toBe(1);diff --git a/packages/cli/clients/cli/commands/build-theme.mjs b/packages/cli/clients/cli/commands/build-theme.mjsindex 3eec657afb..6252d24a03 100644--- a/packages/cli/clients/cli/commands/build-theme.mjs+++ b/packages/cli/clients/cli/commands/build-theme.mjs@@ -397,7 +397,7 @@ function printThemeApp(result) {emit(text('Wire the generated module once in the app root:'),code(- "import {Theme} from '@astryxdesign/core';\n" ++ "import {Theme} from '@astryxdesign/core/theme';\n" +`import {themes, defaultThemeSlug} from './${stem}';\n\n` +'<Theme theme={themes[defaultThemeSlug]}>\n <App />\n</Theme>',),diff --git a/packages/cli/test/__golden__/theme-build-batch-full.txt b/packages/cli/test/__golden__/theme-build-batch-full.txtindex a6e385aceb..48b4cb1310 100644--- a/packages/cli/test/__golden__/theme-build-batch-full.txt+++ b/packages/cli/test/__golden__/theme-build-batch-full.txt@@ -136,7 +136,7 @@ Building theme from themes/orchid.mjs...Install in your app (paths are relative to a file in src/; adjust if yours lives elsewhere):- import { Theme } from '@astryxdesign/core';+ import { Theme } from '@astryxdesign/core/theme';import { amberTheme } from './themes/amber';import './themes/amber.css';@@ -146,7 +146,7 @@ Install in your app (paths are relative to a file in src/; adjust if yours livesOr with a <link> tag:- import { Theme } from '@astryxdesign/core';+ import { Theme } from '@astryxdesign/core/theme';import { amberTheme } from './themes/amber';<link rel="stylesheet" href="./themes/amber.css" />diff --git a/packages/cli/test/taught-core-imports.test.mjs b/packages/cli/test/taught-core-imports.test.mjsindex b71f31582e..bfb64b77ed 100644--- a/packages/cli/test/taught-core-imports.test.mjs+++ b/packages/cli/test/taught-core-imports.test.mjs@@ -8,8 +8,8 @@* names a subpath Core does not export, or names it with the wrong case, fails* in the user's app, so every specifier must match an entry in Core's* package.json `exports`. Wherever command output shows the `<Theme>` wrapper,- * it also shows where `Theme` comes from, and so does every doc page that shows- * it.+ * it also shows that `Theme` comes from `@astryxdesign/core/theme`, the path+ * `astryx component Theme` prints, and so does every doc page that shows it.** @position packages/cli/test — taught imports*/@@ -64,8 +64,7 @@ function isExported(keys, subpath) {});}-const THEME_IMPORT =- /\{\s*Theme\s*\}\s+from\s+'@astryxdesign\/core(?:\/theme)?'/;+const THEME_IMPORT = /\{\s*Theme\s*\}\s+from\s+'@astryxdesign\/core\/theme'/;/*** Every code block (`{type: 'code', code}`) reachable from a doc module.@@ -145,9 +144,7 @@ describe('taught @astryxdesign/core imports', () => {Math.max(previous, index - 400),lineEnd === -1 ? source.length : lineEnd,);- expect(nearby, `${file} at offset ${index}`).toMatch(- /\{\s*Theme\s*\}\s+from\s+'@astryxdesign\/core'/,- );+ expect(nearby, `${file} at offset ${index}`).toMatch(THEME_IMPORT);});},);diff --git a/packages/core/src/Card/Card.doc.mjs b/packages/core/src/Card/Card.doc.mjsindex 247552e656..7dadbb2592 100644--- a/packages/core/src/Card/Card.doc.mjs+++ b/packages/core/src/Card/Card.doc.mjs@@ -83,7 +83,7 @@ export const docs = {code: `import {Card} from '@astryxdesign/core/Card';import {Grid} from '@astryxdesign/core/Grid';-import {VStack} from '@astryxdesign/core/Layout';+import {VStack} from '@astryxdesign/core/VStack';import {Heading} from '@astryxdesign/core/Heading';import {Text} from '@astryxdesign/core/Text';