Skip to content

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

TypeScript

fix(cli): reject custom Heading types with no usable declaration (#6547)

Joeyec4f9a3c76a8
diff --git a/.changeset/cli-spec-heading-type-meaningful-rule.md b/.changeset/cli-spec-heading-type-meaningful-rule.md
new file mode 100644
index 0000000000..da7a2c4b49
--- /dev/null
+++ b/.changeset/cli-spec-heading-type-meaningful-rule.md
@@ -0,0 +1,7 @@
+---
+'@astryxdesign/cli': patch
+---
+
+[fix] `astryx theme build` now fails with `ERR_THEME_INVALID`, before writing anything, when a custom Heading type's standalone rule has no usable declaration: every value is blank, or the compiler dropped every declaration. It previously wrote CSS with an empty or missing rule and still added the type to the generated `HeadingTypeMap`.
+
+@josephfarina
diff --git a/packages/cli/api/theme/build/build.mjs b/packages/cli/api/theme/build/build.mjs
index 7e33a1e192..a0df9d5df5 100644
--- a/packages/cli/api/theme/build/build.mjs
+++ b/packages/cli/api/theme/build/build.mjs
@@ -1931,20 +1931,7 @@ function getThemeComponentLayers(themeDef) {
*/
function validateCustomHeadingTypes(themeDef) {
const layers = getThemeComponentLayers(themeDef);
- const customTypes = new Set();
- for (const {components} of layers) {
- const headingRules = components.heading;
- if (!headingRules || typeof headingRules !== 'object') continue;
-
- for (const key of Object.keys(headingRules)) {
- for (const pair of key.split('+')) {
- const colon = pair.indexOf(':');
- if (colon === -1 || pair.slice(0, colon) !== 'type') continue;
- const value = pair.slice(colon + 1);
- if (value && !BUILTIN_HEADING_TYPES.has(value)) customTypes.add(value);
- }
- }
- }
+ const customTypes = customHeadingTypes(themeDef);
const errors = [];
for (const type of customTypes) {
@@ -1971,10 +1958,65 @@ function validateCustomHeadingTypes(themeDef) {
return errors;
}
+/**
+ * Custom Heading type names declared on the root or media-surface component
+ * maps: the names the generated `HeadingTypeMap` augmentation enrolls.
+ *
+ * @param {{components?: Record<string, Record<string, unknown>>}} themeDef
+ * @returns {Set<string>}
+ */
+function customHeadingTypes(themeDef) {
+ /** @type {Set<string>} */
+ const customTypes = new Set();
+ for (const {components} of getThemeComponentLayers(themeDef)) {
+ const headingRules = components.heading;
+ if (!headingRules || typeof headingRules !== 'object') continue;
+
+ for (const key of Object.keys(headingRules)) {
+ for (const pair of key.split('+')) {
+ const colon = pair.indexOf(':');
+ if (colon === -1 || pair.slice(0, colon) !== 'type') continue;
+ const value = pair.slice(colon + 1);
+ if (value && !BUILTIN_HEADING_TYPES.has(value)) customTypes.add(value);
+ }
+ }
+ }
+ return customTypes;
+}
+
+/**
+ * Custom Heading types with no standalone rule in the generated CSS. A type
+ * whose every declaration the compiler dropped still passes the source check,
+ * and its augmentation would then name a type that has no styles.
+ *
+ * @param {Set<string>} types
+ * @param {string} css - Generated root component and media-surface rules.
+ * @returns {string[]}
+ */
+function headingTypesWithoutEmittedRule(types, css) {
+ /** @type {string[]} */
+ const missing = [];
+ for (const type of types) {
+ const selector = `.astryx-heading[data-type="${type}"]`;
+ let emitted = false;
+ for (
+ let at = css.indexOf(selector);
+ at !== -1 && !emitted;
+ at = css.indexOf(selector, at + 1)
+ ) {
+ // A following attribute is a combined selector, not the standalone rule.
+ emitted = css[at + selector.length] !== '[';
+ }
+ if (!emitted) missing.push(type);
+ }
+ return missing;
+}
+
/**
* Return true when a style object contains a declaration that the theme
- * generator can emit. Empty pseudo blocks do not count: they produce no CSS
- * and would leave the generated type augmentation without a usable rule.
+ * generator can emit. Empty pseudo blocks and blank values do not count: they
+ * produce no usable CSS and would leave the generated type augmentation
+ * without a usable rule.
*
* @param {unknown} styles
* @returns {boolean}
@@ -1988,7 +2030,12 @@ function hasUsableStyleDeclaration(styles) {
if (hasUsableStyleDeclaration(value)) return true;
continue;
}
- if (value !== undefined && value !== null && typeof value !== 'object') {
+ if (
+ value !== undefined &&
+ value !== null &&
+ typeof value !== 'object' &&
+ String(value).trim() !== ''
+ ) {
return true;
}
}
@@ -2387,6 +2434,25 @@ async function themeBuildInternal(
warningMessages.push(w);
logger.warn(` [warn] ${w}`);
}
+ const unemittedHeadingTypes = headingTypesWithoutEmittedRule(
+ customHeadingTypes(themeDef),
+ `${component.join('\n')}\n${onMediaCss}`,
+ );
+ if (unemittedHeadingTypes.length > 0) {
+ throw new AstryxError(
+ unemittedHeadingTypes
+ .map(
+ type =>
+ `Custom Heading type "${type}" has no declaration the theme ` +
+ `compiler could emit: every declaration in its standalone ` +
+ `"type:${type}" rule was dropped. Give that rule at least one ` +
+ 'valid declaration.',
+ )
+ .join('\n'),
+ undefined,
+ ERROR_CODES.ERR_THEME_INVALID,
+ );
+ }
if (cssParts.length === 0) {
logger.log('No overrides found; nothing to build.');
return null;
diff --git a/packages/cli/api/theme/themeBuild.doc.mjs b/packages/cli/api/theme/themeBuild.doc.mjs
index e87b034bca..758f9b97ff 100644
--- a/packages/cli/api/theme/themeBuild.doc.mjs
+++ b/packages/cli/api/theme/themeBuild.doc.mjs
@@ -87,7 +87,10 @@ export const doc = {
code: 'ERR_THEME_LOAD',
when: 'the file cannot be loaded or parsed into a defineTheme() result',
},
- {code: 'ERR_THEME_INVALID', when: 'the resolved theme has no name'},
+ {
+ code: 'ERR_THEME_INVALID',
+ when: 'the resolved theme is invalid, for example it has no name, or a custom Heading type has no standalone rule with a declaration the compiler can emit',
+ },
{
code: 'ERR_PATH_TRAVERSAL',
when: 'the theme name contains a path separator or traversal marker',
diff --git a/packages/cli/clients/cli/commands/build-theme.variants.test.mjs b/packages/cli/clients/cli/commands/build-theme.variants.test.mjs
index 1a386314d1..d0ea6f8e71 100644
--- a/packages/cli/clients/cli/commands/build-theme.variants.test.mjs
+++ b/packages/cli/clients/cli/commands/build-theme.variants.test.mjs
@@ -324,6 +324,82 @@ describe('theme build custom-variant augmentations', () => {
);
});
+ it('rejects a custom Heading type whose only declaration is blank', async () => {
+ const themeFile = writeTheme(
+ tmpDir,
+ `export default {
+ name: 'variants-theme',
+ tokens: { '--color-bg': '#fff' },
+ components: { heading: { 'type:hero': { fontSize: '' } } },
+ };\n`,
+ );
+
+ const result = await runCli(
+ ['theme', 'build', path.relative(tmpDir, themeFile)],
+ tmpDir,
+ );
+
+ expect(result.code).toBe(1);
+ expect(result.stderr).toContain(
+ 'Custom Heading type "hero" needs a non-empty standalone',
+ );
+ expect(fs.existsSync(path.join(tmpDir, 'variants-theme.css'))).toBe(false);
+ });
+
+ it('rejects a custom Heading type whose every declaration the compiler drops', async () => {
+ const themeFile = writeTheme(
+ tmpDir,
+ `export default {
+ name: 'variants-theme',
+ tokens: { '--color-bg': '#fff' },
+ components: {
+ heading: { 'type:hero': { color: 'red; } body { color: blue' } },
+ },
+ };\n`,
+ );
+
+ const result = await runCli(
+ ['--json', 'theme', 'build', path.relative(tmpDir, themeFile)],
+ tmpDir,
+ );
+
+ expect(result.code).toBe(1);
+ const envelope = JSON.parse(result.stdout);
+ expect(envelope.code).toBe('ERR_THEME_INVALID');
+ expect(envelope.error).toContain('Custom Heading type "hero"');
+ expect(fs.existsSync(path.join(tmpDir, 'variants-theme.css'))).toBe(false);
+ expect(
+ fs.existsSync(path.join(tmpDir, 'variants-theme.variants.d.ts')),
+ ).toBe(false);
+ });
+
+ it('builds a custom Heading type that keeps one valid declaration', async () => {
+ const themeFile = writeTheme(
+ tmpDir,
+ `export default {
+ name: 'variants-theme',
+ tokens: { '--color-bg': '#fff' },
+ components: {
+ heading: {
+ 'type:hero': { fontSize: '80px', color: 'red; } body { color: blue' },
+ },
+ },
+ };\n`,
+ );
+
+ const result = await runCli(
+ ['--json', 'theme', 'build', path.relative(tmpDir, themeFile)],
+ tmpDir,
+ );
+
+ expect(result.code).toBe(0);
+ const envelope = JSON.parse(result.stdout);
+ expect(envelope.data.outputs.variantsDts).toBe(
+ 'variants-theme.variants.d.ts',
+ );
+ expect(envelope.data.warnings.join('\n')).toContain('Declaration dropped');
+ });
+
it('makes generated custom component prop values type-check through public subpaths', async () => {
const themeFile = writeTheme(
tmpDir,