@exxatdesignux/ui 0.4.0 → 0.4.2

package/CHANGELOG.md

@@ -1,5 +1,124 @@
 # Changelog
 
+## 0.4.2
+
+### Patch Changes
+
+- ### `HubTable` — stop warning when the centralized default covers a supported view
+
+  The dev-time `Missing renderer for supported view …` warning in
+  `HubTable` only treated `data-table` as having a built-in fallback,
+  even though the same component synthesises centralized defaults for
+  `list-with-toolbar` (when the consumer passes `renderListRow`) and
+  `board-with-toolbar` (when the consumer passes `renderBoardCard` plus
+  `boardGroups`). Every consumer that wired list/board the happy-path
+  way saw a spurious console warning every time their hub mounted —
+  including the freshly-scaffolded Library hub in `create-exxat-app`,
+  where the first thing a new user saw was a repeating
+  `[HubTable: Library] Missing renderer for supported view "list"
+(list-with-toolbar)` line, even though the view renders correctly.
+
+  The warning loop now also skips the two centralized-default cases
+  (it still fires for exotic surfaces that genuinely need an explicit
+  renderer entry, e.g. Placements' per-phase column-search board, or a
+  custom finder body the package doesn't synthesise).
+
+  No behavior change in production builds (the warning is already gated
+  on `process.env.NODE_ENV !== "production"`).
+
+## 0.4.1
+
+### Patch Changes
+
+- ### `@exxatdesignux/ui` — publish hygiene + smarter scaffolder
+
+  Three real bugs in the `0.4.0` tarball made first-run consumer installs
+  fail. All three are now fixed.
+  - **`tokens/hooks-index.json` ships.** The `exports` map declared
+    `"./tokens/hooks-index.json"` but the `files` array did not include
+    `tokens`, so the file was silently omitted from the published tarball.
+    Any `import "@exxatdesignux/ui/tokens/hooks-index.json"` (used by
+    `@exxatdesignux/eslint-plugin`'s `no-deprecated-tokens` rule and by
+    workspaces that read the token registry) blew up with
+    `MODULE_NOT_FOUND`. The `files` array now includes `tokens`.
+  - **No more `workspace:*` leaking into the published template.** The
+    scaffolder template was sync'd from `apps/web/package.json`, which
+    uses `workspace:*` for both `@exxatdesignux/ui` (correct, gets
+    rewritten to a real semver pin) and a handful of monorepo-internal
+    dev tools (`@exxatdesignux/eslint-plugin`, …) which are not published
+    on npm. The previous sync rewrote only the design-system line, so
+    every consumer install (`npm` / `pnpm` / `yarn`) crashed on the
+    leaked entries. The sync script now walks every dep map
+    (`dependencies` / `devDependencies` / `peerDependencies` /
+    `optionalDependencies`), pins `@exxatdesignux/ui`, deletes any
+    remaining `workspace:` value, and fails the build if any leaks
+    survive — so the bug surfaces here, not on a consumer's terminal.
+  - **Consumer-safe `eslint.config.mjs` in the template.** The repo's
+    own `apps/web/eslint.config.mjs` imports
+    `@exxatdesignux/eslint-plugin` for DS guardrails (no hex literals,
+    no deprecated tokens, no SLDS leakage, no Sonner toasts). Because
+    that plugin isn't published, `pnpm lint` in a freshly-scaffolded app
+    crashed with `Cannot find package '@exxatdesignux/eslint-plugin'`.
+    The sync script now overwrites `template/eslint.config.mjs` with a
+    clean `eslint-config-next + globalIgnores + unused-vars` setup that
+    every consumer can run. The DS guardrails graduate to this template
+    whenever the plugin lands on npm.
+
+  ### Smarter `bin/init.mjs` scaffolder
+
+  The `create-exxat-app` binary now matches the conventions of
+  `create-next-app` and `create-vite`:
+  - **Positional target directory.** `create-exxat-app my-app` creates
+    `./my-app` and scaffolds into it. `create-exxat-app .` scaffolds
+    into the current directory. Missing directories are auto-created.
+  - **Package-manager auto-detection.** Reads `npm_config_user_agent`
+    and runs the matching install (`pnpm install` / `yarn install` /
+    `bun install` / `npm install`). The post-install hint prints the
+    matching `<pm> run dev` command.
+  - **`--force` flag.** Allow scaffolding into a non-empty directory
+    (existing files are not overwritten unless the template ships the
+    same path). The previous "directory must be empty" hard-error
+    blocked every "install the DS first, then scaffold" sequence.
+  - **`--no-install` flag.** Skip the install step (useful in CI or
+    sandboxed setups).
+  - **`--help` / `-h`.** Print usage.
+  - **Clearer blocked-directory error.** When the target is non-empty
+    without `--force`, the CLI lists which files are blocking and
+    suggests both options (`create-exxat-app my-new-app` or
+    `create-exxat-app . --force`) instead of failing silently.
+
+  ### Real README on the npm package page
+
+  `packages/ui/` had no `README.md` — the npm landing page at
+  [npmjs.com/package/@exxatdesignux/ui](https://www.npmjs.com/package/@exxatdesignux/ui)
+  showed only the bare package.json description. The new README leads
+  with the 60-second start (`pnpm create exxat-app my-app`), covers
+  "adding to an existing Next.js app", documents `exxat-ui sync-extras`
+  for Cursor skill installation, and links the full doc set.
+
+  ### `create-exxat-app@0.0.x` → new package
+
+  A new `create-exxat-app` discovery package now ships on npm so
+  `pnpm create exxat-app my-app` (and the npm / yarn / bun variants)
+  resolve natively without a `--package=` flag. The shim is intentionally
+  tiny — it depends on `@exxatdesignux/ui` (via `workspace:^`, pinned to
+  `^<version>` at publish) and delegates to
+  `@exxatdesignux/ui/bin/init.mjs`. All template, version-pinning, and
+  package-manager-detection logic stays in `@exxatdesignux/ui` so there
+  is exactly one source of truth.
+
+  ### Migration
+
+  Consumers on `0.4.0` should bump to `0.4.1`:
+
+  ```bash
+  pnpm up @exxatdesignux/ui@latest
+  ```
+
+  If you scaffolded with `0.4.0` and edited `eslint.config.mjs` /
+  `package.json` to work around the workspace leak, you can either keep
+  your manual edits or re-scaffold with `0.4.1` for a clean baseline.
+
 ## 0.4.0
 
 ### Minor Changes

package/README.md

@@ -0,0 +1,138 @@
+# @exxatdesignux/ui
+
+The Exxat Design System — a Next.js + React 19 + Tailwind v4 component
+library plus the full hub-page stack (`ListPageTemplate`, `DataTable`,
+`HubTable`, `TablePropertiesDrawer`, `KeyMetrics`, `PageHeader`, board
+cards, charts, …) wrapped in one publishable package.
+
+## 60-second start
+
+Spin up a brand-new app pre-wired with the DS:
+
+```bash
+pnpm create exxat-app my-app
+cd my-app
+pnpm dev
+```
+
+Works with every modern package manager — the scaffolder auto-detects
+the runner and uses the matching install:
+
+```bash
+npm  create exxat-app my-app
+yarn create exxat-app my-app
+bun  create exxat-app my-app
+```
+
+The scaffolder ships a complete Next.js 16 starter: the reference
+**Library** hub at `/library/all`, the `/columns` cell-catalog showcase,
+typed mock data, the full Cursor skill + pattern doc set under
+`cursor-rules/`, `cursor-skills/`, `patterns/`, and `handbook/`.
+
+## Adding to an existing Next.js app
+
+If you already have a Next 15/16 app and just want the components:
+
+```bash
+pnpm add @exxatdesignux/ui
+```
+
+Then in your global CSS (e.g. `app/globals.css`):
+
+```css
+@import "@exxatdesignux/ui/globals.css";
+```
+
+And import primitives or full patterns from the umbrella or a subpath:
+
+```tsx
+import { DataTable, HubTable, ListPageTemplate, KeyMetrics } from "@exxatdesignux/ui"
+import { Button } from "@exxatdesignux/ui/components/button"
+import { useTableState } from "@exxatdesignux/ui/components/data-table/use-table-state"
+```
+
+Mount `KeyMetricsProvider` near the root if you want the "Ask Leo about
+these metrics" CTA wired to your AI surface (otherwise the strip just
+hides that button automatically).
+
+## Refresh Cursor skills + pattern docs in any consumer
+
+The package ships a parallel set of binding rules, skills, and pattern
+docs so AI agents in your own repo can read the same guidance the source
+repo uses. To install or refresh them in your repo:
+
+```bash
+pnpm dlx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+```
+
+This copies `cursor-rules/`, `cursor-skills/`, `patterns/`, and
+`handbook/` into your repo root. The next time Cursor opens, every
+binding rule + skill is live.
+
+## What's inside
+
+- **Primitives** (`@exxatdesignux/ui/components/<name>`) — Button, Input,
+  Select, Dialog, AlertDialog, Sheet, Drawer, Popover, DropdownMenu,
+  ContextMenu, Tabs, Accordion, Tooltip, Toast-free Banner, ScrollArea,
+  Slider, HoverCard, Avatar, Badge, StatusBadge, Calendar, Kbd, …
+- **Hub stack** — `DataTable<TRow>`, `useTableState<TRow>`,
+  `TablePropertiesDrawer`, `HubTable<TRow>`, `ListPageTemplate`,
+  `PageHeader`, `KeyMetrics`, `ListPageBoardCard`,
+  `ListPageBoardTemplate`, `DataRowList`, `FinderPanelView`,
+  `FolderGridView`, `OutlineTreeMenu`.
+- **Data-list registry** — `DataListViewType`, `DATA_LIST_VIEW_TILES`,
+  `dataListViewIcon`, `dataListViewAddShortcut`, `usesDataTableComponent`,
+  `usesDashboardSurface`.
+- **Templates** — `ListPageTemplate`, `NestedSecondaryPanelShell`,
+  `DedicatedSearchLandingTemplate`, `DedicatedSearchResultsTemplate`.
+- **Tokens** — `tokens/hooks-index.json` (197 tokens · 42 namespaces)
+  feeds the workspace ESLint plugin's `no-deprecated-tokens` rule.
+- **Tailwind v4 token bridge** — `globals.css` imports the L0
+  `--exxat-color-*` / `--exxat-radius-*` / `--exxat-spacing-*` family
+  and wires Tailwind shorthand (`bg-surface-1`, `text-ink-1`,
+  `rounded-2`, …) via `@theme inline`.
+
+## CLI commands
+
+After `pnpm add @exxatdesignux/ui` (or globally `npm i -g @exxatdesignux/ui`):
+
+```bash
+# In an empty directory (or new sub-folder), scaffold an app:
+npx --package=@exxatdesignux/ui create-exxat-app my-app
+
+# Sync Cursor skills + binding rules + pattern docs into your repo:
+npx --package=@exxatdesignux/ui exxat-ui sync-extras
+```
+
+The standalone [`create-exxat-app`](https://www.npmjs.com/package/create-exxat-app)
+package wraps the first command so `<pm> create exxat-app …` resolves
+natively.
+
+## Docs
+
+- Design-system **HANDBOOK** — read-this-first orientation, the 6-step
+  "how to build a hub" walkthrough, the §13 PR checklist.
+- **Blueprints** — framework-agnostic specs for each major composition
+  (`PageHeader`, `DataTable`, `ListPageTemplate`, `BoardCard`,
+  `KeyMetrics`, …).
+- **Component selection guide** — top-of-funnel decision tree for
+  picking the right composition.
+- **Token taxonomy** — naming + deprecation policy for every CSS
+  custom property the DS ships.
+
+The full doc set is mirrored under `handbook/` and `patterns/` in this
+package; `exxat-ui sync-extras` drops them into your repo so they sit
+alongside your source.
+
+## Compatibility
+
+| Peer | Range |
+| --- | --- |
+| React | `>=19.0.0` |
+| Next.js | `>=15.0.0` (App Router) |
+| Tailwind CSS | `>=4.0.0` |
+| Node | `>=22.0.0` (build / dev) |
+
+## License
+
+UNLICENSED — proprietary to Exxat Design.

package/bin/init.mjs

@@ -1,43 +1,146 @@
 #!/usr/bin/env node
-import { cpSync, readFileSync, readdirSync, writeFileSync } from 'fs'
-import { resolve, dirname } from 'path'
-import { fileURLToPath } from 'url'
-import { execSync } from 'child_process'
+/**
+ * Scaffold a new Exxat DS app from the bundled template.
+ *
+ * Usage:
+ *   npx create-exxat-app                 # scaffold into current directory
+ *   npx create-exxat-app my-app          # scaffold into ./my-app (created if missing)
+ *   npx create-exxat-app . --force       # overwrite-merge into current directory
+ *   npx create-exxat-app my-app --no-install   # skip the package install step
+ *
+ * Also runs as `npx --package=@exxatdesignux/ui create-exxat-app …` and as
+ * `pnpm create exxat-app …` when invoked via the standalone create-exxat-app
+ * discovery shim.
+ */
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs"
+import { resolve, dirname, basename, join } from "node:path"
+import { fileURLToPath } from "node:url"
+import { execSync } from "node:child_process"
 
 const __dirname = dirname(fileURLToPath(import.meta.url))
-const templateDir = resolve(__dirname, '../template')
-const selfPkgPath = resolve(__dirname, '../package.json')
-const targetDir = process.cwd()
+const templateDir = resolve(__dirname, "../template")
+const selfPkgPath = resolve(__dirname, "../package.json")
+const selfPkg = JSON.parse(readFileSync(selfPkgPath, "utf8"))
 
-const files = readdirSync(targetDir)
-const isEmpty = files.length === 0 || (files.length === 1 && files[0] === '.git')
+const args = process.argv.slice(2)
+const flags = new Set(args.filter((a) => a.startsWith("--")))
+const positional = args.filter((a) => !a.startsWith("--"))
+const targetArg = positional[0] ?? "."
+const targetDir = resolve(process.cwd(), targetArg)
+const projectName = targetArg === "." ? basename(targetDir) : targetArg
+const force = flags.has("--force")
+const skipInstall = flags.has("--no-install") || flags.has("--skip-install")
 
-if (!isEmpty) {
-  console.error('❌  Target directory is not empty. Run this in a new empty folder.')
+if (flags.has("--help") || flags.has("-h")) {
+  console.log(`
+create-exxat-app — scaffold a Next.js app on @exxatdesignux/ui
+
+Usage:
+  create-exxat-app [target-directory] [options]
+
+Arguments:
+  target-directory    Where to create the app (default: ".")
+                      A relative or absolute path. Created if it does not exist.
+
+Options:
+  --force             Allow scaffolding into a non-empty directory (existing
+                      files are NOT overwritten unless template ships the
+                      same path).
+  --no-install        Skip the dependency install step.
+  -h, --help          Show this message.
+
+Examples:
+  create-exxat-app my-app
+  create-exxat-app .
+  create-exxat-app ../sandbox --force --no-install
+`)
+  process.exit(0)
+}
+
+if (!existsSync(targetDir)) {
+  mkdirSync(targetDir, { recursive: true })
+  console.log(`📁  Created ${projectName}/`)
+}
+
+const targetStat = statSync(targetDir)
+if (!targetStat.isDirectory()) {
+  console.error(`❌  Target ${targetDir} exists but is not a directory.`)
   process.exit(1)
 }
 
-console.log('📦  Copying Exxat DS starter app...')
+const existing = readdirSync(targetDir)
+const ignorable = new Set([".git", ".gitignore", ".DS_Store"])
+const blockers = existing.filter((name) => !ignorable.has(name))
+
+if (blockers.length > 0 && !force) {
+  console.error(`❌  Target directory is not empty (${targetDir}).`)
+  console.error("")
+  console.error("    Found:")
+  for (const name of blockers.slice(0, 8)) console.error(`      - ${name}`)
+  if (blockers.length > 8) console.error(`      … and ${blockers.length - 8} more`)
+  console.error("")
+  console.error("    Options:")
+  console.error(`      1. Scaffold into a new folder:   create-exxat-app my-app`)
+  console.error(`      2. Allow merging existing files: create-exxat-app . --force`)
+  console.error("")
+  process.exit(1)
+}
+
+console.log(`📦  Copying Exxat DS starter app into ${projectName}/ …`)
 cpSync(templateDir, targetDir, { recursive: true })
 
-/** Pin DS to this CLI tarball version so `npm install` does not resolve a stale `latest` from cache. */
-const selfVersion = JSON.parse(readFileSync(selfPkgPath, 'utf8')).version
-const targetPkgPath = resolve(targetDir, 'package.json')
-const targetPkg = JSON.parse(readFileSync(targetPkgPath, 'utf8'))
-if (targetPkg.dependencies?.['@exxatdesignux/ui']) {
-  targetPkg.dependencies['@exxatdesignux/ui'] = `^${selfVersion}`
-  writeFileSync(targetPkgPath, `${JSON.stringify(targetPkg, null, 2)}\n`)
-  console.log(`📌  Pinned @exxatdesignux/ui to ^${selfVersion} (matches this scaffold).`)
+// Pin DS to this CLI's published version so `latest` cache drift cannot
+// trick the consumer into installing an older dist.
+const targetPkgPath = resolve(targetDir, "package.json")
+const targetPkg = JSON.parse(readFileSync(targetPkgPath, "utf8"))
+if (targetPkg.dependencies?.["@exxatdesignux/ui"]) {
+  targetPkg.dependencies["@exxatdesignux/ui"] = `^${selfPkg.version}`
 }
+// Name the project after the target dir for nicer dev-server / process titles.
+targetPkg.name = projectName.replace(/[^a-z0-9-_]/gi, "-").toLowerCase() || "my-exxat-app"
+writeFileSync(targetPkgPath, `${JSON.stringify(targetPkg, null, 2)}\n`)
+console.log(`📌  Pinned @exxatdesignux/ui to ^${selfPkg.version} and named the project "${targetPkg.name}".`)
 
-console.log('📥  Installing dependencies...')
-execSync('npm install', { stdio: 'inherit', cwd: targetDir })
-
-console.log('')
-console.log('✅  Done! Your Exxat DS app is ready.')
-console.log('')
-console.log('   npm run dev   → start dev server')
-console.log('')
-console.log('   Optional — refresh Cursor skills + pattern docs from the same package:')
-console.log(`   npx --package=@exxatdesignux/ui@${selfVersion} exxat-ui sync-extras`)
-console.log('')
+const pm = detectPackageManager()
+if (skipInstall) {
+  console.log(`⏭   Skipped install (--no-install).`)
+} else {
+  console.log(`📥  Installing dependencies with ${pm.label} …`)
+  try {
+    execSync(pm.installCmd, { stdio: "inherit", cwd: targetDir })
+  } catch (err) {
+    console.error("")
+    console.error(`❌  ${pm.label} install failed. You can retry manually:`)
+    console.error(`     cd ${projectName} && ${pm.installCmd}`)
+    process.exit(1)
+  }
+}
+
+console.log("")
+console.log(`✅  Done! Your Exxat DS app is ready in ./${projectName}/`)
+console.log("")
+console.log(`   cd ${projectName}`)
+console.log(`   ${pm.runCmd} dev     # start dev server`)
+console.log("")
+console.log("   Optional — refresh Cursor skills + pattern docs:")
+console.log(`     ${pm.dlxCmd} --package=@exxatdesignux/ui@${selfPkg.version} exxat-ui sync-extras`)
+console.log("")
+
+/**
+ * Detect the package manager that invoked us — npm_config_user_agent is set
+ * by every modern package-runner (npm, pnpm, yarn, bun) and looks like
+ * "pnpm/10.33.0 npm/? node/v22.0.0 darwin arm64". We fall back to npm.
+ */
+function detectPackageManager() {
+  const ua = process.env.npm_config_user_agent ?? ""
+  if (ua.startsWith("pnpm")) {
+    return { label: "pnpm", installCmd: "pnpm install", runCmd: "pnpm", dlxCmd: "pnpm dlx" }
+  }
+  if (ua.startsWith("yarn")) {
+    return { label: "yarn", installCmd: "yarn install", runCmd: "yarn", dlxCmd: "yarn dlx" }
+  }
+  if (ua.startsWith("bun")) {
+    return { label: "bun", installCmd: "bun install", runCmd: "bun", dlxCmd: "bunx" }
+  }
+  return { label: "npm", installCmd: "npm install", runCmd: "npm run", dlxCmd: "npx" }
+}

package/dist/components/data-views/hub-table.js

@@ -5687,11 +5687,12 @@ function HubTable({
     for (const v of supportedViewTypes) {
       const kind = getDataListViewRenderKind(v);
       if (kind === "data-table") continue;
-      if (renderers[kind] == null) {
-        console.warn(
-          `[Exxat DS][HubTable: ${hubLabel}] Missing renderer for supported view "${v}" (${kind}). Add a renderer entry, or remove the view from supportedViewTypes.`
-        );
-      }
+      if (renderers[kind] != null) continue;
+      if (kind === "list-with-toolbar" && renderListRow != null) continue;
+      if (kind === "board-with-toolbar" && renderBoardCard != null && boardGroups != null) continue;
+      console.warn(
+        `[Exxat DS][HubTable: ${hubLabel}] Missing renderer for supported view "${v}" (${kind}). Add a renderer entry, or remove the view from supportedViewTypes.`
+      );
     }
   }
   const composed = {