@nextlyhq/ui 0.0.2-alpha.4 → 0.0.2-alpha.40

package/dist/utils.cjs

@@ -0,0 +1,13 @@
+'use strict';
+
+var clsx = require('clsx');
+var tailwindMerge = require('tailwind-merge');
+
+// src/lib/utils.ts
+function cn(...inputs) {
+  return tailwindMerge.twMerge(clsx.clsx(inputs));
+}
+
+exports.cn = cn;
+//# sourceMappingURL=utils.cjs.map
+//# sourceMappingURL=utils.cjs.map

package/dist/utils.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/utils.ts"],"names":["twMerge","clsx"],"mappings":";;;;;;AAeO,SAAS,MAAM,MAAA,EAAsB;AAC1C,EAAA,OAAOA,qBAAA,CAAQC,SAAA,CAAK,MAAM,CAAC,CAAA;AAC7B","file":"utils.cjs","sourcesContent":["import { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Utility function to merge class names with Tailwind CSS support.\n *\n * Combines clsx for conditional class names with tailwind-merge\n * to properly handle Tailwind CSS class conflicts.\n *\n * @example\n * ```typescript\n * cn('px-2 py-1', 'px-4') // => 'py-1 px-4'\n * cn('text-muted-foreground', condition && 'text-foreground')\n * ```\n */\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n"]}

package/dist/utils.d.cts

@@ -0,0 +1,17 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Utility function to merge class names with Tailwind CSS support.
+ *
+ * Combines clsx for conditional class names with tailwind-merge
+ * to properly handle Tailwind CSS class conflicts.
+ *
+ * @example
+ * ```typescript
+ * cn('px-2 py-1', 'px-4') // => 'py-1 px-4'
+ * cn('text-muted-foreground', condition && 'text-foreground')
+ * ```
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+export { cn };

package/dist/utils.d.ts

@@ -0,0 +1,17 @@
+import { ClassValue } from 'clsx';
+
+/**
+ * Utility function to merge class names with Tailwind CSS support.
+ *
+ * Combines clsx for conditional class names with tailwind-merge
+ * to properly handle Tailwind CSS class conflicts.
+ *
+ * @example
+ * ```typescript
+ * cn('px-2 py-1', 'px-4') // => 'py-1 px-4'
+ * cn('text-muted-foreground', condition && 'text-foreground')
+ * ```
+ */
+declare function cn(...inputs: ClassValue[]): string;
+
+export { cn };

package/dist/utils.mjs

@@ -0,0 +1,11 @@
+import { clsx } from 'clsx';
+import { twMerge } from 'tailwind-merge';
+
+// src/lib/utils.ts
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+export { cn };
+//# sourceMappingURL=utils.mjs.map
+//# sourceMappingURL=utils.mjs.map

package/dist/utils.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/lib/utils.ts"],"names":[],"mappings":";;;;AAeO,SAAS,MAAM,MAAA,EAAsB;AAC1C,EAAA,OAAO,OAAA,CAAQ,IAAA,CAAK,MAAM,CAAC,CAAA;AAC7B","file":"utils.mjs","sourcesContent":["import { type ClassValue, clsx } from \"clsx\";\nimport { twMerge } from \"tailwind-merge\";\n\n/**\n * Utility function to merge class names with Tailwind CSS support.\n *\n * Combines clsx for conditional class names with tailwind-merge\n * to properly handle Tailwind CSS class conflicts.\n *\n * @example\n * ```typescript\n * cn('px-2 py-1', 'px-4') // => 'py-1 px-4'\n * cn('text-muted-foreground', condition && 'text-foreground')\n * ```\n */\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n"]}

package/docs/plugin-ui-authoring.md

@@ -0,0 +1,178 @@
+# Plugin UI authoring guide
+
+How to build admin UI — plugin views, custom fields, dashboards — that looks native
+to the Nextly admin and inherits light/dark mode for free.
+
+The rules here are a **contract**. A lint guard (`pnpm lint:design`, run in CI) fails the
+build on the most common violations, so following this guide is not optional for code that
+ships in this repo.
+
+---
+
+## 1. Where your styles come from
+
+Nextly's design system lives in [`@nextlyhq/ui`](../README.md). It ships two CSS entry
+points:
+
+| Entry point               | Contents                                                                  | Use when                                                |
+| ------------------------- | ------------------------------------------------------------------------- | ------------------------------------------------------- |
+| `@nextlyhq/ui/theme.css`  | Design tokens + `@theme` mappings + `@keyframes`. No reset, no `@import`. | You run your own Tailwind v4 build and want the tokens. |
+| `@nextlyhq/ui/styles.css` | Pre-compiled bundle (Tailwind + tokens + reset). Zero config.             | Standalone UI, or a quick embed with no build wiring.   |
+
+**Inside a Nextly admin plugin you usually need neither.** The admin already loads
+`@nextlyhq/admin/style.css`, which defines every token scoped to `.nextly-admin` (and
+`.nextly-admin.dark` for dark mode). Plugin admin views render inside that scope, so the tokens
+are already on the page. Your plugin CSS should **consume** those tokens, never redefine
+them.
+
+Only import a stylesheet yourself when you render outside the admin shell (e.g. a public
+page or a standalone tool) — then import `@nextlyhq/ui/styles.css` once at the root.
+
+---
+
+## 2. The token contract
+
+Tokens are **complete color values** (OKLCH). Reference them directly:
+
+```css
+.my-panel {
+  background: var(--nx-card);
+  color: var(--nx-foreground);
+  border: 1px solid var(--nx-border);
+  border-radius: var(--radius);
+}
+```
+
+### Never wrap a token in `hsl()` / `rgb()`
+
+Older Nextly builds stored tokens as bare HSL channels (`--nx-primary: 221 83% 53%`) and code
+wrapped them: `hsl(var(--nx-primary))`. **That convention is gone.** Tokens are now full colors
+(`--nx-primary: oklch(0 0 0)`), so `hsl(var(--nx-primary))` becomes `hsl(oklch(0 0 0))`, which is
+invalid CSS — the browser drops the declaration and your element loses its color. Always:
+
+```css
+/* ✗ wrong — produces hsl(oklch(...)), silently dropped */
+color: hsl(var(--nx-foreground));
+
+/* ✓ right */
+color: var(--nx-foreground);
+```
+
+### Alpha / transparency
+
+You can no longer do `hsl(var(--nx-primary) / 0.1)`. Use `color-mix`:
+
+```css
+/* 10% primary over transparent */
+background: color-mix(in srgb, var(--nx-primary) 10%, transparent);
+
+/* a subtle hover tint from the foreground */
+background: color-mix(in srgb, var(--nx-foreground) 6%, transparent);
+```
+
+### The tokens you may use
+
+Colors: `--nx-background` / `--nx-foreground`, `--nx-card` / `--nx-card-foreground`,
+`--nx-popover` / `--nx-popover-foreground`, `--nx-primary` / `--nx-primary-foreground`,
+`--nx-secondary` / `--nx-secondary-foreground`, `--nx-muted` / `--nx-muted-foreground`,
+`--nx-accent` / `--nx-accent-foreground`, `--nx-destructive`, `--nx-success`, `--nx-warning`,
+`--nx-border`, `--nx-border-strong`, `--nx-input`, `--nx-ring`,
+`--nx-sidebar-background` and the `--nx-sidebar-*` family.
+
+Sizing: `--radius` (the system is square — this is `0`; always route corner radius through
+it so a future rounding is one edit), and the control-height scale `--nx-control-height`,
+`--nx-control-height-sm`, `--nx-control-height-md`, `--nx-control-height-lg` for anything that should
+line up with admin inputs and buttons.
+
+Do not hardcode hex, `rgb()`, `rgba()`, or named colors. The only literals allowed are
+`transparent`, `currentColor`, and `inherit`.
+
+---
+
+## 3. Prefer components and utilities over hand-rolled CSS
+
+For new UI, reach for `@nextlyhq/ui` components and Tailwind utility classes before writing
+a stylesheet. They are already token-driven, accessible, and dark-mode-correct.
+
+```tsx
+import { Button, Input, Select, Switch, Badge } from "@nextlyhq/ui";
+import { cn } from "@nextlyhq/ui/utils";
+
+<Button variant="outline" size="sm">Add field</Button>
+<Input placeholder="Form name" />
+```
+
+- Merge conditional classes with `cn()` (clsx + tailwind-merge).
+- Express variants with `cva` (class-variance-authority), the way the components do.
+- Target internal parts with the `data-slot` attribute, not by re-styling the component.
+
+Hand-written CSS is still fine for bespoke layouts (a drag-and-drop canvas, a box-model
+control). When you write it, it must obey the token contract in section 2 and be scoped
+(section 5).
+
+---
+
+## 4. Dark mode is automatic — don't fight it
+
+The admin flips every token under `.nextly-admin.dark`. If you only ever reference tokens, your
+UI switches with it and you never write a dark rule.
+
+- **Never** hardcode a light or dark color.
+- **Never** gate admin theming on `@media (prefers-color-scheme: dark)` — admin dark mode is
+  class-based (`.dark` / `.nextly-admin.dark`), independent of the OS. A media query makes your
+  UI ignore the admin's own theme toggle. Use Tailwind's `dark:` variant or `.nextly-admin.dark`
+  descendant selectors if you truly need a mode-specific tweak.
+
+---
+
+## 5. Scope your class names
+
+Plugin CSS shares the page with the admin. Prefix every class so nothing leaks:
+`nx-pb-*` (page builder), `field-editor-*` / `form-settings-*` (form builder), etc. Never
+style bare element selectors (`button {}`, `input {}`) or admin utility classes.
+
+---
+
+## 6. Responsive: containers, not the viewport
+
+Plugin panels live in variable-width columns, so a media query keyed to the viewport is the
+wrong tool — it fires on window size while your panel might be half that. Use CSS container
+queries (Tailwind v4 core) against the nearest sized ancestor:
+
+```tsx
+<div className="@container/panel">
+  <div className="grid grid-cols-1 @2xl/panel:grid-cols-2">...</div>
+</div>
+```
+
+Container breakpoints are **container-sized**, not viewport-sized: `@md` = a 448px container,
+`@2xl` = 672px, `@4xl` = 896px. Pick the threshold by testing the panel, not by mapping from
+`md:`/`lg:`.
+
+---
+
+## 7. The guardrail
+
+`pnpm lint:design` (run in CI) scans the admin and plugin packages and fails on:
+
+- `hsl(var(--…))` / `rgb(var(--…))` — the dead HSL-channel convention (section 2).
+- Hardcoded colors: hex, `rgb(`, `rgba(`, `hsl(` with literal channels (outside `url(...)`
+  data URIs). Allowed literals: `transparent`, `currentColor`, `inherit`.
+- `!important` outside the small, reviewed allowlist.
+
+Run it locally before pushing. If a finding is a genuine false positive, add it to the
+allowlist in the script with a one-line reason — don't silence the whole check.
+
+---
+
+## Checklist
+
+- [ ] Colors come from `var(--token)` — no `hsl()`/`rgb()` wrappers, no hardcoded values.
+- [ ] Alpha uses `color-mix(in srgb, var(--token) N%, transparent)`.
+- [ ] Corner radius routes through `var(--radius)`; control heights use `--nx-control-height*`.
+- [ ] New UI uses `@nextlyhq/ui` components + Tailwind utilities where practical.
+- [ ] No `@media (prefers-color-scheme)`; dark mode inherited from the admin.
+- [ ] Class names are prefixed/scoped; no bare element selectors.
+- [ ] Responsive rules use container queries, tested against the panel width.
+- [ ] `pnpm lint:design` passes.
+- [ ] Verified in the admin in **both** light and dark mode.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nextlyhq/ui",
-  "version": "0.0.2-alpha.4",
+  "version": "0.0.2-alpha.40",
   "description": "Nextly UI — Reusable React component library for Nextly plugins and custom admin UIs",
   "license": "MIT",
   "keywords": [
@@ -17,13 +17,45 @@
   "types": "dist/index.d.ts",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.mjs",
-      "require": "./dist/index.cjs"
-    }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./tailwind-preset": {
+      "import": {
+        "types": "./dist/tailwind-preset.d.ts",
+        "default": "./dist/tailwind-preset.mjs"
+      },
+      "require": {
+        "types": "./dist/tailwind-preset.d.cts",
+        "default": "./dist/tailwind-preset.cjs"
+      }
+    },
+    "./utils": {
+      "import": {
+        "types": "./dist/utils.d.ts",
+        "default": "./dist/utils.mjs"
+      },
+      "require": {
+        "types": "./dist/utils.d.cts",
+        "default": "./dist/utils.cjs"
+      }
+    },
+    "./theme.css": "./dist/theme.css",
+    "./styles.css": "./dist/styles.css",
+    "./styles.scoped.css": "./dist/styles.scoped.css"
   },
+  "sideEffects": [
+    "**/*.css"
+  ],
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "engines": {
     "node": ">=20.0.0"
@@ -34,22 +66,29 @@
     "react-dom": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
+    "@tailwindcss/cli": "^4.3.2",
+    "@types/culori": "^4.0.1",
     "@types/react": "19.2.0",
     "@types/react-dom": "19.2.0",
     "@vitejs/plugin-react": "^5.1.0",
-    "@vitest/coverage-v8": "^4.0.8",
-    "@vitest/ui": "^4.0.8",
-    "eslint": "^9.34.0",
-    "lucide-react": "^0.544.0",
+    "@vitest/coverage-v8": "^4.1.0",
+    "@vitest/ui": "^4.1.0",
+    "culori": "^4.0.2",
+    "eslint": "^9.39.1",
     "jsdom": "^27.1.0",
+    "lucide-react": "^0.544.0",
+    "postcss": "^8.5.6",
     "react": "19.2.0",
     "react-dom": "19.2.0",
+    "rimraf": "^6.1.3",
+    "tailwindcss": "^4.3.2",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vite-tsconfig-paths": "^5.1.4",
-    "vitest": "^4.0.8",
-    "@nextlyhq/eslint-config": "0.0.2-alpha.3",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.3"
+    "vitest": "^4.1.0",
+    "@nextlyhq/admin-css": "0.0.2-alpha.40",
+    "@nextlyhq/eslint-config": "0.0.2-alpha.40",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.40"
   },
   "dependencies": {
     "@radix-ui/react-accordion": "^1.2.12",
@@ -90,8 +129,10 @@
   },
   "author": "Nextly <contact@nextlyhq.com> (https://nextlyhq.com)",
   "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
+    "build": "pnpm build:js && node scripts/build-css.mjs",
+    "build:js": "rimraf dist && tsup && tsup --config tsup.server-safe.config.ts && node scripts/check-client-directive.mjs",
+    "build:css": "node scripts/build-css.mjs",
+    "dev": "tsup --watch & tsup --config tsup.server-safe.config.ts --watch & wait",
     "check-types": "tsc --noEmit",
     "lint": "eslint . --max-warnings 0",
     "lint:fix": "eslint . --fix",