@exxatdesignux/ui 0.2.11 → 0.2.12

package/CHANGELOG.md

@@ -0,0 +1,45 @@
+# Changelog
+
+All notable changes to `@exxatdesignux/ui` are documented here. The file ships in the npm tarball at `node_modules/@exxatdesignux/ui/CHANGELOG.md`.
+
+## For AI assistants (upgrade handoff)
+
+After the user bumps `@exxatdesignux/ui`, do this in order:
+
+1. Read **`node_modules/@exxatdesignux/ui/CHANGELOG.md`** (this file) for breaking changes and new patterns.
+2. If the repo uses bundled Cursor skills / DS docs, run  
+   `npx --package=@exxatdesignux/ui@<same-version-or-latest> exxat-ui sync-extras`  
+   so **`.cursor/skills/exxat-*`** and **`docs/exxat-ds/*.md`** match the installed package (including **`consumer-upgrade-checklist.md`**).
+3. Treat **`node_modules/@exxatdesignux/ui/template/`** as the reference app for file-level parity (routes, `components/ui` shims, `AGENTS.md` structure). Diff or selectively port; do not assume only `package.json` changed.
+4. Re-run **`pnpm install` / `npm install`** and typecheck; align **`engines.node`** in the host app if the release notes say so.
+
+---
+
+## [0.2.12] - 2026-05-13
+
+### Added
+
+- This **CHANGELOG** (shipped in the package).
+- **`consumer-upgrade-checklist.md`** under packaged patterns → copied to **`docs/exxat-ds/`** by **`exxat-ui sync-extras`**.
+- **`exxat-ui changelog`** — prints this file from the installed package.
+
+### Changed
+
+- **`exxat-ui update`** — now points to the CHANGELOG, template path, and AI checklist above.
+
+## [0.2.11] - 2026-05-13
+
+### Changed
+
+- **`engines.node`**: `>=24` → **`>=22.0.0`** on the published package, starter template, and monorepo apps (fixes **EBADENGINE** on Node 22).
+
+## [0.2.10] - 2026-05-13
+
+### Fixed
+
+- Font Awesome sort icons: valid classes **`fa-arrow-up-a-z`** / **`fa-arrow-down-a-z`** (was invalid `fa-arrow-up-az`).
+- Dropdown / select menu rows: **`[&_i]`** flex rules so FA **`<i>`** icons are not collapsed.
+
+## [0.2.9] - 2026-05-12
+
+Maintenance / prior release (see git history under tag **`ui-v0.2.9`** for full diff).

package/bin/cli.mjs

@@ -11,7 +11,7 @@
  */
 
 import { execFileSync } from "child_process"
-import { readFileSync } from "fs"
+import { existsSync, readFileSync } from "fs"
 import { dirname, resolve } from "path"
 import { fileURLToPath } from "url"
 
@@ -53,6 +53,7 @@ Commands:
   init         Scaffold the Exxat DS starter app (must run in an empty directory).
   sync-extras  Copy packaged Cursor skills + pattern docs into this repo (DS-only paths).
   update       How to upgrade an existing project that depends on this package.
+  changelog    Print CHANGELOG.md from the installed package (release notes + AI upgrade hints).
   doctor       Compare this CLI version vs npm registry "latest" (diagnose stale installs).
 
 Do NOT use plain npx @exxatdesignux/ui — use the scoped form below.
@@ -62,6 +63,7 @@ Examples:
   npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
   npx --package=@exxatdesignux/ui@latest exxat-ui doctor
   npx --package=@exxatdesignux/ui@latest exxat-ui update
+  npx --package=@exxatdesignux/ui@latest exxat-ui changelog
 
 Legacy (npm create):
   npm create exxat-app@latest
@@ -86,15 +88,25 @@ Update @exxatdesignux/ui in your application:
 That refreshes **components / hooks / tokens** under node_modules only — your app
 routes and product copy are unchanged.
 
-**Still seeing old code?** Run **exxat-ui doctor** — the npm "latest" tag often lags
-this Git repo until maintainers publish (git tag **ui-v<version>**).
+After upgrading — for humans and AI tools:
 
-To also refresh **bundled Cursor skills** and **pattern reference docs** from the
-same package version (overwrites only .cursor/skills/exxat-* and docs/exxat-ds/):
+  1. Read release notes:
+       node_modules/@exxatdesignux/ui/CHANGELOG.md
+     or run:
+       npx --package=@exxatdesignux/ui@latest exxat-ui changelog
 
-  npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+  2. Refresh bundled Cursor skills + docs (overwrites only .cursor/skills/exxat-*
+     and docs/exxat-ds/*.md — includes consumer-upgrade-checklist.md):
+       npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+
+  3. Compare your app with the reference template when something new is unclear:
+       node_modules/@exxatdesignux/ui/template/
+
+**Still seeing old code?** Run **exxat-ui doctor** — the npm "latest" tag can lag
+this Git repo until maintainers publish (git tag **ui-v<version>**).
 
-CLI (always pulls this scope): npx --package=@exxatdesignux/ui@latest exxat-ui <init|sync-extras|update|doctor|help>
+CLI (always pulls this scope):
+  npx --package=@exxatdesignux/ui@latest exxat-ui <init|sync-extras|update|changelog|doctor|help>
 
 Monorepo / design-system contributors (this workspace): pull latest Git and run
   pnpm install
@@ -105,6 +117,18 @@ this CLI tarball so npm does not resolve a stale "latest" from cache.
 `)
 }
 
+function printChangelog() {
+  const p = resolve(__dirname, "../CHANGELOG.md")
+  if (!existsSync(p)) {
+    console.error(
+      "CHANGELOG.md not found next to this CLI. Reinstall @exxatdesignux/ui or use a release that ships CHANGELOG.md (0.2.12+).",
+    )
+    process.exitCode = 1
+    return
+  }
+  console.log(readFileSync(p, "utf8"))
+}
+
 function printDoctor() {
   const pkgPath = resolve(__dirname, "../package.json")
   let cliVersion = "unknown"
@@ -161,6 +185,9 @@ switch (cmd) {
   case "update":
     printUpdate()
     break
+  case "changelog":
+    printChangelog()
+    break
   case "doctor":
     printDoctor()
     break

package/bin/sync-extras.mjs

@@ -4,7 +4,7 @@
  *
  * Overwrites ONLY:
  *   - `.cursor/skills/<bundled exxat-* skill folders>/`
- *   - `docs/exxat-ds/*.md` (pattern reference docs from the package)
+ *   - `docs/exxat-ds/*.md` (pattern reference docs + **consumer-upgrade-checklist.md**)
  *
  * Does NOT touch `app/`, `pages/`, `src/` product code, or npm dependencies.
  * Run after `npm install @exxatdesignux/ui@…` / `pnpm update @exxatdesignux/ui`.

package/consumer-extras/README.md

@@ -6,8 +6,9 @@ touching product routes or pages.
 
 | Path in this tarball | After `exxat-ui sync-extras` in your repo |
 |----------------------|-------------------------------------------|
+| `CHANGELOG.md` (package root) | Stay in `node_modules/…` — read for release notes; **`exxat-ui changelog`** prints it |
 | `cursor-skills/exxat-*` | `.cursor/skills/exxat-*` (replaced) |
-| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) |
+| `patterns/*.md` | `docs/exxat-ds/*.md` (replaced) — includes **`consumer-upgrade-checklist.md`** for upgrades + AI handoff |
 
 **Components and hooks** still come only from `node_modules/@exxatdesignux/ui`
 via normal semver installs — `sync-extras` does not copy TS source into your app.

package/consumer-extras/cursor-skills/exxat-ds-skill/SKILL.md

@@ -22,6 +22,7 @@ description: >
 - **App root:** `exxat-ds/app/(app)/` — route group that wraps all authenticated pages
 - **Single source of truth:** `exxat-ds/AGENTS.md` for full prose explanations; this skill is the actionable summary
 - **Companion skills (narrow topics):** `exxat-fontawesome-icons`, `exxat-primary-nav-secondary-panel`, `exxat-centralized-list-dataset`, `exxat-list-page-view-shells`, `exxat-dedicated-search-surfaces`, `exxat-accessibility`, `exxat-board-cards`, `exxat-collaboration-access` — live under `.cursor/skills/`; vetted copies ship with **`@exxatdesignux/ui`** in `consumer-extras/cursor-skills/` after **`pnpm --filter @exxatdesignux/ui vendor:consumer-extras`**.
+- **Consumer repos (npm install of `@exxatdesignux/ui`):** After a version bump, read **`node_modules/@exxatdesignux/ui/CHANGELOG.md`**, run **`npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras`** so **`docs/exxat-ds/consumer-upgrade-checklist.md`** and Cursor skills match the tarball, and diff the host app against **`node_modules/@exxatdesignux/ui/template/`** for anything new to port (routes, re-exports, AGENTS). Use **`exxat-ui changelog`**, **`exxat-ui update`**, and **`exxat-ui doctor`** for CLI guidance.
 
 ---
 

package/consumer-extras/patterns/consumer-upgrade-checklist.md

@@ -0,0 +1,38 @@
+# Upgrading `@exxatdesignux/ui` (human + AI checklist)
+
+Use this after **`npm install @exxatdesignux/ui@…`** / **`pnpm add @exxatdesignux/ui@…`**. It is copied into **`docs/exxat-ds/`** when you run **`exxat-ui sync-extras`**, so Cursor and other tools can find it beside other DS pattern docs.
+
+## 1. See what changed
+
+| Source | Purpose |
+|--------|---------|
+| **`node_modules/@exxatdesignux/ui/CHANGELOG.md`** | Release notes for the installed version (and peers). |
+| **`npx --package=@exxatdesignux/ui@latest exxat-ui changelog`** | Print the changelog from the package on disk / npx extract. |
+
+## 2. Refresh AI / pattern docs (optional but recommended)
+
+```bash
+npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
+```
+
+Overwrites only **`.cursor/skills/exxat-*`** and **`docs/exxat-ds/*.md`** (including this file). Does **not** change your app routes or product code.
+
+## 3. Align app code with the reference template
+
+The npm package includes a full Next.js reference under:
+
+**`node_modules/@exxatdesignux/ui/template/`**
+
+Use it when you need to know **what files exist**, **how shims re-export** `@exxatdesignux/ui`, or **what AGENTS / layout** patterns look like for the current release. Porting is manual: diff template vs your repo and apply intentional changes (imports, new components, CSS entrypoints).
+
+## 4. Dependency and Node
+
+- Keep **`@exxatdesignux/ui`** on the same semver your team tested; prefer explicit **`^x.y.z`** or pinned **`x.y.z`**.
+- Match **`engines.node`** in your app to the value declared in **`node_modules/@exxatdesignux/ui/package.json`** (see CHANGELOG if it changed).
+
+## 5. Still stuck?
+
+- **`npx --package=@exxatdesignux/ui@latest exxat-ui doctor`** — compares local CLI version vs npm **`latest`**.
+- **`npx --package=@exxatdesignux/ui@latest exxat-ui update`** — install commands and reminders.
+
+Maintainers publish from the design-system monorepo with git tags **`ui-v<version>`**; registry **`latest`** follows those tags.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.2.11",
+  "version": "0.2.12",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "type": "module",
   "engines": {
@@ -50,6 +50,7 @@
     "create-exxat-app": "./bin/init.mjs"
   },
   "files": [
+    "CHANGELOG.md",
     "src",
     "bin",
     "template",