pixelize-design-library 2.4.2-beta.42 → 2.4.2-beta.44

package/DESIGN-GUIDE.md

@@ -0,0 +1,210 @@
+# Pixelize Design Guide — how to design a page with `pixelize-design-library`
+
+For any developer or LLM building UI in a consumer app. `COMPONENT-GOTCHAS.md` (next to this file)
+says **which component does what**; this file says **how to compose them into a page that looks
+designed**. Read both before building a screen. Everything here is copyable as-is.
+
+**App conventions win.** If the app has its own density/size file (hrms `core/layout/density.ts`,
+tickets `layoutDensity.ts`), use it — it encodes these same rules. Otherwise the library's
+`PageHeader`, `StatCard` and `QueryStateBoundary` already do.
+
+## 1. The look
+
+Calm, dense, professional SaaS admin — Linear/Stripe-dashboard, not a landing page.
+
+- **Hierarchy comes from type and whitespace, not boxes.** One border per surface. Never nest a
+  bordered card inside a bordered card; inside a card, separate with spacing or a `Divider`.
+- **One primary action per view.** One `variant="solid"` button in the page header; everything
+  else `outline` or `ghost`. The only exception is a composer's Send button.
+- **Left-aligned, scannable.** Titles and forms left-aligned; numbers right-aligned in tables.
+- **Color means something.** Neutral by default; brand color for the primary action and selection;
+  semantic color only for status. No decorative gradients, no colored section backgrounds.
+- **Borders, not shadows, for resting surfaces.** Shadows only on floating things (menus, popovers,
+  modals) and on hover of a card that is itself clickable.
+
+## 2. Spacing (Chakra units, 1 = 4px)
+
+| Where | Value |
+| --- | --- |
+| Page padding | `px={{ base: 4, md: 6 }} py={{ base: 4, md: 5 }}` |
+| Between page sections | `gap={5}` (a `Flex direction="column"`) |
+| Between cards in a grid | `gap={4}` |
+| Inside a card | `Card`'s own padding — don't add more; `bodyProps={{ p: 0 }}` for edge-to-edge content |
+| Between form fields | `gap={4}` vertical, `gap={3}` side by side |
+| Inline clusters (tags, meta, icon + text) | `gap={1.5}`–`gap={2}` |
+| Page header → content | the section gap (`gap={5}`) — no extra margin |
+
+Never raw `px` strings (`"13px"`, `"18px"`) for spacing or size; never `margin` hacks to align.
+Borders are the one px value: `borderWidth="1px"`. Fixed widths (side panel, list pane) in `rem`: `templateColumns={{ base: "1fr", lg: "minmax(0, 1fr) 20rem" }}`.
+
+## 3. Type
+
+| Role | Props |
+| --- | --- |
+| Page title + subtitle | `PageHeader` (`lg`/600 h1, `sm` muted subtitle) — don't hand-build it |
+| Section / card title | `Heading as="h2" fontSize="md" fontWeight={600} color={colors.header[900]}`, in `Card`'s `header` prop |
+| Body | `Text fontSize="sm" color={colors.text[800]}` |
+| Label / meta / helper | `Text fontSize="xs" color={colors.textMuted}` |
+| KPI tile | `StatCard` — pass `trend` and `goodDirection`; the delta is green when the change is *good* (a shorter sales cycle is green) |
+| Numbers in tables/columns | `sx={{ fontVariantNumeric: "tabular-nums" }}` so digits align; `Table` columns take `align: "end"` |
+| Overline (rare) | `fontSize="xs" fontWeight={600} textTransform="uppercase" letterSpacing="0.06em"` |
+
+Chakra size keys only (`xs sm md lg xl 2xl`) — never `fontSize="14px"`, never below `xs`.
+Weights: 400 body, 500 labels, 600 titles, 700 KPI numbers only.
+
+## 4. Color — pick by role
+
+`const { colors } = useCustomTheme();` Never a hex, never `gray.500`/`blue.600` literals — those
+stay light in dark mode.
+
+| Need | Token |
+| --- | --- |
+| Page canvas | `colors.backgroundColor.base` |
+| Card / panel surface | `colors.background[50]` |
+| Your own overlay (popover, panel, `ModalContent bg=`) | `colors.surfaceRaised` — divider inside it `raisedRule(colors)` |
+| Subtle inset (toolbar strip, hovered row, code) | `colors.backgroundColor.secondary` |
+| Border / divider | `colors.boxborder[200]` |
+| Heading ink | `colors.header[900]` |
+| Body ink | `colors.text[800]` |
+| Secondary text, icons | `colors.textMuted` |
+| Brand-colored text/link | `colors.accentText` — never `primary[500]` |
+| Status text/icon | `colors.semanticText.success \| error \| warning \| info` |
+| Status chip | `<Tag label="Won" colorScheme="green" />` (subtle, `sm` by default) — never a painted `Box`. Tone → `colorScheme`: success `green`, warning `orange`, error `red`, info `blue`, neutral `gray` |
+| Selectable list row (inbox, picker) | `listRowBackgrounds(colors)` for hover/selected + `sx={focusVisibleStyles(colors)}`; pad the list `p={2}` so the ring isn't clipped |
+| Any filled surface you paint | `resolveFilledSurface(colors.<scale>, colors)` → `{ fill, color }` |
+| Icon tint chip, avatar tint | `bg={colors.primary.opacity[8]}` + `color={colors.accentText}` (`opacity` exists on `primary`/`secondary`/`tertiary` only) |
+
+**`Tag` — pick `variant` and `colorScheme`/`tone` deliberately, or two chips read as the same thing:**
+
+| Need | Use |
+| --- | --- |
+| Status (draft, active, error, in review, …) | `tone="neutral\|info\|success\|warning\|error"` — wins over `colorScheme` when both are set |
+| Category, label or filter (not a state) | `colorScheme` alone — brand (`primary`/`secondary`/`tertiary`) or a utility scale; never `tone` for a non-status label |
+| Default, everyday chip | `variant="subtle"` (the default) — low-emphasis, sits on any surface |
+| Must stand out (a status that needs attention) | `variant="solid"` |
+| Dense list, table cell, or an already-colored surface | `variant="outline"` — no fill to compete with the surface |
+
+`secondary` and `tertiary` render as the same hex on most brands (see `COMPONENT-GOTCHAS.md`) —
+don't lean on that pair to distinguish two categories; reach for a utility scheme instead.
+
+## 5. Controls — one scale, `sm` by default
+
+Every control shares one height scale — `xs` 24px · `sm` 32px · `md` 40px · `lg` 48px — and
+**defaults to `sm`**: `Button`, `TextInput`, `InputTextArea`, `NumberInput`, `Select`, `Search`,
+`RangeSlider`, the `DatePicker` family and `SegmentedControl`. So on a desktop page **don't pass `size`**; controls
+side by side line up. Nothing in a toolbar or table row is taller than the fields beside it.
+
+| Button role | Props |
+| --- | --- |
+| Primary (one per view) | `variant="solid" colorScheme="primary"` |
+| Secondary | `variant="outline" colorScheme="gray"` |
+| Tertiary / toolbar / row action | `variant="ghost" colorScheme="gray"` |
+| Destructive (confirm step only) | `<AlertDialog tone="danger" confirmButtonText="Delete" … />` — red Confirm, neutral Cancel |
+| Busy | `isLoading` — spinner only, width kept; add `loadingText` only if words must show |
+
+Icons: `lucide-react` only, `size={16}` in controls, `size={14}` inline with `xs` text. Every
+icon-only button gets an `aria-label` and a `ToolTip`. Inline or panel busy indicator: `Spinner`
+(themed; never Chakra's raw one).
+
+**Labels:** use each field's own `label` / `helperText` / `errorMessage` — never wrap a library
+input in `FormControl` + `FormLabel`. In a settings row (title + description left, control right)
+the row title is the label: `<Text as="label" htmlFor={id}>` pointing at the field's `id`.
+
+## 6. Page anatomy
+
+```
+┌ Page header ─ title + subtitle ─────────────── secondary · secondary · PRIMARY ┐
+├ Toolbar ── search · filters ───────────────────────────── view toggle · count ─┤
+│ Content ── table / card grid / form sections                                    │
+└─────────────────────────────────────────────────────────────────────────────────┘
+```
+
+```tsx
+<Flex direction="column" gap={5} px={{ base: 4, md: 6 }} py={{ base: 4, md: 5 }}>
+  <PageHeader
+    title="Deals"
+    subtitle="248 open · $1.2M pipeline"
+    actions={<>
+      <Button variant="outline" colorScheme="gray" label="Export" />
+      <Button variant="solid" colorScheme="primary" label="New deal" />
+    </>}
+  />
+  <QueryStateBoundary isLoading={isLoading} error={error} onRetry={refetch}
+    isEmpty={deals.length === 0} empty={{ icon: Handshake, title: "No deals yet" }}>
+    {() => <DealsTable deals={deals} />}
+  </QueryStateBoundary>
+</Flex>
+```
+
+`PageHeader` also takes `breadcrumbs`, `leading` (avatar), `titleAddon` (status `Tag`), `meta` (icon
+row) and `tabs` — a record page's whole header. KPI rows are a `SimpleGrid` of `StatCard`s; card
+sections are `Card` with the title in `header`.
+
+| Pattern | Component — don't hand-build it |
+| --- | --- |
+| Toolbar: search · filters · active-filter chips · count · actions | `FilterBar` (`search`, children, `activeFilters` + `onRemoveFilter`/`onClearAll`, `summary`, `actions`) |
+| Read-only label/value grid (record details, key facts) | `DescriptionList` (`items`, `columns`, `layout="inline"` for a side panel, `copyable`, `isLoading`) |
+| Settings row (title + description left, control right) | `SettingRow` inside a `SettingsSection` (`isDanger` for the danger zone, `action` for a header-right button) |
+| A person: avatar + name (+ role/email, presence, remove) | `PersonChip` (`orientation="vertical"` for a stacked profile block) |
+| An avatar on its own, or a stack of them | `Avatar` / `AvatarGroup` — never pick the fill, it is derived from `name` |
+| Unsaved-changes bar | `SaveBar isOpen={isDirty} onSave onDiscard isSaving` |
+| Previewing an attachment (image, video, audio, PDF, Office, text, archive) | `MediaViewer` (`items`, `isOpen`, `onClose`) — omit `index` and it owns navigation itself |
+| Notification tray | `NotificationBell` (badge, needs `aria-label`) opening a `NotificationPanel` (zones, filters, all four states) |
+| Confirm that needs the name typed to arm it | `ConfirmDialog confirmationText="delete-me"` — `onConfirm` does **not** close; call `onClose` yourself |
+| Scrim over the page or one panel while something runs | `Backdrop open loader` — `variant="dim"` by default. Add `container` to scope it to the nearest positioned ancestor, `allowBackgroundInteraction` to let clicks through, `onClick` to dismiss |
+
+**Reach for `Backdrop` in new work** — the `dim` scrim (black at 0.5, no blur, 225ms in /
+195ms out) replaces every hand-rolled `position: fixed` overlay. Never build your own
+scrim `Box`. `Loading` is the older API and stays on the heavier house scrim by default; pass
+`variant="dim"` to route it through `Backdrop`, or just use `Backdrop` directly.
+
+## 7. Every page has four states
+
+Design all four, not just the happy path.
+
+`QueryStateBoundary` picks one per content region (loading > error > empty > data). Pass `children`
+as a function when it reads data that may still be undefined.
+
+| State | Render |
+| --- | --- |
+| Loading | `loadingFallback` of `Skeletons` shaped like the content (rows, cards, `StatCard isLoading`) — never a lone centered `Spinner` for a page |
+| Empty (first run) | `empty={{ icon, title, description, action }}` — the primary action as `action` |
+| Empty (filtered) | `EmptyState size="sm"` "No results for these filters" + a ghost "Clear filters" button |
+| Error | `ErrorState` (the boundary's `errorTitle`/`errorDescription`/`onRetry`): what failed + an outline "Retry" (+ `action` "Back to …" on a detail page) |
+
+Page header stays visible in every state; only the content region swaps. Keep **one solid button
+on screen**: when the whole page is empty, the `EmptyState` action is the solid one and the header
+hides its primary; when only one section is empty on a populated page, that section's action is
+`outline`. Header actions that need data (Export, bulk actions) are disabled outside the data state.
+
+## 8. Never
+
+- Hex colors, Chakra color literals, `px` font sizes, inline `style={{}}` for theme concerns.
+- Raw `@chakra-ui/react` imports — layout primitives (`Box`, `Flex`, `Grid`, `Heading`, `Text`,
+  `Menu`…) come from `pixelize-design-library` too. Anything the library owns a component for
+  (`Tabs`, `Accordion`, `Modal`, `Card`, `Select`, `TextInput`, `Skeletons`…) has no Chakra
+  passthrough at all — the owned component is the only one.
+- Reaching for `SelectV2`, `SearchSelect`, `SelectSearch` in new work — all `@deprecated`.
+  One picker now: `Select` (`native={false}` for the themed, searchable, multi popup).
+  `Dropdown` is the exception — it is an action menu, not a picker, and is not replaced.
+- A bordered card inside a bordered card; a shadow on a resting card.
+- Painting a whole table cell with a status color — use a `Tag` in the cell.
+- Centered page titles, hero-sized headings, `size="lg"` buttons, or `size` props restating the default.
+- More than one solid button in a view; a destructive action without `AlertDialog`.
+- A page with only the data state.
+
+## 9. Reference pages
+
+Full screens built only from library exports, each with all four states, live in the library
+playground's **Page examples** section (source: `src/Pages/examples/` in the Micro-Components repo —
+not shipped in this package). Start from the closest one:
+
+| Screen you're building | Reference | Shows |
+| --- | --- | --- |
+| Dashboard / overview | `dashboard.tsx` | `StatCard` row, chart `Card`, stage list with `ProgressBar`, task list, `QueryStateBoundary` |
+| List of records | `records.tsx` | saved views, `FilterBar`, `Table` (`isGlobalSearch={false}`, `Tag` cells), bulk actions, `AlertDialog tone="danger"`, create `Drawer` |
+| One record | `recordDetail.tsx` | `PageHeader` with breadcrumbs/avatar/meta, `Tabs` (declarative `items` with `count` badges), `DescriptionList` (grid + inline side panel), `Timeline` (per-event `icon`/`description`), `ErrorState` + back |
+| Settings / long form | `settings.tsx` | section nav, `SettingsSection` + `SettingRow`, `SaveBar`, danger zone |
+| Board | `pipeline.tsx` | `KanbanBoard` with custom cards and column totals (`height`/`maxH` to size it) |
+| Inbox / master–detail | `inbox.tsx` | selectable list rows, conversation pane, composer, mobile list↔detail |
+

package/README.md

@@ -6,6 +6,8 @@ A comprehensive React component library built with TypeScript, providing a rich
 > [COMPONENT-GOTCHAS.md](./COMPONENT-GOTCHAS.md) first — it documents known silent-failure traps
 > and which near-duplicate component to pick for what. It ships with this package, so it's
 > available at `node_modules/pixelize-design-library/COMPONENT-GOTCHAS.md` too.
+> Building a whole screen? [DESIGN-GUIDE.md](./DESIGN-GUIDE.md) (also shipped) covers page anatomy,
+> spacing, type, color roles and the four page states.
 
 ## Features
 
@@ -26,18 +28,34 @@ Before you begin, ensure you have the following installed:
 
 ## Installation
 
-Install the library and its peer dependencies:
+Install the library, then its peer dependencies:
 
 ```bash
-npm install pixelize-design-library pixelize-authenticator
+npm install pixelize-design-library
 ```
 
-or with yarn:
-
 ```bash
-yarn add pixelize-design-library pixelize-authenticator
+npm install @chakra-ui/react@^2.8.2 @emotion/react@^11.11.4 @emotion/styled@^11.11.5 framer-motion@^10.18.0
+```
+
+`react` and `react-dom` are peers pinned to `^18.3.1`. **React 19 is not supported** — the pin
+tracks Chakra 2.8.
+
+### Versioning — pin a beta exactly
+
+Two dist-tags are published: `latest` (stable) and `beta` (the active feature line).
+
+**On a `beta` version, pin the exact version — never a caret range.** `^2.4.2-beta.43` is
+satisfied by the stable `2.4.2` the moment it publishes, so a routine `npm install` silently
+swaps a newer prerelease for an older stable build with no warning.
+
+```json
+"pixelize-design-library": "2.4.2-beta.43"
 ```
 
+What changed in each release, and what is staged to break in the next major:
+[CHANGELOG.md](CHANGELOG.md).
+
 ## Quick Start
 
 ```tsx
@@ -49,7 +67,7 @@ function App() {
     <div>
       <Card>
         <TextInput placeholder="Enter your name" />
-        <Button variant="primary">Submit</Button>
+        <Button variant="solid" colorScheme="primary">Submit</Button>
       </Card>
     </div>
   );
@@ -100,6 +118,7 @@ Full rules for app developers and AI assistants: [`src/Theme/THEME-CONTRACT.md`]
 - **PinInput** - PIN/OTP input component
 - **RadioButton** - Radio button input
 - **RadioButtonGroup** - Group of radio buttons
+- **RangeSlider** - Single or dual-thumb slider with tick marks
 - **Search** - Search input component
 - **SearchSelect** - Searchable select dropdown
 - **Select** - Single selection dropdown
@@ -110,6 +129,7 @@ Full rules for app developers and AI assistants: [`src/Theme/THEME-CONTRACT.md`]
 
 ### Data Display
 - **Table** - Data table component
+- **MediaViewer** - Full-screen viewer for images, video, audio, PDF, Office, text and archives
 - **Timeline** - Timeline visualization
 - **Skeletons** - Loading skeleton components
 - **ProgressBar** - Progress indicator
@@ -119,13 +139,18 @@ Full rules for app developers and AI assistants: [`src/Theme/THEME-CONTRACT.md`]
 - **ApexPieChart** - Pie chart component
 
 ### Feedback & Status
-- **AlertDialog** - Alert dialog component *(New)*
+- **AlertDialog** - Confirm dialog for destructive actions
+- **ConfirmDialog** - Cancel/Confirm prompt, with optional typed confirmation
+- **NotificationBell** - Badge/bell button
+  - **NotificationPanel** / **NotificationList** / **NotificationItem** - the tray, its body and one row
 - **Loading** - Loading spinner component
+- **Spinner** - Themed inline spinner
 - **Toaster** - Toast notification system
   - **useToaster** - Hook for toast management
 - **ToolTip** - Tooltip component
 
 ### User & Profile
+- **Avatar** / **AvatarGroup** - Fill derived from `name`, so it follows brand and dark mode
 - **ProfileCard** - User profile card
 - **ProfilePhotoViewer** - Profile photo viewer
 - **VerifyEmailOtp** - Email verification component
@@ -143,12 +168,8 @@ import { Button } from 'pixelize-design-library';
 function MyComponent() {
   return (
     <div>
-      <Button variant="primary" size="medium">
-        Primary Button
-      </Button>
-      <Button variant="secondary" size="large">
-        Secondary Button
-      </Button>
+      <Button variant="solid" colorScheme="primary">Primary Button</Button>
+      <Button variant="outline" colorScheme="gray">Secondary Button</Button>
     </div>
   );
 }
@@ -157,6 +178,7 @@ function MyComponent() {
 ### Form with Validation
 
 ```tsx
+import { useState } from 'react';
 import { TextInput, Button, Card } from 'pixelize-design-library';
 
 function LoginForm() {
@@ -169,17 +191,17 @@ function LoginForm() {
         label="Email"
         type="email"
         value={email}
-        onChange={setEmail}
+        onChange={(e) => setEmail(e.target.value)}
         required
       />
       <TextInput
         label="Password"
         type="password"
         value={password}
-        onChange={setPassword}
+        onChange={(e) => setPassword(e.target.value)}
         required
       />
-      <Button variant="primary" type="submit">
+      <Button variant="solid" colorScheme="primary" type="submit">
         Login
       </Button>
     </Card>
@@ -193,14 +215,15 @@ function LoginForm() {
 import { Table } from 'pixelize-design-library';
 
 const columns = [
-  { key: 'name', title: 'Name' },
-  { key: 'email', title: 'Email' },
-  { key: 'role', title: 'Role' }
+  { id: 'name', label: 'Name' },
+  { id: 'email', label: 'Email' },
+  { id: 'role', label: 'Role' }
 ];
 
+// every row needs a unique id
 const data = [
-  { name: 'John Doe', email: 'john@example.com', role: 'Admin' },
-  { name: 'Jane Smith', email: 'jane@example.com', role: 'User' }
+  { id: 1, name: 'John Doe', email: 'john@example.com', role: 'Admin' },
+  { id: 2, name: 'Jane Smith', email: 'jane@example.com', role: 'User' }
 ];
 
 function DataTable() {
@@ -208,8 +231,8 @@ function DataTable() {
     <Table
       columns={columns}
       data={data}
-      pagination
-      searchable
+      paginationMode="client"
+      isGlobalSearch
     />
   );
 }
@@ -217,8 +240,8 @@ function DataTable() {
 
 ## Theming
 
-The library ships **7 brand themes** (`lavender`, `meadow`, `radiant`, `skyline`, `slate`,
-`emerald`, `rosewood`), each with a **light and a dark palette**.
+The library ships **9 brand themes** (`lavender`, `meadow`, `radiant`, `skyline`, `slate`,
+`emerald`, `rosewood`, `storefront`, `zinc`), each with a **light and a dark palette**.
 
 ### Existing apps (unchanged)
 
@@ -360,7 +383,9 @@ module.exports = { transpilePackages: ['pixelize-design-library'] };
 
 `npm start` runs a local component explorer on `http://localhost:5173` — every exported
 component on its own page, with live variants, an interactive playground for editing props,
-and a generated props reference.
+and a generated props reference. The **Page examples** section shows full screens (dashboard,
+records list, record detail, settings, pipeline, inbox) built only from library exports, each with
+its loading, empty and error states.
 
 ```bash
 npm install

package/dist/Components/Accordion/Accordion.js

@@ -6,7 +6,8 @@ const react_2 = require("@chakra-ui/react");
 const lucide_react_1 = require("lucide-react");
 const useCustomTheme_1 = require("../../Theme/useCustomTheme");
 const accentText_1 = require("../../Theme/tokens/builders/accentText");
-const outlineRung_1 = require("../../Theme/tokens/builders/outlineRung");
+const motion_1 = require("../../Theme/tokens/primitives/motion");
+const motion_2 = require("../../Theme/chakra/motion");
 const accordionColors_1 = require("./accordionColors");
 /** Chakra Accordion wrapper for header/content pairs; FilterSidebar composes this directly for its collapsible filter sections. */
 const Accordion = ({ allowMultiple, allowToggle, index, onChange, reduceMotion, items, ...rest }) => {
@@ -16,21 +17,18 @@ const Accordion = ({ allowMultiple, allowToggle, index, onChange, reduceMotion,
     const headingColor = colors.text[800];
     const bodyColor = colors.text[600];
     const { expandedBg, softHover } = (0, react_1.useMemo)(() => (0, accordionColors_1.getAccordionHoverColors)(colors, isDark), [colors, isDark]);
-    const focusRing = (0, react_1.useMemo)(() => (0, outlineRung_1.liftToContrast)(colors.primary[300], colors.background[50], outlineRung_1.AA_NON_TEXT), [colors]);
+    const focusRing = (0, react_1.useMemo)(() => (0, accordionColors_1.accordionFocusRing)(colors), [colors]);
     return ((0, jsx_runtime_1.jsx)(react_2.Accordion, { allowMultiple: allowMultiple, allowToggle: allowToggle, index: index, onChange: onChange, reduceMotion: reduceMotion, ...rest, children: items.map((item, idx) => {
             var _a;
-            return ((0, jsx_runtime_1.jsx)(react_2.AccordionItem, { border: `0.063rem solid ${border}`, borderRadius: "xl", bg: colors.background[50], mb: 3, overflow: "hidden", transition: "border-color 0.15s ease, box-shadow 0.15s ease", _last: { mb: 0 }, _hover: { borderColor: colors.boxborder[200] }, ...item.itemProps, sx: (_a = item.customStyles) === null || _a === void 0 ? void 0 : _a.itemStyle, children: ({ isExpanded }) => {
+            return ((0, jsx_runtime_1.jsx)(react_2.AccordionItem, { border: "1px solid", borderColor: border, borderRadius: "xl", bg: colors.background[50], boxShadow: "none", mb: 3, overflow: "hidden", _last: { mb: 0 }, ...item.itemProps, sx: (_a = item.customStyles) === null || _a === void 0 ? void 0 : _a.itemStyle, children: ({ isExpanded }) => {
                     var _a, _b, _c;
-                    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("h2", { children: (0, jsx_runtime_1.jsxs)(react_2.AccordionButton, { px: 4, py: 3, gap: 3, fontSize: "0.875rem", fontWeight: 600, color: headingColor, bg: isExpanded ? expandedBg : "transparent", transition: "background 0.15s ease", _hover: { bg: isExpanded ? expandedBg : softHover }, _focusVisible: {
-                                        boxShadow: "none",
-                                        outline: `0.125rem solid ${focusRing}`,
-                                        outlineOffset: "-0.125rem",
-                                    }, ...item.buttonProps, sx: {
+                    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsx)("h2", { children: (0, jsx_runtime_1.jsxs)(react_2.AccordionButton, { px: 4, py: 3, gap: 3, fontSize: "0.875rem", fontWeight: 600, color: headingColor, bg: isExpanded ? expandedBg : "transparent", transition: (0, motion_1.transitionFor)(["background-color"]), _hover: { bg: isExpanded ? expandedBg : softHover }, _focusVisible: focusRing, ...item.buttonProps, sx: {
+                                        ...(0, motion_2.reducedMotionSx)(),
                                         ...(_a = item.customStyles) === null || _a === void 0 ? void 0 : _a.buttonStyle,
                                         "&:hover": {
                                             ...(_b = item.customStyles) === null || _b === void 0 ? void 0 : _b.hoverbuttonStyle,
                                         },
-                                    }, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", flex: "1", textAlign: "left", children: item.header }), (0, jsx_runtime_1.jsx)(react_2.Flex, { align: "center", justify: "center", boxSize: "1.5rem", flexShrink: 0, borderRadius: "md", color: isExpanded ? colors.accentText : colors.textMuted, bg: isExpanded ? colors.primary.opacity[16] : "transparent", transform: isExpanded ? "rotate(180deg)" : "rotate(0deg)", transition: "transform 0.2s ease, color 0.2s ease, background 0.2s ease", children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: 16 }) })] }) }), (0, jsx_runtime_1.jsx)(react_2.AccordionPanel, { px: 4, pt: 1, pb: 4, fontSize: "0.875rem", lineHeight: "1.5", color: bodyColor, ...item.panelProps, sx: (_c = item.customStyles) === null || _c === void 0 ? void 0 : _c.panelStyle, children: item.content })] }));
+                                    }, children: [(0, jsx_runtime_1.jsx)(react_2.Box, { as: "span", flex: "1", textAlign: "left", children: item.header }), (0, jsx_runtime_1.jsx)(react_2.Flex, { align: "center", justify: "center", boxSize: "1.5rem", flexShrink: 0, borderRadius: "lg", color: isExpanded ? colors.accentText : colors.textMuted, bg: isExpanded ? colors.primary.opacity[16] : "transparent", transform: isExpanded ? "rotate(180deg)" : "rotate(0deg)", transition: (0, motion_1.transitionFor)(["transform", "color", "background-color"], "base"), sx: (0, motion_2.reducedMotionSx)(), children: (0, jsx_runtime_1.jsx)(lucide_react_1.ChevronDown, { size: 16 }) })] }) }), (0, jsx_runtime_1.jsx)(react_2.AccordionPanel, { px: 4, pt: 1, pb: 4, fontSize: "0.875rem", lineHeight: "1.5", color: bodyColor, ...item.panelProps, sx: (_c = item.customStyles) === null || _c === void 0 ? void 0 : _c.panelStyle, children: item.content })] }));
                 } }, idx));
         }) }));
 };

package/dist/Components/Accordion/accordionColors.d.ts

@@ -3,3 +3,9 @@ export declare const getAccordionHoverColors: (colors: PaletteProps, isDark: boo
     expandedBg: string;
     softHover: string;
 };
+/** The Button's two-tone `focusRing`, drawn inset because the item clips overflow. */
+export declare const accordionFocusRing: (colors: Pick<PaletteProps, "focusRing">) => {
+    outline: string;
+    outlineOffset: string;
+    boxShadow: string;
+};

package/dist/Components/Accordion/accordionColors.js

@@ -1,21 +1,13 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getAccordionHoverColors = void 0;
+exports.accordionFocusRing = exports.getAccordionHoverColors = void 0;
 const color_1 = require("../../Theme/tokens/builders/color");
 const outlineRung_1 = require("../../Theme/tokens/builders/outlineRung");
-/**
- * Same perceptibility floor the SideBar ladder uses — a state a user cannot see is not a state.
- * Light mode `softHover` measured 1.042-1.105 across all 9 brands (invisible) while dark sat at
- * 1.58-1.85; `expandedBg` (`primary.opacity[8]`, an 8%-alpha tint) is the same bug class — an
- * 8% tint composited over a near-white canvas is itself near-white. Both are resolved against
- * the rest surface so light and dark actually agree on "you can see this".
- */
+const focusRing_styles_1 = require("../../Theme/chakra/focusRing.styles");
+// NOTE: light softHover measured 1.04-1.11 (invisible) unresolved — both modes now resolve against the rest surface.
 const MIN_HOVER_STEP = 1.15;
 const getAccordionHoverColors = (colors, isDark) => {
     if (isDark) {
-        // primary.opacity[8] composited over the dark canvas collapses to ~1.07:1 (near-black on
-        // near-black) — gray[200] is an opaque rung that stays visibly above canvas (~1.6:1) without
-        // being as loud as the gray[300] hover fill FilterSidebar/Table already use.
         return {
             expandedBg: colors.gray[200],
             softHover: colors.gray[200],
@@ -29,3 +21,11 @@ const getAccordionHoverColors = (colors, isDark) => {
     };
 };
 exports.getAccordionHoverColors = getAccordionHoverColors;
+/** The Button's two-tone `focusRing`, drawn inset because the item clips overflow. */
+const accordionFocusRing = (colors) => ({
+    outline: "2px solid transparent",
+    outlineOffset: "-2px",
+    boxShadow: `inset 0 0 0 ${focusRing_styles_1.FOCUS_RING_WIDTH - focusRing_styles_1.FOCUS_HALO_WIDTH}px ${colors.focusRing.ring}, ` +
+        `inset 0 0 0 ${focusRing_styles_1.FOCUS_RING_WIDTH}px ${colors.focusRing.halo}`,
+});
+exports.accordionFocusRing = accordionFocusRing;

package/dist/Components/AlertDialog/AlertDialog.d.ts

@@ -1,4 +1,4 @@
 import { AlertDialogsProps } from "./AlertDialogProps";
 /** Renders a fixed Cancel/Confirm AlertDialog from title+content props — not a substitute for Modal when you need custom footer buttons or slots. */
-declare const AlertDialog: ({ isOpen, onClose, leastDestructiveRef, content, title, confirmButtonText, cancelButtonText, isConfirmLoading, onConfirm, ContentStyle, headerStyle, bodyStyle, footerStyle, closeButtonStyle, button1Style, button2Style, isCentered, key, }: AlertDialogsProps) => import("react/jsx-runtime").JSX.Element;
+declare const AlertDialog: ({ isOpen, onClose, leastDestructiveRef, closeOnOverlayClick, closeOnEsc, content, title, confirmButtonText, cancelButtonText, isConfirmLoading, onConfirm, tone, ContentStyle, headerStyle, bodyStyle, footerStyle, closeButtonStyle, button1Style, button2Style, isCentered, }: AlertDialogsProps) => import("react/jsx-runtime").JSX.Element;
 export default AlertDialog;

package/dist/Components/AlertDialog/AlertDialog.js

@@ -1,11 +1,11 @@
 "use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("@chakra-ui/react");
-const useCustomTheme_1 = require("../../Theme/useCustomTheme");
+const Button_1 = __importDefault(require("../Button/Button"));
 /** Renders a fixed Cancel/Confirm AlertDialog from title+content props — not a substitute for Modal when you need custom footer buttons or slots. */
-const AlertDialog = ({ isOpen, onClose, leastDestructiveRef, content, title, confirmButtonText = "Yes", cancelButtonText = "No", isConfirmLoading, onConfirm, ContentStyle, headerStyle, bodyStyle, footerStyle, closeButtonStyle, button1Style, button2Style, isCentered, key, }) => {
-    const { colors } = (0, useCustomTheme_1.useCustomTheme)();
-    return ((0, jsx_runtime_1.jsxs)(react_1.AlertDialog, { motionPreset: "slideInBottom", leastDestructiveRef: leastDestructiveRef, onClose: onClose, isOpen: isOpen, isCentered: isCentered, children: [(0, jsx_runtime_1.jsx)(react_1.AlertDialogOverlay, {}), (0, jsx_runtime_1.jsxs)(react_1.AlertDialogContent, { bg: colors.background[50], sx: ContentStyle, children: [(0, jsx_runtime_1.jsx)(react_1.AlertDialogHeader, { sx: headerStyle, children: title }), (0, jsx_runtime_1.jsx)(react_1.AlertDialogCloseButton, { sx: closeButtonStyle }), (0, jsx_runtime_1.jsx)(react_1.AlertDialogBody, { sx: bodyStyle, children: content }), (0, jsx_runtime_1.jsxs)(react_1.AlertDialogFooter, { sx: footerStyle, children: [(0, jsx_runtime_1.jsx)(react_1.Button, { ref: leastDestructiveRef, onClick: onClose, variant: "outline", colorScheme: "red", size: "sm", sx: button1Style, children: cancelButtonText }), (0, jsx_runtime_1.jsx)(react_1.Button, { colorScheme: "primary", onClick: onConfirm, isLoading: isConfirmLoading, ml: 3, size: "sm", sx: button2Style, children: confirmButtonText })] })] })] }, key));
-};
+const AlertDialog = ({ isOpen, onClose, leastDestructiveRef, closeOnOverlayClick, closeOnEsc, content, title, confirmButtonText = "Confirm", cancelButtonText = "Cancel", isConfirmLoading, onConfirm, tone = "default", ContentStyle, headerStyle, bodyStyle, footerStyle, closeButtonStyle, button1Style, button2Style, isCentered, }) => ((0, jsx_runtime_1.jsxs)(react_1.AlertDialog, { motionPreset: "slideInBottom", leastDestructiveRef: leastDestructiveRef, onClose: onClose, isOpen: isOpen, isCentered: isCentered, closeOnOverlayClick: closeOnOverlayClick, closeOnEsc: closeOnEsc, children: [(0, jsx_runtime_1.jsx)(react_1.AlertDialogOverlay, {}), (0, jsx_runtime_1.jsxs)(react_1.AlertDialogContent, { sx: ContentStyle, children: [(0, jsx_runtime_1.jsx)(react_1.AlertDialogHeader, { sx: headerStyle, children: title }), (0, jsx_runtime_1.jsx)(react_1.AlertDialogCloseButton, { sx: closeButtonStyle }), (0, jsx_runtime_1.jsx)(react_1.AlertDialogBody, { sx: bodyStyle, children: content }), (0, jsx_runtime_1.jsxs)(react_1.AlertDialogFooter, { sx: footerStyle, children: [(0, jsx_runtime_1.jsx)(Button_1.default, { ref: leastDestructiveRef, onClick: onClose, variant: "outline", colorScheme: "gray", size: "sm", sx: button1Style, label: cancelButtonText }), (0, jsx_runtime_1.jsx)(Button_1.default, { colorScheme: tone === "danger" ? "red" : "primary", onClick: onConfirm, isLoading: isConfirmLoading, size: "sm", sx: button2Style, label: confirmButtonText })] })] })] }));
 exports.default = AlertDialog;

package/dist/Components/AlertDialog/AlertDialogProps.d.ts

@@ -1,21 +1,44 @@
 import { AlertDialogProps, AlertProps } from "@chakra-ui/react";
 import { ReactElement } from "react";
-/** colorScheme/size/status/variant/addRole (Picked from Chakra's AlertProps) are typed but never read — buttons are hardcoded; style via button1Style/button2Style. */
-export type AlertDialogsProps = Pick<AlertDialogProps, "isOpen" | "onClose" | "leastDestructiveRef"> & Pick<AlertProps, "addRole" | "colorScheme" | "size" | "status" | "variant"> & {
+/** Props accepted for backward compatibility but never read by AlertDialog. */
+export type AlertDialogDeadProps = {
+    /** @deprecated Never read — the dialog already has role="alertdialog". */
+    addRole?: AlertProps["addRole"];
+    /** @deprecated Never read — use `tone`. */
+    colorScheme?: AlertProps["colorScheme"];
+    /** @deprecated Never read — the dialog always uses Chakra's default size. */
+    size?: AlertProps["size"];
+    /** @deprecated Never read — use `tone`. */
+    status?: AlertProps["status"];
+    /** @deprecated Never read — use `tone`. */
+    variant?: AlertProps["variant"];
+    /** @deprecated Never read — React strips `key` before props arrive. */
+    key?: string | number;
+};
+/** Fixed Cancel/Confirm dialog; `tone="danger"` fills Confirm red, otherwise it is primary. */
+export type AlertDialogsProps = Pick<AlertDialogProps, "isOpen" | "onClose" | "leastDestructiveRef" | "closeOnOverlayClick" | "closeOnEsc"> & AlertDialogDeadProps & {
     title: string;
+    /** Rendered inside the dialog body. */
     content: ReactElement;
     isCentered?: boolean;
+    /** Defaults to "Confirm". */
     confirmButtonText?: string;
+    /** Defaults to "Cancel"; Cancel calls `onClose` and holds `leastDestructiveRef`. */
     cancelButtonText?: string;
+    /** Shows a spinner on the Confirm button. */
     isConfirmLoading?: boolean;
+    /** Fires on Confirm click; does not close the dialog — call `onClose` yourself. */
     onConfirm: () => void;
+    /** Defaults to "default" (primary Confirm); "danger" makes Confirm red. */
+    tone?: "default" | "danger";
+    /** `sx` for the dialog content box. */
     ContentStyle?: React.CSSProperties;
     headerStyle?: React.CSSProperties;
     bodyStyle?: React.CSSProperties;
     footerStyle?: React.CSSProperties;
     closeButtonStyle?: React.CSSProperties;
+    /** Raw style escape hatch for the Cancel button. */
     button1Style?: React.CSSProperties;
+    /** Raw style escape hatch for Confirm; prefer `tone` for a danger action. */
     button2Style?: React.CSSProperties;
-    /** React reserves "key" and never forwards it as a prop, so this is always undefined here — no effect. */
-    key?: string | number;
 };

package/dist/Components/Apexcharts/ApexAreaChart/ApexAreaChart.js

@@ -5,18 +5,21 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const react_1 = require("react");
-const react_apexcharts_1 = __importDefault(require("react-apexcharts"));
 const useCustomTheme_1 = require("../../../Theme/useCustomTheme");
 const chartColorsFromTheme_1 = require("../../../Theme/tokens/builders/chartColorsFromTheme");
 const chartBase_1 = require("../chartBase");
+const LazyReactApexChart_1 = __importDefault(require("../LazyReactApexChart"));
+const ApexChartFallback_1 = __importDefault(require("../ApexChartFallback"));
 /** Filled line chart (basic/stacked/gradient/sparkline); unlike `ApexLineChart`, `data`/`series` are read fresh via `useMemo` every render, not frozen at mount. */
 const ApexAreaChart = ({ variant = "basic", data, series, labels, title, titlePosition = "left", height = 320, width = "100%", colors, showLegend = true, legendPosition = "bottom", yAxisFormatter, }) => {
     const { colors: palette } = (0, useCustomTheme_1.useCustomTheme)();
+    const chartId = `apex-area-${(0, react_1.useId)().replace(/:/g, "")}`;
     const seriesColors = (0, react_1.useMemo)(() => colors !== null && colors !== void 0 ? colors : (0, chartColorsFromTheme_1.getDefaultSeriesColors)(palette), [colors, palette]);
     const resolvedSeries = (0, react_1.useMemo)(() => series !== null && series !== void 0 ? series : [{ name: title !== null && title !== void 0 ? title : "Series 1", data: data !== null && data !== void 0 ? data : [] }], [series, data, title]);
     const isSpark = variant === "sparkline";
     const options = (0, react_1.useMemo)(() => ({
         chart: (0, chartBase_1.baseChart)(palette, {
+            id: chartId,
             type: "area",
             stacked: variant === "stacked",
             sparkline: { enabled: isSpark },
@@ -55,6 +58,7 @@ const ApexAreaChart = ({ variant = "basic", data, series, labels, title, titlePo
         tooltip: (0, chartBase_1.baseTooltip)(palette),
     }), [
         palette,
+        chartId,
         variant,
         isSpark,
         seriesColors,
@@ -66,6 +70,6 @@ const ApexAreaChart = ({ variant = "basic", data, series, labels, title, titlePo
         resolvedSeries.length,
         yAxisFormatter,
     ]);
-    return ((0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)(react_apexcharts_1.default, { options: options, series: resolvedSeries, type: "area", height: height, width: width }) }));
+    return ((0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)(react_1.Suspense, { fallback: (0, jsx_runtime_1.jsx)(ApexChartFallback_1.default, { height: height, width: width }), children: (0, jsx_runtime_1.jsx)(LazyReactApexChart_1.default, { options: options, series: resolvedSeries, type: "area", height: height, width: width }) }) }));
 };
 exports.default = ApexAreaChart;