@osiris-smarttv/style-util 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 OsirisTech SmartTV
+
+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,80 @@
+# @osiris-smarttv/style-util
+
+Layered `className` composition utility for Smart TV UI codebases.
+
+Combines:
+
+- Tailwind utility classes
+- design-token-aware atomic classes
+- CSS module classes
+- caller `className` overrides
+
+with deterministic merge order and `tailwind-merge` conflict resolution.
+
+## Install
+
+```bash
+npm i @osiris-smarttv/style-util
+```
+
+## Quick start
+
+```ts
+import { cn } from '@osiris-smarttv/style-util'
+
+const className = cn({
+  tw: ['flex', 'items-center', 'px-4'],
+  s: [styles.container, isActive && styles.active],
+  className: props.className,
+})
+```
+
+## API
+
+- `cn(input)` - default combiner
+- `createCn()` - build custom combiner
+- `createCnForTokens()` - token-typed combiner factory
+
+Key exported types:
+
+- `CnInput`
+- `TwClass`
+- `AtomicClass`
+- `ModuleClass`
+- `DesignToken`
+- `DesignTokenValue`
+
+## Merge behavior
+
+Layer precedence is explicit and stable:
+
+1. `tw`
+2. `atomic`
+3. `s`
+4. `className`
+
+`tailwind-merge` runs on Tailwind-like layers to drop conflicting utilities.
+Module classes are preserved.
+
+## Local development
+
+```bash
+yarn install
+yarn build
+yarn typecheck
+yarn test
+```
+
+## Manual publish (no GitHub Actions)
+
+```bash
+yarn publish:check
+yarn publish:dry-run
+yarn publish:manual
+```
+
+If publish returns `404` or permission errors for `@osiris-smarttv/*`, verify:
+
+- your npm account has publish access to scope `@osiris-smarttv`
+- package name is allowed by org policy
+- you are authenticated against `https://registry.npmjs.org/`

package/dist/index.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Augment in the host app to narrow default `atomic` tokens (when using `cn()` without a wrapper).
+ *
+ * @example
+ * ```ts
+ * declare module '@osiris-smarttv/style-util' {
+ *   interface DesignTokenRegistry {
+ *     'ds-bg-surface': true
+ *   }
+ * }
+ * ```
+ */
+interface DesignTokenRegistry {
+}
+type RegistryTokenKey = keyof DesignTokenRegistry;
+/** Resolved token id from {@link DesignTokenRegistry}. Falls back to `string` when empty. */
+type RegisteredDesignToken = RegistryTokenKey extends never ? string : RegistryTokenKey & string;
+/** One allowed value in the `atomic` array (token id + clsx falsy). */
+type AtomicClass = string | false | null | undefined;
+/** Tailwind utility class — structural frame. */
+type TwClass = AtomicClass;
+/** SCSS module resolved class name. */
+type ModuleClass = AtomicClass;
+/** Token id `T` plus optional falsy entries (for `atomic: [id, condition && id]`). */
+type DesignTokenValue<T extends string = string> = T | false | null | undefined;
+/** @deprecated Prefer {@link DesignTokenValue}. */
+type DesignToken<T extends string = RegisteredDesignToken> = DesignTokenValue<T>;
+/**
+ * `CnInput` generic = type of **each `atomic` entry**, not the token registry itself.
+ *
+ * @example App wrapper (wide open)
+ * ```ts
+ * type DesignToken = string | false | null | undefined
+ * const cn = (input: CnInput<DesignToken>) => cnLib(input)
+ * ```
+ *
+ * @example App wrapper (narrow ids)
+ * ```ts
+ * type FgnToken = DesignTokenValue<'ds-bg' | 'ds-text'>
+ * const cn = (input: CnInput<FgnToken>) => cnLib(input)
+ * ```
+ */
+type CnInput<TAtomic extends AtomicClass = DesignTokenValue<RegisteredDesignToken>> = {
+    tw?: TwClass[];
+    atomic?: TAtomic[];
+    s?: ModuleClass[];
+    className?: string | string[];
+};
+declare function cn<TAtomic extends AtomicClass = DesignTokenValue<RegisteredDesignToken>>(input: CnInput<TAtomic>): string;
+/** Pin the `atomic` element type (e.g. `DesignTokenValue<'lib-a' | 'lib-b'>`). */
+declare function createCn<TAtomic extends AtomicClass = DesignTokenValue<RegisteredDesignToken>>(): (input: CnInput<TAtomic>) => string;
+/** Pin allowed token **ids**; falsy entries still allowed in `atomic`. */
+declare function createCnForTokens<TTokenId extends string>(): (input: CnInput<DesignTokenValue<TTokenId>>) => string;
+
+export { type AtomicClass, type CnInput, type DesignToken, type DesignTokenRegistry, type DesignTokenValue, type ModuleClass, type RegisteredDesignToken, type TwClass, cn, createCn, createCnForTokens };

package/dist/index.js

@@ -0,0 +1 @@
+import e from'clsx';import {twMerge}from'tailwind-merge';function n(t){let{tw:o,atomic:i,s:r,className:g}=t;return twMerge(e(o),e(i),e(r),e(g))}function s(){return t=>n(t)}function p(){return s()}export{n as cn,s as createCn,p as createCnForTokens};

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@osiris-smarttv/style-util",
+  "version": "0.1.0",
+  "description": "Layered className merge (Tailwind + design tokens + SCSS modules) for Smart TV UI",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OsirisTech-SmartTV/style-util.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OsirisTech-SmartTV/style-util/issues"
+  },
+  "homepage": "https://github.com/OsirisTech-SmartTV/style-util#readme",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "sideEffects": false,
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "dependencies": {
+    "clsx": "^2.1.1",
+    "tailwind-merge": "^3.6.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.0",
+    "typescript": "~6.0.2",
+    "vitest": "^4.1.4"
+  },
+  "scripts": {
+    "clean": "node scripts/clean.mjs",
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify": "yarn typecheck && yarn test",
+    "publish:check": "yarn clean && yarn build && yarn verify && npm pack --dry-run",
+    "publish:dry-run": "npm publish --dry-run --access public",
+    "publish:manual": "npm publish --access public",
+    "prepublishOnly": "yarn clean && yarn build && yarn verify"
+  }
+}