praxis-kit 0.1.0

package/dist/tailwind/safelist.css

@@ -0,0 +1,20 @@
+/*
+ * `createTailwindPipeline` assembles display-mode classes (flex, inline-flex,
+ * grid, hidden, etc.) at runtime from boolean props — they never appear as a
+ * literal string anywhere in scanned source, so Tailwind v4's content
+ * detection never generates their CSS on its own.
+ *
+ * `@source inline(...)` forces Tailwind to generate these utilities
+ * regardless of what its scanner finds. This file is copied verbatim into
+ * `praxis-kit`'s published dist (see packages/kit/scripts/postbuild.mjs) and
+ * exposed as the `praxis-kit/tailwind.css` subpath — `@praxis-kit/tailwind`
+ * itself is a private, unpublished workspace package. Import it alongside
+ * `tailwindcss` in your app's main CSS entry point:
+ *
+ *   @import "tailwindcss";
+ *   @import "praxis-kit/tailwind.css";
+ *
+ * Keep this list in sync with `layout-keys.ts` — enforced by
+ * `tailwind-safelist.test.ts`.
+ */
+@source inline("flex inline-flex grid inline-grid block inline-block inline hidden contents flow-root list-item table inline-table table-caption table-cell table-column table-column-group table-footer-group table-header-group table-row-group table-row");

package/dist/ts-plugin/index.cjs

@@ -0,0 +1,166 @@
+//#region ../../plugins/typescript/src/ast.ts
+function getObjectProperty(ts, obj, key) {
+	for (const prop of obj.properties) {
+		if (!ts.isPropertyAssignment(prop)) continue;
+		const name = prop.name;
+		if (ts.isIdentifier(name) && name.text === key) return prop;
+		if (ts.isStringLiteral(name) && name.text === key) return prop;
+	}
+}
+function asObjectLiteralExpression(ts, node) {
+	if (!node) return void 0;
+	return ts.isObjectLiteralExpression(node) ? node : void 0;
+}
+function asArrayLiteralExpression(ts, node) {
+	if (!node) return void 0;
+	return ts.isArrayLiteralExpression(node) ? node : void 0;
+}
+function asNumericValue(ts, node) {
+	if (!node) return void 0;
+	if (ts.isNumericLiteral(node)) return Number(node.text);
+	if (ts.isPrefixUnaryExpression(node) && (node.operator === ts.SyntaxKind.MinusToken || node.operator === ts.SyntaxKind.PlusToken) && ts.isNumericLiteral(node.operand)) {
+		const val = Number(node.operand.text);
+		return node.operator === ts.SyntaxKind.MinusToken ? -val : val;
+	}
+}
+function isFactoryCall(ts, node, names) {
+	const { expression } = node;
+	if (ts.isIdentifier(expression)) return names.has(expression.text);
+	if (ts.isPropertyAccessExpression(expression)) return names.has(expression.name.text);
+	return false;
+}
+function getFirstObjectArg(ts, node) {
+	const [first] = node.arguments;
+	if (!first) return void 0;
+	return ts.isObjectLiteralExpression(first) ? first : void 0;
+}
+//#endregion
+//#region ../../plugins/typescript/src/diagnostics/walk-enforcement.ts
+/**
+* Walks a source file and calls `cb` for every factory call that has a
+* statically-resolvable `enforcement` object literal argument.
+*/
+function walkEnforcement(ts, sourceFile, calleeNames, cb) {
+	function visit(node) {
+		if (ts.isCallExpression(node) && isFactoryCall(ts, node, calleeNames)) {
+			const arg = getFirstObjectArg(ts, node);
+			if (arg) {
+				const enfProp = getObjectProperty(ts, arg, "enforcement");
+				if (enfProp) {
+					const enf = asObjectLiteralExpression(ts, enfProp.initializer);
+					if (enf) cb(node, enf);
+				}
+			}
+		}
+		ts.forEachChild(node, visit);
+	}
+	visit(sourceFile);
+}
+//#endregion
+//#region ../../plugins/typescript/src/diagnostics/no-enforcement-without-strict.ts
+const MISSING_STRICT_CODE = 90001;
+function checkNoEnforcementWithoutStrict(ts, sourceFile, calleeNames) {
+	const diagnostics = [];
+	walkEnforcement(ts, sourceFile, calleeNames, (_node, enf) => {
+		if (!(getObjectProperty(ts, enf, "strict") !== void 0)) for (const field of ["children", "aria"]) {
+			const fieldProp = getObjectProperty(ts, enf, field);
+			if (!fieldProp) continue;
+			if (field === "children") {
+				const arr = asArrayLiteralExpression(ts, fieldProp.initializer);
+				if (!arr || arr.elements.length === 0) continue;
+			}
+			const anchor = fieldProp.name;
+			diagnostics.push({
+				file: sourceFile,
+				start: anchor.getStart(sourceFile),
+				length: anchor.getWidth(sourceFile),
+				category: ts.DiagnosticCategory.Warning,
+				code: MISSING_STRICT_CODE,
+				messageText: `enforcement.${field} is defined but enforcement.strict is not explicitly set. Adapter defaults vary — declare strict explicitly so the behavior is clear at the call site.`,
+				source: "praxis-kit/ts-plugin"
+			});
+			break;
+		}
+	});
+	return diagnostics;
+}
+//#endregion
+//#region ../../plugins/typescript/src/diagnostics/valid-cardinality.ts
+const NEGATIVE_MIN_CODE = 90002;
+const NEGATIVE_MAX_CODE = 90003;
+const MAX_LESS_THAN_MIN_CODE = 90004;
+function checkValidCardinality(ts, sourceFile, calleeNames) {
+	const diagnostics = [];
+	walkEnforcement(ts, sourceFile, calleeNames, (_, enf) => {
+		const childrenProp = getObjectProperty(ts, enf, "children");
+		if (!childrenProp) return;
+		const arr = asArrayLiteralExpression(ts, childrenProp.initializer);
+		if (!arr) return;
+		for (const element of arr.elements) {
+			if (!ts.isObjectLiteralExpression(element)) continue;
+			const cardProp = getObjectProperty(ts, element, "cardinality");
+			if (!cardProp) continue;
+			const card = asObjectLiteralExpression(ts, cardProp.initializer);
+			if (!card) continue;
+			const minProp = getObjectProperty(ts, card, "min");
+			const maxProp = getObjectProperty(ts, card, "max");
+			const min = minProp ? asNumericValue(ts, minProp.initializer) : void 0;
+			const max = maxProp ? asNumericValue(ts, maxProp.initializer) : void 0;
+			if (min !== void 0 && min < 0) diagnostics.push({
+				file: sourceFile,
+				start: minProp.getStart(sourceFile),
+				length: minProp.getWidth(sourceFile),
+				category: ts.DiagnosticCategory.Error,
+				code: NEGATIVE_MIN_CODE,
+				messageText: `cardinality.min must be >= 0 (got ${min}).`,
+				source: "praxis-kit/ts-plugin"
+			});
+			if (max !== void 0 && max < 0) diagnostics.push({
+				file: sourceFile,
+				start: maxProp.getStart(sourceFile),
+				length: maxProp.getWidth(sourceFile),
+				category: ts.DiagnosticCategory.Error,
+				code: NEGATIVE_MAX_CODE,
+				messageText: `cardinality.max must be >= 0 (got ${max}).`,
+				source: "praxis-kit/ts-plugin"
+			});
+			if (min !== void 0 && max !== void 0 && min >= 0 && max > 0 && max < min) diagnostics.push({
+				file: sourceFile,
+				start: cardProp.getStart(sourceFile),
+				length: cardProp.getWidth(sourceFile),
+				category: ts.DiagnosticCategory.Error,
+				code: MAX_LESS_THAN_MIN_CODE,
+				messageText: `cardinality.max (${max}) must be >= cardinality.min (${min}). This rule can never be satisfied.`,
+				source: "praxis-kit/ts-plugin"
+			});
+		}
+	});
+	return diagnostics;
+}
+//#endregion
+//#region ../../plugins/typescript/src/index.ts
+const DEFAULT_CALLEE_NAMES = ["createContractComponent"];
+function init(modules) {
+	const ts = modules.typescript;
+	function create(info) {
+		const calleeNames = new Set(info.config.calleeNames ?? DEFAULT_CALLEE_NAMES);
+		const proxy = Object.create(null);
+		for (const k of Object.keys(info.languageService)) {
+			const x = info.languageService[k];
+			Reflect.set(proxy, k, typeof x === "function" ? x.bind(info.languageService) : x);
+		}
+		proxy.getSemanticDiagnostics = (fileName) => {
+			const existing = info.languageService.getSemanticDiagnostics(fileName);
+			const program = info.languageService.getProgram();
+			if (!program) return existing;
+			const sourceFile = program.getSourceFile(fileName);
+			if (!sourceFile) return existing;
+			const extra = [...checkNoEnforcementWithoutStrict(ts, sourceFile, calleeNames), ...checkValidCardinality(ts, sourceFile, calleeNames)];
+			return [...existing, ...extra];
+		};
+		return proxy;
+	}
+	return { create };
+}
+module.exports = init;
+//#endregion

package/dist/ts-plugin/index.d.cts

@@ -0,0 +1,9 @@
+import tsserverlibrary from "typescript/lib/tsserverlibrary";
+//#region ../../plugins/typescript/src/index.d.ts
+type TS = typeof tsserverlibrary;
+declare function init(modules: {
+  typescript: TS;
+}): {
+  create: (info: tsserverlibrary.server.PluginCreateInfo) => tsserverlibrary.LanguageService;
+};
+export = init;

package/dist/utils/index.d.ts

@@ -0,0 +1,19 @@
+import "clsx";
+import "../_shared/diagnostics.js";
+import "type-fest";
+//#region ../../lib/primitive/src/types/function-types.d.ts
+/** A single-argument pure function — the shape `memoize()` wraps. */
+type UnaryFn<T, R> = (arg: T) => R;
+//#endregion
+//#region ../../lib/primitive/src/utils/memoize.d.ts
+/**
+ * Caches the result of a pure, single-argument function in an unbounded `Map`.
+ *
+ * Best suited to functions that are expensive relative to a cache lookup and
+ * repeatedly called with a relatively small, bounded set of inputs (for
+ * example, a finite vocabulary of tokens or strings). Avoid memoizing
+ * unbounded or attacker-controlled input spaces, as the cache will grow
+ * without limit. Use `LRUCache` instead when cache size should remain bounded.
+ */
+export declare function memoize<T, R>(fn: UnaryFn<T, R>): UnaryFn<T, R>;
+//#endregion

package/dist/utils/index.js

@@ -0,0 +1,21 @@
+//#region ../../lib/primitive/src/utils/memoize.ts
+/**
+* Caches the result of a pure, single-argument function in an unbounded `Map`.
+*
+* Best suited to functions that are expensive relative to a cache lookup and
+* repeatedly called with a relatively small, bounded set of inputs (for
+* example, a finite vocabulary of tokens or strings). Avoid memoizing
+* unbounded or attacker-controlled input spaces, as the cache will grow
+* without limit. Use `LRUCache` instead when cache size should remain bounded.
+*/
+function memoize(fn) {
+	const cache = /* @__PURE__ */ new Map();
+	return (arg) => {
+		if (cache.has(arg)) return cache.get(arg);
+		const result = fn(arg);
+		cache.set(arg, result);
+		return result;
+	};
+}
+//#endregion
+export { memoize };

package/dist/vite-plugin/index.d.ts

@@ -0,0 +1,200 @@
+import ts from "typescript";
+import "clsx";
+import { DiagnosticCode } from "../_shared/diagnostics.js";
+import { Plugin } from "vite";
+import "type-fest";
+//#region ../../lib/foundation/src/string-map.d.ts
+/**
+ * A string-keyed object whose values are of type `T`.
+ */
+type StringMap<T = unknown> = Record<string, T>;
+//#endregion
+//#region ../../lib/primitive/src/types/aria-rule/severity.d.ts
+type Severity = 'error' | 'warning' | (string & {});
+//#endregion
+//#region ../../plugins/vite/src/types/plugin-options.d.ts
+/** Options accepted by contractPlugin() and analyze(). */
+type PluginOptions = {
+  /**
+   * Factory function names to look for.
+   * @default ['createPolymorphicComponent', 'createContractComponent']
+   */
+  calleeNames?: string[];
+  /**
+   * Severity of cardinality violations in Vite build output.
+   * Matches the Severity vocabulary used by ValidationViolation.
+   * @default 'warning'
+   */
+  severity?: Severity;
+};
+//#endregion
+//#region ../../plugins/vite/src/design-tokens.d.ts
+type ComponentTokens = {
+  base: string[];
+  variantClasses: string[];
+  compoundClasses: string[];
+  tagClasses: string[];
+};
+type DesignTokenManifest = {
+  components: StringMap<ComponentTokens>;
+  allClasses: string[];
+};
+type DesignTokensOptions = {
+  /**
+   * Path where the manifest JSON is written, relative to the Vite project root.
+   * @default 'praxis-tokens.json'
+   */
+  outFile?: string;
+} & Pick<PluginOptions, 'calleeNames'>;
+/**
+ * Vite plugin that collects every statically-declared class string from
+ * `createContractComponent` factory calls and writes a design token manifest
+ * to a JSON file on each build.
+ *
+ * The manifest contains per-component class lists and a flat `allClasses`
+ * union that can be used as a Tailwind content source to prevent purging of
+ * variant classes.
+ *
+ * @example
+ * // vite.config.ts
+ * import { designTokensPlugin } from 'praxis-kit/vite-plugin'
+ * export default { plugins: [designTokensPlugin({ outFile: 'praxis-tokens.json' })] }
+ *
+ * @example
+ * // tailwind.config.js
+ * export default { content: ['./src/**', './praxis-tokens.json'] }
+ */
+export declare function designTokensPlugin(options?: DesignTokensOptions): Plugin;
+//#endregion
+//#region ../../plugins/vite/src/index.d.ts
+/**
+ * Vite plugin that performs static enforcement.children cardinality checks at
+ * build time for components created with createContractComponent.
+ *
+ * **Single-file scope:** Components defined and used in the same `.tsx` / `.jsx`
+ * file are validated during `transform`. JSX children containing expressions
+ * (`{...}`) are skipped — their count is unknowable at compile time.
+ *
+ * **Cross-file scope:** Components imported from other files are validated in
+ * `buildEnd` once the full constraint registry is populated. Only named imports
+ * whose source file was also transformed by this plugin are checked.
+ *
+ * @example
+ * // vite.config.ts
+ * import { contractPlugin } from 'praxis-kit/vite-plugin'
+ * export default { plugins: [contractPlugin()] }
+ */
+export declare function contractPlugin(options?: PluginOptions): Plugin;
+/**
+ * Vite plugin that removes dead `styling.compounds` entries from factory calls
+ * at build time, reducing bundle size and eliminating unreachable CVA compound
+ * checks at runtime.
+ *
+ * A compound entry is dead when any of its conditions reference a variant key
+ * that does not exist in `styling.variants`, or a value that is not valid for
+ * that key. Only entries whose conditions are fully static (string/array
+ * literals) are pruned — dynamic conditions are left unchanged.
+ *
+ * Place before `contractPlugin` so the pruned source is what gets analyzed.
+ *
+ * @example
+ * // vite.config.ts
+ * import { compoundPrunePlugin, contractPlugin } from 'praxis-kit/vite-plugin'
+ * export default { plugins: [compoundPrunePlugin(), contractPlugin()] }
+ */
+export declare function compoundPrunePlugin(options?: Pick<PluginOptions, 'calleeNames'>): Plugin;
+/**
+ * Vite plugin that pre-computes variant class strings at build time and injects
+ * them as a static `precomputedClasses` map into each factory call's `styling`
+ * object.
+ *
+ * At runtime, `VariantClassResolver` checks this map before calling CVA — a
+ * plain object lookup replaces a CVA invocation + LRU cache write for every
+ * statically-known combination. Only combinations that appear in the map are
+ * accelerated; invalid or dynamic variant values fall through to the existing
+ * compute path unchanged.
+ *
+ * Injection is skipped when:
+ * - `styling.variants` is absent or contains non-literal values
+ * - `styling.compounds` contains non-literal conditions or classes
+ * - The number of valid combinations exceeds 512
+ *
+ * Place after `compoundPrunePlugin` so the injected map reflects the live
+ * compound set.
+ *
+ * @example
+ * // vite.config.ts
+ * import { compoundPrunePlugin, classExtractPlugin, contractPlugin } from 'praxis-kit/vite-plugin'
+ * export default { plugins: [compoundPrunePlugin(), classExtractPlugin(), contractPlugin()] }
+ */
+export declare function classExtractPlugin(options?: Pick<PluginOptions, 'calleeNames'>): Plugin;
+/**
+ * Vite plugin that transforms `asChild` JSX usage sites to the render-prop form
+ * at build time, eliminating the Slot/cloneElement/mergeProps runtime path.
+ *
+ * Only transforms sites where the transform is semantically safe:
+ * - Exactly one static child element
+ * - Child has no `className`, `style`, or event handler props
+ *
+ * Complex asChild patterns (conflicting props, dynamic children, Slottable
+ * siblings) are left unchanged and handled by the runtime Slot path.
+ *
+ * Place before `contractPlugin` so cardinality analysis sees the transformed
+ * source.
+ *
+ * @example
+ * // vite.config.ts
+ * import { slotTransformPlugin, contractPlugin } from 'praxis-kit/vite-plugin'
+ * export default { plugins: [slotTransformPlugin(), contractPlugin()] }
+ */
+export declare function slotTransformPlugin(): Plugin;
+/**
+ * Vite plugin that replaces polymorphic component usage sites with direct
+ * element creation at build time, eliminating the runtime render pipeline for
+ * statically-analyzable usages.
+ *
+ * **Requires classExtractPlugin to run first** so that `precomputedClasses` is
+ * present in the factory call before this plugin reads it. Place after
+ * `classExtractPlugin` in the plugins array.
+ *
+ * A usage site is inlined when:
+ * - The component is defined in the same file or imported from a file already
+ *   transformed by this plugin, with `precomputedClasses` injected
+ * - No `as`, `asChild`, `render`, or spread attributes at the site
+ * - All variant props are static string literals
+ * - `className` is absent or a static string literal
+ * - The factory config has no `defaults` or `enforcement`
+ *
+ * Cross-file inlining degrades gracefully when the definition file has not yet
+ * been transformed (dev mode ordering, barrel re-exports, aliased imports).
+ *
+ * @example
+ * // vite.config.ts
+ * import { classExtractPlugin, staticCompositionPlugin } from 'praxis-kit/vite-plugin'
+ * export default { plugins: [classExtractPlugin(), staticCompositionPlugin()] }
+ */
+export declare function staticCompositionPlugin(options?: Pick<PluginOptions, 'calleeNames'>): Plugin;
+/**
+ * Convenience plugin bundle that applies all three build-time rendering
+ * optimisations in the correct dependency order:
+ *
+ *   1. `slotTransformPlugin`       — rewrites `asChild` → render-prop form,
+ *                                    eliminating `cloneElement` for static sites
+ *   2. `classExtractPlugin`        — injects `precomputedClasses` into factory
+ *                                    calls for O(1) variant class resolution
+ *   3. `staticCompositionPlugin`   — inlines same-file static usages into direct
+ *                                    element creation, bypassing the runtime
+ *                                    pipeline entirely
+ *
+ * Place before `contractPlugin` so cardinality analysis sees the transformed
+ * source. Especially effective for SSR builds where each component renders
+ * exactly once per request and eliminates per-render pipeline overhead.
+ *
+ * @example
+ * // vite.config.ts
+ * import { ssrOptimizePlugin, contractPlugin } from 'praxis-kit/vite-plugin'
+ * export default { plugins: [ssrOptimizePlugin(), contractPlugin()] }
+ */
+export declare function ssrOptimizePlugin(options?: Pick<PluginOptions, 'calleeNames'>): Plugin[];
+//#endregion
+export type { ComponentTokens, DesignTokenManifest, DesignTokensOptions, PluginOptions };