pixelize-design-library 2.4.1 → 2.4.2-beta.0

package/.cursor/plans/current.theme-tokens-dark.md

@@ -1,155 +0,0 @@
-# Theme refactor → portable tokens + full dark mode + exported theme switcher
-
-## Complexity
-hard
-
-## Goal
-1. **Restructure theme into a pure, platform-agnostic token layer** (zero Chakra/React/CSS imports)
-   so the mobile design library can copy-paste it. Web-only Chakra binding lives separately.
-2. **Full dark mode** across every component (derived from each brand's existing colors).
-3. **Export** `PixelizeThemeProvider` + `useThemeMode()` + `<ThemeSwitcher/>` for consuming apps.
-4. Refactor/improve along the way (dedupe 7 identical brand theme files, types, a11y contrast).
-
-## Constraints (non-negotiable)
-- **Backward compatible — zero consumer rework.** No removed/renamed public exports, no changed
-  prop signatures. `pixelize-design-library` stays **2.x**.
-- **Light mode must stay pixel-identical.** Dark mode is purely additive.
-- **Keep existing internal import paths as re-export shims** — `Theme/useCustomTheme` (91 importers)
-  and `Theme/themeProps` (~20 importers) must not move.
-- Purity boundary: `Theme/tokens/**` must never import Chakra, React, or CSS.
-  (`fonts.ts` CSS side-effect + `common.ts` `cssVarPrefix` are web-only → stay in web layer.)
-
-## Phase checklist
-- [x] 1. Plan
-- [ ] 2a. Wave 0a — token restructure (serial)
-- [ ] 2b. Wave 0b — dark palettes + provider/hook/switcher (serial)
-- [ ] 2c. Wave 1 — component hex migration (PARALLEL, 17 disjoint families)
-- [ ] 3a/3b. Tests
-- [ ] 3d. Doc sync
-- [ ] 3c. PR readiness (lint + typecheck + test + build)
-- [ ] 4. Review gate
-- [ ] 5. Commit
-
-## Baseline
-- `npx tsc --noEmit` → **exit 0** (green before any change).
-- Branch: `develop`, clean tree. Package v2.3.21.
-
----
-
-## Architecture — the linchpin
-
-Components read **resolved hex strings** via `useCustomTheme()` and interpolate them:
-```tsx
-border={`0.063rem solid ${theme.colors.border?.[500]}`}
-```
-Chakra `semanticTokens` **cannot** work here (they only resolve as style-prop token names).
-
-**Therefore:** make `useCustomTheme()` **color-mode-aware** — it returns the dark palette when
-`colorMode === "dark"`. All **127** token-consuming files then flip to dark with **zero edits**.
-Remaining real work = the **22** files that hardcode hex.
-
-## Target structure
-
-```
-src/Theme/
-  tokens/                       ← PURE. zero Chakra/React/CSS. Copy-paste to mobile.
-    index.ts                    ← barrel (brands, primitives, builders, types)
-    types.ts                    ← PaletteProps, ThemeName, ColorMode
-    primitives/                 ← space, sizes, radii, shadows, zIndices,
-                                   breakpoints, lineHeights, letterSpacings, typography
-    builders/
-      buildBrandTokens.ts       ← moved (already pure)
-      buildDarkPalette.ts       ← NEW: pure light→dark derivation
-    brands/<brand>/palette.light.ts + palette.dark.ts   ← 7 brands
-  chakra/                       ← WEB-ONLY binding
-    createBrandTheme.ts         ← factory replacing 7 duplicated theme.ts
-    componentStyles.ts          ← moved
-    fonts.web.ts                ← CSS side-effect import + typography
-  provider/                     ← NEW
-    PixelizeThemeProvider.tsx, useThemeMode.ts, ThemeSwitcher.tsx, storage.ts
-  useCustomTheme.ts             ← KEEP PATH, now color-mode-aware
-  themeProps.ts                 ← KEEP PATH, re-export shim
-  index.ts, <Brand>/theme.ts, <Brand>/palette.ts   ← KEEP PATHS as shims
-```
-
-## Dark palette derivation (my call — "mix of existing theme colours")
-Pure `buildDarkPalette(lightPalette)`, applied to all 7 brands — **role-preserving inversion**:
-- **Surface/neutral/text/border scales** (`background`, `text`, `header`, `placeholder`, `border`,
-  `boxborder`, `table.hover`, `disabled`, `gray`): reverse the ramp (50↔900 …) so each index keeps
-  its semantic role but flips lightness. Because each brand's light ramps are already brand-tinted
-  (lavender's gray is violet-tinted), reversing yields **brand-tinted dark for free** — no invented hexes.
-- **Named surface keys** (`backgroundColor.{main,secondary,…,tableHeader}`): explicit dark anchors;
-  elevation goes **lighter** in dark (inverse of light mode).
-- **Brand/semantic** (`primary`, `secondary`, `tertiary`, `semantic.*`): keep hue; accessible accent
-  on dark shifts lighter.
-- **`boxShadow`**: deepen. **`sidebar`**: already dark in light mode → keep near-identical.
-- Verify WCAG AA contrast for text-on-surface pairs.
-
-## API contract (FROZEN)
-Additive exports from `src/index.ts` — nothing removed:
-```ts
-export { PixelizeThemeProvider } from "./Theme/provider/PixelizeThemeProvider";
-export { useThemeMode } from "./Theme/provider/useThemeMode";
-export { ThemeSwitcher } from "./Theme/provider/ThemeSwitcher";
-export type { ColorMode, ThemeName, PaletteProps } from "./Theme/tokens/types";
-// unchanged: default withTheme, useCustomTheme, ThemesList, all 73 components
-```
-```ts
-type ColorMode = "light" | "dark" | "system";
-useThemeMode(): {
-  mode: ColorMode;            // user selection
-  resolvedMode: "light"|"dark";// after system resolution
-  setMode(m: ColorMode): void;
-  toggle(): void;
-  brand: ThemeName;
-  setBrand(b: ThemeName): void;
-};
-<PixelizeThemeProvider brand? defaultMode? storageKey? disablePersistence?>
-<ThemeSwitcher variant?="icon"|"segmented"|"menu" showBrandPicker?=false />
-```
-- Persisted to localStorage; SSR-safe (no window access during render).
-- `withTheme` keeps working unchanged (delegates to the provider internally).
-
-## Wave plan (parallel/serial split)
-- **Wave 0a — SERIAL (orchestrator).** Token restructure + shims. Pure moves, zero behavior change.
-  Gate: `tsc --noEmit` exit 0.
-- **Wave 0b — SERIAL (orchestrator).** `buildDarkPalette`, 7 dark palettes, color-mode-aware
-  `useCustomTheme`, provider/hook/switcher, componentStyles `_dark`, exports.
-  Serial because every Wave-1 agent depends on this contract.
-- **Wave 1 — PARALLEL (17 disjoint families).** Migrate the 22 hex files → tokens.
-  *Proof of independence:* each agent owns exactly one `src/Components/<Family>/` folder; the sets are
-  pairwise disjoint; **no agent touches** `src/index.ts`, `src/Theme/**`, `src/withTheme.tsx`,
-  `src/App.tsx`, `src/Layout.tsx`, `src/global.css`, or any git/npm command. No new exports needed
-  (all 22 files are in already-exported components) → shared registry untouched.
-- **Wave 2 — SERIAL.** `global.css` dark, playground demo, docs, full verify.
-
-## Files — Wave 1 lanes (22 files / 17 families, pairwise disjoint)
-| Lane | Family | Files |
-|---|---|---|
-| 1 | UserDetails | UserDetails.tsx (16), DeactivateConfirmModal.tsx (3) |
-| 2 | OrganizationDetails | OrganizationDetails.tsx (16), DeleteOrgModal.tsx (2) |
-| 3 | OrgSwitcher | OrgSwitcher.tsx (13), OrgSwitcherProps.tsx (8) |
-| 4 | RolesPermission | RolesPermission.tsx (8), DeleteRoleModal.tsx (2) |
-| 5 | Toaster | Toaster.tsx (8) |
-| 6 | StageProgress | StageProgressProps.tsx (7) |
-| 7 | PdfViewer | PdfViewer.tsx (6) |
-| 8 | CustomModulesTable | CustomModulesTable.tsx (5), DeleteModuleModal.tsx (2) |
-| 9 | CopyButton | CopyButton.tsx (5) |
-| 10 | SignInActivityTable | SignInActivityTable.tsx (5) |
-| 11 | EmptyState | EmptyState.tsx (4) |
-| 12 | FilePreview | FilePreview.tsx (4) |
-| 13 | FieldSelectModal | FieldSelectModal.tsx (3) |
-| 14 | UpgradeButton | UpgradeButton.tsx (3) |
-| 15 | MoreItems | MoreItems.tsx (2) |
-| 16 | LazyWrapper | LazyWrapper.tsx (1) |
-| 17 | ToolTip | ToolTip.tsx (1) |
-
-## Risks
-- 38 **test/story** files assert hardcoded hex → may break when components move to tokens. Handled in 3a/3b.
-- `Switch.tsx` / `InputSwitch.tsx` already call `useColorModeValue` → will finally activate under the
-  provider; verify they look right in both modes.
-- `Theme/Default/palette` imported directly by 2 DatePicker tests → keep shim path.
-- Coverage thresholds are 80% global; new provider/builder code needs tests to hold the gate.
-
-## Files-changed manifest
-(updated as waves land)

package/.cursor/rules

@@ -1,31 +0,0 @@
-## Session start
-- Always read CLAUDE.md before starting any task
-- Always read MODULE.md before touching a component family (`.cursor/modules/<domain>/MODULE.md`)
-- Read one similar existing component before implementing
-- Never invent a new pattern if one already exists
-
-## Implementation
-- Components live in `src/Components/<Name>/`
-- Public API via `src/index.ts` only
-- Demo pages in `src/Pages/` for playground — not published
-- Never add CRM/app-specific API calls to library components
-- Use theme tokens from `src/Theme/` — no hardcoded brand colors
-- Add Jest tests for new behavior (`*.test.tsx`)
-- Keep changes minimal — no scope creep
-
-## Output quality
-- Never create placeholder files unless explicitly asked
-- Never use fake data, lorem ipsum, example.com, or demo seeds
-- Never leave TODO comments — implement fully or report blocked
-- Production-ready components with loading/error states where applicable
-
-## Branch rules
-- Always branch from **develop** — never from main
-- Feature work: `feature/<domain>-<short-description>`
-- Bug fixes: `fix/<domain>-<short-description>`
-- Never commit directly to main
-
-## Commit rules
-- Never commit without explicit user confirmation
-- Never run git push under any condition
-- Never add Cursor co-author lines

package/.cursor/skills/task/SKILL.md

@@ -1,167 +0,0 @@
----
-name: task
-description: >-
-  Runs the Pixelize Design Library dev pipeline: task-plan → fe-impl → test-create → test-exec → review gate → commit. Use when the user invokes @task, /task, or requests component library delivery.
-disable-model-invocation: true
----
-
-# Task Pipeline — Pixelize Design Library
-
-Single library repo **Micro-Components** (`pixelize-design-library`). Module docs: `.cursor/modules/<domain>/MODULE.md`.
-
-Run phases in order. Do not skip unless user opts out.
-
-```
-- [ ] 1. Task plan       (agent: task-plan)
-- [ ] 2. Implementation  (agents: fe-impl + be-impl, parallel when both needed)
-- [ ] 3a. Test creation  (agent: test-create)
-- [ ] 3b. Test execution (agent: test-exec)
-- [ ] 4. Review gate     (orchestrator — show diff, wait for user)
-- [ ] 5. Commit          (orchestrator only)
-```
-
----
-
-## Before Starting
-
-1. Read CLAUDE.md
-2. Confirm user goal — feat / fix / refactor / chore
-3. Tell user which phases apply
-
----
-
-## Phase 1 — Task Plan
-
-Agent: task-plan → `.cursor/agents/task-plan.md`
-
-- Read `.cursor/modules/<domain>/MODULE.md` for touched component families
-- Plan saved to `.cursor/plans/current.md`
-- If current.md already exists — read it first, user may be resuming
-
-Gate: do not start phase 2 until plan has concrete tasks.
-
----
-
-## Phase 2 — Implementation
-
-| Plan says | Action |
-|-----------|--------|
-| Library only | Invoke fe-impl only |
-| Both | Rare — fe-impl + test agents |
-
-Pass `.cursor/plans/current.md` to each agent.
-
-If blocked mid-task:
-- Save progress to `.cursor/plans/blocked/<task-name>.md` with exact blocker details
-- Stop pipeline and report to user
-
-Gate: all required agents must report Done or Blocked before phase 3.
-
----
-
-## Phase 3 — Tests
-
-3a: test-create → `.cursor/agents/test-create.md`
-3b: test-exec → `.cursor/agents/test-exec.md`
-
-Jest: `npm test` from repo root.
-
-Gate: do not proceed to review if tests failed and not explicitly waived by user.
-
----
-
-## Phase 4 — Review Gate
-
-```bash
-git status
-git diff
-git diff --staged
-git log -5 --oneline
-```
-
-Run git status/diff. STOP and wait for user approval.
-
-```
-CHANGES READY TO COMMIT
-
-Backend:
-- path/to/file — what changed
-
-Frontend:
-- path/to/component — what changed
-
-Tests:
-- path/to/test — what it covers
-
-MODULE.md updates:
-- path/to/MODULE.md
-
-Excluded:
-- none
-```
-
-STOP. Wait for: "yes" / "commit" / "looks good" / "go ahead"
-
-
-## Phase 5 — Commit
-
-### Commit message format
-
-```
-<type>(<module>): <concise imperative title>
-
-Backend:
-- <specific change — file context>
-
-Frontend:
-- <specific change — file context>
-
-Tests:
-- <what is covered and where>
-
-Config:
-- <migrations, registry changes, config updates>
-```
-
-### Commit steps
-
-1. Scan diff — if .env or secrets found, warn user and ask if they want to include. Commit only on confirmation.
-2. git add relevant files — state any exclusions clearly
-3. git commit using HEREDOC — never add Cursor attribution lines
-4. If Cursor injects co-author lines — amend immediately if unpushed
-5. Verify: git status + git log -1 --format=full
-6. Show commit hash to user
-7. Move `.cursor/plans/current.md` → `.cursor/plans/done/<YYYY-MM-DD>-<title>.md`
-
-Never run git push under any condition.
-
-### Commit safety
-
-- Never --no-verify unless user explicitly requests
-- Never force-push any branch
-- Nothing staged → skip commit, report clearly
-
----
-
-## Final Report
-
-| Phase    | Status         | Notes                             |
-| -------- | -------------- | --------------------------------- |
-| 1 Plan   | done / skipped | saved to .cursor/plans/current.md |
-| 2 Impl   | fe / be / both | done / blocked                    |
-| 3 Tests  | create / exec  | pass / fail / blocked             |
-| 4 Review | approved       | confirmed by user                 |
-| 5 Commit | done / skipped | hash if committed                 |
-
----
-
-## User Opt-outs
-
-| User says     | Effect                                    |
-| ------------- | ----------------------------------------- |
-| "plan only"   | Stop after phase 1                        |
-| "no tests"    | Skip phase 3 — confirm with user first    |
-| "no commit"   | Stop after phase 4 review                 |
-| "commit only" | Phase 4+5 only — still show diff and wait |
-| "skip review" | Go straight to commit — confirm with user |
-

package/CLAUDE.md

@@ -1,148 +0,0 @@
-# Pixelize Design Library — Agent Guide
-
-Rules for AI assistants working in **Micro-Components** (npm: `pixelize-design-library`).
-
-## 1. App name and purpose
-
-**Pixelize Design Library** — shared React UI component library and theme system for all Pixelize frontends. Published to npm; local Vite playground demos components in `src/Pages/`.
-
-## 2. Stack
-
-| Layer         | Technology                          | Version        |
-| ------------- | ----------------------------------- | -------------- |
-| Framework     | React + TypeScript                  | 18.3.1 / 5.9.3 |
-| UI base       | Chakra UI + Emotion + Framer Motion | 2.8.2          |
-| Build         | `tsc` → `dist/` + CSS copy          | —              |
-| Dev           | Vite playground                     | 6.2.0          |
-| Styling       | Tailwind + global CSS               | 3.4.17         |
-| Tests         | Jest + Testing Library              | 29.7.0         |
-| Package       | `pixelize-design-library`           | 2.2.x          |
-
-Not a monorepo — single package, one `package.json`.
-
-## 3. Repo relationship
-
-| Repo / package              | Role                                              |
-| --------------------------- | ------------------------------------------------- |
-| **Micro-Components** (here) | Source of `pixelize-design-library` npm package   |
-| **crm-frontend**            | Consumer — `npm run pixelize` to update           |
-| **account-frontend**        | Consumer                                          |
-| **social-frontend**         | Consumer                                          |
-| **tickets-frontend**        | Consumer                                          |
-| **crm-mobile**              | Consumer (native-base overlap — check mobile)     |
-| **pixelize-authenticator**  | Companion auth UI package (separate repo)         |
-
-No backend API in this repo. Demo pages may call dev APIs for playground only.
-
-## 4. Folder structure (2 levels)
-
-```
-Micro-Components/
-├── package.json, tsconfig.json, vite.config.ts
-├── src/
-│   ├── index.ts              public exports (~110)
-│   ├── withTheme.tsx         legacy HOC wrapper (light-only, unchanged)
-│   ├── Components/           73 component families
-│   ├── Theme/
-│   │   ├── tokens/           PURE, platform-agnostic — shared with the mobile lib
-│   │   │   ├── types.ts      PaletteProps, ThemeName, ColorMode
-│   │   │   ├── primitives/   space, sizes, radii, shadows, typography, …
-│   │   │   ├── builders/     buildDarkPalette, buildBrandTokens, color math
-│   │   │   └── brands/<brand>/palette.light.ts + palette.dark.ts   (7 brands)
-│   │   ├── chakra/           WEB-ONLY binding (createBrandTheme, componentStyles, fonts)
-│   │   ├── provider/         PixelizeThemeProvider, useThemeMode, ThemeSwitcher
-│   │   ├── useCustomTheme.ts hook used by ~127 components
-│   │   └── index.ts          ThemesList (light) + brandThemes (light+dark)
-│   ├── Pages/                49 Vite demo/playground pages
-│   ├── Utils/, Hooks/, services/, types/
-│   └── App.tsx, Layout.tsx   playground shell
-├── dist/                     publish output (gitignored)
-└── .cursor/modules/          MODULE.md per component domain (22 domains)
-```
-
-### Theme rules (read before touching color)
-
-- **`Theme/tokens/**` must never import Chakra, React, or CSS.** It is copy-paste portable to the
-  mobile design library; one CSS/Chakra import breaks that. Web-only concerns (the Inter font-face
-  import, Chakra's `cssVarPrefix`) live in `Theme/chakra/`.
-- **Dark mode works by swapping which palette the theme carries** — not via `_dark`/`semanticTokens`.
-  `componentStyles` variants are functions of `({ theme })` and `useCustomTheme()` reads
-  `theme.colors`, so both follow the active palette automatically.
-- **Never hardcode a hex in a component.** Read tokens from `useCustomTheme()`, or the component
-  will be stuck in light mode.
-- **`colors.white` is a foreground token** (the label on a filled button) and stays white in dark.
-  For a white *surface* use `colors.background[50]` — identical `#ffffff` in light, dark-aware.
-- Dark palettes are **derived** (`buildDarkPalette`) from each brand's own light palette, so brand
-  hue carries through. Override per brand in that brand's `palette.dark.ts` if ever needed.
-- `withTheme` stays **light-only** so existing apps are visually unchanged; dark is opt-in via
-  `PixelizeThemeProvider` (defaults to `system`).
-
-## 5. Dev commands
-
-```bash
-npm start              # Vite playground
-npm run build          # tsc + copy CSS → dist/
-npm test               # Jest
-npm run test:watch
-npm run remove         # strip dev artifacts from dist before publish
-npm run package        # version patch + build + publish
-```
-
-## 6. Module / component pattern
-
-Follow the **Table** or **KanbanBoard** pattern for complex components:
-
-| Step | Path |
-| ---- | ---- |
-| Component | `src/Components/<Name>/` |
-| Subcomponents | `src/Components/<Name>/Components/` or nested folders |
-| Props/types | `<Name>Props.ts` or colocated types |
-| Tests | `*.test.tsx` next to component |
-| Stories | `*.stories.tsx` (where present) |
-| Demo page | `src/Pages/<name>.tsx` |
-| Public export | add to `src/index.ts` |
-| Module doc | `.cursor/modules/<domain>/MODULE.md` |
-
-Read `.cursor/modules/<domain>/MODULE.md` before touching a component family.
-
-## 7. Publishing integration
-
-- **Exports:** every public component must be exported from `src/index.ts`
-- **Peers:** React 18, Chakra, Emotion — consumers install alongside library
-- **Build:** `npm run build` compiles to `dist/`; never edit `dist/` directly
-- **Version:** patch releases via `npm run package`; CI publishes on merge to `develop`
-- **Breaking changes:** require version bump + consumer update in frontends
-
-## 8. Checklist — adding a new component
-
-1. Read similar component + `.cursor/modules/<domain>/MODULE.md`
-2. Create `src/Components/<Name>/` with component + props
-3. Add demo page in `src/Pages/` if needed
-4. Export from `src/index.ts`
-5. Add Jest tests (`*.test.tsx`)
-6. Update `.cursor/modules/<domain>/MODULE.md`
-7. Verify playground: `npm start`
-8. After merge to develop: consumers run `npm run pixelize` in their frontend
-
-## 9. Do
-
-- Match existing Chakra + design token patterns in `src/Theme/`
-- Keep components framework-agnostic where possible (props in, events out)
-- Add tests for new behavior
-- Use `useCustomTheme` / theme tokens — no hardcoded brand colors
-- Branch from **feature/cursor-ai-setup** or **develop**
-
-## 10. Don't
-
-- Don't add app-specific business logic (CRM entities, API calls) to library components
-- Don't break existing exports without semver major bump
-- Don't edit `dist/` — always change `src/` and rebuild
-- Don't skip `index.ts` export for public components
-- Don't introduce a second component pattern without team agreement
-- Don't commit npm tokens or `.env` secrets
-
-## Task pipeline
-
-- **Feature work:** invoke via **`/` menu → `task`** (not by typing `/task` in the message).
-- Cross-repo: **`/ → design-task**`.
-- One-time status line + hook details: [.cursor/TASK-SETUP.md](.cursor/TASK-SETUP.md).

package/__mocks__/styleMock.js

@@ -1,8 +0,0 @@
-/**
- * Stub for CSS/SCSS imports under Jest (see `moduleNameMapper` in package.json).
- *
- * jest.moduleNameMapper has always referenced this file, but it did not exist — no test
- * imported a stylesheet (even transitively) until the public-API guard began importing
- * `src/index.ts`, which pulls in the Inter font-face CSS via the theme.
- */
-module.exports = {};