@matteoaliano/forest-ui 0.5.2 → 0.7.0

package/dist/theme.mjs

@@ -45,7 +45,7 @@ import {
   violet,
   warning,
   widths
-} from "./chunk-TECEHFAG.mjs";
+} from "./chunk-WUUQHE5X.mjs";
 export {
   alpha,
   avatarColors,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@matteoaliano/forest-ui",
-  "version": "0.5.2",
+  "version": "0.7.0",
   "description": "Forest Design System — themed MUI components",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -83,5 +83,14 @@
     "typescript": "^5.0.0"
   },
   "license": "MIT",
-  "sideEffects": false
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Witailer/wtl-design-system-forest.git",
+    "directory": "packages/forest-ui"
+  },
+  "bugs": {
+    "url": "https://github.com/Witailer/wtl-design-system-forest/issues"
+  },
+  "homepage": "https://github.com/Witailer/wtl-design-system-forest#readme"
 }

package/skills/forest-alkemy-plus/SKILL.md

@@ -3,7 +3,7 @@ name: forest-alkemy-plus
 description: Forest UI Design System rules for the Alkemy+ (charcoal/red) preset. Enforces correct imports, component usage, and theming with @matteoaliano/forest-ui. Use when the project uses forest-ui, forest-alkemy-plus preset, or when user builds UI components in a forest-ui project. Triggers on "forest", "forest-ui", "forest alkemy", "forest alkemy+", "@matteoaliano/forest-ui".
 metadata:
   author: Forest Design System
-  version: 0.5.2
+  version: 0.7.0
 ---
 
 # Forest UI — Alkemy+ Preset
@@ -75,7 +75,7 @@ import "@matteoaliano/forest-ui/fonts/alkemy-beta/alkemy-beta.css";
 
 **Charts:** BarChart, LineChart, PieChart, ScatterChart, Gauge, SparkLineChart, useChartColors, plus composition primitives (see components.md)
 
-See `references/components.md` for full API details and `references/patterns.md` for code examples.
+See `references/components.md` for full API details, `references/patterns.md` for code examples, and `references/upgrading.md` for update / re-sync guidance.
 
 ## Tooltip vs Popover
 

package/skills/forest-alkemy-plus/references/upgrading.md

@@ -0,0 +1,137 @@
+# Forest UI — Upgrading
+
+How to keep `@matteoaliano/forest-ui` and its peer dependencies up to date.
+
+## TL;DR
+
+```bash
+npm update @matteoaliano/forest-ui   # bump within the semver range
+npx @matteoaliano/forest-ui          # re-sync the Claude Code skill
+```
+
+That's it for routine minor/patch updates. For majors, read the changelog first.
+
+## Check the installed version
+
+```bash
+npm list @matteoaliano/forest-ui
+# → @matteoaliano/forest-ui@0.6.0
+```
+
+Or read it directly from `package.json`.
+
+## See available versions
+
+```bash
+npm view @matteoaliano/forest-ui versions --json | tail
+npm view @matteoaliano/forest-ui version           # latest
+```
+
+## Upgrade within the current semver range (minor / patch)
+
+```bash
+npm update @matteoaliano/forest-ui
+# pnpm update @matteoaliano/forest-ui
+# yarn upgrade @matteoaliano/forest-ui
+```
+
+This respects the `^` or `~` range in `package.json` and will **not** cross a major boundary.
+
+## Upgrade across a major (e.g. 0.x → 1.0)
+
+```bash
+npm install @matteoaliano/forest-ui@latest
+```
+
+**Before running**, check the changelog for:
+
+- Removed / renamed components
+- Prop name changes
+- Changed default variants (e.g. Button defaults)
+- Theme token renames
+- Peer-dependency bumps (MUI, Emotion)
+
+Commit your lockfile before upgrading so a rollback is one `git checkout` away.
+
+## Re-sync the Claude Code skill
+
+The skill ships **inside** the package and evolves with it. After every upgrade:
+
+```bash
+npx @matteoaliano/forest-ui
+```
+
+This refreshes `.claude/skills/forest-alkemy-plus/` with the latest component list, prop signatures, and patterns. **Skipping this step means Claude is working from stale rules** — it may recommend components that no longer exist or miss new ones.
+
+Automate it by wiring `postinstall`:
+
+```json
+{
+  "scripts": {
+    "postinstall": "forest-ui"
+  }
+}
+```
+
+Commit `.claude/skills/` so every teammate (and CI) gets the same snapshot.
+
+## Peer dependencies
+
+Forest UI has multiple peer deps — keep them aligned with the major the package was built against:
+
+```bash
+npm install @matteoaliano/forest-ui@latest \
+  @mui/material @mui/x-data-grid @mui/x-date-pickers @mui/x-charts \
+  @emotion/react @emotion/styled dayjs
+```
+
+If you see `UNMET PEER DEPENDENCY` warnings after an upgrade, the package expects a newer MUI / Emotion — bump them together, not individually. Running two different MUI majors in the same app breaks theming silently.
+
+Check what's required:
+
+```bash
+npm view @matteoaliano/forest-ui peerDependencies
+```
+
+## Verify the upgrade
+
+Quick checklist after bumping:
+
+- [ ] App builds (`npm run build` / `next build`)
+- [ ] No TypeScript errors on component props you use
+- [ ] No runtime console errors about missing theme tokens
+- [ ] `<ForestProvider>` still wraps the app root
+- [ ] Fonts still render (Aeonik / Aeonik Mono / Alkemy BETA)
+- [ ] Visual spot-check on one page per preset in use
+- [ ] `.claude/skills/forest-alkemy-plus/SKILL.md` `version` frontmatter matches the new package version
+
+## Rollback
+
+If something breaks and you need to revert:
+
+```bash
+git checkout -- package.json package-lock.json
+npm install
+npx @matteoaliano/forest-ui   # re-sync to restore older skill
+```
+
+Or pin to a known-good version explicitly:
+
+```bash
+npm install @matteoaliano/forest-ui@0.5.2
+```
+
+## When a breaking change affects your code
+
+1. **Read the error at face value.** MUI-layer errors usually point to the renamed prop or component.
+2. **Search the synced skill's `components.md`** — it's the authoritative component list for the installed version.
+3. **Don't shim.** Don't wrap deprecated components in custom adapters; update callsites directly. Shims accumulate and block the next upgrade.
+4. **If a component was removed**, the skill's `components.md` won't list it anymore — search the forest-ui CHANGELOG or the repo's Storybook for the replacement.
+
+## Never do this on upgrade
+
+- Don't skip `npx @matteoaliano/forest-ui` — stale skills are worse than no skills
+- Don't upgrade MUI separately from forest-ui — they're paired
+- Don't mix two forest-ui majors in a monorepo without a shared hoist
+- Don't suppress peer-dep warnings — they're the early signal for theme breakage
+- Don't commit `package.json` without `package-lock.json` — reproducibility breaks