@nqmcreative/ui 0.2.3 → 0.4.0

package/cli/index.mjs

@@ -3,16 +3,19 @@
  * @nqmcreative/ui CLI
  *
  *   nqm-ui init            wire the design system into this project
+ *   nqm-ui update          rewrite that wiring after upgrading the package
  *   nqm-ui add <name...>   print (or insert) the import for a component
  *   nqm-ui list [category] every component and its subpath
  *   nqm-ui info <name>     what one component pulls in
  *
  * Node built-ins only, so `bunx @nqmcreative/ui init` needs nothing installed.
- * Every write is idempotent: running init twice changes nothing the second
- * time.
+ * Every write is idempotent: the lines this CLI owns are rewritten from
+ * scratch on every run, so running it twice changes nothing the second time —
+ * and running it after an upgrade picks up whatever those lines became.
  */
 import { readFile, writeFile, mkdir } from 'node:fs/promises';
 import { existsSync } from 'node:fs';
+import { createInterface } from 'node:readline/promises';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 
@@ -76,27 +79,56 @@ function findComponent(list, query) {
  * The style to work in. There is no default on purpose: a component belongs to
  * a style, and picking one by accident is the mistake this package exists to
  * prevent. Asking once beats shipping the wrong look.
+ *
+ * `--style` answers it up front. Without it a terminal gets a numbered prompt;
+ * a pipe or a CI job gets the list and a non-zero exit, because there is
+ * nobody there to answer.
  */
-function pickStyle(styles) {
+async function pickStyle(styles) {
 	const index = argv.indexOf('--style');
 	const wanted = index !== -1 ? argv[index + 1] : null;
 
-	if (!wanted) {
-		log();
-		log('  which style?');
-		log();
-		for (const style of styles) {
-			log(`    ${c.cyan(style.name.padEnd(8))} ${c.dim(style.description)}`);
-		}
-		log();
-		log(`  ${c.dim(`e.g. ${command} --style ${styles[0].name}`)}`);
+	if (wanted) {
+		const named = styles.find((s) => s.name === wanted);
+		if (!named) fail(`unknown style "${wanted}" — try ${styles.map((s) => s.name).join(' or ')}`);
+		return named;
+	}
+
+	log();
+	log('  which style?');
+	log();
+	styles.forEach((style, i) => {
+		log(`    ${c.cyan(`${i + 1})`)} ${c.bold(style.name.padEnd(8))} ${c.dim(style.description)}`);
+	});
+	log();
+
+	if (!process.stdin.isTTY) {
+		log(`  ${c.dim(`not a terminal — pass it: ${command} --style ${styles[0].name}`)}`);
 		log();
 		process.exit(1);
 	}
 
-	const style = styles.find((s) => s.name === wanted);
-	if (!style) fail(`unknown style "${wanted}" — try ${styles.map((s) => s.name).join(' or ')}`);
-	return style;
+	const rl = createInterface({ input: process.stdin, output: process.stdout });
+	try {
+		for (let attempt = 0; attempt < 3; attempt++) {
+			const answer = (await rl.question(`  1-${styles.length}, or a name [1]: `)).trim();
+			if (!answer) return styles[0];
+
+			const number = Number(answer);
+			if (Number.isInteger(number) && number >= 1 && number <= styles.length) {
+				return styles[number - 1];
+			}
+
+			const named = styles.find((s) => s.name === answer.toLowerCase());
+			if (named) return named;
+
+			warn(`no style called "${answer}"`);
+		}
+	} finally {
+		rl.close();
+	}
+
+	fail(`try ${command} --style ${styles[0].name}`);
 }
 
 /* ------------------------------------------------------------ file edits -- */
@@ -121,6 +153,39 @@ async function write(path, content, label) {
 
 /* -------------------------------------------------------------- detection -- */
 
+/**
+ * Which kind of project this is.
+ *
+ * The library itself is plain Svelte 5 — no `$app/*`, no `$env/*`, no
+ * `@sveltejs/kit` anywhere in it — so a framework only decides where four
+ * things live:
+ *
+ *   kit      src/app.css          src/app.html            src/routes/+layout.svelte
+ *   vite     src/app.css          index.html              src/main.ts
+ *   laravel  resources/css/…      resources/views/…       the @vite directive
+ */
+function detectFramework(deps) {
+	if ('@sveltejs/kit' in deps) return 'kit';
+	if (existsSync(join(cwd, 'artisan'))) return 'laravel';
+	return 'vite';
+}
+
+const FRAMEWORK_LABEL = {
+	kit: 'SvelteKit',
+	laravel: 'Laravel + Svelte',
+	vite: 'Svelte + Vite'
+};
+
+/** The first candidate that exists, or the first one as the place to create. */
+function pickPath(candidates) {
+	return candidates.find((path) => existsSync(join(cwd, path))) ?? candidates[0];
+}
+
+/** The one that exists, or null — for files we patch but never invent. */
+function findPath(candidates) {
+	return candidates.find((path) => existsSync(join(cwd, path))) ?? null;
+}
+
 async function detectProject() {
 	const pkgPath = join(cwd, 'package.json');
 	if (!existsSync(pkgPath)) fail('no package.json here — run this inside your project');
@@ -128,17 +193,156 @@ async function detectProject() {
 	const pkg = JSON.parse(await readFile(pkgPath, 'utf8'));
 	const deps = { ...pkg.dependencies, ...pkg.devDependencies };
 
-	const isKit = '@sveltejs/kit' in deps;
+	const framework = detectFramework(deps);
+	const isKit = framework === 'kit';
 	const hasTailwind = '@tailwindcss/vite' in deps || 'tailwindcss' in deps;
 	const hasUi = '@nqmcreative/ui' in deps;
+	// Kit brings its own; everywhere else the components are .svelte files in
+	// node_modules and something has to compile them.
+	const hasCompiler = isKit || '@sveltejs/vite-plugin-svelte' in deps;
 
 	// Where the Tailwind entry CSS lives, or should.
-	const candidates = isKit
-		? ['src/app.css', 'src/routes/+layout.css', 'src/app.postcss']
-		: ['src/app.css', 'src/style.css', 'src/main.css'];
-	const css = candidates.find((path) => existsSync(join(cwd, path))) ?? candidates[0];
+	const css = pickPath(
+		{
+			kit: ['src/app.css', 'src/routes/+layout.css', 'src/app.postcss'],
+			laravel: ['resources/css/app.css'],
+			vite: ['src/app.css', 'src/style.css', 'src/main.css']
+		}[framework]
+	);
+
+	// The document head, for the font preconnect and the no-flash theme script.
+	// Kit gets one written if it is missing; the other two are only patched,
+	// because guessing at someone's Blade layout would do more harm than a
+	// printed reminder.
+	const head = {
+		kit: 'src/app.html',
+		laravel: findPath([
+			'resources/views/app.blade.php',
+			'resources/views/layouts/app.blade.php',
+			'resources/views/components/layouts/app.blade.php',
+			'resources/views/welcome.blade.php'
+		]),
+		vite: findPath(['index.html'])
+	}[framework];
+
+	// Where the entry CSS gets imported. Laravel has nowhere: the `@vite`
+	// directive in the Blade layout links it directly.
+	const entry = {
+		kit: 'src/routes/+layout.svelte',
+		laravel: null,
+		vite: findPath(['src/main.ts', 'src/main.js'])
+	}[framework];
+
+	return {
+		pkg,
+		deps,
+		framework,
+		isKit,
+		hasTailwind,
+		hasUi,
+		hasCompiler,
+		css: join(cwd, css),
+		cssRel: css,
+		head,
+		entry
+	};
+}
+
+/* ------------------------------------------------------------------ head -- */
 
-	return { pkg, deps, isKit, hasTailwind, hasUi, css: join(cwd, css), cssRel: css };
+/** Escapes a literal for use inside a RegExp — the markers contain `%` and `/`. */
+const escapeRe = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+
+/** The two things that have to run before first paint, in document order. */
+function headAdditions(style, html) {
+	const additions = [];
+	if (style.fonts && !html.includes('fonts.gstatic.com')) {
+		additions.push(`<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />`);
+	}
+	if (!html.includes('nqm-theme')) {
+		additions.push(
+			`<script>`,
+			`\tconst saved = localStorage.getItem('nqm-theme');`,
+			`\tif (saved === 'dark' || saved === 'light') document.documentElement.classList.add(saved);`,
+			`</script>`
+		);
+	}
+	return additions;
+}
+
+/**
+ * Puts them in the document head, wherever that is for this framework.
+ *
+ * Kit renders into a `%sveltekit.head%` placeholder; a Vite index.html and a
+ * Blade layout both have a real `</head>` to sit above. When there is no file
+ * to patch — or no marker in it — the lines are printed instead of guessed at.
+ */
+async function wireHead(project, style) {
+	const { framework, head } = project;
+
+	const printByHand = (additions, reason) => {
+		log();
+		warn(reason);
+		log(additions.map((line) => c.cyan(`    ${line}`)).join('\n'));
+	};
+
+	if (!head) {
+		printByHand(
+			headAdditions(style, ''),
+			framework === 'laravel'
+				? 'no Blade layout found — put these inside <head> in yours:'
+				: 'no index.html found — put these inside its <head>:'
+		);
+		return;
+	}
+
+	const htmlPath = join(cwd, head);
+	let html = await readOr(htmlPath);
+
+	if (!html && framework === 'kit') {
+		// Some `sv create` templates omit it and let SvelteKit fall back to a
+		// built-in. Write the standard one so there is somewhere to put the
+		// preconnect and the no-flash theme script.
+		html = [
+			'<!doctype html>',
+			'<html lang="en">',
+			'	<head>',
+			'		<meta charset="utf-8" />',
+			'		<meta name="viewport" content="width=device-width, initial-scale=1" />',
+			'		%sveltekit.head%',
+			'	</head>',
+			'	<body data-sveltekit-preload-data="hover">',
+			'		<div style="display: contents">%sveltekit.body%</div>',
+			'	</body>',
+			'</html>',
+			''
+		].join('\n');
+		skip('src/app.html was missing — creating it');
+	}
+
+	const additions = headAdditions(style, html);
+	if (additions.length === 0) {
+		skip(`${head} already wired`);
+		return;
+	}
+
+	const marker = framework === 'kit' ? '%sveltekit.head%' : '</head>';
+	if (!html.includes(marker)) {
+		printByHand(additions, `${head} has no ${marker} — add these by hand, inside <head>:`);
+		return;
+	}
+
+	// Matched with its own indentation so the block lands at the right depth,
+	// and replaced through a function so a `$` in the lines stays literal.
+	html = html.replace(new RegExp(`([ \\t]*)${escapeRe(marker)}`), (_match, indent) => {
+		// The placeholder is itself a child of <head>; a closing tag is not, so
+		// its children sit one level deeper — in whichever unit the file uses.
+		const unit = indent.startsWith('\t') ? '\t' : '    ';
+		const inner = framework === 'kit' ? indent : `${indent}${unit}`;
+		const body = additions.map((line) => line.replace(/^\t/, unit));
+		return `${inner}${body.join(`\n${inner}`)}\n${indent}${marker}`;
+	});
+	await write(htmlPath, html, head);
 }
 
 /** How many `../` from the CSS file up to node_modules. */
@@ -151,12 +355,12 @@ function sourcePath(cssRel) {
 
 async function init() {
 	const { styles } = await registry();
-	const style = pickStyle(styles);
+	const style = await pickStyle(styles);
 	const project = await detectProject();
 
 	log();
 	log(c.bold(`  @nqmcreative/ui — ${style.title}`));
-	log(c.dim(`  ${project.isKit ? 'SvelteKit' : 'Svelte + Vite'} project detected`));
+	log(c.dim(`  ${FRAMEWORK_LABEL[project.framework]} project detected`));
 	log();
 
 	if (!project.hasUi) {
@@ -171,6 +375,13 @@ async function init() {
 		log();
 	}
 
+	if (!project.hasCompiler) {
+		// The package ships .svelte files, so the app compiles them itself.
+		warn('nothing here compiles Svelte components:');
+		log(c.cyan('    bun add -d svelte @sveltejs/vite-plugin-svelte'));
+		log();
+	}
+
 	/* --- 1. the entry CSS --- */
 	const source = sourcePath(project.cssRel);
 	const lines = [
@@ -185,110 +396,90 @@ async function init() {
 
 	const css = await readOr(project.css);
 
-	// Matched against *this* style's theme, not any of them. A file left over
-	// from an older layout — or wired to a different style — has to be reported,
-	// not skipped as already done.
-	if (css.includes(`@nqmcreative/ui/${style.name}/theme.css`)) {
-		skip(`${project.cssRel} already imports the theme`);
+	// The block above belongs to this package, so it is rewritten on every run
+	// rather than left alone once it is there. That is what makes an upgrade
+	// land: when a release changes which files a style imports, or where
+	// `@source` has to point, the old lines would otherwise sit here and the
+	// new components would come up unstyled.
+	//
+	// Only those lines. Everything below is the project's own CSS and is
+	// carried over untouched — including an `@import` of another package, which
+	// is why the match is anchored to this one.
+	const stale =
+		/^@import ['"]@nqmcreative\/ui\/[^'"]+\.css['"];$|^@source ['"][^'"]*@nqmcreative\/ui[^'"]*['"];$/;
+
+	const kept = css
+		.split('\n')
+		.filter((line) => !stale.test(line.trim()))
+		.join('\n')
+		.replace(/@import ['"]tailwindcss['"];\n?/, '')
+		.replace(/\/\* Tailwind v4 skips node_modules[\s\S]*?\*\/\n?/, '')
+		.replace(/\n{3,}/g, '\n\n')
+		.trim();
+
+	const body = kept ? `${lines.join('\n')}\n\n${kept}\n` : `${lines.join('\n')}\n`;
+	if (body === css) {
+		skip(`${project.cssRel} already up to date`);
 	} else {
-		// Drop whatever this package left here before — an older layout's
-		// `@nqmcreative/ui/theme.css`, another style's, and the `@source` that
-		// went with them. Keeping those would either fight the new tokens or fail
-		// to resolve, so a rewrite is cleaner than an append.
-		const stale =
-			/^@import ['"]@nqmcreative\/ui\/[^'"]+\.css['"];$|^@source ['"][^'"]*@nqmcreative\/ui[^'"]*['"];$/;
-
-		const kept = css
-			.split('\n')
-			.filter((line) => !stale.test(line.trim()))
-			.join('\n')
-			.replace(/@import ['"]tailwindcss['"];\n?/, '')
-			.replace(/\n{3,}/g, '\n\n')
-			.trim();
-
-		const body = kept ? `${lines.join('\n')}\n\n${kept}\n` : `${lines.join('\n')}\n`;
 		await write(project.css, body, project.cssRel);
 	}
 
-	/* --- 2. app.html: font preconnect + no-flash theme --- */
-	if (project.isKit) {
-		const htmlPath = join(cwd, 'src/app.html');
-		let html = await readOr(htmlPath);
-		if (!html) {
-			// Some `sv create` templates omit it and let SvelteKit fall back to a
-			// built-in. Write the standard one so there is somewhere to put the
-			// preconnect and the no-flash theme script.
-			html = [
-				'<!doctype html>',
-				'<html lang="en">',
-				'	<head>',
-				'		<meta charset="utf-8" />',
-				'		<meta name="viewport" content="width=device-width, initial-scale=1" />',
-				'		%sveltekit.head%',
-				'	</head>',
-				'	<body data-sveltekit-preload-data="hover">',
-				'		<div style="display: contents">%sveltekit.body%</div>',
-				'	</body>',
-				'</html>',
-				''
-			].join('\n');
-			skip('src/app.html was missing — creating it');
-		}
-		{
-			// Unindented — `%sveltekit.head%` already sits at its own indentation,
-			// so the join below supplies it and the first line does not double up.
-			const additions = [];
-			if (style.fonts && !html.includes('fonts.gstatic.com')) {
-				additions.push(`<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />`);
-			}
-			if (!html.includes('nqm-theme')) {
-				additions.push(
-					`<script>`,
-					`\tconst saved = localStorage.getItem('nqm-theme');`,
-					`\tif (saved === 'dark' || saved === 'light') document.documentElement.classList.add(saved);`,
-					`</script>`
-				);
-			}
-			if (additions.length === 0) {
-				skip('src/app.html already wired');
-			} else if (!html.includes('%sveltekit.head%')) {
-				warn('src/app.html has no %sveltekit.head% — add these by hand:');
-				log(additions.map((line) => `\t\t${line}`).join('\n'));
-			} else {
-				const indent = /([ \t]*)%sveltekit\.head%/.exec(html)?.[1] ?? '\t\t';
-				html = html.replace(
-					'%sveltekit.head%',
-					`${additions.join(`\n${indent}`)}\n${indent}%sveltekit.head%`
-				);
-				await write(htmlPath, html, 'src/app.html');
-			}
-		}
+	// Laravel keeps its markup outside resources/css, so automatic detection
+	// never reaches it. These are the project's own lines, not ours — printed
+	// rather than written, so removing them stays possible.
+	if (project.framework === 'laravel' && !/@source ['"]\.\.\/(js|views)/.test(body)) {
+		log();
+		warn(`Tailwind also has to see your own markup — add to ${project.cssRel}:`);
+		log(c.cyan(`    @source '../js';`));
+		log(c.cyan(`    @source '../views';`));
 	}
 
+	/* --- 2. the document head: font preconnect + no-flash theme --- */
+	await wireHead(project, style);
+
 	/* --- 3. remind about the vite plugin, which we will not rewrite --- */
 	const viteConfig =
-		['vite.config.ts', 'vite.config.js'].map((f) => join(cwd, f)).find((f) => existsSync(f)) ??
-		null;
+		['vite.config.ts', 'vite.config.js', 'vite.config.mjs']
+			.map((f) => join(cwd, f))
+			.find((f) => existsSync(f)) ?? null;
 	const viteSource = viteConfig ? await readOr(viteConfig) : '';
 	if (!viteSource.includes('@tailwindcss/vite')) {
+		const plugins = {
+			kit: `plugins: [tailwindcss(), sveltekit()]`,
+			laravel: `plugins: [laravel({ input: ['${project.cssRel}', 'resources/js/app.js'] }), tailwindcss(), svelte()]`,
+			vite: `plugins: [tailwindcss(), svelte()]`
+		}[project.framework];
+		const after = project.framework === 'kit' ? 'sveltekit()' : 'svelte()';
+
 		log();
 		warn(
-			`add the Tailwind plugin to ${viteConfig ? relative(cwd, viteConfig) : 'your vite config'} — before sveltekit():`
+			`add the Tailwind plugin to ${viteConfig ? relative(cwd, viteConfig) : 'your vite config'} — before ${after}:`
 		);
 		log(c.cyan(`    import tailwindcss from '@tailwindcss/vite';`));
-		log(c.cyan(`    plugins: [tailwindcss(), sveltekit()]`));
+		log(c.cyan(`    ${plugins}`));
 	} else {
 		skip('vite config already has the Tailwind plugin');
 	}
 
 	/* --- 4. import the CSS once --- */
-	if (project.isKit) {
-		const layoutPath = join(cwd, 'src/routes/+layout.svelte');
+	if (project.framework === 'laravel') {
+		// Nothing imports it: the Blade layout hands the path to Vite, which is
+		// also what makes `php artisan serve` pick up the built file.
+		const blade = project.head ? await readOr(join(cwd, project.head)) : '';
+		if (blade.includes(project.cssRel)) {
+			skip(`${project.head} already loads ${project.cssRel}`);
+		} else {
+			log();
+			warn(`load the CSS from your Blade layout, inside <head>:`);
+			log(c.cyan(`    @vite(['${project.cssRel}', 'resources/js/app.js'])`));
+		}
+	} else if (project.framework === 'kit') {
+		const layoutPath = join(cwd, project.entry);
 		let layout = await readOr(layoutPath);
 		const line = `import '../app.css';`;
 
 		if (layout.includes('app.css')) {
-			skip('src/routes/+layout.svelte already imports the CSS');
+			skip(`${project.entry} already imports the CSS`);
 		} else if (!layout.trim()) {
 			await write(
 				layoutPath,
@@ -300,16 +491,37 @@ async function init() {
 
 {@render children()}
 `,
-				'src/routes/+layout.svelte'
+				project.entry
 			);
 		} else if (/<script[^>]*>/.test(layout)) {
 			layout = layout.replace(/(<script[^>]*>\n)/, `$1\t${line}\n`);
-			await write(layoutPath, layout, 'src/routes/+layout.svelte');
+			await write(layoutPath, layout, project.entry);
 		} else {
 			log();
-			warn('import the CSS once, at the top of src/routes/+layout.svelte:');
+			warn(`import the CSS once, at the top of ${project.entry}:`);
 			log(c.cyan(`    ${line}`));
 		}
+	} else {
+		// Plain Vite: the entry module is the one thing every page loads.
+		const rel = project.entry
+			? relative(dirname(join(cwd, project.entry)), project.css)
+					.split(/[\\/]/)
+					.join('/')
+			: null;
+		const line = rel ? `import '${rel.startsWith('.') ? rel : `./${rel}`}';` : null;
+
+		if (!project.entry) {
+			log();
+			warn(`import ${project.cssRel} once, at the top of your entry module:`);
+			log(c.cyan(`    import './${project.cssRel.split('/').pop()}';`));
+		} else {
+			const source = await readOr(join(cwd, project.entry));
+			if (source.includes(line) || /import ['"][^'"]*app\.css['"]/.test(source)) {
+				skip(`${project.entry} already imports the CSS`);
+			} else {
+				await write(join(cwd, project.entry), `${line}\n${source}`, project.entry);
+			}
+		}
 	}
 
 	log();
@@ -321,7 +533,7 @@ async function init() {
 
 async function add() {
 	const { components, styles } = await registry();
-	const style = pickStyle(styles);
+	const style = await pickStyle(styles);
 	const names = args.slice(1);
 	if (names.length === 0) fail('which component? e.g. `nqm-ui add button dialog`');
 
@@ -435,22 +647,26 @@ function help() {
 	log(`
   ${c.bold('@nqmcreative/ui')}
 
-    ${c.cyan('init --style <s>')}      wire one style into this project
+    ${c.cyan('init')}                  wire one style into this project
+    ${c.cyan('update')}                rewrite that wiring after upgrading the package
     ${c.cyan('add <name...>')}         print the import for a component
-      ${c.dim('--style <s>')}         which style to import from (required)
       ${c.dim('--to <file>')}         …and insert it into that file instead
     ${c.cyan('list [category]')}       every component in the catalogue
     ${c.cyan('info <name>')}           what one component pulls in, in every style
 
+    ${c.dim('--style <s>')}           skip the picker: matte, paper or sprout
     ${c.dim('--dry-run')}             show the writes without making them
 
-  ${c.dim('Every style implements every component. Run init once per project.')}
+  ${c.dim('Every style implements every component. Run init once per project,')}
+  ${c.dim('then update after each upgrade — it overwrites the lines it owns.')}
 `);
 }
 
 /* ------------------------------------------------------------------ main -- */
 
-const commands = { init, add, list, info };
+// `update` is `init` under the name people reach for after an upgrade: both
+// rewrite the lines this CLI owns and leave the rest of the file alone.
+const commands = { init, update: init, add, list, info };
 if (!command || flags.has('--help') || command === 'help') {
 	help();
 } else if (commands[command]) {

package/dist/core/color.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Hex colours for the colour field.
+ *
+ * Only hex: it is the one notation `<input type="color">` accepts and the one
+ * every design tool copies to the clipboard. Anything else the app can convert
+ * before it binds.
+ */
+/**
+ * `abc`, `#ABC`, `#aabbcc` → `#aabbcc`. Returns `null` when it is not a hex
+ * colour, so a half-typed value can be left alone rather than corrected under
+ * the caret.
+ *
+ * Shorthand is expanded and alpha is dropped: the native swatch understands
+ * neither, and a value the swatch cannot show is worse than a rounded one.
+ */
+export declare function normaliseHex(text: string): string | null;
+/**
+ * True when a colour is dark enough to want light text on top of it.
+ *
+ * Rec. 601 luma rather than WCAG relative luminance — the threshold is for
+ * picking one of two label colours on a swatch, not for proving a contrast
+ * ratio, and this is the version everyone's design tokens are tuned against.
+ */
+export declare function isDark(hex: string): boolean;

package/dist/core/color.js

@@ -0,0 +1,39 @@
+/**
+ * Hex colours for the colour field.
+ *
+ * Only hex: it is the one notation `<input type="color">` accepts and the one
+ * every design tool copies to the clipboard. Anything else the app can convert
+ * before it binds.
+ */
+const HEX = /^#?([0-9a-f]{3}|[0-9a-f]{4}|[0-9a-f]{6}|[0-9a-f]{8})$/i;
+/**
+ * `abc`, `#ABC`, `#aabbcc` → `#aabbcc`. Returns `null` when it is not a hex
+ * colour, so a half-typed value can be left alone rather than corrected under
+ * the caret.
+ *
+ * Shorthand is expanded and alpha is dropped: the native swatch understands
+ * neither, and a value the swatch cannot show is worse than a rounded one.
+ */
+export function normaliseHex(text) {
+    const match = HEX.exec(text.trim());
+    if (!match)
+        return null;
+    let digits = match[1].toLowerCase();
+    if (digits.length <= 4)
+        digits = [...digits].map((digit) => digit + digit).join('');
+    return `#${digits.slice(0, 6)}`;
+}
+/**
+ * True when a colour is dark enough to want light text on top of it.
+ *
+ * Rec. 601 luma rather than WCAG relative luminance — the threshold is for
+ * picking one of two label colours on a swatch, not for proving a contrast
+ * ratio, and this is the version everyone's design tokens are tuned against.
+ */
+export function isDark(hex) {
+    const value = normaliseHex(hex);
+    if (!value)
+        return false;
+    const [r, g, b] = [1, 3, 5].map((at) => parseInt(value.slice(at, at + 2), 16));
+    return (r * 299 + g * 587 + b * 114) / 1000 < 140;
+}

package/dist/core/index.d.ts

@@ -25,7 +25,14 @@ export { pageRange } from './pagination.js';
 export { sortFiles, matchesAccept, formatSize } from './files.js';
 export type { RejectedFile, FileRules } from './files.js';
 export { passwordScore } from './password.js';
-export { clampToStep, percentOf, stepDecimals } from './number.js';
+export { clampToStep, formatGrouped, parseGrouped, percentOf, stepDecimals } from './number.js';
+export type { GroupOptions } from './number.js';
+export { caretIndex, clearFrom, fillFrom, sanitisePin } from './pin.js';
+export type { PinMode } from './pin.js';
+export { addTag, splitTags } from './tags.js';
+export type { TagRules, TagRejection } from './tags.js';
+export { normaliseHex, isDark } from './color.js';
+export { MINUTES_IN_DAY, clampTime, formatClock, formatTime, parseTime, stepTime } from './time.js';
 export { toISO, fromISO, today, isSameDay, addDays, addMonths, monthGrid, weekdayNames, monthLabel, isOutOfRange, formatISO, parseFormatted } from './date.js';
 export type { DateFormat } from './date.js';
 export { calendarKeyMove, dateHint } from './calendar.js';

package/dist/core/index.js

@@ -23,7 +23,11 @@ export { nextSort, sortRows, toggleKey } from './table.js';
 export { pageRange } from './pagination.js';
 export { sortFiles, matchesAccept, formatSize } from './files.js';
 export { passwordScore } from './password.js';
-export { clampToStep, percentOf, stepDecimals } from './number.js';
+export { clampToStep, formatGrouped, parseGrouped, percentOf, stepDecimals } from './number.js';
+export { caretIndex, clearFrom, fillFrom, sanitisePin } from './pin.js';
+export { addTag, splitTags } from './tags.js';
+export { normaliseHex, isDark } from './color.js';
+export { MINUTES_IN_DAY, clampTime, formatClock, formatTime, parseTime, stepTime } from './time.js';
 /* --- dates --- */
 export { toISO, fromISO, today, isSameDay, addDays, addMonths, monthGrid, weekdayNames, monthLabel, isOutOfRange, formatISO, parseFormatted } from './date.js';
 export { calendarKeyMove, dateHint } from './calendar.js';