praxis-kit 1.1.0

package/dist/tailwind/index.d.ts

@@ -0,0 +1,138 @@
+import { VariantMap, ClassPipelineOptions, StrictMode, ClassPlugin } from '@praxis-kit/core';
+import { Simplify } from 'type-fest';
+import { EmptyRecord } from '@praxis-kit/shared';
+
+declare const LAYOUT_FAMILY_MAP: {
+    readonly flex: "flex";
+    readonly 'inline-flex': "flex";
+    readonly grid: "grid";
+    readonly 'inline-grid': "grid";
+    readonly block: "none";
+    readonly 'inline-block': "none";
+    readonly inline: "none";
+    readonly hidden: "none";
+    readonly contents: "none";
+    readonly 'flow-root': "none";
+    readonly 'list-item': "none";
+    readonly table: "none";
+    readonly 'table-caption': "none";
+    readonly 'table-cell': "none";
+    readonly 'table-column': "none";
+    readonly 'table-column-group': "none";
+    readonly 'table-footer-group': "none";
+    readonly 'table-header-group': "none";
+    readonly 'table-row-group': "none";
+    readonly 'table-row': "none";
+};
+
+declare const layoutKeys: readonly ["flex", "inline-flex", "grid", "inline-grid", "block", "inline-block", "inline", "hidden", "contents", "flow-root", "list-item", "table", "table-caption", "table-cell", "table-column", "table-column-group", "table-footer-group", "table-header-group", "table-row-group", "table-row"];
+
+type LayoutKey = (typeof layoutKeys)[number];
+type LayoutFamily = (typeof LAYOUT_FAMILY_MAP)[LayoutKey];
+type LayoutMode = LayoutKey | 'none';
+type ExclusiveTrueProp<K extends PropertyKey> = {
+    [P in K]: Simplify<Record<P, true> & Partial<Record<Exclude<K, P>, never>>>;
+}[K];
+/**
+ * Mutually exclusive display shorthand props.
+ *
+ * At most one key may be `true`. Passing multiple is a compile-time error; the
+ * runtime also warns and lets the first key in declaration order take precedence.
+ */
+type LayoutProps = ExclusiveTrueProp<LayoutKey> | Partial<Record<LayoutKey, never>>;
+
+type ClassToken = string;
+type Token<TKind extends string, TData extends object = EmptyRecord> = {
+    kind: TKind;
+    raw: string;
+} & TData;
+type LayoutToken = Token<'layout', {
+    value: LayoutKey;
+}>;
+type ConditionalToken = Token<'conditional', {
+    requires: Exclude<LayoutFamily, 'none'>;
+}>;
+type GapToken = Token<'gap'>;
+type UtilityToken = Token<'utility', {
+    base: string;
+}>;
+type ClassifiedToken = LayoutToken | ConditionalToken | GapToken | UtilityToken;
+
+type VariantSelection = Record<string, string>;
+type CompoundVariant = {
+    class?: unknown;
+} & Record<string, unknown>;
+
+/**
+ * Layout-aware class pipeline for Tailwind CSS utility class strings.
+ *
+ * This is a `ClassPluginFactory` — the runtime calls it with the component's
+ * resolved pipeline options and strict mode. Do NOT call it yourself; pass the
+ * function reference as `styling.plugin` and let the runtime invoke it.
+ *
+ * @example
+ * ```ts
+ * // CORRECT — pass the reference; the runtime calls it
+ * createContractComponent({
+ *   tag: 'div',
+ *   styling: {
+ *     base: 'items-center',
+ *     plugin: createTailwindPipeline,
+ *   },
+ * })
+ *
+ * // WRONG — calling it manually produces a ClassPlugin where a ClassPluginFactory is expected
+ * createContractComponent({
+ *   tag: 'div',
+ *   styling: {
+ *     plugin: createTailwindPipeline({ base: 'items-center' }, false),
+ *   },
+ * })
+ * ```
+ *
+ * With the plugin active, pass any display prop (`flex`, `inline-flex`, `grid`,
+ * `inline-grid`, `block`, `hidden`, etc.) as a boolean to control the display
+ * mode. The pipeline injects the display class and strips conflicting utilities:
+ * flex-family modes strip `grid-*`; grid-family modes strip `flex-*`; all other
+ * display values (and no prop) strip both `flex-*` and `grid-*`.
+ */
+declare function createTailwindPipeline<V extends VariantMap = VariantMap>(options: ClassPipelineOptions<V>, strict: StrictMode): ClassPlugin<LayoutProps>;
+
+declare class ClassBuilder {
+    #private;
+    build(tokens: ClassifiedToken[]): string;
+}
+
+declare class ClassClassifier {
+    #private;
+    classify(token: ClassToken): ClassifiedToken;
+}
+
+type DependencyRules = Record<Exclude<LayoutFamily, 'none'>, readonly RegExp[]>;
+declare const defaultDependencyRules: DependencyRules;
+
+/**
+ * The resolved display mode for a single render.
+ *
+ * Mode is owned by the display props; a display class literal in the resolved
+ * class string is a reserved-literal authoring mistake. Defaults to `'none'`
+ * when no prop is set.
+ *
+ * `family` is derived from mode: `'flex'` for flex/inline-flex, `'grid'` for
+ * grid/inline-grid, `'none'` for all other values (and when no prop is set).
+ * The evaluator uses family — not mode — for utility and gap filtering.
+ */
+declare class LayoutState {
+    #private;
+    constructor(mode: LayoutMode);
+    get mode(): LayoutMode;
+    get family(): LayoutFamily;
+}
+
+declare class DependencyEvaluator {
+    private readonly rules;
+    constructor(rules: DependencyRules);
+    evaluate(token: ClassifiedToken, state: LayoutState): boolean;
+}
+
+export { ClassBuilder, ClassClassifier, type ClassToken, type ClassifiedToken, type CompoundVariant, type ConditionalToken, DependencyEvaluator, type DependencyRules, type GapToken, type LayoutFamily, type LayoutKey, type LayoutMode, type LayoutProps, LayoutState, type LayoutToken, type UtilityToken, type VariantSelection, createTailwindPipeline, defaultDependencyRules };

package/dist/tailwind/index.js

@@ -0,0 +1,508 @@
+// ../../lib/primitive/src/utils/is-object.ts
+function isString(value) {
+  return typeof value === "string";
+}
+
+// ../../lib/primitive/src/utils/assert-never.ts
+function assertNever(value) {
+  throw new Error(`Unexpected value: ${String(value)}`);
+}
+
+// ../../lib/primitive/src/utils/cn.ts
+import { clsx } from "clsx";
+function cn(...inputs) {
+  return clsx(...inputs);
+}
+
+// ../../node_modules/.pnpm/class-variance-authority@0.7.1/node_modules/class-variance-authority/dist/index.mjs
+import { clsx as clsx2 } from "clsx";
+var falsyToString = (value) => typeof value === "boolean" ? `${value}` : value === 0 ? "0" : value;
+var cx = clsx2;
+var cva = (base, config) => (props) => {
+  var _config_compoundVariants;
+  if ((config === null || config === void 0 ? void 0 : config.variants) == null) return cx(base, props === null || props === void 0 ? void 0 : props.class, props === null || props === void 0 ? void 0 : props.className);
+  const { variants, defaultVariants } = config;
+  const getVariantClassNames = Object.keys(variants).map((variant) => {
+    const variantProp = props === null || props === void 0 ? void 0 : props[variant];
+    const defaultVariantProp = defaultVariants === null || defaultVariants === void 0 ? void 0 : defaultVariants[variant];
+    if (variantProp === null) return null;
+    const variantKey = falsyToString(variantProp) || falsyToString(defaultVariantProp);
+    return variants[variant][variantKey];
+  });
+  const propsWithoutUndefined = props && Object.entries(props).reduce((acc, param) => {
+    let [key, value] = param;
+    if (value === void 0) {
+      return acc;
+    }
+    acc[key] = value;
+    return acc;
+  }, {});
+  const getCompoundVariantClassNames = config === null || config === void 0 ? void 0 : (_config_compoundVariants = config.compoundVariants) === null || _config_compoundVariants === void 0 ? void 0 : _config_compoundVariants.reduce((acc, param) => {
+    let { class: cvClass, className: cvClassName, ...compoundVariantOptions } = param;
+    return Object.entries(compoundVariantOptions).every((param2) => {
+      let [key, value] = param2;
+      return Array.isArray(value) ? value.includes({
+        ...defaultVariants,
+        ...propsWithoutUndefined
+      }[key]) : {
+        ...defaultVariants,
+        ...propsWithoutUndefined
+      }[key] === value;
+    }) ? [
+      ...acc,
+      cvClass,
+      cvClassName
+    ] : acc;
+  }, []);
+  return cx(base, getVariantClassNames, getCompoundVariantClassNames, props === null || props === void 0 ? void 0 : props.class, props === null || props === void 0 ? void 0 : props.className);
+};
+
+// ../../lib/styling/src/cva.ts
+function cva2(base, config) {
+  const fn = cva(base, config);
+  return (props) => cn(fn(props));
+}
+
+// ../../lib/styling/src/static-class-resolver.ts
+var StaticClassResolver = class {
+  #baseClass;
+  #cache = /* @__PURE__ */ new Map();
+  #resolveTag;
+  constructor(baseClass, tagMap) {
+    this.#baseClass = Array.isArray(baseClass) ? baseClass.join(" ") : baseClass;
+    this.#resolveTag = tagMap ? (tag) => {
+      const extra = tagMap[tag];
+      if (!extra) return this.#baseClass;
+      const extraStr = Array.isArray(extra) ? extra.join(" ") : extra;
+      return `${this.#baseClass} ${extraStr}`;
+    } : () => this.#baseClass;
+  }
+  resolve(tag, skipTagMap = false) {
+    if (typeof tag !== "string" || skipTagMap) return this.#baseClass;
+    const cached = this.#cache.get(tag);
+    if (cached !== void 0) {
+      this.#cache.delete(tag);
+      this.#cache.set(tag, cached);
+      return cached;
+    }
+    const result = this.#resolveTag(tag);
+    this.#cache.set(tag, result);
+    if (this.#cache.size > 200) {
+      const lru = this.#cache.keys().next().value;
+      if (lru !== void 0) this.#cache.delete(lru);
+    }
+    return result;
+  }
+};
+
+// ../../lib/styling/src/variant-class-resolver.ts
+var VariantClassResolver = class _VariantClassResolver {
+  #cvaFn;
+  #presetMap;
+  #variantKeys;
+  #precomputedClasses;
+  #cache = /* @__PURE__ */ new Map();
+  constructor(cvaFn, presetMap, variantKeys, precomputedClasses) {
+    this.#cvaFn = cvaFn ?? null;
+    this.#presetMap = Object.freeze(presetMap ?? {});
+    this.#variantKeys = variantKeys ?? null;
+    this.#precomputedClasses = precomputedClasses ?? null;
+  }
+  resolve({ props, variantKey }) {
+    const normalizedKey = variantKey ?? "__none__";
+    const cacheKey = this.#createCacheKey(props, normalizedKey);
+    if (this.#precomputedClasses !== null) {
+      const precomputed = this.#precomputedClasses[cacheKey];
+      if (precomputed !== void 0) return precomputed;
+    }
+    const cached = this.#cache.get(cacheKey);
+    if (cached !== void 0) {
+      this.#cache.delete(cacheKey);
+      this.#cache.set(cacheKey, cached);
+      return cached;
+    }
+    const result = this.#compute(props, variantKey);
+    this.#cache.set(cacheKey, result);
+    if (this.#cache.size > 1e3) {
+      const lru = this.#cache.keys().next().value;
+      if (lru !== void 0) this.#cache.delete(lru);
+    }
+    return result;
+  }
+  #compute(props, variantKey) {
+    if (!this.#cvaFn) return "";
+    if (!variantKey) return this.#cvaFn(props);
+    const preset = this.#presetMap[variantKey];
+    if (!preset) return this.#cvaFn(props);
+    return this.#cvaFn({ ...preset, ...props });
+  }
+  // When variantKeys is provided, only those keys are included in the cache key — non-variant
+  // props (className, id, etc.) produce identical CVA output and must not fragment the cache.
+  // Iterating #variantKeys directly (fixed Set insertion order) avoids Object.keys + filter + sort.
+  // String is built incrementally to avoid a parts[] array allocation on every render.
+  #createCacheKey(props, variantKey) {
+    if (this.#variantKeys !== null) {
+      let key2 = variantKey;
+      for (const k of this.#variantKeys) {
+        if (k in props) key2 += `|${k}:${_VariantClassResolver.#serializeValue(props[k])}`;
+      }
+      return key2;
+    }
+    let key = variantKey;
+    for (const k of Object.keys(props).sort()) {
+      key += `|${k}:${_VariantClassResolver.#serializeValue(props[k])}`;
+    }
+    return key;
+  }
+  static #serializeValue(value) {
+    if (value === void 0) return "u";
+    if (value === null) return "n";
+    if (typeof value === "boolean") return `b:${value}`;
+    if (typeof value === "string") return `s:${value}`;
+    return `x:${String(value)}`;
+  }
+};
+
+// ../../lib/styling/src/create-class-pipeline.ts
+function createClassPipeline(resolved) {
+  const baseClass = resolved.baseClassName ?? "";
+  const cvaFn = resolved.variants ? cva2("", {
+    variants: resolved.variants,
+    defaultVariants: resolved.defaultVariants,
+    compoundVariants: resolved.compoundVariants
+  }) : null;
+  const variantKeys = resolved.variants ? new Set(Object.keys(resolved.variants)) : void 0;
+  const staticResolver = new StaticClassResolver(baseClass, resolved.tagMap);
+  const variantResolver = new VariantClassResolver(
+    cvaFn,
+    resolved.presetMap,
+    variantKeys,
+    resolved.precomputedClasses
+  );
+  return function resolveClasses(tag, props, className, variantKey) {
+    const staticClasses = staticResolver.resolve(tag, variantKey !== void 0);
+    const variantClasses = variantResolver.resolve({ props, variantKey });
+    if (!className)
+      return staticClasses && variantClasses ? `${staticClasses} ${variantClasses}` : staticClasses || variantClasses;
+    return cn(staticClasses, variantClasses, className);
+  };
+}
+
+// ../tailwind/src/class-builder.ts
+var ClassBuilder = class {
+  build(tokens) {
+    const layout = [];
+    const normal = [];
+    for (const token of tokens) {
+      switch (token.kind) {
+        case "layout": {
+          layout.push(token.raw);
+          break;
+        }
+        case "utility":
+        case "gap":
+        case "conditional": {
+          normal.push(token.raw);
+          break;
+        }
+        default:
+          throw assertNever(token);
+      }
+    }
+    return [...this.#dedupe(layout).toSorted(), ...this.#dedupe(normal)].join(" ");
+  }
+  #dedupe(arr) {
+    return [...new Set(arr)];
+  }
+};
+
+// ../tailwind/src/layout-keys.ts
+var layoutKeys = [
+  "flex",
+  "inline-flex",
+  "grid",
+  "inline-grid",
+  "block",
+  "inline-block",
+  "inline",
+  "hidden",
+  "contents",
+  "flow-root",
+  "list-item",
+  "table",
+  "table-caption",
+  "table-cell",
+  "table-column",
+  "table-column-group",
+  "table-footer-group",
+  "table-header-group",
+  "table-row-group",
+  "table-row"
+];
+
+// ../tailwind/src/constants.ts
+var LAYOUT_OWNED_KEYS = new Set(layoutKeys);
+var LAYOUT_FAMILY_MAP = {
+  flex: "flex",
+  "inline-flex": "flex",
+  grid: "grid",
+  "inline-grid": "grid",
+  block: "none",
+  "inline-block": "none",
+  inline: "none",
+  hidden: "none",
+  contents: "none",
+  "flow-root": "none",
+  "list-item": "none",
+  table: "none",
+  "table-caption": "none",
+  "table-cell": "none",
+  "table-column": "none",
+  "table-column-group": "none",
+  "table-footer-group": "none",
+  "table-header-group": "none",
+  "table-row-group": "none",
+  "table-row": "none"
+};
+var EMPTY_SET = /* @__PURE__ */ new Set();
+var COMPOUND_META_KEYS = /* @__PURE__ */ new Set(["class"]);
+
+// ../tailwind/src/class-classifier.ts
+var CONDITIONALS = {
+  "[&.flex": "flex",
+  "[&.grid": "grid"
+};
+var ClassClassifier = class _ClassClassifier {
+  static #getBaseUtility(token) {
+    let depth = 0;
+    for (let i = token.length - 1; i >= 0; i--) {
+      const char = token[i];
+      if (char === "]") depth++;
+      else if (char === "[") depth--;
+      else if (char === ":" && depth === 0 && token[i - 1] !== "\\") {
+        return token.slice(i + 1);
+      }
+    }
+    return token;
+  }
+  classify(token) {
+    const base = _ClassClassifier.#getBaseUtility(token);
+    if (LAYOUT_OWNED_KEYS.has(base)) {
+      return {
+        kind: "layout",
+        value: base,
+        raw: token
+      };
+    }
+    for (const [prefix, requires] of Object.entries(CONDITIONALS)) {
+      if (token.startsWith(prefix)) {
+        return {
+          kind: "conditional",
+          requires,
+          raw: token
+        };
+      }
+    }
+    return base === "gap" || base.startsWith("gap-") ? {
+      kind: "gap",
+      raw: token
+    } : {
+      kind: "utility",
+      base,
+      raw: token
+    };
+  }
+};
+
+// ../tailwind/src/dependency-rules.ts
+var defaultDependencyRules = {
+  flex: [/^flex-/, /^grow/, /^shrink/, /^basis-/],
+  grid: [/^grid-/, /^col-/, /^row-/, /^auto-cols-/, /^auto-rows-/]
+};
+
+// ../tailwind/src/dependency-evaluator.ts
+var DependencyEvaluator = class {
+  constructor(rules) {
+    this.rules = rules;
+  }
+  rules;
+  evaluate(token, state) {
+    switch (token.kind) {
+      case "layout": {
+        return token.value === state.mode;
+      }
+      case "conditional": {
+        return token.requires === state.family;
+      }
+      case "utility": {
+        for (const layout of Object.keys(this.rules)) {
+          if (this.rules[layout].some((r) => r.test(token.base))) {
+            return state.family === layout;
+          }
+        }
+        return true;
+      }
+      case "gap": {
+        return state.family !== "none";
+      }
+      default:
+        throw assertNever(token);
+    }
+  }
+};
+
+// ../tailwind/src/layout-state.ts
+var LayoutState = class {
+  #mode;
+  #family;
+  constructor(mode) {
+    this.#mode = mode;
+    this.#family = mode === "none" ? "none" : LAYOUT_FAMILY_MAP[mode];
+    Object.freeze(this);
+  }
+  get mode() {
+    return this.#mode;
+  }
+  get family() {
+    return this.#family;
+  }
+};
+
+// ../tailwind/src/create-tailwind-pipeline.ts
+var DEV = process.env.NODE_ENV !== "production";
+var pendingAsyncWarns = /* @__PURE__ */ new Set();
+var asyncWarnScheduled = false;
+function flushAsyncWarns() {
+  asyncWarnScheduled = false;
+  const messages = [...pendingAsyncWarns];
+  pendingAsyncWarns.clear();
+  for (const msg of messages) {
+    console.warn(msg);
+  }
+}
+function pipelineWarn(strict, message) {
+  if (!strict) return;
+  if (strict === "async-warn") {
+    if (pendingAsyncWarns.has(message)) return;
+    pendingAsyncWarns.add(message);
+    if (!asyncWarnScheduled) {
+      asyncWarnScheduled = true;
+      queueMicrotask(flushAsyncWarns);
+    }
+    return;
+  }
+  console.warn(message);
+}
+var classifier = new ClassClassifier();
+var evaluator = new DependencyEvaluator(defaultDependencyRules);
+var builder = new ClassBuilder();
+function normalizeVariantValue(value) {
+  if (isString(value)) return value;
+  return value.join(" ");
+}
+function resolveLayout(props) {
+  const active = [];
+  for (const key of layoutKeys) {
+    if (props[key]) active.push(key);
+  }
+  if (DEV && active.length > 1) {
+    console.warn(
+      `[createTailwindPipeline] Multiple display props set (${active.join(", ")}); "${active[0]}" takes precedence.`
+    );
+  }
+  return active[0] ?? "none";
+}
+function warnReservedLayoutLiterals(strict, tokens) {
+  if (!strict) return;
+  const reserved = [];
+  for (const token of tokens) {
+    if (token.kind === "layout") reserved.push(token.raw);
+  }
+  if (reserved.length === 0) return;
+  pipelineWarn(
+    strict,
+    `[createTailwindPipeline] Reserved display class(es) ${reserved.map((r) => `"${r}"`).join(", ")} found in resolved classes. The display mode is controlled by the display props (flex, inline-flex, grid, block, hidden, etc.), not by class strings.`
+  );
+}
+function getVariantConfig(options) {
+  return options.variants;
+}
+function getCompoundVariants(options) {
+  return options.compoundVariants ?? [];
+}
+function classifyTokens(className) {
+  return className.split(/\s+/).filter(Boolean).map(classifier.classify);
+}
+function compoundDimensions(compounds) {
+  if (compounds.length === 0) return EMPTY_SET;
+  const dims = /* @__PURE__ */ new Set();
+  for (const compound of compounds) {
+    for (const key in compound) {
+      if (!COMPOUND_META_KEYS.has(key)) dims.add(key);
+    }
+  }
+  return dims;
+}
+function getDefaultVariants(options) {
+  return options.defaultVariants;
+}
+function resolveActiveSelection(options, variants, props, variantKey) {
+  const preset = variantKey ? options.presetMap?.[variantKey] : void 0;
+  const defaults = getDefaultVariants(options);
+  const selection = {};
+  for (const dim in variants) {
+    const value = props[dim] ?? preset?.[dim] ?? defaults?.[dim];
+    if (value !== void 0 && value !== null) selection[dim] = String(value);
+  }
+  return selection;
+}
+function warnDeadVariants(strict, options, compoundDims, props, variantKey, state) {
+  if (!strict) return;
+  const variants = getVariantConfig(options);
+  if (!variants) return;
+  const selection = resolveActiveSelection(options, variants, props, variantKey);
+  for (const dim in selection) {
+    if (compoundDims.has(dim)) continue;
+    const value = selection[dim];
+    const raw = variants[dim]?.[value];
+    if (raw == null) continue;
+    const classStr = normalizeVariantValue(raw);
+    const tokens = classifyTokens(classStr);
+    if (tokens.length === 0) continue;
+    if (tokens.every((t) => !evaluator.evaluate(t, state))) {
+      pipelineWarn(
+        strict,
+        `[createTailwindPipeline] Variant "${dim}=${value}" contributes only classes stripped under layout mode "${state.mode}" ("${classStr}") \u2014 it produces nothing in this mode.`
+      );
+    }
+  }
+}
+function createTailwindPipeline(options, strict) {
+  const pipeline = createClassPipeline(options);
+  const compoundDims = compoundDimensions(getCompoundVariants(options));
+  return {
+    ownedKeys: LAYOUT_OWNED_KEYS,
+    pipeline(tag, props, className, variantKey) {
+      const mode = resolveLayout(props);
+      const raw = pipeline(tag, props, className, variantKey);
+      const tokens = classifyTokens(raw);
+      const state = new LayoutState(mode);
+      if (DEV) {
+        warnReservedLayoutLiterals(strict, tokens);
+        warnDeadVariants(strict, options, compoundDims, props, variantKey, state);
+      }
+      const filtered = tokens.filter((token) => evaluator.evaluate(token, state));
+      const built = builder.build(filtered);
+      if (mode === "none") return built;
+      return filtered.some((t) => t.kind === "layout" && t.value === mode) ? built : cn(mode, built);
+    }
+  };
+}
+export {
+  ClassBuilder,
+  ClassClassifier,
+  DependencyEvaluator,
+  LayoutState,
+  createTailwindPipeline,
+  defaultDependencyRules
+};