@jk2908/cxx 0.3.6 → 0.4.0

package/src/build.ts

@@ -1,13 +1,14 @@
 import type { Dirent } from 'node:fs'
 
 import { createHash } from 'node:crypto'
+import { mkdirSync, writeFileSync } from 'node:fs'
 import fs from 'node:fs/promises'
 import path from 'node:path'
 
 import { transform } from 'lightningcss'
 import MagicString, { type SourceMap } from 'magic-string'
 
-import type { PluginConfig, Tags } from './types.js'
+import type { EmbedStyleDescriptor, PluginConfig, Tags } from './types.js'
 import { AUTOGEN_MSG, GENERATED_DIR, NAME, PKG_NAME } from './config.js'
 import { Logger } from './logger.js'
 import { LruCache } from './lru.js'
@@ -22,11 +23,17 @@ const encoder = new TextEncoder()
  * LRU cache of `collect` results by file id + last seen source + config so watcher and transform
  * can reuse the same parsed template/tags.
  */
+export type StyleSheet = {
+	hash: string
+	css: string
+}
+
 const collectCache = new LruCache<{
 	source: string
 	config: string
 	template: string
 	tags: Tags
+	sheets: StyleSheet[]
 	map: SourceMap | null
 }>()
 
@@ -94,19 +101,20 @@ export async function maybeWrite(filePath: string, content: string) {
 	return true
 }
 
-// matches `[css, classes, href] = cxx\`...\`` and `cxx.tag<T>('name')\`...\``
-// capture groups: 1 optional `export `, 2-4 assigned variable names, 5 plain
-// css body, 6 quote kind, 7 tag name, 8 tagged css body
+// matches cxx.embed and cxx.extract, with an optional `.tag('name')`.
+// capture groups: 1 mode, 2 quote kind, 3 tag name, 4 css body
 const regex =
-	/((?:export\s+)?)(?:const|var|let)\s*\[(\w*)\s*,?\s*(\w*)\s*,?\s*(\w*)\s*\]\s*=\s*cxx(?:\s*`([\s\S]*?)`|\s*\.\s*tag(?:\s*<[^>]+>)?\s*\(\s*(['"])(.*?)\6\s*\)\s*`([\s\S]*?)`)/gm
+	/\bcxx\.(embed|extract)(?:\.tag(?:\s*<[^>]+>)?\s*\(\s*(['"])(.*?)\2\s*\))?\s*`([\s\S]*?)`/g
 
 const IDENTIFIER = /^[A-Za-z_$][A-Za-z0-9_$]*$/
 
 /**
- * Hash transformed CSS into a stable href for style deduplication.
+ * Hash transformed CSS into a stable href and asset key.
  */
 function hashCss(code: Uint8Array) {
-	return `cxx-${createHash('sha256').update(code).digest('base64url').slice(0, 12)}`
+	const hash = createHash('sha256').update(code).digest('base64url').slice(0, 12)
+
+	return { href: `cxx-${hash}`, key: hash }
 }
 
 export class DuplicateTagError extends Error {
@@ -139,6 +147,7 @@ export function collect(source: string, id: string, config: PluginConfig) {
 	if (cached?.source === source && cached.config === configKey) return cached
 
 	const tags: Tags = new Map()
+	const sheets: StyleSheet[] = []
 	const magic = new MagicString(source)
 
 	let matched = false
@@ -152,9 +161,8 @@ export function collect(source: string, id: string, config: PluginConfig) {
 	while ((match = regex.exec(source))) {
 		matched = true
 
-		// capture groups: export, three bindings, plain css, (quote), tag, tagged css
-		const [, exp, varOne, varTwo, varThree, plainCss, , tag, taggedCss] = match
-		const css = plainCss ?? taggedCss
+		const [, rawMode, , tag, css] = match
+		const mode = rawMode === 'extract' ? 'extract' : 'embed'
 		const matchIndex = match.index
 
 		// compile the CSS to minified CSS Modules, reporting the source line on failure
@@ -172,7 +180,9 @@ export function collect(source: string, id: string, config: PluginConfig) {
 			}
 		})()
 
-		const href = hashCss(code)
+		const { href, key } = hashCss(code)
+		const cssText = decoder.decode(code)
+
 		// map each class name to its generated (scoped) name
 		const styles = Object.fromEntries(
 			Object.entries(classExports).map(([k, v]) => [k, v.name]),
@@ -194,22 +204,23 @@ export function collect(source: string, id: string, config: PluginConfig) {
 			tags.set(tagWithSuffix, Object.keys(styles))
 		}
 
-		const statements: string[] = []
+		let replacement: string
 
-		if (varOne) {
-			statements.push(`${exp}const ${varOne} = ${JSON.stringify(decoder.decode(code))}`)
-		}
-
-		if (varTwo) {
-			statements.push(`${exp}const ${varTwo} = ${JSON.stringify(styles)}`)
-		}
+		if (mode === 'extract') {
+			sheets.push({ hash: key, css: cssText })
+			replacement = `{\n\tmode: 'extract',\n\tstyles: ${JSON.stringify(styles)}\n}`
+		} else {
+			const styleProps: EmbedStyleDescriptor = {
+				mode: 'embed',
+				href,
+				css: cssText,
+				precedence: 'default',
+			}
 
-		if (varThree) {
-			statements.push(`${exp}const ${varThree} = ${JSON.stringify(href)}`)
+			replacement = `{\n\tmode: 'embed',\n\tstyles: ${JSON.stringify(styles)},\n\tstyleProps: ${JSON.stringify(styleProps)}\n}`
 		}
 
-		// swap the template for the generated declarations, keeping the export keyword
-		magic.overwrite(matchIndex, matchIndex + match[0].length, statements.join('\n'))
+		magic.overwrite(matchIndex, matchIndex + match[0].length, replacement)
 	}
 
 	const template = magic.toString()
@@ -217,13 +228,44 @@ export function collect(source: string, id: string, config: PluginConfig) {
 	const map = matched
 		? magic.generateMap({ source: id, includeContent: true, hires: true })
 		: null
-	const result = { source, config: configKey, template, tags, map }
+	const result = { source, config: configKey, template, tags, sheets, map }
 
 	collectCache.set(id, result)
 
 	return result
 }
 
+/**
+ * Write generated styles next to their source file and return relative import specifiers.
+ */
+export function writeStyleSheets(filePath: string, sheets: StyleSheet[]) {
+	if (sheets.length === 0) return []
+
+	const dir = path.join(path.dirname(filePath), '.cxx')
+	mkdirSync(dir, { recursive: true })
+
+	return sheets.map(sheet => {
+		writeFileSync(path.join(dir, `${sheet.hash}.css`), sheet.css)
+		return `./.cxx/${sheet.hash}.css`
+	})
+}
+
+/**
+ * Insert style imports after any leading module directive.
+ */
+export function injectStyleImports(template: string, imports: string[]) {
+	if (imports.length === 0) return template
+
+	const directive =
+		/^(?:\s|\/\/[^\n]*\n|\/\*[\s\S]*?\*\/)*(['"])use (?:client|server)\1;?/.exec(template)
+	const at = directive ? directive[0].length : 0
+	const lines = imports
+		.map(specifier => `import ${JSON.stringify(specifier)};`)
+		.join('\n')
+
+	return `${template.slice(0, at)}\n${lines}\n${template.slice(at)}`
+}
+
 /**
  * Render the generated declaration file contents for a set of collected tags.
  */
@@ -447,11 +489,36 @@ export async function refreshFile(file: string, config: PluginConfig) {
 	await writeTypesForFile(file, tags)
 }
 
+/**
+ * Remove orphaned `.tmp` files left by a write that was killed before its rename. Only the seed
+ * does this, because it runs once at startup before any write is in flight.
+ */
+async function sweepTmpFiles() {
+	for (const dir of [GENERATED_DIR, PARTIAL_DIR]) {
+		let entries: string[]
+
+		try {
+			entries = await fs.readdir(dir)
+		} catch (err) {
+			if (isENOENT(err)) continue
+			throw err
+		}
+
+		for (const entry of entries) {
+			if (entry.endsWith('.tmp')) {
+				await fs.rm(path.join(dir, entry), { force: true })
+			}
+		}
+	}
+}
+
 /**
  * Walk every source file under `root` and seed the type surface, so a fresh checkout (and a build
  * with no edits) has types without waiting for a transform.
  */
 export async function seedTypes(root: string, config: PluginConfig) {
+	await sweepTmpFiles()
+
 	async function scan(dir: string) {
 		let entries: Dirent[]
 

package/src/index.ts

@@ -1,6 +1,23 @@
-import type { Cxx, Result } from './types.js'
+import type {
+	Cxx,
+	EmbedResult,
+	EmbedStyleTag,
+	ExtractResult,
+	ExtractStyleTag,
+} from './types.js'
 
-export type { Cxx, Result, Tag } from './types.js'
+export { Style } from './style.js'
+export type {
+	Cxx,
+	EmbedResult,
+	EmbedStyleDescriptor,
+	EmbedStyleTag,
+	ExtractResult,
+	ExtractStyleTag,
+	Result,
+	StyleMode,
+	StyleProps,
+} from './types.js'
 
 /**
  * Hit when a `cxx` template reaches runtime, which means the build transform did
@@ -9,8 +26,8 @@ export type { Cxx, Result, Tag } from './types.js'
  * @example
  * ```ts
  * // no cxx plugin configured
- * const [css, styles, href] = cxx`.a { color: red; }`
- * // Error: cxx template was not transformed ...
+ * const button = cxx.embed`.a { color: red; }`
+ * // error: cxx template was not transformed ...
  * ```
  */
 function untransformed(): never {
@@ -19,15 +36,25 @@ function untransformed(): never {
 	)
 }
 
+function tag<_ClassName extends string = string>(_: string) {
+	return (_strings: TemplateStringsArray): never => untransformed()
+}
+
+function embedTag(): EmbedStyleTag {
+	return Object.assign((_: TemplateStringsArray): EmbedResult => untransformed(), { tag })
+}
+
+function extractTag(): ExtractStyleTag {
+	return Object.assign((_: TemplateStringsArray): ExtractResult => untransformed(), {
+		tag,
+	})
+}
+
+const embed = embedTag()
+const extract = extractTag()
+
 /**
- * Build-time template tag placeholder used by the transform to emit CSS, classes and href values.
+ * Build-time template tag namespace used by the transform to emit class maps
+ * and style descriptors.
  */
-export const cxx: Cxx = Object.assign(
-	(_: TemplateStringsArray): Result => untransformed(),
-	{
-		tag:
-			<ClassName extends string = string>(_: string) =>
-			(_strings: TemplateStringsArray): Result<ClassName> =>
-				untransformed(),
-	},
-)
+export const cxx: Cxx = { embed, extract }

package/src/next/index.ts

@@ -4,7 +4,13 @@ import path from 'node:path'
 import { fileURLToPath } from 'node:url'
 
 import type { PluginConfig } from '../types.js'
-import { collect, seedTypes, writeTypesForFile } from '../build.js'
+import {
+	collect,
+	injectStyleImports,
+	seedTypes,
+	writeStyleSheets,
+	writeTypesForFile,
+} from '../build.js'
 import { Logger } from '../logger.js'
 
 const typeLogger = new Logger('cxx')
@@ -29,10 +35,12 @@ export function processFile(
 	}
 
 	const result = collect(source, resolvedFilePath, pluginConfig)
+	const imports = writeStyleSheets(resolvedFilePath, result.sheets)
+	const template = injectStyleImports(result.template, imports)
 
 	void writeTypesForFile(resolvedFilePath, result.tags)
 
-	return result
+	return { ...result, template }
 }
 
 const TURBOPACK_GLOB = '*.{tsx,jsx,ts,js}'

package/src/style.tsx

@@ -0,0 +1,14 @@
+import type { StyleProps } from './types.js'
+
+/**
+ * Render an embedded style descriptor as a hoisted style element.
+ */
+export function Style(props: StyleProps) {
+	const { mode: _mode, href, css, precedence, ...rest } = props
+
+	return (
+		<style {...rest} href={href} precedence={precedence}>
+			{css}
+		</style>
+	)
+}

package/src/types.ts

@@ -1,8 +1,38 @@
-export type Result<ClassName extends string = string> = readonly [
-	css: string,
-	classes: Readonly<Record<ClassName, string>>,
-	href: string,
-]
+import type { ComponentPropsWithRef } from 'react'
+
+export type StyleMode = 'embed' | 'extract'
+
+export type EmbedStyleDescriptor = {
+	mode: 'embed'
+	href: string
+	css: string
+	precedence: string
+}
+
+export type EmbedResult<ClassName extends string = string> = {
+	mode: 'embed'
+	styles: Readonly<Record<ClassName, string>>
+	styleProps: EmbedStyleDescriptor
+}
+
+export type ExtractResult<ClassName extends string = string> = {
+	mode: 'extract'
+	styles: Readonly<Record<ClassName, string>>
+}
+
+export type Result<ClassName extends string = string> =
+	| EmbedResult<ClassName>
+	| ExtractResult<ClassName>
+
+type StyleElementProps = Omit<
+	ComponentPropsWithRef<'style'>,
+	'href' | 'precedence' | 'children'
+> & {
+	href: string
+	precedence: string
+}
+
+export type StyleProps = EmbedStyleDescriptor & StyleElementProps
 
 export type Tags = Map<string, string[]>
 
@@ -14,10 +44,23 @@ export type PluginConfig = {
 	}
 }
 
-export type Tag = <ClassName extends string = string>(
+export type EmbedTag = <ClassName extends string = string>(
+	name: string,
+) => (_: TemplateStringsArray) => EmbedResult<ClassName>
+
+export type ExtractTag = <ClassName extends string = string>(
 	name: string,
-) => (_: TemplateStringsArray) => Result<ClassName>
+) => (_: TemplateStringsArray) => ExtractResult<ClassName>
+
+export type EmbedStyleTag = ((_: TemplateStringsArray) => EmbedResult) & {
+	tag: EmbedTag
+}
+
+export type ExtractStyleTag = ((_: TemplateStringsArray) => ExtractResult) & {
+	tag: ExtractTag
+}
 
-export type Cxx = ((_: TemplateStringsArray) => Result) & {
-	tag: Tag
+export type Cxx = {
+	embed: EmbedStyleTag
+	extract: ExtractStyleTag
 }

package/src/vite/index.ts

@@ -7,9 +7,11 @@ import type { PluginConfig } from '../types.js'
 import {
 	collect,
 	flushTypes,
+	injectStyleImports,
 	refreshFile,
 	seedTypes,
 	SOURCE_EXTENSIONS,
+	writeStyleSheets,
 	writeTypesForFile,
 } from '../build.js'
 import { GENERATED_DIR } from '../config.js'
@@ -121,15 +123,19 @@ export default function cxx(pluginConfig: PluginConfig = {}) {
 
 			if (!SOURCE_EXTENSIONS.has(path.extname(cleanId))) return null
 
-			const { template, tags, map } = collect(code, cleanId, pluginConfig)
+			const result = collect(code, cleanId, pluginConfig)
 
-			if (template === code) return null
+			if (result.template === code) return null
 
-			void writeTypesForFile(resolveWatchFile(cleanId), tags)
+			const file = resolveWatchFile(cleanId)
+			const imports = writeStyleSheets(file, result.sheets)
+			const template = injectStyleImports(result.template, imports)
+
+			void writeTypesForFile(file, result.tags)
 
 			return {
 				code: template,
-				map,
+				map: result.map,
 			}
 		},
 		configureServer(server: ViteDevServer) {