@webjsdev/cli 0.10.42 → 0.10.43

package/lib/create.js

@@ -18,6 +18,7 @@ import { existsSync } from 'node:fs';
 import { createRequire } from 'node:module';
 import { spawnSync } from 'node:child_process';
 import { bunifyProse, bunifyDockerfile, bunifyCompose, bunifyCi } from './runtime-rewrite.js';
+import { leanComponentSource } from './lean-copy.js';
 
 /**
  * Detect which package manager invoked us. Reads `npm_config_user_agent`,
@@ -120,12 +121,16 @@ async function readUiComponent(name) {
   const raw = await readFile(src, 'utf8');
   // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
   // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
-  return raw
+  const rewritten = raw
     .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
     .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"')
     // onBeforeCache lives in its own client-only module so cn() stays pure (#819).
     .replaceAll("'../lib/dom.ts'", "'#lib/utils/dom.ts'")
     .replaceAll('"../lib/dom.ts"', '"#lib/utils/dom.ts"');
+  // Strip the worked @example from a Tier-1 helper (same as `webjs ui add`), so
+  // the scaffolded component is lean and the example is served on demand. The
+  // shared helper is used by the saas-template copier too, so they cannot drift.
+  return leanComponentSource(rewritten, name);
 }
 
 /**

package/lib/lean-copy.js

@@ -0,0 +1,43 @@
+/**
+ * The scaffold's lean-copy of a ui component (#983).
+ *
+ * `webjs create` copies a few `@webjsdev/ui` registry components into a
+ * generated app. To match what `webjs ui add` writes, a Tier-1 helper's worked
+ * `@example` is stripped (the example is served on demand by `webjs ui view` /
+ * the MCP `ui` tool), while a Tier-2 element file is kept whole. Both scaffold
+ * copiers (`create.js` and `saas-template.js`) go through THIS one helper so
+ * they cannot drift.
+ *
+ * The strip primitives live in `@webjsdev/ui/registry/extract`; if that subpath
+ * cannot be resolved, this degrades to a no-op (keep the example) so the strip
+ * is never a reason `webjs create` fails.
+ *
+ * @module lean-copy
+ */
+
+let _mod = null;
+
+async function loadPrimitives() {
+  if (_mod) return _mod;
+  try {
+    const m = await import('@webjsdev/ui/registry/extract');
+    _mod = { stripExample: m.stripExample, isCustomElementSource: m.isCustomElementSource };
+  } catch {
+    _mod = { stripExample: (s) => s, isCustomElementSource: () => true };
+  }
+  return _mod;
+}
+
+/**
+ * Return the component source as `webjs ui add` would write it: a Tier-1 helper
+ * has its worked `@example` stripped and a pointer left; a Tier-2 element is
+ * returned unchanged.
+ *
+ * @param {string} source  the component source (imports already rewritten)
+ * @param {string} name    the component name (for the pointer)
+ * @returns {Promise<string>}
+ */
+export async function leanComponentSource(source, name) {
+  const { stripExample, isCustomElementSource } = await loadPrimitives();
+  return isCustomElementSource(source) ? source : stripExample(source, name);
+}

package/lib/saas-template.js

@@ -5,6 +5,7 @@
 
 import { mkdir, writeFile, readFile } from 'node:fs/promises';
 import { bunifyProse } from './runtime-rewrite.js';
+import { leanComponentSource } from './lean-copy.js';
 import { existsSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
@@ -25,7 +26,7 @@ async function readUiComponent(name) {
   const raw = await readFile(src, 'utf8');
   // The registry component imports cn() via a relative `../lib/utils.ts`; rewrite
   // it to the scaffolded app's aliased path (cn lives at lib/utils/cn.ts).
-  return raw
+  const rewritten = raw
     .replaceAll("'../lib/utils.ts'", "'#lib/utils/cn.ts'")
     .replaceAll('"../lib/utils.ts"', '"#lib/utils/cn.ts"')
     // onBeforeCache lives in its own client-only module so cn() stays pure (#819).
@@ -33,6 +34,9 @@ async function readUiComponent(name) {
     // (which resolves to a nonexistent components/lib/dom.ts) and fails typecheck.
     .replaceAll("'../lib/dom.ts'", "'#lib/utils/dom.ts'")
     .replaceAll('"../lib/dom.ts"', '"#lib/utils/dom.ts"');
+  // Strip a Tier-1 helper's worked @example (same as create.js + `webjs ui add`)
+  // so switch / checkbox are lean, not just the full-stack base set (#983).
+  return leanComponentSource(rewritten, name);
 }
 
 /** Copy named registry components into `<appDir>/components/ui/`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@webjsdev/cli",
-  "version": "0.10.42",
+  "version": "0.10.43",
   "type": "module",
   "description": "webjs CLI - dev, start, create, db",
   "bin": {

package/templates/.agents/skills/webjs/SKILL.md

@@ -44,6 +44,7 @@ Classify the task first, then load the smallest useful reference set. Each refer
 | Tailwind, light-DOM tag-prefix rule, tokens, fixed headers, no-reflow layout | `references/styling.md`                        |
 | Client router, prefetch, frames, view transitions, Suspense streaming        | `references/client-router-and-streaming.md`   |
 | Optimistic UI for a user-facing mutation                                     | `references/optimistic-ui.md`                 |
+| The `@webjsdev/ui` component kit (a `components.json` is present): class helpers, tokens, `add` / `view`, the MCP `ui` tool | `references/ui-kit.md`                         |
 | TypeScript at runtime, erasable syntax, full-stack types                     | `references/typescript.md`                     |
 | Unit, browser, e2e tests, the `handle()` harness, Bun parity                 | `references/testing.md`                        |
 | Auth, caching, env vars, rate limit, file storage, the `webjs` config block  | `references/built-ins.md`                      |

package/templates/.agents/skills/webjs/references/ui-kit.md

@@ -0,0 +1,68 @@
+# The `@webjsdev/ui` component kit
+
+Load this when the app has a `components.json` (it uses `@webjsdev/ui`, the
+shadcn-style kit for WebJs). The source is copied into your repo (`components/ui/`),
+so you own and edit it. Two tiers:
+
+- **Tier 1, class helpers (23 components).** Pure functions returning Tailwind
+  class strings (`buttonClass({ variant })`, `cardClass()`), composed with
+  whatever native element you write. Reach for these instead of expanding
+  Tailwind by hand: the call site is a fraction of the tokens and the class list
+  cannot drift.
+- **Tier 2, stateful custom elements (9 components).** `<ui-dialog>`, `<ui-tabs>`,
+  `<ui-dropdown-menu>`, and friends own their ARIA (focus trap, roving tabindex,
+  `aria-controls` / `inert`, live regions). Write the tag and the accessible
+  behaviour comes with it. Do NOT hand-roll these; the wiring is easy to get
+  subtly wrong.
+
+## The workflow: query for the structure, do not guess it
+
+`add` copies a Tier-1 component's class helpers plus a lean header (what each
+helper is, the accessibility obligations) and a one-line pointer. It does NOT
+copy the worked structural example, because that example is guidance you consume
+once while composing, not code that should sit in your repo. Get the full
+paste-ready structure on demand:
+
+- **MCP `ui` tool** (preferred when available): call `ui` with no args for the
+  kit inventory (each component's tier, helper signatures, npm deps); pass
+  `{ name: "accordion" }` for one component's helper signatures, the paste-ready
+  structural example, the accessibility header, and deps.
+- **CLI**: `webjs ui list` (inventory), `webjs ui view <name>` (the projected
+  view plus the full source). Same data as the MCP tool (one shared projector).
+
+So the loop is: `add` the component, then query `ui <name>` (MCP) or
+`webjs ui view <name>` for the accessible structure, paste it, and fill it in.
+
+## Setup and resolution
+
+- `webjs ui init` writes `components.json`, `lib/utils.ts`, and the CSS design
+  tokens the helpers render against (`--background`, `--foreground`,
+  `--destructive`, ...). It HARD-FAILS if the tokens cannot be written, so a
+  clean exit means the kit is styled. `add` self-heals the tokens if they go
+  missing.
+- Resolution is LOCAL-FIRST: `init` / `add` / `list` / `view` read the registry
+  that ships inside the installed `@webjsdev/ui`, with no network. This pins you
+  to the installed version; run `webjs ui diff` to see where your local copies
+  drift from the upstream (that command alone compares against the live registry).
+
+## Inventory (run `webjs ui list` or the MCP `ui` tool for the authoritative, current set)
+
+**Tier 1 (class helpers):** accordion, alert, aspect-ratio, avatar, badge,
+breadcrumb, button, card, checkbox, collapsible, input, kbd, label,
+native-select, pagination, popover, progress, radio-group, separator, skeleton,
+switch, table, textarea.
+
+**Tier 2 (custom elements, own their ARIA):** alert-dialog, dialog,
+dropdown-menu, hover-card, sonner, tabs, tooltip, plus toggle and toggle-group
+(these two register an element AND export a `*Class` helper).
+
+## Idioms
+
+- A helper is a function, so compose it: `class=${buttonClass({ variant: 'outline' })}`.
+  The unquoted `${...}` is a normal `html` attribute hole.
+- Tier-1 helpers assume the design tokens exist; if a component paints unstyled,
+  the tokens are missing (re-run `webjs ui init` or let `add` self-heal them).
+- Custom elements are display-only-safe at SSR and hydrate in the browser, the
+  standard WebJs component model (`references/components.md`).
+
+Full per-package reference lives in the installed `@webjsdev/ui/AGENTS.md`.