@sableui/react 0.3.1 → 0.4.0

package/scripts/agent-setup.mjs

@@ -1,14 +1,40 @@
 import { createHash } from "node:crypto"
-import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs"
-import { dirname, join } from "node:path"
+import { existsSync, lstatSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs"
+import { dirname, isAbsolute, join, relative, resolve } from "node:path"
 
 const hash = content => createHash("sha256").update(content).digest("hex")
 
-/** Install discoverable loaders; the installed package owns the actual workflow. */
-export function installAgentSkill({ root, packageRoot, target = "all", update = false, dryRun = false }) {
+const RESOLVE = `node -p "require.resolve('@sableui/react/registry.json')"`
+const CONTEXT = "From the target project's dependency context, run:"
+
+/**
+ * The entry as written at `root`. When Sable is a dependency of a workspace
+ * package rather than of the root, a bare `require.resolve` from the root fails
+ * (pnpm does not hoist it), so the entry names the package and resolves through it.
+ */
+function entryContent(source, projectPath) {
+	if (!projectPath) return source
+	if (!source.includes(RESOLVE) || !source.includes(CONTEXT)) throw new Error("The installed skill entry has an unexpected shape. Reinstall Sable.")
+	return source
+		.replace(CONTEXT, `Sable is installed in this repository's \`${projectPath}\` package. From the repository root, run:`)
+		.replace(RESOLVE, `node -p "require.resolve('@sableui/react/registry.json', { paths: ['${projectPath}'] })"`)
+}
+
+/**
+ * Install discoverable loaders; the installed package owns the actual workflow.
+ *
+ * `project` is where Sable is a dependency (the directory setup runs in); `root`
+ * is where the agent entries go. They differ in a monorepo, where agents start at
+ * the repository root but Sable belongs to one workspace package.
+ */
+export function installAgentSkill({ root, project = root, packageRoot, target = "all", update = false, dryRun = false }) {
 	const reject = (message) => { throw new Error(message) }
 	if (!["all", "codex", "claude", "cursor"].includes(target)) reject("Choose --target all, codex, claude, or cursor.")
-	if (!existsSync(join(root, "package.json"))) reject("Run setup from a project with a package.json.")
+	if (!existsSync(join(project, "package.json"))) reject("Run setup from a project with a package.json.")
+	if (!existsSync(root) || !statSync(root).isDirectory()) reject(`--root is not a directory: ${root}`)
+	const projectPath = relative(resolve(root), resolve(project)).replaceAll("\\", "/")
+	if (projectPath.startsWith("..") || isAbsolute(projectPath)) reject("--root must be the project directory or one of its ancestors, such as the repository root.")
+	if (/['"\\`]/.test(projectPath)) reject(`Unsupported characters in the project path: ${projectPath}`)
 	const canonical = join(packageRoot, "skills/sable/SKILL.md")
 	const entry = join(packageRoot, "skills/entry/SKILL.md")
 	if (!existsSync(canonical) || !existsSync(entry)) reject("The installed package is missing its skill. Reinstall Sable.")
@@ -29,8 +55,9 @@ export function installAgentSkill({ root, packageRoot, target = "all", update =
 		receipt = JSON.parse(readFileSync(join(root, receiptPath), "utf8"))
 		if (receipt.schemaVersion !== 1 || !receipt.files || typeof receipt.files !== "object") reject("Invalid Sable setup receipt.")
 	}
+	const skill = entryContent(readFileSync(entry, "utf8"), projectPath)
 	const files = destinations.flatMap(destination => [
-		{ path: `${destination}/SKILL.md`, content: readFileSync(entry, "utf8") },
+		{ path: `${destination}/SKILL.md`, content: skill },
 		...(destination.startsWith(".agents/") ? [{ path: `${destination}/agents/openai.yaml`, content: readFileSync(join(packageRoot, "skills/sable/agents/openai.yaml"), "utf8") }] : []),
 	])
 	// Preflight every host and the receipt before any writes; preserve local edits.
@@ -50,5 +77,5 @@ export function installAgentSkill({ root, packageRoot, target = "all", update =
 		mkdirSync(dirname(join(root, receiptPath)), { recursive: true })
 		writeFileSync(join(root, receiptPath), JSON.stringify(receipt, null, 2) + "\n")
 	}
-	return { destination: destinations[0], destinations, files: files.map(file => file.path), dryRun, update, next: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
+	return { destination: destinations[0], destinations, root, project: projectPath || ".", files: files.map(file => file.path), dryRun, update, next: "Use $sable build <your brief> in Codex or /sable build <your brief> in Claude Code or Cursor." }
 }

package/scripts/design-presets.mjs

@@ -15,7 +15,7 @@ try {
 	const action = modes[0]
 	if (action === "--template") {
 		const manifest = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8"))
-		const css = readFileSync(resolve(packageRoot, "dist/themes/base/base.css"), "utf8").replace(/\/\*[\s\S]*?\*\//g, "")
+		const css = readFileSync(resolve(packageRoot, "dist/themes/sable/sable.css"), "utf8").replace(/\/\*[\s\S]*?\*\//g, "")
 		const groups = { light: {}, dark: {} }
 		for (const match of css.matchAll(/([^{}]+)\{([^{}]*)\}/g)) {
 			const target = match[1].includes(".dark") ? groups.dark : groups.light

package/scripts/grade.mjs

@@ -33,7 +33,7 @@ import { existsSync, readFileSync, readdirSync, statSync } from "node:fs"
 import { createHash } from "node:crypto"
 import { dirname, extname, join, relative, resolve } from "node:path"
 import { fileURLToPath } from "node:url"
-import { lintText, makeRules } from "./lint-rules.mjs"
+import { ignoreGlob, lintText, makeRules } from "./lint-rules.mjs"
 import { skeletonize } from "./skeleton.mjs"
 import { assessReview, reviewTemplate } from "./review-evidence.mjs"
 
@@ -44,8 +44,9 @@ const CWD = process.cwd()
 const argv = process.argv.slice(2)
 const flags = new Map()
 const targets = []
+const ignores = []
 const BOOLEAN_FLAGS = new Set(["json", "help", "template", "strict"])
-const VALUE_FLAGS = new Set(["cli-log", "review"])
+const VALUE_FLAGS = new Set(["cli-log", "review", "icons"])
 const JSON_OUT = argv.includes("--json")
 function abort(message) {
 	const error = { type: "error", code: "ERR_GRADE_INPUT", message, suggestions: ["sable grade --help", "sable grade --template"] }
@@ -55,7 +56,11 @@ function abort(message) {
 for (let i = 0; i < argv.length; i++) {
 	const a = argv[i]
 	if (!a.startsWith("--")) targets.push(a)
-	else if (BOOLEAN_FLAGS.has(a.slice(2))) flags.set(a.slice(2), true)
+	else if (a === "--ignore" || a.startsWith("--ignore=")) {
+		const glob = a === "--ignore" ? argv[++i] : a.slice(9)
+		if (!glob || glob.startsWith("--")) abort("--ignore requires a glob.")
+		ignores.push(glob)
+	} else if (BOOLEAN_FLAGS.has(a.slice(2))) flags.set(a.slice(2), true)
 	else if (VALUE_FLAGS.has(a.slice(2))) {
 		if (!argv[i + 1] || argv[i + 1].startsWith("--")) abort(`${a} requires a file path.`)
 		flags.set(a.slice(2), argv[++i])
@@ -72,12 +77,14 @@ if (flags.has("help") || !targets.length) {
 		[
 			"grade — check the static contract and recorded review evidence. No model calls.",
 			"",
-			"  sable grade <dir...> [--json] [--review <review.json>] [--strict]",
+			"  sable grade <dir...> [--json] [--review <review.json>] [--icons <icons.json>] [--ignore <glob>] [--strict]",
 			"",
 			"  --json           machine-readable scorecard",
 			"  --cli-log        a SABLE_CLI_LOG jsonl, to report whether the CLI was used at all",
 			"  --template       print a review JSON template; fill after inspecting the rendered build",
 			"  --review         validate evidence files and observations; paths are relative to this JSON",
+			'  --icons          icon names the app adds with composeIconSets: { "names": [...] }. Default: .sable/icons.json',
+			"  --ignore         skip matching paths in the checks, as sable-lint --ignore (repeatable)",
 			"  --strict         exit 1 for static findings or a missing/incomplete/unresolved review",
 			"",
 			"Checks: design-contract violations · hallucinated components and props ·",
@@ -102,7 +109,27 @@ const motionTokens = new Set(
 	].filter(Boolean),
 )
 const RULES = makeRules({ semanticTokens, motionTokens }).filter((r) => r.scope !== "package")
+const PROP_SURFACE = REGISTRY.propSurface?.items ?? {}
 const ICONS = new Set(REGISTRY.iconContract?.names ?? [])
+/**
+ * The names an app adds with `composeIconSets(appExtras, reiconIconSet)`. That is
+ * the sanctioned way to extend the set, and the grade cannot read a set's names
+ * out of a render function, so the app declares them once. Without this every
+ * domain icon read as off-contract.
+ */
+const APP_ICONS = (() => {
+	const explicit = flags.get("icons")
+	const path = resolve(CWD, explicit ?? ".sable/icons.json")
+	if (!existsSync(path)) {
+		if (explicit) abort(`Not found: ${explicit}`)
+		return null
+	}
+	let names
+	try { names = JSON.parse(readFileSync(path, "utf8")).names }
+	catch (error) { abort(`Cannot read ${relative(CWD, path)}: ${error.message}`) }
+	if (!Array.isArray(names) || !names.every((n) => typeof n === "string" && n)) abort(`${relative(CWD, path)} must be { "names": ["icon-name", …] }.`)
+	return { file: relative(CWD, path).replaceAll("\\", "/"), names: new Set(names) }
+})()
 const PATTERNS = REGISTRY.patterns?.items ?? []
 
 /**
@@ -173,7 +200,13 @@ for (const t of targets) {
 	else snapshotFiles.push(abs)
 }
 snapshotFiles.splice(0, snapshotFiles.length, ...new Set(snapshotFiles.sort()))
-const files = snapshotFiles.filter((file) => CODE.test(file))
+/* --ignore takes the same globs sable-lint does, so the grade judges the same
+   files the lint does. A data layer (palette fixtures, document colours) is
+   skipped by the checks but still fingerprinted: it is part of the build. */
+const ignoreRes = ignores.map(ignoreGlob)
+const isIgnored = (file) => ignoreRes.some((re) => re.test(relative(CWD, file).replaceAll("\\", "/")))
+const ignoredFiles = snapshotFiles.filter((file) => CODE.test(file) && isIgnored(file))
+const files = snapshotFiles.filter((file) => CODE.test(file) && !isIgnored(file))
 if (!files.length) abort("No source files found.")
 if (!files.some((file) => readFileSync(file, "utf8").trim().length > 0)) abort("No non-empty source content found.")
 // Git checkouts may use CRLF on Windows and LF in CI. Normalize only known text
@@ -275,11 +308,14 @@ for (const file of files) {
 		}
 	}
 
-	/* 3. Props set on a Sable component that its contract does not declare. */
+	/* 3. Props set on a Sable component that its contract does not declare.
+	      The contract is the component's real type (registry → propSurface),
+	      which includes what it forwards to Base UI — Toggle's `pressed`,
+	      Combobox's `filter` — plus its documented table. */
 	for (const m of text.matchAll(/<([A-Z][\w]*)[\s/>]/g)) {
 		const comp = REGISTRY.components?.find((c) => c.name === m[1])
 		if (!comp?.props?.length) continue
-		const declared = new Set(comp.props.map((p) => p.name))
+		const declared = new Set([...comp.props.map((p) => p.name), ...(PROP_SURFACE[m[1]] ?? [])])
 		for (const sub of comp.subcomponents ?? []) {
 			if (typeof sub !== "string") for (const p of sub.props ?? []) declared.add(p.name)
 		}
@@ -307,9 +343,10 @@ for (const file of files) {
 		if (px >= 20 && px <= 56) findings.hardcodedControl.push({ file: rel, match: m[0], line: lineOf(text, m.index) })
 	}
 
-	/* 6. Icon names outside the contract render nothing at all. */
+	/* 6. Icon names outside the contract render nothing at all — unless the app
+	      supplies them itself and has declared them (APP_ICONS). */
 	for (const m of text.matchAll(/<Icon\s+[^>]*name=["']([^"']+)["']/g)) {
-		if (!ICONS.has(m[1])) findings.offContractIcon.push({ file: rel, name: m[1], line: lineOf(text, m.index) })
+		if (!ICONS.has(m[1]) && !APP_ICONS?.names.has(m[1])) findings.offContractIcon.push({ file: rel, name: m[1], line: lineOf(text, m.index) })
 	}
 
 	/* 7. Composition. Anything exporting a component that returns a big tree is
@@ -438,6 +475,7 @@ const result = {
 	sourceHash,
 	fingerprint: { algorithm: "sha256", files: snapshotFiles.length, packageHash, coverage: "All non-test files in supplied targets, plus Sable runtime sources, registry, and lint contract. Known text formats normalize CRLF to LF; binary assets retain their bytes. Pass public/ for external asset directories; remote resources are not covered." },
 	files: files.length,
+	ignored: { globs: ignores, files: ignoredFiles.length },
 	loc,
 	score,
 	scoreMeaning: "Static contract only. Pattern similarity does not affect this score; visual quality is not scored.",
@@ -447,6 +485,7 @@ const result = {
 	per100loc: Object.fromEntries(Object.entries(counts).map(([k, v]) => [k, per100(v)])),
 	conformance: { informationalOnly: true, mean: meanConformance, routes: conformance },
 	cliUsage,
+	appIcons: APP_ICONS ? { file: APP_ICONS.file, names: APP_ICONS.names.size } : null,
 	findings,
 }
 
@@ -459,7 +498,7 @@ if (JSON_OUT) {
 
 const L = (s = "") => process.stdout.write(`${s}\n`)
 L()
-L(`  grade — ${files.length} files, ${loc} lines, against @sableui/react ${REGISTRY.version}`)
+L(`  grade — ${files.length} files, ${loc} lines, against @sableui/react ${REGISTRY.version}${ignoredFiles.length ? ` (${ignoredFiles.length} ignored)` : ""}`)
 L(`  ${"─".repeat(66)}`)
 const row = (label, n, note = "") =>
 	L(`  ${label.padEnd(26)}${String(n).padStart(4)}${note ? `   ${note}` : ""}`)
@@ -468,7 +507,7 @@ row("hallucinated components", counts.hallucinatedComponent)
 row("hallucinated props", counts.hallucinatedProp)
 row("Radix idioms", counts.radixIdiom, counts.radixIdiom ? "asChild / direct primitive imports" : "")
 row("hardcoded control heights", counts.hardcodedControl)
-row("off-contract icon names", counts.offContractIcon)
+row("off-contract icon names", counts.offContractIcon, APP_ICONS ? `+${APP_ICONS.names.size} app icons from ${APP_ICONS.file}` : counts.offContractIcon ? "app-supplied? list them in .sable/icons.json" : "")
 L()
 if (conformance.length) {
 	L(`  pattern similarity (informational) — ${conformance.length} route-like file(s), mean ${meanConformance}`)

package/scripts/lint-rules.mjs

@@ -537,10 +537,14 @@ export function makeRules({ semanticTokens, motionTokens }) {
 			since: "0.1.0",
 			code: true,
 			why:
-				"A colour hand-mixed from the foreground ink — `color-mix(… var(--foreground) …)`. Sable already derives these from the surface underneath, in every theme and mode: `sable-well` (a recessed track, pad or well), `sable-surface` + `sable-surface-interactive` (hover and selected fills on any surface), `bg-hairline` / `border-hairline` (a faint ink edge or fill). `npx sable search` finds them; `registry.json → utilities` explains each. If none fits, it is a gap — report it, then take the escape hatch with the reason.",
+				"A colour hand-mixed from the foreground ink — `color-mix(… var(--foreground) …)`. Sable already derives these from the surface underneath, in every theme and mode: `sable-well` (a recessed track, pad or well), `sable-surface` + `sable-surface-interactive` (hover and selected fills on any surface), `bg-hairline` / `border-hairline` (a faint ink edge or fill). `npx sable search` finds them; `registry.json → utilities` explains each. If none fits, it is a gap — report it, then take the escape hatch with the reason. " +
+				"Exempt: the value of a `--theme-*` hook (`--theme-panel-field: color-mix(…)`), which is how a theme tunes a derived token.",
 			find(line) {
 				const out = []
 				for (const m of line.matchAll(/color-mix\([^;"'`]*?var\(--foreground\)/g)) {
+					// A theme hook is the sanctioned place to retune a derived surface,
+					// in CSS or as an arbitrary property ([--theme-x:color-mix(…)]).
+					if (/--theme-[\w-]+\s*:\s*$/.test(line.slice(0, m.index))) continue
 					out.push({ match: m[0].length > 60 ? `${m[0].slice(0, 57)}…` : m[0] })
 				}
 				return out
@@ -964,6 +968,21 @@ function stripComments(src) {
 		.replace(/(^|[^:])\/\/[^\n]*/gm, (m, p) => p + " ".repeat(m.length - p.length))
 }
 
+/**
+ * An `--ignore` glob as a RegExp over a CWD-relative, forward-slash path:
+ * `**` crosses directories, `*` stays within one. Shared by sable-lint and
+ * sable grade so the same flag skips the same files in both.
+ */
+export function ignoreGlob(glob) {
+	return new RegExp(
+		`^${glob
+			.replace(/[.+^${}()|[\]\\]/g, "\\$&")
+			.replace(/\*\*/g, "\0")
+			.replace(/\*/g, "[^/]*")
+			.replace(/\0/g, ".*")}$`,
+	)
+}
+
 export function lintText(text, rules, ctx) {
 	const lines = text.split(/\r?\n/)
 	const codeLines = stripComments(text).split(/\r?\n/)

package/dist/themes/base/index.d.ts

@@ -1,9 +0,0 @@
-import { T as ThemeManifest } from '../../_contract-o3tUc8Ig.js';
-
-/**
- * Base — the default Sable theme. Concrete token values live in
- * `base.css`; this manifest is the typed, machine-readable description.
- */
-declare const baseTheme: ThemeManifest;
-
-export { baseTheme, baseTheme as default };

package/dist/themes/base/index.js

@@ -1 +0,0 @@
-export { baseTheme, base_default as default } from '../../chunk-EP55KSYA.js';