@menapo/vicss 0.0.0-stage → 1.0.0

package/dist/index.js

@@ -0,0 +1,369 @@
+//#region src/runtime/merge.ts
+/**
+* S2 over the arguments, arrays flattened and a dynamic style read as its
+* constant style: the classes kept as they are, in order and once each, and
+* merge id → class. An argument's ids replace their own id and drop the ids
+* below them in their chain (`p` drops `p-b-s`, `md:p` does not); one
+* argument is an already merged set, whose ids never clear each other. The
+* recipe resolver and the compiler's fold share it.
+*/
+const merge = (args) => {
+	const names = /* @__PURE__ */ new Set();
+	const kept = /* @__PURE__ */ new Map();
+	const add = (list) => list.split(/\s+/).map((name) => name && names.add(name));
+	for (let arg of args.flat(1 / 0)) if (arg = arg && (arg.$c ?? arg)) if (arg.split) add(arg);
+	else {
+		for (const id of kept.keys()) for (const key in arg) if (id[key.length] == "-" && id.startsWith(key) && !id.includes(":", key.length)) {
+			kept.delete(id);
+			break;
+		}
+		for (const id in arg) if (id == "$n") add(arg[id]);
+		else kept.set(id, arg[id]);
+	}
+	return [names, kept];
+};
+/**
+* The class attribute: the classes kept as they are, then one class per id
+* in id order (S3), so folded, server and client output agree. The ids sort
+* alone: sorting `[id, class]` entries would join each into a string per
+* comparison, five times the cost.
+*/
+const join = ([names, kept]) => [...names, ...[...kept.keys()].sort().map((id) => kept.get(id))].join(" ");
+const cache = /* @__PURE__ */ new Map();
+let nodes = 0;
+let vars;
+/**
+* One argument: the trie node below `node` for it, or 0 once the call cannot
+* be cached. Falsy arguments contribute nothing, so they add no level.
+*/
+const walk = (node, arg) => {
+	if (!arg) return node;
+	const known = node && node.get(arg);
+	if (known) return known;
+	if (arg.map) return arg.reduce(walk, 0);
+	if (arg.$c) {
+		Object.assign(vars, arg.$s);
+		return walk(node, arg.$c);
+	}
+	return node && (nodes++, node.set(arg, /* @__PURE__ */ new Map()).get(arg));
+};
+/** The merged class attribute, cached per argument identity; `style` collects the custom properties. */
+const classes = (args, style) => {
+	if (nodes >> 10) {
+		cache.clear();
+		nodes = 0;
+	}
+	vars = style;
+	return (args.reduce(walk, cache) || {}).r ??= join(merge(args));
+};
+/**
+* Attributes for React and Preact. In other frameworks the plugin points
+* `sx` at the function of their shape, so its type is the project's
+* (`Register`, types.ts).
+*/
+const sx$1 = (...args) => {
+	const style = {};
+	const attrs = { className: classes(args, style) };
+	for (const _ in style) attrs.style = style;
+	return attrs;
+};
+/** Attributes for Solid and Vue: `style` as an object. */
+const sxClass = (...args) => {
+	const style = {};
+	const attrs = { class: classes(args, style) };
+	for (const _ in style) attrs.style = style;
+	return attrs;
+};
+/** Attributes for Svelte, Astro and vanilla JS: `style` as `a:b;c:d`. */
+const sxString = (...args) => {
+	const style = {};
+	const attrs = { class: classes(args, style) };
+	const text = Object.entries(style).filter(([, value]) => value != null && value !== false && value !== "").map((entry) => entry.join(":")).join(";");
+	if (text) attrs.style = text;
+	return attrs;
+};
+//#endregion
+//#region src/runtime/uncompiled.ts
+const notCompiled = (name) => {
+	throw new Error(`vicss: ${name}() was not compiled. Add the plugin from "@menapo/vicss/vite" to the Vite config: plugins: [vicss()].`);
+};
+/**
+* A style object compiled to a style (merge id → class) that records the
+* keys it sets; a function style compiles to a function returning that
+* style and the custom properties its classes read. `{ name: "card" }` adds
+* the class `card` as it is.
+*/
+const css = () => notCompiled("css");
+function recipe() {
+	return notCompiled("recipe");
+}
+function theme() {
+	return notCompiled("theme");
+}
+function group() {
+	return notCompiled("group");
+}
+function peer() {
+	return notCompiled("peer");
+}
+function keyframes() {
+	return notCompiled("keyframes");
+}
+function token() {
+	return notCompiled("token");
+}
+//#endregion
+//#region src/runtime/recipe.ts
+/**
+* The recipe resolver (PLAN §4.4, §5.7): what a compiled `recipe()` becomes,
+* `__vxRecipe(table)`, or `__vxRecipe(table, __vxResponsive)` for a recipe
+* with responsive variants. The compiler did the styling: every cell of the
+* table is a compiled style (merge id → class), so a call chooses cells and
+* merges them with `sx`'s rule, in the order a style object would be assigned: base,
+* each variant in declaration order, then the compounds that hold. Literal
+* calls fold at build time through `resolveRecipe` in src/core/recipe.ts,
+* which must agree with this file class for class. Bytes matter more than
+* elegance: tests/runtime/size.test.ts holds both functions to a budget, and
+* an app without responsive recipes never bundles `__vxResponsive`.
+*
+* The table (`RecipeTable` below; src/core/recipe.ts writes it):
+*
+* - `k`: variant names in declaration order; `s`: slot names, in slot recipes.
+* - `b`, `v[variant][value]`: base and variant styles. A cell is a style,
+*   or a style per slot in a slot recipe.
+* - `c`: compounds in order, `[when, classes, ranges?, cut?]`; `when` lists
+*   the values each named variant must have, as strings (`"true"`).
+* - `d`: defaults as strings, `"false"` for a boolean variant without one.
+* - `q`: `[conditions, breakpoints]`, the conditions a responsive prop may
+*   set (`md`, `containerMd`) in ascending rank, of which the first
+*   `breakpoints` are breakpoints and the rest container sizes.
+* - `r[variant][value][condition]`: a responsive variant's value under each
+*   of those conditions. Every responsive variant has an entry, in
+*   declaration order.
+* - `ranges[piece]`: a compound under the range condition of each piece of
+*   the width axis, keyed by its bounds (`",md"` below md, `"md,lg"`, `"lg,"`
+*   from lg, `"containerMd,"`); `cut` lists the responsive variants whose
+*   conditions cut the axis into the pieces it is evaluated on.
+* - `f`, in dev only: each flattened base's atoms, as a style, by its class
+*   (the cell's `$b`, src/core/flatten.ts), for `flatBases`.
+*/
+const warn = (message) => console.warn("vicss: " + message);
+/**
+* Dev only: the atoms of every flattened base a resolver was made with, by
+* class, which `sx()`'s dev variant reads (runtime/dev.ts). Production
+* builds drop it with the branch that fills it.
+*/
+const flatBases = {};
+const __vxRecipe = (t, x) => {
+	const { k: keys, d: defaults, v: variants } = t;
+	const memo = /* @__PURE__ */ new Map();
+	if (process.env.NODE_ENV != "production") Object.assign(flatBases, t.f);
+	return Object.assign((props = {}) => {
+		const id = JSON.stringify(keys.map((key) => props[key] ?? defaults[key]));
+		let result = memo.get(id);
+		if (!result) {
+			const values = {};
+			const cells = [t.b];
+			for (const key of keys) {
+				let value = props[key] ?? defaults[key];
+				if (typeof value == "object") {
+					if (process.env.NODE_ENV != "production" && !t.r?.[key]) warn(`\`${key}\` is not a responsive variant; its base value applies.`);
+					value = value.base ?? defaults[key];
+				}
+				cells.push(variants[key][values[key] = "" + value]);
+			}
+			const add = x?.(t, props, values, cells);
+			for (const compound of t.c) if (add) add(compound);
+			else if (Object.keys(compound[0]).every((key) => compound[0][key].includes(values[key]))) cells.push(compound[1]);
+			const slot = (name) => Object.fromEntries(merge(cells.map((cell) => typeof cell == "object" && (name ? cell[name] : cell)))[1]);
+			result = t.s ? Object.fromEntries(t.s.map((name) => [name, slot(name)])) : slot();
+			if (process.env.NODE_ENV != "production") Object.freeze(result);
+			if (memo.size >> 10) memo.clear();
+			memo.set(id, result);
+		}
+		return result;
+	}, {
+		variantKeys: keys,
+		splitProps: (props) => {
+			const split = [{}, {}];
+			for (const key in props) split[keys.includes(key) ? 0 : 1][key] = props[key];
+			return split;
+		},
+		schema: {
+			variants: Object.fromEntries(keys.map((key) => [key, Object.keys(variants[key])])),
+			defaults
+		}
+	});
+};
+/**
+* Responsive props (PLAN §4.4): each condition a prop sets adds its value's
+* `r` cell, in rank order, so values stack mobile-first. A compound that has
+* ranges is evaluated on each piece of the width axis, cut at the conditions
+* its `cut` variants' props set, with the values in effect there, and adds
+* its classes under the range condition of each piece where it holds: that
+* range outranks every condition that holds anywhere in the piece. `ranges`
+* keys a piece by its bounds: `",md"` below md, `"md,lg"`, `"lg,"` from lg.
+*/
+const __vxResponsive = (t, props, values, cells) => {
+	const [all, breakpoints] = t.q;
+	const r = t.r;
+	/** The value `key`'s prop sets under condition `name`; `key` is a responsive variant. */
+	const at = (key, name) => props[key]?.["_" + name];
+	for (const key in r) {
+		if (process.env.NODE_ENV != "production" && typeof props[key] == "object") {
+			for (const name in props[key]) if (name != "base" && !(name[0] == "_" && all.includes(name.slice(1)))) warn(`\`${name}\` is not a breakpoint or container condition of \`${key}\`; it is ignored. A recipe takes those of the design system it was compiled with: a library's, its own.`);
+		}
+		for (const name of all) if (at(key, name) != null) cells.push(r[key][at(key, name)]?.[name]);
+	}
+	return ([when, classes, ranges, cut = []]) => {
+		const current = { ...values };
+		const points = all.filter((name) => cut.some((key) => at(key, name) != null));
+		const n = points.length;
+		const held = ["", ...points].map((point) => (cut.map((key) => current[key] = "" + (at(key, point) ?? current[key])), Object.keys(when).every((key) => when[key].includes(current[key]))));
+		if (!n) return held[0] && cells.push(classes);
+		if (all.indexOf(points[n - 1]) < breakpoints) return held.map((holds, i) => holds && cells.push(ranges[[points[i - 1], points[i]] + ""]));
+		let i = n;
+		if (all.indexOf(points[0]) >= breakpoints) for (; i >= 0 && held[i]; i--) cells.push(i ? ranges[points[i - 1] + ","] : classes);
+		if (process.env.NODE_ENV != "production" && held.slice(0, i + 1).includes(true)) warn(`a compound variant on ${Object.keys(when).join(", ")} holds where no breakpoint or container condition expresses; it is left out there.`);
+	};
+};
+//#endregion
+//#region src/runtime/dev.ts
+/**
+* Dev only (PLAN §5.14): the compiler rewrites a runtime `sx()` call to the
+* variant of its module's shape (§5.12), so the element names the source
+* line that styled it, and wraps a function style's runtime values in a
+* check. Builds never reference them, so they cost production bundles
+* nothing.
+*/
+/**
+* The arguments' compiled styles, nested arrays flattened and a dynamic
+* style's constant one taken: each one merged apart, as `sx()` merges them.
+* Classes of the app's own (strings) set no merge id.
+*/
+const styles = (args) => args.flat(1 / 0).flatMap((arg) => arg && typeof arg == "object" ? [arg.$c ?? arg] : []);
+/**
+* The classes under one reserved id among the arguments (`$t`, a theme,
+* core/theme.ts; `$b`, a flattened base, core/flatten.ts), in the order of
+* their last appearance: the last one is the one kept.
+*/
+const lastOf = (records, id) => {
+	const found = /* @__PURE__ */ new Set();
+	for (const record of records) {
+		const name = record[id];
+		if (name === void 0) continue;
+		found.delete(name);
+		found.add(name);
+	}
+	return [...found];
+};
+const withoutBase = (record) => {
+	const { $b: _, ...rest } = record;
+	return rest;
+};
+const classesOf = (args) => new Set(merge(args)[1].values());
+/**
+* The classes of earlier arguments that the flattened base `base` would
+* clear, or beat by tier, as atoms and, applied under every class of its
+* element, cannot: core/flatten.ts's `shadowedByEarlier`, with the runtime
+* merge.
+*/
+const shadowed = (records, base) => {
+	const atoms = flatBases[base];
+	const at = records.findLastIndex((record) => record.$b === base);
+	if (atoms === void 0 || at < 1) return [];
+	const without = records.map(withoutBase);
+	const own = Object.fromEntries(merge([atoms, without[at]])[1]);
+	const atomic = classesOf([
+		...without.slice(0, at),
+		own,
+		...without.slice(at + 1)
+	]);
+	const flattened = classesOf([atoms, ...without]);
+	const lost = Object.entries(atoms).filter(([, name]) => atomic.has(name) && !flattened.has(name)).map(([id]) => id);
+	const out = /* @__PURE__ */ new Set();
+	for (const record of without.slice(0, at)) for (const [id, name] of Object.entries(record)) if (lost.some((other) => other == id || other.startsWith(id + "-")) || flattened.has(name) && !atomic.has(name)) out.add(name);
+	return [...out].sort();
+};
+/**
+* The shape's attributes plus `data-vx-src="src/Card.tsx:12"`. Two themes,
+* or two flattened recipe bases, among the arguments warn: one element
+* keeps the last (core/theme.ts, core/flatten.ts); so does an earlier
+* argument a flattened base cannot override.
+*/
+const withSource = (shape) => (src, ...args) => {
+	const records = styles(args);
+	const themes = lastOf(records, "$t");
+	if (themes.length > 1) {
+		const lost = themes.slice(0, -1).map((name) => `\`${name}\``);
+		console.warn(`vicss: ${src}: sx() keeps one theme per element, the last (\`${themes.at(-1)}\`): ${lost.join(", ")} ${lost.length === 1 ? "is" : "are"} dropped. Write one theme() with every override, or apply the themes to nested elements.`);
+	}
+	const bases = lastOf(records, "$b");
+	if (bases.length > 1) {
+		const lost = bases.slice(0, -1).map((name) => `\`${name}\``);
+		console.warn(`vicss: ${src}: sx() keeps one flattened recipe base per element, the last (\`${bases.at(-1)}\`): ${lost.join(", ")} ${lost.length === 1 ? "is" : "are"} dropped. Flatten one of the recipes only (\`flatten: false\` on the other), or apply them to nested elements.`);
+	} else if (bases.length === 1) {
+		const lost = shadowed(records, bases[0]).map((name) => `\`${name}\``);
+		if (lost.length > 0) console.warn(`vicss: ${src}: sx() applies the flattened recipe base \`${bases[0]}\` under every class of the element: ${lost.join(", ")}, from an earlier argument, ${lost.length === 1 ? "wins" : "win"} over what the base sets, which an atomic base would override. Pass the recipe's result first (sx(recipe(…), …)), or leave its base atomic (\`flatten: false\`).`);
+	}
+	return {
+		...shape(...args),
+		"data-vx-src": src
+	};
+};
+const warned = /* @__PURE__ */ new Set();
+/**
+* Warns once per value that is neither a token (`variable`, the custom
+* property it would read) nor a CSS value of `property`: the browser
+* drops such a declaration without a word (PLAN D33).
+*/
+const check = (property, value, variable) => {
+	const { CSS, getComputedStyle, document } = globalThis;
+	const id = `${property}:${value}`;
+	if (!CSS?.supports || warned.has(id) || CSS.supports(property, value)) return;
+	if (variable && getComputedStyle && document && getComputedStyle(document.documentElement).getPropertyValue(variable) !== "") return;
+	warned.add(id);
+	console.warn(`vicss: \`${value}\` is ${variable ? "neither a token nor" : "not"} a valid value of \`${property}\`, so the browser ignores it. A function style writes a runtime value as it is${variable ? " when it names no token" : ""}: type the parameter Token<"…"> to name tokens, and pass a CSS value otherwise.`);
+};
+/** A function style's runtime value in dev: as in a build, checked. */
+const devValue = (property, value) => {
+	if (typeof value == "string" && value) check(property, value);
+	return value;
+};
+/**
+* A Token-typed parameter's value in dev: what core/compile.ts
+* `tokenExpression` writes in a build, checked.
+*/
+const devToken = (property, prefix, value) => {
+	if (value == null) return void 0;
+	const text = String(value);
+	if (!/^[\w.-]+$/.test(text)) {
+		check(property, text);
+		return text;
+	}
+	const variable = prefix + text.replace(/\./g, "-");
+	check(property, text, variable);
+	return `var(${variable}, ${text})`;
+};
+/** React and Preact: `{ className, style, "data-vx-src" }`. */
+const sxDev = /*#__PURE__*/ withSource(sx$1);
+/** Solid and Vue: `{ class, style, "data-vx-src" }`, `style` an object. */
+const sxDevClass = /*#__PURE__*/ withSource(sxClass);
+/** Svelte, Astro and vanilla JS: `{ class, style, "data-vx-src" }`, `style` a string. */
+const sxDevString = /*#__PURE__*/ withSource(sxString);
+//#endregion
+//#region src/index.ts
+/**
+* The runtime entry, `@menapo/vicss` (PLAN §5.1). In an app the plugin replaces
+* `css()`, `recipe()`, `theme()`, `group()`, `peer()`, `keyframes()` and `token()`
+* with constants, so only `sx` and the recipe resolver ship.
+* Nothing here imports from the build side; the plugin lives in `/vite`.
+*/
+/**
+* `sx()` with the public types: compiled styles and class strings in, the
+* attributes of the project's framework out. The runtime's own signature
+* returns React's shape.
+*/
+const sx = sx$1;
+//#endregion
+export { devToken as __vxDevToken, devValue as __vxDevValue, flatBases as __vxFlatBases, __vxRecipe, __vxResponsive, sxClass as __vxSxClass, sxDev as __vxSxDev, sxDevClass as __vxSxDevClass, sxDevString as __vxSxDevString, sxString as __vxSxString, css, group, keyframes, peer, recipe, sx, theme, token };

package/dist/lint.d.ts

@@ -0,0 +1,114 @@
+//#region src/lint/names.d.ts
+/**
+ * The rules' names, apart from the analysis: the entry's declarations name
+ * them (`rules`), and the analysis imports Vite's AST types, which a project
+ * type-checking its lint config may not have installed.
+ */
+type RuleName = "static-styles" | "valid-styles" | "no-private-tokens" | "no-uncompiled-styles" | "no-arbitrary";
+//#endregion
+//#region src/lint/rules.d.ts
+/** A source range, as both linters' fixers take it. */
+type Range = [number, number];
+/** An edit, as a fixer makes it. */
+interface Fix {
+  range: Range;
+  text: string;
+}
+/** The fixer both linters pass to `fix` and to a suggestion's `fix`. */
+interface Fixer {
+  replaceTextRange(range: Range, text: string): Fix;
+}
+interface ReportBase {
+  readonly message: string;
+  readonly fix?: (fixer: Fixer) => Fix[];
+  readonly suggest?: Array<{
+    desc: string;
+    fix: (fixer: Fixer) => Fix[];
+  }>;
+}
+/** A report names a node (it has a `range` in both linters' ASTs) or a line and a column. */
+type Report = ReportBase & ({
+  readonly node: {
+    readonly range: Range;
+  };
+} | {
+  readonly loc: {
+    readonly line: number;
+    readonly column: number;
+  };
+});
+/** What a rule's `create` receives, in Oxlint and in ESLint: the part these rules read. */
+interface RuleContext {
+  readonly filename: string;
+  readonly cwd?: string;
+  readonly options: readonly unknown[];
+  readonly settings?: Readonly<Record<string, unknown>>;
+  readonly sourceCode: {
+    readonly text: string;
+    readonly ast: unknown;
+  };
+  report(report: Report): void;
+}
+interface RuleMeta {
+  readonly type: "problem" | "suggestion";
+  readonly docs: {
+    readonly description: string;
+    readonly recommended: boolean;
+    readonly requiresSnapshot: boolean;
+    readonly url: string;
+  };
+  readonly fixable?: "code";
+  readonly hasSuggestions?: boolean;
+  /** JSON Schemas of the options, one per option. */
+  readonly schema: Array<Record<string, unknown>>;
+}
+interface Rule {
+  readonly meta: RuleMeta;
+  create(context: RuleContext): {
+    Program(node: unknown): void;
+  };
+}
+export declare const rules: Readonly<Record<RuleName, Rule>>;
+//#endregion
+//#region src/lint/snapshot.d.ts
+/** `settings.vicss` in the Oxlint or ESLint config. */
+interface LintSettings {
+  /** The snapshot file, relative to the working directory, when it is not found by searching. */
+  readonly snapshot?: string;
+  /** Modules that re-export the vicss runtime, besides the config's `importSources`. */
+  readonly importSources?: readonly string[];
+}
+//#endregion
+//#region src/lint.d.ts
+type Severity = "off" | "warn" | "error";
+/** The rules `recommended` turns on: every rule but `no-arbitrary`, which a design-system team opts into. */
+export declare const recommendedRules: Readonly<Record<string, Severity>>;
+export interface VicssLintPlugin {
+  readonly meta: {
+    readonly name: "vicss";
+  };
+  readonly rules: Readonly<Record<string, Rule>>;
+  readonly configs: {
+    /** An ESLint flat config object; its `rules` serve Oxlint's config too. */
+    readonly recommended: {
+      readonly name: string;
+      readonly plugins: {
+        readonly vicss: VicssLintPlugin;
+      };
+      readonly rules: Readonly<Record<string, Severity>>;
+    };
+  };
+}
+declare const plugin: VicssLintPlugin;
+export declare const configs: {
+  /** An ESLint flat config object; its `rules` serve Oxlint's config too. */
+  readonly recommended: {
+    readonly name: string;
+    readonly plugins: {
+      readonly vicss: VicssLintPlugin;
+    };
+    readonly rules: Readonly<Record<string, Severity>>;
+  };
+};
+//#endregion
+export { type Fix, type Fixer, type LintSettings, type Range, type Report, type Rule, type RuleContext, type RuleMeta, plugin as default };