@tea-ui/utils 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 landnevermore
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,24 @@
+# @tea-ui/utils
+
+Shared types, class-name composition and small helpers.
+
+Part of [TEA UI](https://landnevermore.github.io/TEAui/) — a design system built once and reused across
+products. The whole system is documented at https://landnevermore.github.io/TEAui/docs/.
+
+## Install
+
+```bash
+npm install @tea-ui/utils
+```
+
+React 18.2 or 19 is expected as a peer dependency.
+
+## Use
+
+```ts
+import { tokens } from "@tea-ui/utils";
+```
+
+## Licence
+
+MIT. See [LICENSE](./LICENSE).

package/dist/index.d.ts

@@ -0,0 +1,53 @@
+import { ClassValue } from 'clsx';
+export { ClassValue, clsx } from 'clsx';
+export { VariantProps, cva } from 'class-variance-authority';
+
+/**
+ * TEA UI — utilities.
+ *
+ * The smallest package in the system, and the one with the fewest opinions.
+ * Its job is to make the house style the path of least resistance: one class
+ * merge, one variant author, one prefix, one exhaustive check.
+ *
+ * It has no React dependency and no design opinions, so anything that needs
+ * either belongs elsewhere.
+ */
+
+declare function cn(...inputs: ClassValue[]): string;
+/** Alias for {@link cn}, for call sites where "compose" reads better. */
+declare const cx: typeof cn;
+
+/** Every TEA UI component prefixes its `data-slot` with this. */
+declare const TEA_PREFIX = "tea";
+/**
+ * Build a namespaced `data-slot` value, e.g. `slot("button", "icon")` ->
+ * `"tea-button-icon"`. One helper means one naming convention, and a
+ * convention that a test can assert.
+ */
+declare function slot(...parts: string[]): string;
+/**
+ * Exhaustiveness check. The audit found five independent hand-written
+ * status-to-label tables per project, each disagreeing with the others; the
+ * type system catches the sixth version of that the moment a new variant
+ * appears without a label.
+ *
+ * ```ts
+ * function toneOf(t: Tone): string {
+ *   switch (t) {
+ *     case "positive": return "ok";
+ *     // ...
+ *     default: return assertNever(t);
+ *   }
+ * }
+ * ```
+ */
+declare function assertNever(value: never, message?: string): never;
+/**
+ * Join class names and drop falsy entries, without merging. Useful when
+ * composing a class string that must NOT be deduplicated against a base
+ * (rare — prefer {@link cn} — but needed when a caller deliberately wants two
+ * `bg-*` classes to both reach the cascade).
+ */
+declare function joinClasses(...inputs: ClassValue[]): string;
+
+export { TEA_PREFIX, assertNever, cn, cx, joinClasses, slot };

package/dist/index.js

@@ -0,0 +1,61 @@
+import { clsx } from "clsx";
+import { extendTailwindMerge } from "tailwind-merge";
+const twMerge = extendTailwindMerge({
+  extend: {
+    classGroups: {
+      "font-size": [
+        { text: ["label", "micro", "ui", "body", "lead", "title", "section", "display", "hero", "mono"] }
+      ],
+      rounded: [{ rounded: ["none", "pill"] }],
+      shadow: [{ shadow: ["none", "raised", "overlay", "modal", "inset"] }]
+    }
+  }
+});
+const Z_UTILITIES = /* @__PURE__ */ new Set([
+  "z-base",
+  "z-raised",
+  "z-sticky",
+  "z-header",
+  "z-dropdown",
+  "z-overlay",
+  "z-modal",
+  "z-popover",
+  "z-toast",
+  "z-tooltip",
+  "z-max"
+]);
+function keepLastZUtilities(merged) {
+  const classes = merged.split(" ").filter(Boolean);
+  const lastIndex = /* @__PURE__ */ new Map();
+  classes.forEach((className, index) => {
+    if (Z_UTILITIES.has(className)) lastIndex.set(className, index);
+  });
+  if (lastIndex.size < 2) return merged;
+  return classes.filter((className, index) => !Z_UTILITIES.has(className) || lastIndex.get(className) === index).join(" ");
+}
+function cn(...inputs) {
+  return keepLastZUtilities(twMerge(clsx(inputs)));
+}
+const cx = cn;
+import { cva } from "class-variance-authority";
+const TEA_PREFIX = "tea";
+function slot(...parts) {
+  return [TEA_PREFIX, ...parts].join("-");
+}
+function assertNever(value, message) {
+  throw new Error(message ?? `Unhandled variant: ${String(value)}`);
+}
+function joinClasses(...inputs) {
+  return clsx(inputs);
+}
+export {
+  TEA_PREFIX,
+  assertNever,
+  clsx,
+  cn,
+  cva,
+  cx,
+  joinClasses,
+  slot
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * TEA UI — utilities.\n *\n * The smallest package in the system, and the one with the fewest opinions.\n * Its job is to make the house style the path of least resistance: one class\n * merge, one variant author, one prefix, one exhaustive check.\n *\n * It has no React dependency and no design opinions, so anything that needs\n * either belongs elsewhere.\n */\n\nimport { clsx, type ClassValue } from \"clsx\";\nimport { extendTailwindMerge } from \"tailwind-merge\";\n\n/**\n * The single class merge used by every TEA UI package.\n *\n * Both source projects had a `cn`, but they were not the same function: one\n * was a compiled `clsx + tailwind-merge` replacement, the other an explicit\n * composition, and HomeServerManager even had a second import path that\n * bypassed its own barrel. A component copied between projects therefore\n * changed behaviour silently. There is exactly one now, and there is exactly\n * one import path.\n *\n * TEA UI's colour, radius, shadow and type utilities come from a reset\n * Tailwind namespace, so they are not in tailwind-merge's default theme\n * vocabulary. They are registered explicitly below: without this, `bg-surface`\n * and `bg-canvas` would be treated as unrelated classes and both would reach\n * the DOM, leaving the winner to stylesheet order instead of the caller.\n */\nconst twMerge = extendTailwindMerge({\n  extend: {\n    classGroups: {\n      \"font-size\": [\n        { text: [\"label\", \"micro\", \"ui\", \"body\", \"lead\", \"title\", \"section\", \"display\", \"hero\", \"mono\"] },\n      ],\n      rounded: [{ rounded: [\"none\", \"pill\"] }],\n      shadow: [{ shadow: [\"none\", \"raised\", \"overlay\", \"modal\", \"inset\"] }],\n    },\n  },\n});\n\n/**\n * The z-index scale TEA UI ships as custom utilities. Tailwind has no `z-*`\n * theme namespace, so tailwind-merge has no group to extend for it, and\n * `z-50 z-modal` would otherwise both reach the DOM with the winner decided by\n * stylesheet order. A five-line pass is cheaper than a fork of tailwind-merge.\n */\nconst Z_UTILITIES = new Set([\n  \"z-base\",\n  \"z-raised\",\n  \"z-sticky\",\n  \"z-header\",\n  \"z-dropdown\",\n  \"z-overlay\",\n  \"z-modal\",\n  \"z-popover\",\n  \"z-toast\",\n  \"z-tooltip\",\n  \"z-max\",\n]);\n\n/** Keep only the last occurrence of each TEA z utility. */\nfunction keepLastZUtilities(merged: string): string {\n  const classes = merged.split(\" \").filter(Boolean);\n  const lastIndex = new Map<string, number>();\n  classes.forEach((className, index) => {\n    if (Z_UTILITIES.has(className)) lastIndex.set(className, index);\n  });\n  if (lastIndex.size < 2) return merged;\n  return classes\n    .filter((className, index) => !Z_UTILITIES.has(className) || lastIndex.get(className) === index)\n    .join(\" \");\n}\n\nexport function cn(...inputs: ClassValue[]): string {\n  return keepLastZUtilities(twMerge(clsx(inputs)));\n}\n\n/** Alias for {@link cn}, for call sites where \"compose\" reads better. */\nexport const cx = cn;\n\nexport type { ClassValue };\n\nexport { clsx };\n\n/**\n * `class-variance-authority`, re-exported from one place so variant authoring\n * is uniform across packages. cva is the only supported way to express a\n * variant surface: it keeps a component's variant space declarative and\n * greppable instead of spread across a `switch` in a render function.\n */\nexport { cva, type VariantProps } from \"class-variance-authority\";\n\n/** Every TEA UI component prefixes its `data-slot` with this. */\nexport const TEA_PREFIX = \"tea\";\n\n/**\n * Build a namespaced `data-slot` value, e.g. `slot(\"button\", \"icon\")` ->\n * `\"tea-button-icon\"`. One helper means one naming convention, and a\n * convention that a test can assert.\n */\nexport function slot(...parts: string[]): string {\n  return [TEA_PREFIX, ...parts].join(\"-\");\n}\n\n/**\n * Exhaustiveness check. The audit found five independent hand-written\n * status-to-label tables per project, each disagreeing with the others; the\n * type system catches the sixth version of that the moment a new variant\n * appears without a label.\n *\n * ```ts\n * function toneOf(t: Tone): string {\n *   switch (t) {\n *     case \"positive\": return \"ok\";\n *     // ...\n *     default: return assertNever(t);\n *   }\n * }\n * ```\n */\nexport function assertNever(value: never, message?: string): never {\n  throw new Error(message ?? `Unhandled variant: ${String(value)}`);\n}\n\n/**\n * Join class names and drop falsy entries, without merging. Useful when\n * composing a class string that must NOT be deduplicated against a base\n * (rare — prefer {@link cn} — but needed when a caller deliberately wants two\n * `bg-*` classes to both reach the cascade).\n */\nexport function joinClasses(...inputs: ClassValue[]): string {\n  return clsx(inputs);\n}\n"],"mappings":"AAWA,SAAS,YAA6B;AACtC,SAAS,2BAA2B;AAkBpC,MAAM,UAAU,oBAAoB;AAAA,EAClC,QAAQ;AAAA,IACN,aAAa;AAAA,MACX,aAAa;AAAA,QACX,EAAE,MAAM,CAAC,SAAS,SAAS,MAAM,QAAQ,QAAQ,SAAS,WAAW,WAAW,QAAQ,MAAM,EAAE;AAAA,MAClG;AAAA,MACA,SAAS,CAAC,EAAE,SAAS,CAAC,QAAQ,MAAM,EAAE,CAAC;AAAA,MACvC,QAAQ,CAAC,EAAE,QAAQ,CAAC,QAAQ,UAAU,WAAW,SAAS,OAAO,EAAE,CAAC;AAAA,IACtE;AAAA,EACF;AACF,CAAC;AAQD,MAAM,cAAc,oBAAI,IAAI;AAAA,EAC1B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF,CAAC;AAGD,SAAS,mBAAmB,QAAwB;AAClD,QAAM,UAAU,OAAO,MAAM,GAAG,EAAE,OAAO,OAAO;AAChD,QAAM,YAAY,oBAAI,IAAoB;AAC1C,UAAQ,QAAQ,CAAC,WAAW,UAAU;AACpC,QAAI,YAAY,IAAI,SAAS,EAAG,WAAU,IAAI,WAAW,KAAK;AAAA,EAChE,CAAC;AACD,MAAI,UAAU,OAAO,EAAG,QAAO;AAC/B,SAAO,QACJ,OAAO,CAAC,WAAW,UAAU,CAAC,YAAY,IAAI,SAAS,KAAK,UAAU,IAAI,SAAS,MAAM,KAAK,EAC9F,KAAK,GAAG;AACb;AAEO,SAAS,MAAM,QAA8B;AAClD,SAAO,mBAAmB,QAAQ,KAAK,MAAM,CAAC,CAAC;AACjD;AAGO,MAAM,KAAK;AAYlB,SAAS,WAA8B;AAGhC,MAAM,aAAa;AAOnB,SAAS,QAAQ,OAAyB;AAC/C,SAAO,CAAC,YAAY,GAAG,KAAK,EAAE,KAAK,GAAG;AACxC;AAkBO,SAAS,YAAY,OAAc,SAAyB;AACjE,QAAM,IAAI,MAAM,WAAW,sBAAsB,OAAO,KAAK,CAAC,EAAE;AAClE;AAQO,SAAS,eAAe,QAA8B;AAC3D,SAAO,KAAK,MAAM;AACpB;","names":[]}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@tea-ui/utils",
+  "version": "0.1.0",
+  "description": "Shared types, class-name composition and small helpers.",
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./dist/index.d.ts",
+  "module": "./dist/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup && node ../../scripts/fix-esm-extensions.mjs utils",
+    "prepublishOnly": "node ../../scripts/prepublish-guard.mjs"
+  },
+  "dependencies": {
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.3.1"
+  },
+  "keywords": [
+    "react",
+    "typescript",
+    "cn",
+    "clsx",
+    "utility",
+    "tea-ui",
+    "design-system"
+  ],
+  "author": "landnevermore",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/landnevermore/TEAui.git",
+    "directory": "packages/utils"
+  },
+  "homepage": "https://landnevermore.github.io/TEAui/docs/",
+  "bugs": {
+    "url": "https://github.com/landnevermore/TEAui/issues"
+  }
+}