Theme: Inline values for primitive tokens in CSS output

packages/theme/bin/terrazzo-plugin-ds-tokens-docs/index.ts

@@ -4,10 +4,6 @@
 import { FORMAT_ID } from '@terrazzo/plugin-css';
 import type { Plugin } from '@terrazzo/parser';
 
-function isPrivateToken( token: string ) {
-	return /-private-/i.test( token );
-}
-
 function titleCase( str: string ) {
 	return str[ 0 ].toUpperCase() + str.slice( 1 );
 }
@@ -24,7 +20,6 @@ export default function pluginDsTokenDocs( {
 				return;
 			}
 
-			const primitiveTokens: TokensMap = {};
 			const semanticTokens: TokensMap = {};
 			// Re-use transformed tokens from the CSS plugin
 			for ( const token of getTransforms( {
@@ -46,24 +41,16 @@ export default function pluginDsTokenDocs( {
 						.at( -1 )
 						?.split( '.json' )[ 0 ] ?? 'Miscellaneous';
 
-				// Organize tokens in semantic/private, and group by category.
-				const tokensObject = isPrivateToken( token.localID )
-					? primitiveTokens
-					: semanticTokens;
-				tokensObject[ group ] ??= {};
-				tokensObject[ group ][ token.localID ] =
+				// Group by category
+				semanticTokens[ group ] ??= {};
+				semanticTokens[ group ][ token.localID ] =
 					token.token.$description ?? 'N/A';
 			}
 
-			function tokensToMdTable(
-				tokens: TokensMap,
-				isPrivate: boolean = false
-			) {
+			function tokensToMdTable( tokens: TokensMap ) {
 				return Object.entries( tokens )
 					.map( ( [ group, tokensInGroup ] ) => [
-						`### ${ titleCase( group ) }${
-							isPrivate ? ' (private)' : ''
-						}`,
+						`### ${ titleCase( group ) }`,
 						'',
 						'| Variable name | Description |',
 						'|---|---|',
@@ -89,12 +76,6 @@ export default function pluginDsTokenDocs( {
 					'## Semantic tokens',
 					'',
 					...tokensToMdTable( semanticTokens ),
-					'',
-					'## Primitive tokens',
-					'',
-					'**🚨 Note: These tokens are only private implementation details of the Theme, and should never be referenced / consumed directly in the code.**',
-					'',
-					...tokensToMdTable( primitiveTokens, true ),
 					'', // final empty line
 				].join( '\n' )
 			);

packages/theme/bin/terrazzo-plugin-inline-alias-values/index.ts

@@ -0,0 +1,84 @@
+/**
+ * External dependencies
+ */
+import { type Plugin } from '@terrazzo/parser';
+
+interface InlineAliasValuesOptions {
+	/**
+	 * Output filename for the generated aliased tokens mapping.
+	 */
+	filename?: string;
+
+	/**
+	 * Pattern matching IDs of tokens whose values should be inlined into their alias references.
+	 */
+	pattern: RegExp;
+
+	/**
+	 * Optional function to transform token IDs in the output.
+	 */
+	tokenId?: ( tokenId: string ) => string;
+}
+
+/**
+ * Inlines the values of tokens matching the given pattern into their alias
+ * references. Matching tokens are removed from the output, and a TypeScript
+ * file is emitted with the mapping of aliased tokens.
+ *
+ * @param options          The options for the plugin.
+ * @param options.filename
+ * @param options.pattern
+ * @param options.tokenId
+ */
+export default function inlineAliasValues( {
+	filename,
+	pattern,
+	tokenId = ( id ) => id,
+}: InlineAliasValuesOptions ): Plugin {
+	const aliasedBy: Record< string, string[] > = {};
+
+	return {
+		name: '@wordpress/terrazzo-plugin-inline-alias-values',
+		async transform( { tokens } ) {
+			Object.keys( tokens )
+				.filter( ( id ) => pattern.test( id ) )
+				.forEach( ( id ) => {
+					const token = tokens[ id ];
+					if ( token.aliasedBy ) {
+						aliasedBy[ tokenId( id ) ] =
+							token.aliasedBy.map( tokenId );
+
+						for ( const aliasedId of token.aliasedBy ) {
+							Object.assign( tokens[ aliasedId ], {
+								$value: token.$value,
+								mode: token.mode,
+								originalValue: token.originalValue,
+							} );
+						}
+					}
+
+					delete tokens[ id ];
+				} );
+		},
+		async build( { outputFile } ) {
+			if ( ! filename ) {
+				return;
+			}
+
+			const json = JSON.stringify( aliasedBy, null, 2 );
+
+			outputFile(
+				filename,
+				[
+					'/**',
+					' * This file is generated by the @wordpress/terrazzo-plugin-inline-alias-values plugin.',
+					' * Do not edit this file directly.',
+					' */',
+					'',
+					`export default ${ json } as Record< string, string[] >;`,
+					'',
+				].join( '\n' )
+			);
+		},
+	};
+}

packages/theme/bin/terrazzo-plugin-known-wpds-css-variables/index.ts

@@ -4,12 +4,8 @@
 import { FORMAT_ID } from '@terrazzo/plugin-css';
 import type { Plugin } from '@terrazzo/parser';
 
-function isPrivateToken( token: string ) {
-	return /-private-/i.test( token );
-}
-
 export default function pluginKnownWpdsCssVariables( {
-	exports = [ { filename: 'design-tokens.js', modes: false } ],
+	filename = 'design-tokens.js',
 } = {} ): Plugin {
 	return {
 		name: '@terrazzo/plugin-known-wpds-css-variables',
@@ -31,42 +27,26 @@ export default function pluginKnownWpdsCssVariables( {
 					continue;
 				}
 
-				if ( ! isPrivateToken( token.localID ) ) {
-					tokensToExport[ token.localID ] ??= {};
-
-					tokensToExport[ token.localID ][ token.mode ] = token.value;
-				}
+				tokensToExport[ token.localID ] ??= {};
+				tokensToExport[ token.localID ][ token.mode ] = token.value;
 			}
 
-			const exportsAsArray = ! Array.isArray( exports )
-				? [ exports ]
-				: exports;
-			for ( const { filename, modes } of exportsAsArray ) {
-				outputFile(
-					filename,
-					[
-						'/**',
-						' * This file is generated by the @terrazzo/plugin-known-wpds-css-variables plugin.',
-						' * Do not edit this file directly.',
-						' */',
-						'',
-						`export default ${ JSON.stringify(
-							modes === false
-								? Array.from(
-										new Set( Object.keys( tokensToExport ) )
-								  )
-								: tokensToExport,
-							null,
-							2
-						) }${
-							filename.endsWith( '.ts' ) && modes
-								? ' as Record< string, Record< string, string > >'
-								: ''
-						}`,
-						'', // final empty line
-					].join( '\n' )
-				);
-			}
+			outputFile(
+				filename,
+				[
+					'/**',
+					' * This file is generated by the @terrazzo/plugin-known-wpds-css-variables plugin.',
+					' * Do not edit this file directly.',
+					' */',
+					'',
+					`export default ${ JSON.stringify(
+						Array.from( new Set( Object.keys( tokensToExport ) ) ),
+						null,
+						2
+					) }`,
+					'', // final empty line
+				].join( '\n' )
+			);
 		},
 	};
 }