@nextlyhq/ui 0.0.2-alpha.5 → 0.0.2-alpha.50

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,228 @@
+# 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` (see the radius tiers below), 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`.
+
+### Corner radius: pick a tier, never a value
+
+The admin ships square today (`--radius: 0`), but the whole scale derives from that one
+knob, so an operator who sets `--radius: 12px` re-rounds every surface at once. Your plugin
+keeps up with that only if it picks a **tier by element category** rather than writing a
+length. Hardcoding a corner — `rounded-none` just as much as `rounded-[6px]` or
+`border-radius: 4px` — pins your UI at that value and opts it out of the knob.
+
+The scale is three steps. These are exactly what `@nextlyhq/ui/tailwind-preset` exports, and
+exactly what the shipped components use, so matching a Nextly component means picking the
+tier it picks.
+
+| Tier                         | Use for                                                                                                                                      |
+| ---------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `rounded-lg` / `--radius-lg` | Floating and grouping containers: cards, dialogs, alert dialogs, popovers, tooltips, dropdown / select / command panels, empty-state panels  |
+| `rounded-md` / `--radius-md` | Controls and the inline surfaces among them: buttons, inputs, textareas, select triggers, icon buttons, alerts, table wrappers, image frames |
+| `rounded-sm` / `--radius-sm` | Small controls and adornments: menu and list items, badges, chips, tags, checkboxes, toolbar affordances                                     |
+| `rounded-full`               | Circles and pills, outside the scale — avatars, status dots, spinners, progress tracks, switch tracks and thumbs                             |
+
+Four consequences worth internalising:
+
+- **`rounded-full` is deliberately outside the scale.** It is `9999px`, not a `--radius`
+  step. Those elements are round because of their shape, not because of the theme, so a
+  retheme must never flatten them.
+- **`rounded-xl` and `rounded-2xl` are not tiers of this knob.** The preset exports only
+  `lg`, `md` and `sm`, so a plugin built against it gets Tailwind's fixed `0.75rem` /
+  `1rem` for those two, detached from `--radius`. Inside the admin's own build they are
+  defined, but as `--radius + 4px` and `--radius + 8px`, so at the shipped `--radius: 0`
+  they resolve to `4px` and `8px` — visibly round inside a square admin. Pick from
+  `sm` / `md` / `lg`.
+- **`--radius: 0` is not "every step is zero".** `--radius-lg` is `0`, but `--radius-sm`
+  and `--radius-md` compute to `-4px` and `-2px`. They _render_ square only because
+  `border-radius` clamps a negative length to `0`. The token keeps its negative value, so
+  reading a step for padding, for an inset, or through `getComputedStyle` gives you `-4px`,
+  not `0`. Clamp it yourself if you consume a step as a length rather than as a corner.
+- **A rounded container must handle full-bleed children.** If a child paints a background
+  all the way to the container's edge (a tinted footer, a sticky header, a hover row), give
+  the container `overflow-hidden` or give the child a matching corner with
+  `rounded-b-[inherit]` / `rounded-t-[inherit]`. Otherwise the child's fill paints square
+  across the parent's curve at any nonzero `--radius`.
+
+If a specific element genuinely must stay square, keep `rounded-none` and leave a comment
+saying why (overlapped-border strips, full-bleed fills inside an already-rounded parent,
+underline tabs). Square with a stated reason is a decision; square without one is an element
+nobody wired to the knob. Tabs are square for exactly that reason — the active state is a
+bottom border that has to run the full width of the trigger — which is why they are not in
+the `rounded-sm` tier above. Sheet is the counter-example: it is anchored to the viewport
+edge and carries no radius class at all.
+
+---
+
+## 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 picks a tier (`rounded-lg`/`md`/`sm`), never a hardcoded value; circles
+      use `rounded-full`; any `rounded-none` carries a reason; rounded containers clip or
+      match their full-bleed children. 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.5",
+  "version": "0.0.2-alpha.50",
   "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.4",
-    "@nextlyhq/tsconfig": "0.0.2-alpha.4"
+    "vitest": "^4.1.0",
+    "@nextlyhq/admin-css": "0.0.2-alpha.50",
+    "@nextlyhq/eslint-config": "0.0.2-alpha.50",
+    "@nextlyhq/tsconfig": "0.0.2-alpha.50"
   },
   "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",