pixelize-design-library 3.0.1-beta.1 → 3.1.1

package/README.md

@@ -2,6 +2,13 @@
 
 A comprehensive React component library built with TypeScript, providing a rich set of UI components for modern web applications.
 
+> **Building with this library (including via an AI assistant)?** Read
+> [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
 
 - 🎨 **Modern Design System** - Consistent and beautiful components
@@ -15,24 +22,39 @@ A comprehensive React component library built with TypeScript, providing a rich
 
 Before you begin, ensure you have the following installed:
 
-- Node.js (v16 or higher)
+- Node.js (v18 or higher)
 - npm (v7 or higher) or yarn
-- React (v16.8 or higher)
+- React and React DOM `^18.3.1`
 
 ## 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
+
+Everything ships on the `latest` dist-tag. Stable `3.x` takes a caret range:
+
+```json
+"pixelize-design-library": "^3.0.0"
 ```
 
+There are no prereleases from 3.0.0 onward. The old `2.4.2-beta.N` line was folded into 3.0.0; if you are
+still pinned to one, change the pin to `3.0.0`.
+
+What changed in each release, and what breaks in 3.0.0:
+[CHANGELOG.md](CHANGELOG.md).
+
 ## Quick Start
 
 ```tsx
@@ -44,7 +66,7 @@ function App() {
     <div>
       <Card>
         <TextInput placeholder="Enter your name" />
-        <Button variant="primary">Submit</Button>
+        <Button variant="solid" colorScheme="primary">Submit</Button>
       </Card>
     </div>
   );
@@ -53,6 +75,27 @@ function App() {
 export default App;
 ```
 
+## Theming and filled surfaces
+
+Nine brand presets with light/dark palettes. Wrap your app in `PixelizeThemeProvider` and read tokens
+via `useCustomTheme()`.
+
+**Do not** pair a scale's `[500]` swatch with `colors.white` or `onPrimary` for custom filled UI —
+white often fails WCAG on `[500]` and ink falls back to black (e.g. black text on red badges). Use
+library components (`Button`, `Tag`, `Badge`) or:
+
+```ts
+import { resolveFilledSurface, useCustomTheme } from "pixelize-design-library";
+
+const { colors } = useCustomTheme();
+const solid = resolveFilledSurface(colors.red, colors);
+// solid.fill, solid.color, solid.hoverFill, solid.hoverColor, …
+```
+
+Full rules for app developers and AI assistants: [`src/Theme/THEME-CONTRACT.md`](src/Theme/THEME-CONTRACT.md)
+(§ *Filled surfaces in consumer apps*). After upgrading, rebuild the library (`npm run build`) and run
+`npm run pixelize` in consumer frontends.
+
 ## Components
 
 ### Layout & Navigation
@@ -68,22 +111,24 @@ export default App;
 - **ButtonGroupIcon** - Icon-based button group
 - **Checkbox** - Checkbox input control
 - **DatePicker** - Date selection component
-- **Dropdown** - Dropdown selection component
-- **MultiSelect** - Multi-selection dropdown
+- **Dropdown** - Action menu (a menu button, not a value picker)
+- **MultiSelect** - Typed email-chip input (no options list)
 - **NumberInput** - Numeric input field
 - **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
-- **Switch** - Toggle switch component
+- **Select** - Native or themed popup picker, single or multi, optionally searchable
+- **ToggleSwitch** - On/off switch (`Switch` is a deprecated two-option pill)
 - **TextInput** - Text input field
 - **InputTextArea** - Multi-line text input
-- **NoteTextArea** - Rich text editor
+- **NoteTextArea** - Textarea with a title and file attach (not rich text; use `Editor`)
 
 ### 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
@@ -93,13 +138,18 @@ export default App;
 - **ApexPieChart** - Pie chart component
 
 ### Feedback & Status
-- **AlertDialog** - Alert dialog component *(New)*
-- **Loading** - Loading spinner component
+- **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** - Blocking loading overlay (`Backdrop` for a lighter scrim)
+- **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
@@ -107,6 +157,9 @@ export default App;
 ### Editor
 - **Editor** - Rich text editor component
 
+The lists above are the common components. Every export, including the helpers, hooks and tokens, is
+in the [Exports index](#exports-index).
+
 ## Usage Examples
 
 ### Basic Button Usage
@@ -117,12 +170,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>
   );
 }
@@ -131,6 +180,7 @@ function MyComponent() {
 ### Form with Validation
 
 ```tsx
+import { useState } from 'react';
 import { TextInput, Button, Card } from 'pixelize-design-library';
 
 function LoginForm() {
@@ -143,17 +193,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>
@@ -167,14 +217,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() {
@@ -182,8 +233,8 @@ function DataTable() {
     <Table
       columns={columns}
       data={data}
-      pagination
-      searchable
+      paginationMode="client"
+      isGlobalSearch
     />
   );
 }
@@ -191,17 +242,87 @@ function DataTable() {
 
 ## Theming
 
-The library supports custom theming through CSS variables:
+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)
+
+`withTheme` is the original default export and still renders **light only**. Upgrading the package
+changes nothing visually:
+
+```tsx
+import withTheme, { ThemesList } from 'pixelize-design-library';
+
+export default withTheme(App, ThemesList.lavender);
+```
+
+### Opting into light / dark / system
+
+Wrap the app in `PixelizeThemeProvider` instead. It defaults to **`system`** (follows the OS) and
+persists the user's choice to `localStorage`.
+
+```tsx
+import { PixelizeThemeProvider, ThemeSwitcher } from 'pixelize-design-library';
 
-```css
-:root {
-  --primary-color: #007bff;
-  --secondary-color: #6c757d;
-  --success-color: #28a745;
-  --danger-color: #dc3545;
-  --warning-color: #ffc107;
-  --info-color: #17a2b8;
+function Root() {
+  return (
+    <PixelizeThemeProvider brand="lavender" defaultMode="system">
+      <App />
+    </PixelizeThemeProvider>
+  );
 }
+
+// Drop the switcher anywhere inside the provider:
+<ThemeSwitcher />                                    // icon toggle
+<ThemeSwitcher variant="segmented" />                // Light / System / Dark
+<ThemeSwitcher variant="menu" showBrandPicker />     // + brand picker
+```
+
+| `PixelizeThemeProvider` prop | Default | Meaning |
+| ---------------------------- | ------- | ------- |
+| `brand` | `"lavender"` | Which brand theme to use |
+| `defaultMode` | `"system"` | `"light"` \| `"dark"` \| `"system"` |
+| `storageKey` | `"pixelize-theme"` | localStorage key |
+| `disablePersistence` | `false` | Don't read/write localStorage |
+| `onBrandChange` / `onModeChange` | — | Fire on user-driven changes only |
+| `themeOverrides` | — | Chakra theme object merged over the brand theme |
+| `reducedMotion` | `"components"` | `"global"` applies one reduced-motion rule to the whole document |
+
+### Reading or changing the theme in code
+
+```tsx
+import { useThemeMode, useCustomTheme } from 'pixelize-design-library';
+
+const { mode, resolvedMode, setMode, toggle, brand, setBrand } = useThemeMode();
+const theme = useCustomTheme(); // returns the palette for the ACTIVE color mode
+```
+
+`useCustomTheme()` returns the dark palette automatically in dark mode, so components that read
+their colors from it are dark-aware with no extra work.
+
+### Building components
+
+Read colors from the theme — never hardcode a hex, or the component will be stuck in light mode:
+
+```tsx
+const theme = useCustomTheme();
+<Box bg={theme.colors.background[50]} color={theme.colors.text[900]} />  // ✅ adapts
+<Box bg="#ffffff" color="#26213c" />                                     // ❌ breaks in dark
+```
+
+`colors.white` is a **foreground** token (the label on a filled button) and stays white in dark
+mode. For a white **surface**, use `colors.background[50]`.
+
+### Design tokens (shared with the mobile library)
+
+`lightPalettes`, `darkPalettes`, `palettes`, `themeNames`, and `buildDarkPalette` are exported for
+apps that build custom themes. The token source (`src/Theme/tokens/`) is pure TypeScript with no
+Chakra, React, or CSS imports, so it is portable to React Native.
+
+```ts
+import { lightPalettes, buildDarkPalette } from 'pixelize-design-library';
+
+const myDark = buildDarkPalette(lightPalettes.emerald);
 ```
 
 ## TypeScript Support
@@ -209,7 +330,7 @@ The library supports custom theming through CSS variables:
 All components are built with TypeScript and include full type definitions:
 
 ```tsx
-import { ButtonProps } from 'pixelize-design-library';
+import { Button, ButtonProps } from 'pixelize-design-library';
 
 interface CustomButtonProps extends ButtonProps {
   customProp?: string;
@@ -220,21 +341,115 @@ function CustomButton({ customProp, ...props }: CustomButtonProps) {
 }
 ```
 
+## Bundle size and tree-shaking
+
+The package ships both CommonJS (`main`) and ES modules (`module`). Bundlers pick the ESM
+build and tree-shake it, so **you only pay for what you import**:
+
+```tsx
+import { Button } from 'pixelize-design-library';
+```
+
+That import produces roughly **113 KB** — it contains no chart, editor, drag-and-drop,
+virtual-list or date code, even though the package depends on all of them.
+
+To keep it that way:
+
+- **Import from the package root.** The root barrel is tree-shakeable; there is no size
+  penalty for it, and it is the only path covered by semver.
+- **Do not import from `dist/` for values.** Deep imports still work (and are used for types),
+  but they bypass the ESM build and pull in the CommonJS copy.
+- **Do not disable `sideEffects` handling** in your bundler config.
+
+### Heavy components load on demand
+
+`Editor` wraps Jodit, which is by far the largest dependency. It is loaded lazily, when the
+component first renders, rather than when the package is imported. An app that uses `Editor`
+ships about **96 KB** up front and fetches the ~1.5 MB editor chunk on demand. No extra setup
+is required — `Editor` renders its own `Suspense` boundary.
+
+### Fonts
+
+The theme self-hosts Inter Variable. The stylesheet is split by `unicode-range`, so a
+Latin-script page downloads a single **47 KB** font file; Cyrillic, Greek and Vietnamese
+subsets are only fetched if the page actually renders those scripts.
+
+### Server-side rendering
+
+Components are browser-targeted and the theme imports a CSS file, so the package must be
+transpiled by your bundler rather than imported by bare Node. In Next.js:
+
+```js
+// next.config.js
+module.exports = { transpilePackages: ['pixelize-design-library'] };
+```
+
+## Exports index
+
+Every value the package root exports, so an export is never invisible to a developer or an LLM that
+only has this package. For how to use a component see [DESIGN-GUIDE.md](./DESIGN-GUIDE.md) and
+[COMPONENT-GOTCHAS.md](./COMPONENT-GOTCHAS.md); props are documented in the `*Props` types. This
+block is generated: after adding or removing an export run
+`UPDATE_README_EXPORTS=1 npx jest src/readmeExportsIndex.test.ts --coverage=false`.
+
+<!-- exports-index:start -->
+
+**Components and primitives (256)**
+
+`Accordian`, `Accordion`, `AddressCard`, `AddressCardGroup`, `Alert`, `AlertDescription`, `AlertDialog`, `AlertIcon`, `AlertTitle`, `ApexAreaChart`, `ApexBarChart`, `ApexLineChart`, `ApexPieChart`, `ApexPolarChart`, `ApexRadialChart`, `AppSwitcher`, `AppearanceSettings`, `AudioRecorder`, `Avatar`, `AvatarGroup`, `Backdrop`, `Badge`, `BagBar`, `Box`, `Breadcrumbs`, `BulkSelectionBar`, `Button`, `ButtonGroupIcon`, `CalendarGrid`, `Card`, `CartItem`, `Center`, `ChakraProvider`, `Checkbox`, `ChoiceCard`, `ChoiceCardGroup`, `CircularProgress`, `Collapse`, `ConfirmDialog`, `ContactForm`, `Container`, `CopyButton`, `CouponField`, `CustomModulesTable`, `DatePicker`, `DescriptionList`, `DetailSections`, `Divider`, `Drawer`, `DrawerBody`, `DrawerFooter`, `DrawerHeader`, `Dropdown`, `Editor`, `EmptyState`, `ErrorState`, `FeedbackForm`, `FieldMessage`, `FieldSelectModal`, `FilePreview`, `FilePreviewTrigger`, `FileUpload`, `FileUploader`, `FilterBar`, `FilterSidebar`, `FilteredEmptyState`, `Flex`, `FormControl`, `FormDrawer`, `FormErrorMessage`, `FormField`, `FormHelperText`, `FormLabel`, `FormWrapper`, `Grid`, `GridItem`, `Header`, `HeaderActions`, `Heading`, `Hide`, `Icon`, `IconButton`, `Image`, `InputSwitch`, `InputTextArea`, `KanbanActions`, `KanbanBoard`, `Kbd`, `KbdShortcut`, `LauncherSearchEngine`, `LauncherTrigger`, `LazyWrapper`, `LimitReachedModal`, `Link`, `List`, `ListIcon`, `ListItem`, `Loading`, `MediaAudioPlayer`, `MediaDocumentStage`, `MediaGallery`, `MediaImageViewer`, `MediaLightbox`, `MediaScrubber`, `MediaStatusPanel`, `MediaVideoPlayer`, `MediaViewer`, `Menu`, `MenuButton`, `MenuDivider`, `MenuGroup`, `MenuItem`, `MenuItemOption`, `MenuList`, `MenuOptionGroup`, `Modal`, `ModalBody`, `ModalFooter`, `ModalHeader`, `MoreItems`, `MultiSelect`, `NavLauncher`, `NavigationBar`, `NewTabLink`, `NoteTextArea`, `Notification`, `NotificationBell`, `NotificationItem`, `NotificationList`, `NotificationPanel`, `NumberInput`, `OffersList`, `OptionChip`, `OrderStatusTimeline`, `OrderSummary`, `OrderedList`, `OrgSwitcher`, `OrganizationDetails`, `OverflowToolTip`, `PageHeader`, `Pagination`, `PaymentCard`, `PaymentOption`, `PaymentOptionGroup`, `PdfViewer`, `PersonChip`, `PhoneNumberInput`, `PinInput`, `PinToggle`, `PincodeChecker`, `PixelizeThemeProvider`, `PlanBadge`, `PlanPill`, `Popover`, `PopoverArrow`, `PopoverBody`, `PopoverCloseButton`, `PopoverContent`, `PopoverFooter`, `PopoverHeader`, `PopoverTrigger`, `Portal`, `PriceBlock`, `ProductBadges`, `ProductCard`, `ProductCardGrid`, `ProductCardSkeleton`, `ProductDetails`, `ProfileCard`, `ProfileCardBody`, `ProfileCardFooter`, `ProfileCardHeader`, `ProfilePhotoViewer`, `ProgressBar`, `QuantityStepper`, `QueryStateBoundary`, `QuickAddSheet`, `RadioButton`, `RadioButtonGroup`, `RangeSlider`, `Rating`, `Reorder`, `ReviewList`, `ReviewSummary`, `RolesPermission`, `SaveBar`, `ScrollToTop`, `ScrollbarBox`, `Search`, `SearchSelect`, `SectionRail`, `SegmentedControl`, `Select`, `SelectSearch`, `SelectV2`, `SettingRow`, `SettingsSection`, `Show`, `SideBar`, `SignInActivityTable`, `SimpleGrid`, `Skeletons`, `SkipLink`, `Slider`, `Spacer`, `SpecTable`, `Spinner`, `Stack`, `StageItem`, `StageProgress`, `StatCard`, `StatusTag`, `StickyBuyBar`, `StockStatus`, `Switch`, `Tab`, `TabList`, `TabPanel`, `TabPanels`, `Table`, `TableContainer`, `TableRoot`, `TableToggle`, `Tabs`, `Tag`, `TagInput`, `Tbody`, `Td`, `Text`, `TextInput`, `Tfoot`, `Th`, `Thead`, `ThemeSwitcher`, `ThemesList`, `TimePicker`, `Timeline`, `Toaster`, `ToggleSwitch`, `ToolTip`, `Tr`, `TrustBadges`, `UnorderedList`, `UpgradeButton`, `UserDetails`, `VariantSelector`, `VerifyEmailOtp`, `VisuallyHidden`, `WishlistToggle`, `Wizard`, `WizardDialog`, `WorkspaceTray`, `WorkspaceTrayPreview`, `WorkspaceWindow`, `Wrap`, `WrapItem`
+
+**Hooks (18)**
+
+`useAnchoredPanelHeight`, `useAppSwitcherShortcut`, `useBreakpointValue`, `useChartTheme`, `useCustomTheme`, `useDebouncedCallback`, `useDebouncedValue`, `useDisclosure`, `useFieldIds`, `useFileViewer`, `useFontSizeSync`, `useIsTruncated`, `useMediaQuery`, `usePrefersReducedMotion`, `useSidebarPrefs`, `useThemeMode`, `useToaster`, `useToken`
+
+**Constants (45)**
+
+`AA_NON_TEXT`, `AA_NORMAL_TEXT`, `ACCENT_GRADIENT`, `AVATAR_SEEDS`, `BORDER_WIDTHS`, `CALENDAR_DAY_CLASS`, `CATEGORICAL_SERIES`, `CONTROL_SIZES`, `CONTROL_SIZE_NAMES`, `DARK_CANVAS_LUMINANCE`, `DAY_STATE_KEYS`, `DEFAULT_CONTROL_SIZE`, `DEFAULT_DATE_FALLBACK`, `DEFAULT_FONT_SIZE`, `DISABLED_OPACITY`, `EMAIL_REGEX`, `FOCUS_HALO_WIDTH`, `FOCUS_RING_WIDTH`, `FOCUS_VISIBLE_OVER_STATE`, `FONT_SIZE_OPTIONS`, `LOW_STOCK_THRESHOLD`, `MAX_ZOOM`, `MIN_ZOOM`, `MOTION_BEZIER`, `MOTION_EASE`, `MOTION_EASE_IN`, `MOTION_EASE_OUT`, `MOTION_KEEP_CLASS`, `MOTION_LOOP_MS`, `MOTION_MS`, `MOTION_PRESS_SCALE`, `NUMERIC_TEXT`, `OVERLAY_BLUR`, `PIXELIZE_SUITE`, `PLAYBACK_SPEEDS`, `RADIUS_ROLE`, `RAISED_OVERLAY`, `REDUCED_MOTION_QUERY`, `SCRIM_OPACITY`, `SCROLLBAR_WIDTH`, `SEEK_STEP_SECONDS`, `STATUS_INK`, `TEXT_STYLES`, `TONES`, `ZOOM_STEP`
+
+**Helpers and tokens (185)**
+
+`HStack`, `VStack`, `accentTextOnCanvas`, `accentTextOnPlanes`, `appInitials`, `avatarFillFor`, `avatarScaleKeyFor`, `bandOn`, `brandThemes`, `buildDarkPalette`, `buildFileItems`, `buildFocusRing`, `buildMediaItems`, `buildSuiteApps`, `buildSurfaceRaised`, `cardRule`, `chartAxisLabelColor`, `chartInk`, `chartMode`, `chipBorder`, `chipFill`, `chipHtml`, `chipify`, `clearChunkReloadGuard`, `compositeOver`, `contrastRatio`, `controlSizeStyles`, `countMedia`, `createAccountHandoff`, `createEnumLabelResolver`, `darkPalettes`, `darkerFillRung`, `debounce`, `default`, `defaultMediaAudioPlayerLabels`, `defaultMediaDocumentStageLabels`, `defaultMediaGalleryLabels`, `defaultMediaImageViewerLabels`, `defaultMediaLightboxLabels`, `defaultMediaVideoPlayerLabels`, `defaultMediaViewerLabels`, `defaultPaginationLabels`, `defaultValidationMessages`, `describeDayStates`, `discountAmount`, `discountPercent`, `downloadBlob`, `extendTheme`, `extractTokens`, `fieldControlStyles`, `fieldLabelStyles`, `fieldMessageStyles`, `fieldSurfaces`, `fieldToken`, `fileKind`, `filterApps`, `findVariant`, `firstAvailableSelection`, `firstInvalidStep`, `flattenScreens`, `focusRingShadow`, `focusVisibleRing`, `focusVisibleStyles`, `formatCount`, `formatDate`, `formatDateRange`, `formatDateTime`, `formatPlanElapsed`, `formatPlanExpiry`, `formatPlanRemaining`, `formatPrice`, `formatRelativeTime`, `formatShortcut`, `getApiErrorMessage`, `getApiErrorStatus`, `getCategoricalSeriesColors`, `getDefaultSeriesColors`, `globalScrollbarStyles`, `gradientCss`, `groupConsecutive`, `hexToHsl`, `hexToRgb`, `hexToRgba`, `highlightSegments`, `hslToHex`, `hslToRgb`, `humanize`, `initialsFor`, `inkSafeGradient`, `inkSafeGradientToken`, `installPreloadErrorReload`, `isAllowedReturnUrl`, `isChunkLoadError`, `isControlSize`, `isDarkCanvas`, `isDayStateKey`, `isFontSize`, `isOptionAvailable`, `isTone`, `labelOnFill`, `labelOnSeries`, `lazyWithRetry`, `liftToContrast`, `lightPalettes`, `listRowBackgrounds`, `matchesShortcut`, `meetsBodyText`, `mergeRefs`, `mix`, `motionTransition`, `onFilled`, `onGradient`, `optionRowCursorSx`, `optionRowDescriptionInk`, `optionRowFill`, `optionRowInk`, `optionRowWeight`, `overlayScrim`, `overlayScrimStyles`, `palettes`, `pickAccentText`, `placeholderInk`, `placeholderInkOn`, `planPreview`, `priceRange`, `rafThrottle`, `raisedRule`, `recessOn`, `reducedMotionSx`, `relativeLuminance`, `remainingStock`, `resolveAvatarColorway`, `resolveAvatarFill`, `resolveDayStateVisual`, `resolveFilledSurface`, `resolveFontSize`, `resolveGradient`, `resolveMediaUrl`, `resolvePlanBadge`, `resolveReturnUrl`, `resolveSoftTone`, `resolveStatusTone`, `resolveSuiteApps`, `rgbToHex`, `rgbToHsl`, `ruleOn`, `safeFileName`, `scrollbarStyles`, `searchLauncher`, `searchLauncherSections`, `sectionizeByDay`, `selectionComplete`, `serializeChips`, `setRef`, `settleBetween`, `shadowsFor`, `solidFillRung`, `splitMonthsAndDays`, `statusGradient`, `stockState`, `themeNames`, `toCsv`, `toWords`, `toneInk`, `toneScale`, `toneToColorScheme`, `toneToSemantic`, `tooltipSurface`, `transitionFor`, `unitPrice`, `unknownTokens`, `validateEmail`, `validateFile`, `validateFileSize`, `validateFileType`, `validatePassword`, `validatePositiveNumber`, `validateRequired`, `validateVideoFile`, `validateVideoFileType`, `validateYoutubeUrl`, `withFocusRing`, `withLightness`, `withOutlineRung`, `wizardTransition`
+
+<!-- exports-index:end -->
+
+## Demo app
+
+`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. The **Page examples** section shows full screens (dashboard,
+records list, record detail, settings, pipeline, inbox, app launcher, wizard, template editor,
+storefront) built only from library exports, each with its loading, empty and error states.
+
+```bash
+npm install
+npm start
+```
+
+The demo lives in `src/Pages/` and is excluded from the published package. See
+[GOTCHAS.md](GOTCHAS.md) for the traps involved in keeping it that way.
+
 ## Contributing
 
-We welcome contributions! Please see our [Contributing Guide](CONTRIBUTING.md) for details.
+Read [CLAUDE.md](CLAUDE.md) for the repo layout, component pattern and the checklist for
+adding a component, and [GOTCHAS.md](GOTCHAS.md) before touching the theme provider, the
+build config or `package.json`.
 
-## License
+```bash
+npm install
+npm start        # demo app on :5173
+npm test         # Jest — not vitest
+npm run lint
+npm run typecheck
+```
 
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
+Every component needs a demo page in `src/Pages/` and Jest tests next to the component.
 
-## Support
+## License
 
-For support and questions:
-- 📧 Email: support@pixelize.com
-- 📖 Documentation: [docs.pixelize.com](https://docs.pixelize.com)
-- 🐛 Issues: [GitHub Issues](https://github.com/pixelize/design-library/issues)
+Not yet declared. The `license` field in `package.json` is unset and there is no `LICENSE`
+file in the repo — both need the owning entity's decision before the package is published
+outside the organisation.
 
-## Changelog
+## Support
 
-See [CHANGELOG.md](CHANGELOG.md) for a list of changes and updates.
+- Issues: [github.com/pixelize-tech/Micro-Components/issues](https://github.com/pixelize-tech/Micro-Components/issues)

package/dist/Assets/defaultLogo.d.ts

@@ -1,3 +1,2 @@
-import React from 'react';
-declare const DefaultLogo: () => React.JSX.Element;
+declare const DefaultLogo: () => import("react/jsx-runtime").JSX.Element;
 export default DefaultLogo;

package/dist/Assets/defaultLogo.js

@@ -1,15 +1,7 @@
 "use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-var react_1 = __importDefault(require("react"));
-var useCustomTheme_1 = require("../Theme/useCustomTheme");
-var DefaultLogo = function () {
-    var theme = (0, useCustomTheme_1.useCustomTheme)();
-    return (react_1.default.createElement("svg", { width: "12.09", height: "15.95", viewBox: "0 0 31 29", fill: "none", xmlns: "http://www.w3.org/2000/svg" },
-        react_1.default.createElement("path", { d: "M30.4999 6.26137V7.81058H15.9761H14.8787V22.8508V28.8862H12.5226C9.6824 28.8862 7.32632 26.4656 7.06812 23.3995C7.06812 23.2381 7.06812 23.0444 7.06812 22.8508V18.3323C7.06812 18.2677 7.06812 18.2032 7.06812 18.1063V15.5889V6.2291C7.06812 2.80793 9.84378 -5.72205e-06 13.2972 -5.72205e-06H24.8517C28.0147 0.355021 30.4676 3.00158 30.4676 6.2291L30.4999 6.26137Z", fill: theme.colors.black }),
-        react_1.default.createElement("path", { d: "M7.10053 23.3672H7.03598C5.16402 23.2381 3.48571 22.4635 2.25926 21.3338C0.871428 20.0428 0 18.2677 0 16.3312V15.6211H7.06825V18.1386C7.06825 18.2032 7.06825 18.2677 7.06825 18.3645V22.883C7.06825 23.0767 7.06825 23.2381 7.06825 23.4317L7.10053 23.3672Z", fill: theme.colors.black }),
-        react_1.default.createElement("path", { d: "M30.4678 12.0063V15.6211V17.1703C30.4678 20.6238 26.272 23.3994 21.0757 23.3994H14.8789V22.8508V15.6211H22.6572V7.81056C22.6895 7.81056 30.5001 7.81056 30.5001 7.81056V11.5868C30.5001 11.7159 30.5001 11.8772 30.5001 12.0063H30.4678Z", fill: theme.colors.black })));
+const jsx_runtime_1 = require("react/jsx-runtime");
+const DefaultLogo = () => {
+    return ((0, jsx_runtime_1.jsxs)("svg", { width: "12.09", height: "15.95", viewBox: "0 0 31 29", fill: "none", xmlns: "http://www.w3.org/2000/svg", children: [(0, jsx_runtime_1.jsx)("path", { d: "M30.4999 6.26137V7.81058H15.9761H14.8787V22.8508V28.8862H12.5226C9.6824 28.8862 7.32632 26.4656 7.06812 23.3995C7.06812 23.2381 7.06812 23.0444 7.06812 22.8508V18.3323C7.06812 18.2677 7.06812 18.2032 7.06812 18.1063V15.5889V6.2291C7.06812 2.80793 9.84378 -5.72205e-06 13.2972 -5.72205e-06H24.8517C28.0147 0.355021 30.4676 3.00158 30.4676 6.2291L30.4999 6.26137Z", fill: "currentColor" }), (0, jsx_runtime_1.jsx)("path", { d: "M7.10053 23.3672H7.03598C5.16402 23.2381 3.48571 22.4635 2.25926 21.3338C0.871428 20.0428 0 18.2677 0 16.3312V15.6211H7.06825V18.1386C7.06825 18.2032 7.06825 18.2677 7.06825 18.3645V22.883C7.06825 23.0767 7.06825 23.2381 7.06825 23.4317L7.10053 23.3672Z", fill: "currentColor" }), (0, jsx_runtime_1.jsx)("path", { d: "M30.4678 12.0063V15.6211V17.1703C30.4678 20.6238 26.272 23.3994 21.0757 23.3994H14.8789V22.8508V15.6211H22.6572V7.81056C22.6895 7.81056 30.5001 7.81056 30.5001 7.81056V11.5868C30.5001 11.7159 30.5001 11.8772 30.5001 12.0063H30.4678Z", fill: "currentColor" })] }));
 };
 exports.default = DefaultLogo;

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

@@ -1,4 +1,4 @@
-import React from "react";
 import { AccordionProps } from "./AccordionProps";
-declare const Accordion: ({ allowMultiple, allowToggle, index, onChange, reduceMotion, items, ...rest }: AccordionProps) => React.JSX.Element;
+/** Chakra Accordion wrapper for header/content pairs; FilterSidebar composes this directly for its collapsible filter sections. */
+declare const Accordion: ({ allowMultiple, allowToggle, index, onChange, reduceMotion, items, ...rest }: AccordionProps) => import("react/jsx-runtime").JSX.Element;
 export default Accordion;

package/dist/Components/Accordion/Accordion.js

@@ -1,40 +1,38 @@
 "use strict";
-var __assign = (this && this.__assign) || function () {
-    __assign = Object.assign || function(t) {
-        for (var s, i = 1, n = arguments.length; i < n; i++) {
-            s = arguments[i];
-            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
-                t[p] = s[p];
-        }
-        return t;
-    };
-    return __assign.apply(this, arguments);
-};
-var __rest = (this && this.__rest) || function (s, e) {
-    var t = {};
-    for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p) && e.indexOf(p) < 0)
-        t[p] = s[p];
-    if (s != null && typeof Object.getOwnPropertySymbols === "function")
-        for (var i = 0, p = Object.getOwnPropertySymbols(s); i < p.length; i++) {
-            if (e.indexOf(p[i]) < 0 && Object.prototype.propertyIsEnumerable.call(s, p[i]))
-                t[p[i]] = s[p[i]];
-        }
-    return t;
-};
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
-var react_1 = __importDefault(require("react"));
-var react_2 = require("@chakra-ui/react");
-var Accordion = function (_a) {
-    var allowMultiple = _a.allowMultiple, allowToggle = _a.allowToggle, index = _a.index, onChange = _a.onChange, reduceMotion = _a.reduceMotion, items = _a.items, rest = __rest(_a, ["allowMultiple", "allowToggle", "index", "onChange", "reduceMotion", "items"]);
-    return (react_1.default.createElement(react_2.Accordion, __assign({ allowMultiple: allowMultiple, allowToggle: allowToggle, index: index, onChange: onChange, reduceMotion: reduceMotion }, rest), items.map(function (item, idx) {
-        var _a, _b, _c, _d;
-        return (react_1.default.createElement(react_2.AccordionItem, __assign({ key: idx }, item.itemProps, { sx: (_a = item.customStyles) === null || _a === void 0 ? void 0 : _a.itemStyle }),
-            react_1.default.createElement("h2", null,
-                react_1.default.createElement(react_2.AccordionButton, __assign({}, item.buttonProps, { sx: __assign(__assign({}, (_b = item.customStyles) === null || _b === void 0 ? void 0 : _b.buttonStyle), { '&:hover': __assign({}, (_c = item.customStyles) === null || _c === void 0 ? void 0 : _c.hoverbuttonStyle) }) }), item.header)),
-            react_1.default.createElement(react_2.AccordionPanel, __assign({}, item.panelProps, { sx: (_d = item.customStyles) === null || _d === void 0 ? void 0 : _d.panelStyle }), item.content)));
-    })));
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+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 motion_1 = require("../../Theme/tokens/primitives/motion");
+const motion_2 = require("../../Theme/chakra/motion");
+const accordionColors_1 = require("./accordionColors");
+const HEADER_ACTION_RIGHT = "3.25rem";
+/** 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 }) => {
+    const { colors } = (0, useCustomTheme_1.useCustomTheme)();
+    const isDark = (0, accentText_1.isDarkCanvas)(colors.backgroundColor.main);
+    const border = colors.boxborder[200];
+    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, 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: "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, _d, _e;
+                    return ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [(0, jsx_runtime_1.jsxs)(react_2.Box, { as: "h2", position: item.headerAction ? "relative" : undefined, sx: item.headerAction
+                                    ? { "&:hover > button": { background: isExpanded ? expandedBg : softHover, ...(_a = item.customStyles) === null || _a === void 0 ? void 0 : _a.hoverbuttonStyle } }
+                                    : undefined, children: [(0, jsx_runtime_1.jsxs)(react_2.AccordionButton, { px: 4, py: 3, gap: 3, fontSize: "sm", 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)(),
+                                            ...(_b = item.customStyles) === null || _b === void 0 ? void 0 : _b.buttonStyle,
+                                            "&:hover": {
+                                                ...(_c = item.customStyles) === null || _c === void 0 ? void 0 : _c.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: "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 }) })] }), item.headerAction && ((0, jsx_runtime_1.jsx)(react_2.Flex, { position: "absolute", top: "50%", right: HEADER_ACTION_RIGHT, transform: "translateY(-50%)", align: "center", sx: (_d = item.customStyles) === null || _d === void 0 ? void 0 : _d.headerActionStyle, children: item.headerAction }))] }), (0, jsx_runtime_1.jsx)(react_2.AccordionPanel, { px: 4, pt: 1, pb: 4, fontSize: "sm", lineHeight: "1.5", color: bodyColor, ...item.panelProps, sx: (_e = item.customStyles) === null || _e === void 0 ? void 0 : _e.panelStyle, children: item.content })] }));
+                } }, idx));
+        }) }));
 };
 exports.default = Accordion;

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

@@ -1,15 +1,31 @@
 import { AccordionProps as ChakraAccordionProps, AccordionItemProps, AccordionButtonProps, AccordionPanelProps } from "@chakra-ui/react";
+/** Chakra's AccordionProps plus the header/content rows to render; each row can override its own button/panel/item styles. */
 export type AccordionProps = ChakraAccordionProps & {
+    /** One entry per accordion row, rendered in order. */
     items: {
+        /** Always-visible content of the row's toggle button. */
         header: React.ReactNode;
+        /** Panel body, shown while the row is expanded. */
         content: React.ReactNode;
+        /** Spread after the built-in style props (incl. `_hover`) — `bg`/`_hover` here replace, not merge, the expanded/hover highlight. */
         buttonProps?: AccordionButtonProps;
+        /** A control over the header's trailing edge, beside the button (a button inside a button is invalid); the header hover stays lit while the pointer is on it. Reserve its width in `header`. */
+        headerAction?: React.ReactNode;
+        /** Props spread onto the row's panel. */
         panelProps?: AccordionPanelProps;
+        /** Props spread onto the row's item wrapper. */
         itemProps?: AccordionItemProps;
+        /** Inline style overrides per part of this row. */
         customStyles?: {
+            /** Inline style for the header button. */
             buttonStyle?: React.CSSProperties;
+            /** Inline style applied to the header button on hover. */
             hoverbuttonStyle?: React.CSSProperties;
+            /** Overrides the action's default `right` (button padding + chevron slot); set it when `buttonStyle` changes the button padding. */
+            headerActionStyle?: React.CSSProperties;
+            /** Inline style for the panel. */
             panelStyle?: React.CSSProperties;
+            /** Inline style for the item wrapper. */
             itemStyle?: React.CSSProperties;
         };
     }[];

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

@@ -0,0 +1,11 @@
+import type { PaletteProps } from "../../Theme/tokens/types";
+export declare const getAccordionHoverColors: (colors: PaletteProps, isDark: boolean) => {
+    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;
+};