@jcsoftdev/ui 0.1.6 → 0.2.0

package/src/utils/class-merge.ts

@@ -0,0 +1,248 @@
+import {
+  CONFLICTS,
+  type Def,
+  GROUPS,
+  type GroupEntry,
+  ORDER_SENSITIVE,
+  RADII,
+  SHADOWS,
+  SPACINGS,
+  TEXT_SIZES,
+  type ThemeKey,
+  type ThemeRef,
+} from "./class-groups.js";
+import type { Validator } from "./class-validators.js";
+
+/**
+ * Tailwind class conflict resolver (Tailwind v4 conventions). Derived from the MIT-licensed
+ * twMerge by Dany Castillo (github.com/dcastil), copyright (c) 2021 Dany Castillo: classes are
+ * scanned last to first and a class is dropped when a later one already claimed its group,
+ * with variants and `!` part of the identity. Unrecognized classes are kept untouched.
+ */
+
+interface Node {
+  next: Map<string, Node>;
+  validators: [group: string, test: Validator][];
+  group?: string;
+}
+
+const node = (): Node => ({ next: new Map(), validators: [] });
+
+function child(parent: Node, path: string): Node {
+  let cur = parent;
+  for (const part of path.split("-")) {
+    let next = cur.next.get(part);
+    if (!next) {
+      next = node();
+      cur.next.set(part, next);
+    }
+    cur = next;
+  }
+  return cur;
+}
+
+/** Extra theme tokens, without the Tailwind prefix: `text: ["hero"]` teaches `text-hero`. */
+export type ClassMergeTheme = Partial<Record<ThemeKey, readonly string[]>>;
+
+/** Options for {@link createClassMerger}. */
+export interface ClassMergeConfig {
+  /** Extra tokens per theme namespace, added to the kit's own. */
+  theme?: ClassMergeTheme;
+  /** Extra class groups, `[groupId, prefix, values]`. Reusing a kit group id joins that group. */
+  classGroups?: readonly GroupEntry[];
+  /** Extra conflicts: `groupId -> groups it overrides`. Merged with the kit's map. */
+  conflicts?: Readonly<Record<string, readonly string[]>>;
+}
+
+const KIT_THEME: Record<ThemeKey, readonly string[]> = {
+  text: TEXT_SIZES,
+  spacing: SPACINGS,
+  radius: RADII,
+  shadow: SHADOWS,
+  color: [],
+};
+
+const isThemeRef = (def: Def): def is ThemeRef => typeof (def as ThemeRef).$theme === "string";
+
+function add(into: Node, group: string, defs: readonly Def[], tokens: (key: ThemeKey) => string[]) {
+  for (const def of defs) {
+    if (typeof def === "string") {
+      // The empty string means the prefix itself (`rounded`, `border`).
+      (def === "" ? into : child(into, def)).group = group;
+    } else if (typeof def === "function") {
+      into.validators.push([group, def]);
+    } else if (isThemeRef(def)) {
+      for (const token of tokens(def.$theme)) child(into, token).group = group;
+    } else {
+      for (const key of Object.keys(def)) add(child(into, key), group, def[key], tokens);
+    }
+  }
+}
+
+function lookup(parts: string[], at: number, cur: Node): string | undefined {
+  if (at === parts.length) return cur.group;
+  const next = cur.next.get(parts[at]);
+  if (next) {
+    const hit = lookup(parts, at + 1, next);
+    if (hit) return hit;
+  }
+  if (cur.validators.length === 0) return undefined;
+  const rest = parts.slice(at).join("-");
+  for (const [group, test] of cur.validators) if (test(rest)) return group;
+  return undefined;
+}
+
+function groupIn(root: Node, base: string): string | undefined {
+  if (base.startsWith("[") && base.endsWith("]")) {
+    // Arbitrary property `[mask-type:luminance]` conflicts with itself only.
+    const inner = base.slice(1, -1);
+    const colon = inner.indexOf(":");
+    return colon > 0 ? `arbitrary..${inner.slice(0, colon)}` : undefined;
+  }
+  const parts = base.split("-");
+  // `-inset-1`: the empty first part marks a negative value.
+  return lookup(parts, parts[0] === "" && parts.length > 1 ? 1 : 0, root);
+}
+
+interface Parsed {
+  variants: string[];
+  important: boolean;
+  base: string;
+  /** Index of a `/` modifier inside `base` (`text-lg/7`, `bg-red/50`). */
+  slash?: number;
+}
+
+/** Split `a:b:[&_p]:!text-lg/7` at top level only, ignoring `:` and `/` inside `[]` and `()`. */
+function parse(cls: string): Parsed {
+  const variants: string[] = [];
+  let depth = 0;
+  let start = 0;
+  let slash: number | undefined;
+  for (let i = 0; i < cls.length; i++) {
+    const c = cls[i];
+    if (depth === 0) {
+      if (c === ":") {
+        variants.push(cls.slice(start, i));
+        start = i + 1;
+        continue;
+      }
+      if (c === "/") {
+        slash = i;
+        continue;
+      }
+    }
+    if (c === "[" || c === "(") depth++;
+    else if (c === "]" || c === ")") depth--;
+  }
+  let base = variants.length === 0 ? cls : cls.slice(start);
+  let important = false;
+  // Trailing `!` is v4; a leading `!` is the v3 spelling that v4 still accepts.
+  if (base.endsWith("!")) {
+    base = base.slice(0, -1);
+    important = true;
+  } else if (base.startsWith("!")) {
+    base = base.slice(1);
+    important = true;
+  }
+  return {
+    variants,
+    important,
+    base,
+    slash: slash !== undefined && slash > start ? slash - start : undefined,
+  };
+}
+
+/** Variants are order-independent (`hover:focus:` equals `focus:hover:`) except pseudo-element ones. */
+function variantKey(variants: string[]): string {
+  if (variants.length < 2) return variants[0] ?? "";
+  const out: string[] = [];
+  let run: string[] = [];
+  for (const v of variants) {
+    if (v[0] === "[" || ORDER_SENSITIVE.has(v)) {
+      out.push(...run.sort(), v);
+      run = [];
+    } else {
+      run.push(v);
+    }
+  }
+  out.push(...run.sort());
+  return out.join(":");
+}
+
+const WHITESPACE = /\s+/;
+const CACHE_LIMIT = 500;
+
+/**
+ * Build a class resolver. The group trie is built on first use and results are cached per
+ * instance, so create one at module scope and reuse it; instances never share state.
+ */
+export function createClassMerger(config: ClassMergeConfig = {}): (list: string) => string {
+  const extra = config.theme ?? {};
+  const conflicts = config.conflicts;
+  const cache = new Map<string, string>();
+  let root: Node | undefined;
+
+  const table = (): Node => {
+    if (root) return root;
+    const tokens = (key: ThemeKey): string[] => [...KIT_THEME[key], ...(extra[key] ?? [])];
+    root = node();
+    for (const [group, prefix, values] of GROUPS) {
+      add(prefix ? child(root, prefix) : root, group, values, tokens);
+    }
+    for (const [group, prefix, values] of config.classGroups ?? []) {
+      add(prefix ? child(root, prefix) : root, group, values, tokens);
+    }
+    return root;
+  };
+
+  const conflictsOf = (group: string): readonly string[] | undefined => {
+    const own = CONFLICTS[group];
+    const more = conflicts?.[group];
+    return more ? (own ? [...own, ...more] : more) : own;
+  };
+
+  return (list) => {
+    const hit = cache.get(list);
+    if (hit !== undefined) return hit;
+    const trie = table();
+    const claimed = new Set<string>();
+    const kept: string[] = [];
+    const classes = list.trim().split(WHITESPACE);
+    for (let i = classes.length - 1; i >= 0; i--) {
+      const original = classes[i];
+      const { variants, important, base, slash } = parse(original);
+      let group: string | undefined;
+      let hasSlash = slash !== undefined;
+      if (slash !== undefined) {
+        group = groupIn(trie, base.slice(0, slash));
+        // `@container/name` is the only group where the `/` belongs to the class itself.
+        if (group === "container-type") {
+          const whole = groupIn(trie, base);
+          if (whole && whole !== group) {
+            group = whole;
+            hasSlash = false;
+          }
+        }
+      } else {
+        group = groupIn(trie, base);
+      }
+      if (!group && hasSlash) {
+        group = groupIn(trie, base);
+        hasSlash = false;
+      }
+      if (!group) {
+        kept.push(original);
+        continue;
+      }
+      const prefix = variantKey(variants) + (important ? "!" : "");
+      if (claimed.has(prefix + group)) continue;
+      claimed.add(prefix + group);
+      for (const other of conflictsOf(group) ?? []) claimed.add(prefix + other);
+      kept.push(original);
+    }
+    const result = kept.reverse().join(" ");
+    if (cache.size >= CACHE_LIMIT) cache.clear();
+    cache.set(list, result);
+    return result;
+  };
+}

package/src/utils/class-names.ts

@@ -0,0 +1,9 @@
+/**
+ * Per-part class overrides for a multi-part component.
+ *
+ * Every styled component that renders more than one styled element accepts
+ * `classNames={{ root, <part>, ... }}` next to the usual `className` (which
+ * always targets the root). Values are merged with `cn`, so consumer classes win
+ * over the kit's own on conflicting utilities.
+ */
+export type ClassNames<Part extends string> = Partial<Record<Part, string>>;

package/src/utils/class-tokens.generated.ts

@@ -0,0 +1,101 @@
+// Generated by scripts/build-class-tokens.mjs from styles/theme.css. Do not edit.
+
+/** `text-*` font-size tokens; without them they would read as colors. */
+export const TEXT_SIZES: readonly string[] = [
+  "kpi-number",
+  "page-title",
+  "dialog-title",
+  "card-title",
+  "lede",
+  "body",
+  "row-title",
+  "control",
+  "meta",
+  "chip-text",
+  "overline",
+  "clock",
+  "data",
+  "count",
+  "m-title",
+  "m-card-title",
+  "m-row-title",
+  "m-body",
+  "m-button",
+  "m-meta",
+  "fs-95",
+  "fs-100",
+  "fs-105",
+  "fs-110",
+  "fs-115",
+  "fs-120",
+  "fs-125",
+  "fs-130",
+  "fs-140",
+  "fs-150",
+  "fs-160",
+  "fs-220",
+  "fs-300",
+  "fs-440",
+];
+
+/** `rounded-*` radius tokens (role radii and legacy names). */
+export const RADII: readonly string[] = [
+  "xs",
+  "chip",
+  "event",
+  "control",
+  "tile",
+  "banner",
+  "card",
+  "dialog",
+  "sheet",
+  "pill",
+  "button",
+  "input",
+  "badge",
+  "avatar",
+  "popover",
+];
+
+/** `shadow-*` tokens (role shadows and legacy names). */
+export const SHADOWS: readonly string[] = [
+  "flat",
+  "hero",
+  "cta",
+  "sel",
+  "pop",
+  "card",
+  "raised",
+  "overlay",
+  "control",
+  "selected",
+  "inset",
+  "inset-accent",
+  "pinned-start",
+  "pinned-end",
+];
+
+/** Spacing tokens used by `h-*`, `w-*`, `p-*`, `gap-*`, `inset-*` and friends. */
+export const SPACINGS: readonly string[] = [
+  "side-width",
+  "top-height",
+  "control-height",
+  "control-height-sm",
+  "control-height-lg",
+  "input-height",
+  "agenda-hour",
+  "agenda-col",
+  "m-button",
+  "m-tray",
+  "m-chip",
+  "m-hour",
+  "control",
+  "control-sm",
+  "control-lg",
+  "input",
+  "control-x",
+  "card",
+  "density-sm",
+  "density",
+  "density-lg",
+];

package/src/utils/class-validators.ts

@@ -0,0 +1,69 @@
+/** Value validators used by the class group table (`class-groups.ts`). */
+export type Validator = (value: string) => boolean;
+
+const arbitraryValueRegex = /^\[(?:(\w[\w-]*):)?(.+)\]$/i;
+const arbitraryVariableRegex = /^\((?:(\w[\w-]*):)?(.+)\)$/i;
+const fractionRegex = /^\d+(?:\.\d+)?\/\d+(?:\.\d+)?$/;
+const tshirtUnitRegex = /^(\d+(\.\d+)?)?(xs|sm|md|lg|xl)$/;
+const lengthUnitRegex =
+  /\d+(%|px|r?em|[sdl]?v([hwib]|min|max)|pt|pc|in|cm|mm|cap|ch|ex|r?lh|cq(w|h|i|b|min|max))|\b(calc|min|max|clamp)\(.+\)|^0$/;
+const colorFunctionRegex = /^(rgba?|hsla?|hwb|(ok)?(lab|lch)|color-mix|color|light-dark)\(.+\)$/;
+const shadowRegex = /^(inset_)?-?((\d+)?\.?(\d+)[a-z]+|0)_-?((\d+)?\.?(\d+)[a-z]+|0)/;
+const imageRegex =
+  /^(url|image|image-set|cross-fade|element|(repeating-)?(linear|radial|conic)-gradient)\(.+\)$/;
+
+export const isAny: Validator = () => true;
+const isNever: Validator = () => false;
+export const isFraction: Validator = (v) => fractionRegex.test(v);
+export const isNumber: Validator = (v) => !!v && !Number.isNaN(Number(v));
+export const isInteger: Validator = (v) => !!v && Number.isInteger(Number(v));
+export const isPercent: Validator = (v) => v.endsWith("%") && isNumber(v.slice(0, -1));
+export const isTshirtSize: Validator = (v) => tshirtUnitRegex.test(v);
+export const isArbitraryValue: Validator = (v) => arbitraryValueRegex.test(v);
+export const isArbitraryVariable: Validator = (v) => arbitraryVariableRegex.test(v);
+export const isAnyNonArbitrary: Validator = (v) => !isArbitraryValue(v) && !isArbitraryVariable(v);
+
+// `color-function(... 0% ...)` contains percentages that would otherwise read as lengths.
+const isLengthOnly: Validator = (v) => lengthUnitRegex.test(v) && !colorFunctionRegex.test(v);
+const isShadow: Validator = (v) => shadowRegex.test(v);
+const isImage: Validator = (v) => imageRegex.test(v);
+
+export const isNamedContainerQuery: Validator = (v) =>
+  v.startsWith("@container") &&
+  ((v[10] === "/" && v[11] !== undefined) ||
+    (v[11] === "s" && v[16] !== undefined && v.startsWith("-size/", 10)) ||
+    (v[11] === "n" && v[18] !== undefined && v.startsWith("-normal/", 10)));
+
+/** `[label:value]` is checked by label; an unlabelled `[value]` by its content. */
+function arbitrary(labels: string[], test: Validator): Validator {
+  return (v) => {
+    const m = arbitraryValueRegex.exec(v);
+    if (!m) return false;
+    return m[1] ? labels.includes(m[1]) : test(m[2]);
+  };
+}
+
+/** `(--var)` is checked by label; an unlabelled variable matches only when `bare` is set. */
+function variable(labels: string[], bare = false): Validator {
+  return (v) => {
+    const m = arbitraryVariableRegex.exec(v);
+    if (!m) return false;
+    return m[1] ? labels.includes(m[1]) : bare;
+  };
+}
+
+export const isArbitrarySize = arbitrary(["length", "size", "bg-size"], isNever);
+export const isArbitraryLength = arbitrary(["length"], isLengthOnly);
+export const isArbitraryNumber = arbitrary(["number"], isNumber);
+export const isArbitraryWeight = arbitrary(["number", "weight"], isAny);
+export const isArbitraryFamilyName = arbitrary(["family-name"], isNever);
+export const isArbitraryPosition = arbitrary(["position", "percentage"], isNever);
+export const isArbitraryImage = arbitrary(["image", "url"], isImage);
+export const isArbitraryShadow = arbitrary(["shadow"], isShadow);
+export const isArbitraryVariableLength = variable(["length"]);
+export const isArbitraryVariableFamilyName = variable(["family-name"]);
+export const isArbitraryVariablePosition = variable(["position", "percentage"]);
+export const isArbitraryVariableSize = variable(["length", "size", "bg-size"]);
+export const isArbitraryVariableImage = variable(["image", "url"]);
+export const isArbitraryVariableShadow = variable(["shadow"], true);
+export const isArbitraryVariableWeight = variable(["number", "weight"], true);

package/src/utils/cn.ts

@@ -1,94 +1,89 @@
-import { type ClassValue, clsx } from "clsx";
-import { extendTailwindMerge } from "tailwind-merge";
+import { type ClassMergeConfig, createClassMerger } from "./class-merge.js";
 
-/** Custom `text-*` size tokens from theme.css; without them twMerge reads them as colors. */
-const TEXT_SIZES = [
-  "kpi-number",
-  "page-title",
-  "dialog-title",
-  "card-title",
-  "lede",
-  "body",
-  "row-title",
-  "control",
-  "meta",
-  "chip-text",
-  "overline",
-  "clock",
-  "data",
-  "count",
-  "m-title",
-  "m-card-title",
-  "m-row-title",
-  "m-body",
-  "m-button",
-  "m-meta",
-];
+export type { ClassMergeConfig, ClassMergeTheme } from "./class-merge.js";
 
-/** Role radii and legacy radius names from theme.css (`rounded-*`). */
-const RADII = [
-  "xs",
-  "chip",
-  "event",
-  "control",
-  "tile",
-  "banner",
-  "card",
-  "dialog",
-  "sheet",
-  "pill",
-  "button",
-  "input",
-  "badge",
-  "avatar",
-  "popover",
-];
+export type ClassValue =
+  | string
+  | number
+  | bigint
+  | boolean
+  | null
+  | undefined
+  | ClassDictionary
+  | ClassArray;
+export type ClassDictionary = Record<string, unknown>;
+export type ClassArray = ClassValue[];
 
-/** Role shadows and legacy shadow names from theme.css (`shadow-*`). */
-const SHADOWS = [
-  "flat",
-  "hero",
-  "cta",
-  "sel",
-  "pop",
-  "card",
-  "raised",
-  "overlay",
-  "control",
-  "selected",
-  "inset",
-  "inset-accent",
-  "pinned-start",
-  "pinned-end",
-];
+/** Join class values (strings, numbers, arrays, objects) skipping falsy ones; clsx-compatible. */
+function clsx(...inputs: ClassValue[]): string {
+  let out = "";
+  for (const input of inputs) {
+    const part = toClass(input);
+    if (part) out += (out ? " " : "") + part;
+  }
+  return out;
+}
 
-/** Density-aware sizes from theme.css, used by `h-*`, `p-*`, `px-*` and `gap-*`. */
-const SPACINGS = [
-  "control",
-  "control-sm",
-  "input",
-  "control-x",
-  "card",
-  "density-sm",
-  "density",
-  "density-lg",
-  "control-height",
-  "control-height-sm",
-  "input-height",
-];
+function toClass(value: ClassValue): string {
+  if (!value) return "";
+  if (typeof value === "string") return value;
+  if (typeof value === "number" || typeof value === "bigint") return String(value);
+  if (typeof value !== "object") return "";
+  if (Array.isArray(value)) return clsx(...value);
+  let out = "";
+  for (const key of Object.keys(value)) {
+    if (value[key]) out += (out ? " " : "") + key;
+  }
+  return out;
+}
 
-const twMerge = extendTailwindMerge({
-  extend: {
-    theme: { radius: RADII, shadow: SHADOWS, spacing: SPACINGS },
-    classGroups: {
-      "font-size": [{ text: TEXT_SIZES }],
-      // Preset edges set width, style and color together; a later `border-2` or `border-0` wins.
-      "border-w": [{ border: ["card", "control", "divider"] }],
-    },
-  },
-});
+/** A class-name joiner that resolves conflicting Tailwind utilities (last one wins). */
+export interface Cn {
+  (...inputs: ClassValue[]): string;
+  /** The configuration this instance was created with; read by {@link extendCn}. */
+  readonly config: ClassMergeConfig;
+}
 
-/** Merge class names, resolving conflicting Tailwind utilities (last one wins). */
-export function cn(...inputs: ClassValue[]): string {
-  return twMerge(clsx(inputs));
+/**
+ * Create a `cn` that also knows your own theme tokens, so `text-hero` and `text-lg` conflict
+ * instead of both being kept. Create it once at module scope: the lookup table is built on first
+ * use and results are cached per instance. The default {@link cn} is never affected.
+ *
+ * @example
+ * const cn = createCn({
+ *   theme: { text: ["hero"], spacing: ["gutter"], radius: ["blob"], shadow: ["glow"] },
+ * });
+ * cn("text-lg text-hero"); // "text-hero"
+ * cn("p-gutter p-2"); // "p-2"
+ *
+ * `theme.color` is accepted for symmetry, but any unknown value already reads as a color.
+ * Use `classGroups` (`[groupId, prefix, values]`) and `conflicts` for utilities beyond the theme.
+ */
+export function createCn(config: ClassMergeConfig = {}): Cn {
+  const merge = createClassMerger(config);
+  const instance = (...inputs: ClassValue[]): string => merge(clsx(...inputs));
+  return Object.assign(instance, { config });
 }
+
+/**
+ * Build a new `cn` from an existing one plus more configuration; theme tokens, class groups and
+ * conflicts are concatenated, the base instance is left untouched.
+ */
+export function extendCn(base: Cn, more: ClassMergeConfig): Cn {
+  const theme: Record<string, readonly string[]> = { ...base.config.theme };
+  for (const [key, tokens] of Object.entries(more.theme ?? {})) {
+    theme[key] = [...(theme[key] ?? []), ...(tokens ?? [])];
+  }
+  const conflicts: Record<string, readonly string[]> = { ...base.config.conflicts };
+  for (const [group, others] of Object.entries(more.conflicts ?? {})) {
+    conflicts[group] = [...(conflicts[group] ?? []), ...others];
+  }
+  return createCn({
+    theme,
+    classGroups: [...(base.config.classGroups ?? []), ...(more.classGroups ?? [])],
+    conflicts,
+  });
+}
+
+/** Merge class names, resolving conflicting Tailwind utilities (last one wins). */
+export const cn: Cn = /* @__PURE__ */ createCn();

package/src/utils/compose.ts

@@ -0,0 +1,19 @@
+import { type Ref, type RefCallback, useCallback } from "react";
+import { composeRefs } from "./slot.js";
+
+/** Runs the caller's handler first and skips ours once it called `preventDefault`. */
+export function composeHandlers<E extends { defaultPrevented: boolean }>(
+  user: ((event: E) => void) | undefined,
+  ours: ((event: E) => void) | undefined,
+): (event: E) => void {
+  return (event) => {
+    user?.(event);
+    if (!event.defaultPrevented) ours?.(event);
+  };
+}
+
+/** Stable composed ref: changes identity only when one of the refs does. */
+export function useComposedRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T> {
+  // biome-ignore lint/correctness/useExhaustiveDependencies: the refs are the dependencies
+  return useCallback(composeRefs(...refs), refs);
+}