@jcsoftdev/ui 0.1.7 → 0.2.0

package/dist/utils/class-merge.d.ts

@@ -0,0 +1,17 @@
+import { type GroupEntry, type ThemeKey } from "./class-groups.js";
+/** 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[]>>;
+}
+/**
+ * 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 declare function createClassMerger(config?: ClassMergeConfig): (list: string) => string;

package/dist/utils/class-merge.js

@@ -0,0 +1,187 @@
+import {
+  CONFLICTS,
+  GROUPS,
+  ORDER_SENSITIVE,
+  RADII,
+  SHADOWS,
+  SPACINGS,
+  TEXT_SIZES
+} from "./class-groups.js";
+const node = () => ({ next: /* @__PURE__ */ new Map(), validators: [] });
+function child(parent, path) {
+  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;
+}
+const KIT_THEME = {
+  text: TEXT_SIZES,
+  spacing: SPACINGS,
+  radius: RADII,
+  shadow: SHADOWS,
+  color: []
+};
+const isThemeRef = (def) => typeof def.$theme === "string";
+function add(into, group, defs, tokens) {
+  for (const def of defs) {
+    if (typeof def === "string") {
+      (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, at, cur) {
+  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 void 0;
+  const rest = parts.slice(at).join("-");
+  for (const [group, test] of cur.validators) if (test(rest)) return group;
+  return void 0;
+}
+function groupIn(root, base) {
+  if (base.startsWith("[") && base.endsWith("]")) {
+    const inner = base.slice(1, -1);
+    const colon = inner.indexOf(":");
+    return colon > 0 ? `arbitrary..${inner.slice(0, colon)}` : void 0;
+  }
+  const parts = base.split("-");
+  return lookup(parts, parts[0] === "" && parts.length > 1 ? 1 : 0, root);
+}
+function parse(cls) {
+  const variants = [];
+  let depth = 0;
+  let start = 0;
+  let slash;
+  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;
+  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 !== void 0 && slash > start ? slash - start : void 0
+  };
+}
+function variantKey(variants) {
+  if (variants.length < 2) return variants[0] ?? "";
+  const out = [];
+  let run = [];
+  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;
+function createClassMerger(config = {}) {
+  const extra = config.theme ?? {};
+  const conflicts = config.conflicts;
+  const cache = /* @__PURE__ */ new Map();
+  let root;
+  const table = () => {
+    if (root) return root;
+    const tokens = (key) => [...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) => {
+    const own = CONFLICTS[group];
+    const more = conflicts?.[group];
+    return more ? own ? [...own, ...more] : more : own;
+  };
+  return (list) => {
+    const hit = cache.get(list);
+    if (hit !== void 0) return hit;
+    const trie = table();
+    const claimed = /* @__PURE__ */ new Set();
+    const kept = [];
+    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;
+      let hasSlash = slash !== void 0;
+      if (slash !== void 0) {
+        group = groupIn(trie, base.slice(0, slash));
+        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;
+  };
+}
+export {
+  createClassMerger
+};

package/dist/utils/class-names.d.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/dist/utils/class-tokens.generated.d.ts

@@ -0,0 +1,8 @@
+/** `text-*` font-size tokens; without them they would read as colors. */
+export declare const TEXT_SIZES: readonly string[];
+/** `rounded-*` radius tokens (role radii and legacy names). */
+export declare const RADII: readonly string[];
+/** `shadow-*` tokens (role shadows and legacy names). */
+export declare const SHADOWS: readonly string[];
+/** Spacing tokens used by `h-*`, `w-*`, `p-*`, `gap-*`, `inset-*` and friends. */
+export declare const SPACINGS: readonly string[];

package/dist/utils/class-tokens.generated.js

@@ -0,0 +1,98 @@
+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",
+  "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"
+];
+const RADII = [
+  "xs",
+  "chip",
+  "event",
+  "control",
+  "tile",
+  "banner",
+  "card",
+  "dialog",
+  "sheet",
+  "pill",
+  "button",
+  "input",
+  "badge",
+  "avatar",
+  "popover"
+];
+const SHADOWS = [
+  "flat",
+  "hero",
+  "cta",
+  "sel",
+  "pop",
+  "card",
+  "raised",
+  "overlay",
+  "control",
+  "selected",
+  "inset",
+  "inset-accent",
+  "pinned-start",
+  "pinned-end"
+];
+const SPACINGS = [
+  "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"
+];
+export {
+  RADII,
+  SHADOWS,
+  SPACINGS,
+  TEXT_SIZES
+};

package/dist/utils/class-validators.d.ts

@@ -0,0 +1,27 @@
+/** Value validators used by the class group table (`class-groups.ts`). */
+export type Validator = (value: string) => boolean;
+export declare const isAny: Validator;
+export declare const isFraction: Validator;
+export declare const isNumber: Validator;
+export declare const isInteger: Validator;
+export declare const isPercent: Validator;
+export declare const isTshirtSize: Validator;
+export declare const isArbitraryValue: Validator;
+export declare const isArbitraryVariable: Validator;
+export declare const isAnyNonArbitrary: Validator;
+export declare const isNamedContainerQuery: Validator;
+export declare const isArbitrarySize: Validator;
+export declare const isArbitraryLength: Validator;
+export declare const isArbitraryNumber: Validator;
+export declare const isArbitraryWeight: Validator;
+export declare const isArbitraryFamilyName: Validator;
+export declare const isArbitraryPosition: Validator;
+export declare const isArbitraryImage: Validator;
+export declare const isArbitraryShadow: Validator;
+export declare const isArbitraryVariableLength: Validator;
+export declare const isArbitraryVariableFamilyName: Validator;
+export declare const isArbitraryVariablePosition: Validator;
+export declare const isArbitraryVariableSize: Validator;
+export declare const isArbitraryVariableImage: Validator;
+export declare const isArbitraryVariableShadow: Validator;
+export declare const isArbitraryVariableWeight: Validator;

package/dist/utils/class-validators.js

@@ -0,0 +1,78 @@
+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)\(.+\)$/;
+const isAny = () => true;
+const isNever = () => false;
+const isFraction = (v) => fractionRegex.test(v);
+const isNumber = (v) => !!v && !Number.isNaN(Number(v));
+const isInteger = (v) => !!v && Number.isInteger(Number(v));
+const isPercent = (v) => v.endsWith("%") && isNumber(v.slice(0, -1));
+const isTshirtSize = (v) => tshirtUnitRegex.test(v);
+const isArbitraryValue = (v) => arbitraryValueRegex.test(v);
+const isArbitraryVariable = (v) => arbitraryVariableRegex.test(v);
+const isAnyNonArbitrary = (v) => !isArbitraryValue(v) && !isArbitraryVariable(v);
+const isLengthOnly = (v) => lengthUnitRegex.test(v) && !colorFunctionRegex.test(v);
+const isShadow = (v) => shadowRegex.test(v);
+const isImage = (v) => imageRegex.test(v);
+const isNamedContainerQuery = (v) => v.startsWith("@container") && (v[10] === "/" && v[11] !== void 0 || v[11] === "s" && v[16] !== void 0 && v.startsWith("-size/", 10) || v[11] === "n" && v[18] !== void 0 && v.startsWith("-normal/", 10));
+function arbitrary(labels, test) {
+  return (v) => {
+    const m = arbitraryValueRegex.exec(v);
+    if (!m) return false;
+    return m[1] ? labels.includes(m[1]) : test(m[2]);
+  };
+}
+function variable(labels, bare = false) {
+  return (v) => {
+    const m = arbitraryVariableRegex.exec(v);
+    if (!m) return false;
+    return m[1] ? labels.includes(m[1]) : bare;
+  };
+}
+const isArbitrarySize = arbitrary(["length", "size", "bg-size"], isNever);
+const isArbitraryLength = arbitrary(["length"], isLengthOnly);
+const isArbitraryNumber = arbitrary(["number"], isNumber);
+const isArbitraryWeight = arbitrary(["number", "weight"], isAny);
+const isArbitraryFamilyName = arbitrary(["family-name"], isNever);
+const isArbitraryPosition = arbitrary(["position", "percentage"], isNever);
+const isArbitraryImage = arbitrary(["image", "url"], isImage);
+const isArbitraryShadow = arbitrary(["shadow"], isShadow);
+const isArbitraryVariableLength = variable(["length"]);
+const isArbitraryVariableFamilyName = variable(["family-name"]);
+const isArbitraryVariablePosition = variable(["position", "percentage"]);
+const isArbitraryVariableSize = variable(["length", "size", "bg-size"]);
+const isArbitraryVariableImage = variable(["image", "url"]);
+const isArbitraryVariableShadow = variable(["shadow"], true);
+const isArbitraryVariableWeight = variable(["number", "weight"], true);
+export {
+  isAny,
+  isAnyNonArbitrary,
+  isArbitraryFamilyName,
+  isArbitraryImage,
+  isArbitraryLength,
+  isArbitraryNumber,
+  isArbitraryPosition,
+  isArbitraryShadow,
+  isArbitrarySize,
+  isArbitraryValue,
+  isArbitraryVariable,
+  isArbitraryVariableFamilyName,
+  isArbitraryVariableImage,
+  isArbitraryVariableLength,
+  isArbitraryVariablePosition,
+  isArbitraryVariableShadow,
+  isArbitraryVariableSize,
+  isArbitraryVariableWeight,
+  isArbitraryWeight,
+  isFraction,
+  isInteger,
+  isNamedContainerQuery,
+  isNumber,
+  isPercent,
+  isTshirtSize
+};

package/dist/utils/cn.d.ts

@@ -1,3 +1,34 @@
-import { type ClassValue } from "clsx";
+import { type ClassMergeConfig } from "./class-merge.js";
+export type { ClassMergeConfig, ClassMergeTheme } from "./class-merge.js";
+export type ClassValue = string | number | bigint | boolean | null | undefined | ClassDictionary | ClassArray;
+export type ClassDictionary = Record<string, unknown>;
+export type ClassArray = ClassValue[];
+/** 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;
+}
+/**
+ * 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 declare function createCn(config?: ClassMergeConfig): Cn;
+/**
+ * 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 declare function extendCn(base: Cn, more: ClassMergeConfig): Cn;
 /** Merge class names, resolving conflicting Tailwind utilities (last one wins). */
-export declare function cn(...inputs: ClassValue[]): string;
+export declare const cn: Cn;

package/dist/utils/cn.js

@@ -1,86 +1,47 @@
-import { clsx } from "clsx";
-import { extendTailwindMerge } from "tailwind-merge";
-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"
-];
-const RADII = [
-  "xs",
-  "chip",
-  "event",
-  "control",
-  "tile",
-  "banner",
-  "card",
-  "dialog",
-  "sheet",
-  "pill",
-  "button",
-  "input",
-  "badge",
-  "avatar",
-  "popover"
-];
-const SHADOWS = [
-  "flat",
-  "hero",
-  "cta",
-  "sel",
-  "pop",
-  "card",
-  "raised",
-  "overlay",
-  "control",
-  "selected",
-  "inset",
-  "inset-accent",
-  "pinned-start",
-  "pinned-end"
-];
-const SPACINGS = [
-  "control",
-  "control-sm",
-  "input",
-  "control-x",
-  "card",
-  "density-sm",
-  "density",
-  "density-lg",
-  "control-height",
-  "control-height-sm",
-  "input-height"
-];
-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"] }]
-    }
+import { createClassMerger } from "./class-merge.js";
+function clsx(...inputs) {
+  let out = "";
+  for (const input of inputs) {
+    const part = toClass(input);
+    if (part) out += (out ? " " : "") + part;
   }
-});
-function cn(...inputs) {
-  return twMerge(clsx(inputs));
+  return out;
 }
+function toClass(value) {
+  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;
+}
+function createCn(config = {}) {
+  const merge = createClassMerger(config);
+  const instance = (...inputs) => merge(clsx(...inputs));
+  return Object.assign(instance, { config });
+}
+function extendCn(base, more) {
+  const theme = { ...base.config.theme };
+  for (const [key, tokens] of Object.entries(more.theme ?? {})) {
+    theme[key] = [...theme[key] ?? [], ...tokens ?? []];
+  }
+  const conflicts = { ...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
+  });
+}
+const cn = /* @__PURE__ */ createCn();
 export {
-  cn
+  cn,
+  createCn,
+  extendCn
 };

package/dist/utils/compose.d.ts

@@ -0,0 +1,7 @@
+import { type Ref, type RefCallback } from "react";
+/** Runs the caller's handler first and skips ours once it called `preventDefault`. */
+export declare function composeHandlers<E extends {
+    defaultPrevented: boolean;
+}>(user: ((event: E) => void) | undefined, ours: ((event: E) => void) | undefined): (event: E) => void;
+/** Stable composed ref: changes identity only when one of the refs does. */
+export declare function useComposedRefs<T>(...refs: Array<Ref<T> | undefined>): RefCallback<T>;

package/dist/utils/compose.js

@@ -0,0 +1,15 @@
+import { useCallback } from "react";
+import { composeRefs } from "./slot.js";
+function composeHandlers(user, ours) {
+  return (event) => {
+    user?.(event);
+    if (!event.defaultPrevented) ours?.(event);
+  };
+}
+function useComposedRefs(...refs) {
+  return useCallback(composeRefs(...refs), refs);
+}
+export {
+  composeHandlers,
+  useComposedRefs
+};

package/dist/utils/form-bubble.d.ts

@@ -0,0 +1,30 @@
+import { type MouseEvent } from "react";
+/**
+ * Native form participation for custom toggles. The visible control is a
+ * button; a visually hidden input mirrors its state so FormData, `required`
+ * validation, `form` association and form-level change listeners keep working.
+ */
+export declare function useFormBubble(form?: string): {
+    control: HTMLElement | null;
+    setControl: import("react").Dispatch<import("react").SetStateAction<HTMLElement | null>>;
+    input: HTMLInputElement | null;
+    setInput: import("react").Dispatch<import("react").SetStateAction<HTMLInputElement | null>>;
+    stoppedRef: import("react").RefObject<boolean>;
+    interactions: number;
+    isFormControl: boolean;
+    onControlClick: (event: MouseEvent, interacted?: boolean) => void;
+};
+export type FormBubble = ReturnType<typeof useFormBubble>;
+/** Runs `onReset` when the associated form resets. */
+export declare function useFormReset(control: HTMLElement | null, form: string | undefined, onReset: () => void): void;
+export interface BubbleInputProps {
+    type: "checkbox" | "radio";
+    checked: boolean | "indeterminate";
+    bubble: FormBubble;
+    name?: string | undefined;
+    value?: string | undefined;
+    required?: boolean | undefined;
+    disabled?: boolean | undefined;
+    form?: string | undefined;
+}
+export declare function BubbleInput({ type, checked, bubble, name, value, required, disabled, form, }: BubbleInputProps): import("react").JSX.Element;