@djangocfg/ui-core 2.1.320 → 2.1.322

package/README.md

@@ -6,13 +6,9 @@
 
 # @djangocfg/ui-core
 
-Pure React UI library with 65+ components built on Radix UI + Tailwind CSS v4.
+Framework-agnostic React UI library: 70+ components on Radix + Tailwind v4, plus a router-adapter system that lets the same `<Link>` / `<Sidebar>` / `<SSRPagination>` work under Next.js, Vite, Electron, Wails, or plain React.
 
-**No Next.js dependencies** — works with Electron, Vite, CRA, and any React environment.
-
-**Part of [DjangoCFG](https://djangocfg.com)** — modern Django framework for production-ready SaaS applications.
-
-**[Live Demo & Props](https://djangocfg.com/demo/)**
+**Part of [DjangoCFG](https://djangocfg.com).** **[Live demo](https://djangocfg.com/demo/)**.
 
 ## Install
 
@@ -20,515 +16,102 @@ Pure React UI library with 65+ components built on Radix UI + Tailwind CSS v4.
 pnpm add @djangocfg/ui-core
 ```
 
-## Why ui-core?
-
-| Package | Use Case |
-|---------|----------|
-| `@djangocfg/ui-core` | Electron, Vite, CRA, any React app |
-| `@djangocfg/ui-tools` | Heavy tools with lazy loading |
-| `@djangocfg/ui-nextjs` | Next.js apps (extends ui-core) |
-
-## Components (65+)
-
-Components are organized by category in `components/`. All exports are available from the root:
-```tsx
-import { Button, Dialog, Table } from '@djangocfg/ui-core';
-```
-
-### Forms (18)
-`Button` `ButtonLink` `ButtonGroup` `Input` `Textarea` `Checkbox` `RadioGroup` `Switch` `Slider` `Label` `Form` `Field` `InputOTP` `PhoneInput` `InputGroup` `DownloadButton` `OTPInput` `Textarea`
-
-### Select (8)
-`Select` `Combobox` `MultiSelect` `MultiSelectPro` `MultiSelectProAsync` `CountrySelect` `LanguageSelect`
-
-> **Select Components** — All select components now support **icons** and **badges**:
-> - `Select` — Radix primitives with `icon` on trigger/item, `badge` on item
-> - `Combobox` — Searchable single-select with icon + badge in trigger and dropdown
-> - `MultiSelectPro` — Multi-select with colored badges, icons, animations
-> 
-> See `components/select/README.md` for full documentation.
-
-### Layout (8)
-`Card` `Separator` `Skeleton` `AspectRatio` `Sticky` `ScrollArea` `Resizable` `Section`
-
-### Overlay (9)
-`Dialog` `AlertDialog` `Sheet` `Drawer` `Popover` `HoverCard` `Tooltip` `ResponsiveSheet` `SidePanel`
-
-**`Dialog`** — `DialogContent` adds two props on top of Radix:
-
-- `fullscreen` — drops card chrome and stretches to `100dvw × 100dvh`.
-- `closeButton` — `undefined` (default `X`), `false` (none), or a `ReactNode` (wrap in `DialogClose`).
-
-```tsx
-<DialogContent
-  fullscreen
-  closeButton={
-    <DialogClose className="absolute right-4 top-4 inline-flex h-10 w-10 cursor-pointer items-center justify-center rounded-full border bg-background/90 hover:bg-accent">
-      <X className="h-4 w-4" />
-    </DialogClose>
-  }
->
-  …your fullscreen layout…
-</DialogContent>
-```
-
-**`SidePanel`** — non-modal side drawer (right by default, or left). Surrounding UI stays interactive; Esc-to-close + swipe-to-close via vaul. Prefer `Sheet` for modal side surfaces.
+## Imports
 
 ```tsx
-<SidePanel open={open} onOpenChange={setOpen} side="right">
-  <SidePanel.Content width="440px">
-    <SidePanel.Header>
-      <SidePanel.Title>Details</SidePanel.Title>
-      <SidePanel.Close className="ml-auto" />
-    </SidePanel.Header>
-    <SidePanel.Body>…</SidePanel.Body>
-    <SidePanel.Footer>…</SidePanel.Footer>
-  </SidePanel.Content>
-</SidePanel>
+import { Button, Card, Sidebar, SSRPagination } from '@djangocfg/ui-core/components';
+import { useIsMobile, useNavigate, useQueryParams } from '@djangocfg/ui-core/hooks';
+import { cn } from '@djangocfg/ui-core/lib';
 ```
 
-**`Drawer`** — modal vaul panel sliding from any edge (`top` / `right` / `bottom` / `left`). Sizes: `sm` `md` `lg` `xl` `full`, default `md`; or pass an explicit `width` / `height`. Pass `resizable` to drag the inner edge — auto-disabled on mobile (< 768px) unless `resizableOnDesktopOnly={false}`. Tune with `minSize` / `maxSize` (px). Resize is controlled via `resizedSize` + `onSizeChange` (uncontrolled if omitted). For built-in `localStorage` persistence use the `useDrawerSize(key, { axis, min, max })` hook — it returns `{ size, setSize, reset }` you wire into the same props. Backed by the centralized `useUIPersistedState` / `useUIPersistStore` (see below).
-
-```tsx
-<Drawer direction="right">
-  <DrawerTrigger asChild><Button>Open</Button></DrawerTrigger>
-  <DrawerContent direction="right" size="lg">
-    <DrawerHeader>
-      <DrawerTitle>Details</DrawerTitle>
-    </DrawerHeader>
-    …
-  </DrawerContent>
-</Drawer>
-```
-
-### Navigation (8)
-`Tabs` `Accordion` `Collapsible` `Command` `ContextMenu` `DropdownMenu` `Menubar` `NavigationMenu`
-
-`ContextMenuItem`, `DropdownMenuItem`, and `MenubarItem` accept `variant?: 'default' | 'destructive'`. The `destructive` variant turns the row red on focus — use it for delete/remove actions:
-
-```tsx
-<DropdownMenuItem variant="destructive" onClick={remove}>
-  <Trash className="mr-2 size-4" /> Delete
-</DropdownMenuItem>
-```
+## Components
 
-### Data (10)
-`Table` `Badge` `Avatar` `Progress` `Calendar` `Carousel` `Chart` `Toggle` `ToggleGroup` `DatePicker`
+Organized in `components/` by category — everything re-exported from the root barrel.
 
-### Feedback (5)
-`Alert` `Toaster` (Sonner) `Spinner` `Empty` `Preloader`
+| Category | Examples |
+|---|---|
+| **Forms** | `Button`, `ButtonLink`, `ButtonGroup`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Label`, `Form`, `Field`, `InputOTP`, `PhoneInput`, `InputGroup`, `DownloadButton` |
+| **Select** | `Select`, `Combobox`, `MultiSelect`, `MultiSelectPro`, `MultiSelectProAsync`, `CountrySelect`, `LanguageSelect` (all support icons + badges; `Select` accepts empty-string values) |
+| **Overlay** | `Dialog`, `AlertDialog`, `Sheet`, `Drawer`, `Popover`, `Tooltip`, `HoverCard`, `ResponsiveSheet`, `SidePanel` |
+| **Navigation** | `Link`, `Breadcrumb`, `BreadcrumbNavigation`, `Pagination`, `StaticPagination`, `SSRPagination`, `Sidebar` (full shadcn primitives), `Tabs`, `Accordion`, `Collapsible`, `Command`, `DropdownMenu`, `ContextMenu`, `Menubar`, `NavigationMenu` |
+| **Layout** | `Card`, `Section`, `Sticky`, `ScrollArea`, `Resizable`, `Separator`, `Skeleton`, `AspectRatio` |
+| **Data** | `Table`, `Badge`, `Avatar`, `Progress`, `Carousel`, `Calendar`, `DatePicker`, `DateRangePicker`, `Toggle`, `ToggleGroup`, `Chart*` |
+| **Feedback** | `Alert`, `Spinner`, `Empty`, `Preloader`, `Toaster` (Sonner) |
+| **Specialized** | `Kbd`, `CopyButton`, `CopyField`, `TokenIcon`, `Item`, `Portal`, `ImageWithFallback`, `Flag`, `LanguageFlag` |
+| **Effects** | `GlowBackground` |
 
-### Specialized (9)
-`Kbd` `TokenIcon` `Item` `Portal` `ImageWithFallback` `CopyButton` `CopyField` `Flag` `LanguageFlag`
+> Pagination, breadcrumb and sidebar live here (not in ui-nextjs). `SSRPagination` reads URL state through `useLocation` + `useQueryParams`, so it works under any router adapter.
 
-**`Flag`** / **`LanguageFlag`** — SVG country flags (3:2 aspect) backed by `country-flag-icons`. `Flag` takes an ISO 3166-1 alpha-2 `countryCode` and covers every ISO country (~270 entries); `LanguageFlag` resolves a locale (`'en'`, `'pt-BR'`, `'zh_CN'`) to a country and renders the flag. Both render `null` for unknown codes. Used by `LocaleSwitcher`, `PhoneInput`, and `CountrySelect` — no emoji fallbacks anywhere.
+## Hooks
 
 ```tsx
-<Flag countryCode="JP" rounded className="h-3 w-4" />
-<LanguageFlag code="pt-BR" rounded className="h-3 w-4" />
+import { useIsMobile, useMediaQuery, useShortcutModLabel } from '@djangocfg/ui-core/hooks';
+import { useNavigate, useLocation, useQueryParams, useRouter, useIsActive } from '@djangocfg/ui-core/hooks/router';
 ```
 
-Helper: `getLanguageCountryCode(locale)` returns the resolved alpha-2 code (or `null`). The static `LANGUAGE_TO_COUNTRY` map is exported for callers that need their own lookup.
-
-## Hooks (30+)
-
-Hooks are organized by domain inside the package (`src/hooks/<group>/`).
-Public import path is the single barrel:
-
-```tsx
-import { useIsMobile, useScroll, useNavigate } from '@djangocfg/ui-core/hooks';
-```
-
-### `dom/` — DOM & viewport
-
-| Hook | Description |
-|------|-------------|
-| `useScroll(target?)` | Reactive `{ x, y, direction, isScrolling }` for window or any scrollable element. `useSyncExternalStore` + module-level shared store + rAF throttle + passive listener. |
-| `useScrollPosition(target?)` / `useScrollDirection(target?)` / `useIsScrolling(target?)` | Single-field variants — re-render only when their slice changes. |
-| `useBodyScrollLock(locked)` | Lock body scroll while `locked=true`; counter-based (multi-consumer safe), iOS-safe via `position: fixed` fallback. |
-| `useCopy` | Copy to clipboard. |
-| `useImageLoader` | Image loading state. |
-
-### `media/` — viewport size
-
-| Hook | Description |
-|------|-------------|
-| `useMediaQuery(query)` | Raw media query — pass any CSS query string. Exports `BREAKPOINTS` constants (Tailwind v4 defaults). |
-| `useIsPhone()` | `< 640px` — phones only. |
-| `useIsMobile()` | `< 768px` — phones + small tablets. |
-| `useIsTabletOrBelow()` | `< 1024px` — phones + tablets. |
-
-### `state/` — state primitives
-
-| Hook | Description |
-|------|-------------|
-| `useDebounce` | Debounce values. |
-| `useDebouncedCallback` | Debounced callbacks. |
-| `useLocalStorage` / `useSessionStorage` | Type-safe wrappers with TTL. |
-| `useStoredValue` | Unified API over local/session storage. |
-
-### `device/` — environment detection
-
-| Hook | Description |
-|------|-------------|
-| `useBrowserDetect` | Browser detection (Chrome, Safari, in-app browsers, etc.). |
-| `useDeviceDetect` | Device detection (mobile, tablet, desktop, OS, etc.). |
-| `useShortcutModLabel()` | Returns `⌘` or `Ctrl` for shortcut hints (Apple vs Windows/Linux); pairs with `metaKey \|\| ctrlKey` handlers. |
-
-### Other groups
-
 | Group | Hooks |
-|-------|-------|
-| `feedback/` | `useToast`, `toast` (Sonner). |
-| `theme/` | `useResolvedTheme` — current resolved theme (light/dark/system). |
-| `time/` | `useCountdown`, `useCountdownFromSeconds`. |
-| `events/` | `useEventListener`, `events` (PubSub bus). |
-| `hotkey/` | `useHotkey`, `HotkeysProvider` (react-hotkeys-hook). |
-| `debug/` | `useDebugTools`. |
-| `router/` | See [Router Hooks](#router-hooks) below — its own subsection. |
-
-```tsx
-import { useMediaQuery, useIsPhone, useIsMobile, BREAKPOINTS } from '@djangocfg/ui-core/hooks'
-
-// semantic
-const isPhone  = useIsPhone()   // < 640px
-const isMobile = useIsMobile()  // < 768px
-
-// custom with constants
-const isNarrow = useMediaQuery(`(max-width: ${BREAKPOINTS.sm - 1}px)`)
-const isDark   = useMediaQuery('(prefers-color-scheme: dark)')
+|---|---|
+| **Router** (adapter-driven) | `useNavigate`, `useLocation`, `useQueryParams`, `useQueryState` (typed), `useRouter`, `useUrlBuilder`, `useSmartLink`, `useIsActive`, `useBackOrFallback` + parsers (`parseAsInteger`, `parseAsBoolean`, …) |
+| **Media** | `useIsMobile`, `useIsPhone`, `useIsTabletOrBelow`, `useMediaQuery` |
+| **Device** | `useDeviceDetect`, `useBrowserDetect`, `useShortcutModLabel` |
+| **State** | `useDebounce`, `useDebouncedCallback`, `useCountdown`, `useImageLoader`, `useMounted` |
+| **DOM** | `useEventListener` |
+| **Theme** | `useThemeColor`, `useThemePalette` (palette-aware hex colors for Canvas/SVG) |
+| **Hotkey** | `useHotkey`, `HotkeysProvider`, `useHotkeysContext` |
+| **Feedback** | `useToast`, `toast` (Sonner) |
+| **Debug** | `useDebugTools` |
 
-// scroll snapshot — direction-aware navbar
-const { direction, isScrolling } = useScroll()
-const hideNav = direction === 'down' && isScrolling
-```
+## Router adapters
 
-## Router Hooks
-
-Framework-agnostic navigation primitives — work on plain History API by default, plug into any router via the adapter pattern. Full docs in [`src/hooks/router/README.md`](./src/hooks/router/README.md).
-
-| Hook | Purpose |
-|------|---------|
-| `useLocation()` | Reactive `{ pathname, search, hash, href }`. |
-| `useLocationProperty(get, getSsr)` | Subscribe to ONE field — skip re-renders on unrelated changes. |
-| `useNavigate()` | `navigate`, `navigateExternal`, `push`, `replace`, `back`, `forward`. |
-| `useQueryParams()` | Record-style read/write of `?key=value` URL state. |
-| `useQueryState(key, parser)` | Typed `useState`-style hook bound to one URL key (with `clearOnDefault`). |
-| `useBackOrFallback()` | Smart Back that falls back to a route when there's no in-app history. |
-| `useUrlBuilder()` | Pure URL assembly: `build`, `withCurrentParams`. |
-| `useSmartLink(href)` | Make any element a link (cmd-click, middle-click, Enter, Space). |
-| `useIsActive(href)` | Boolean for nav-item highlighting. |
-| `useRouter()` | Convenience facade composing everything. |
-| `RouterAdapterProvider` | Swap the navigation backend. |
-| `parseAsString` / `parseAsInteger` / `parseAsFloat` / `parseAsBoolean` / `parseAsIsoDate` / `parseAsStringEnum` / `parseAsArrayOf` / `parseAsJson` | Parsers for `useQueryState`. Each has `.withDefault(value)`. |
+`<Link>`, `<Sidebar>`, `<SSRPagination>` and friends are wired through a small adapter system, so the same component renders correctly under any router.
 
 ```tsx
-import {
-  useNavigate,
-  useQueryState,
-  parseAsInteger,
-} from '@djangocfg/ui-core/hooks';
-
-const { navigate } = useNavigate();
-const [page, setPage] = useQueryState('page', parseAsInteger.withDefault(1));
+// Next.js host (e.g. apps/demo)
+import { LinkProvider } from '@djangocfg/ui-core/components';
+import NextLink from 'next/link';
 
-navigate('/products');
-setPage((p) => p + 1);  // ?page=2 — `page=1` is dropped (clearOnDefault)
+<LinkProvider value={NextLink}>{children}</LinkProvider>
 ```
 
-### Next.js adapter
-
-In Next apps, mount both adapters once near the root so navigation flows through `next/navigation` (server components + prefetch keep working) and `<Link>` delegates to `next/link`:
+When no adapter is mounted, `<Link>` falls back to a plain `<a>` and routes clicks through the History API. `@djangocfg/layouts/BaseApp` mounts the Next adapters by default.
 
-```tsx
-import { NextRouterAdapter, NextLinkProvider } from '@djangocfg/ui-core/adapters/nextjs';
-
-<NextRouterAdapter>
-  <NextLinkProvider>
-    <App />
-  </NextLinkProvider>
-</NextRouterAdapter>
-```
+## Schema-driven configurators
 
-`next` is an **optional peer dependency** — Wails / Electron / Vite consumers don't pull it in. `@djangocfg/layouts/BaseApp` mounts both adapters automatically.
-
-## Theme Palette Hooks
-
-Hooks for accessing theme colors from CSS variables (useful for Canvas, SVG, charts, diagrams, etc.):
-
-| Hook / Util | Description |
-|-------------|-------------|
-| `useThemePalette()` | Full hex color palette from CSS variables |
-| `useThemeColor(var, opacity?)` | Single color by CSS var name — lighter alternative |
-| `useStylePresets()` | Pre-built `{ fill, stroke, color }` configs for diagrams |
-| `useBoxColors()` | Semi-transparent RGBA colors for boxes/containers |
-| `alpha(hex, opacity)` | Convert hex color to `rgba()` string |
+`@djangocfg/ui-core/lib` exports a portable JSON Schema 7 subset (`CustomJsonSchema7`, `CustomJsonUiSchema7`, `CustomJsonUiGroup`, `CustomJsonUiDisabledWhenRule`) for packages that ship configurator schemas without taking a runtime dependency on RJSF.
 
 ```tsx
-import {
-  useThemePalette,
-  useThemeColor,
-  useStylePresets,
-  useBoxColors,
-  alpha,
-} from '@djangocfg/ui-core/styles/palette';
-
-function MyCanvas() {
-  const palette = useThemePalette();
-
-  // Use in Canvas / inline styles
-  ctx.fillStyle = palette.primary;            // '#a855f7' (theme-aware)
-  ctx.fillStyle = alpha(palette.primary, 0.3); // 'rgba(168, 85, 247, 0.3)'
-}
-
-function MyWaveform() {
-  // Lighter: only subscribes to 'primary', not the entire palette
-  const primary         = useThemeColor('primary');        // '#a855f7'
-  const primaryFaded    = useThemeColor('primary', 0.3);   // 'rgba(168, 85, 247, 0.3)'
-  const errorBackground = useThemeColor('destructive', 0.1);
-}
-
-function MyChart() {
-  const presets = useStylePresets();
-  // presets.primary = { fill: '#a855f7', stroke: '#a855f7', color: '#fff' }
-  // presets.success = { fill: '#22c55e', stroke: '#22c55e', color: '#fff' }
-  // presets.danger  = { fill: '#ef4444', stroke: '#ef4444', color: '#fff' }
-  // presets.warning = { fill: '#f59e0b', stroke: '#f59e0b', color: '#fff' }
-  // presets.info    = { fill: '#3b82f6', stroke: '#3b82f6', color: '#fff' }
-
-  const boxes = useBoxColors();
-  // boxes.primary = 'rgba(168, 85, 247, 0.15)'  (0.3 in dark mode)
-  // boxes.success = 'rgba(34, 197, 94, 0.15)'
-  // etc.
-
-  return <Chart colors={[presets.success.fill, presets.warning.fill]} />;
-}
+import type { CustomJsonSchema7, CustomJsonUiSchema7 } from '@djangocfg/ui-core/lib';
 ```
 
-### Color Utilities (HSL conversion)
-
-```tsx
-import { hslToHex, hslToRgbString, hslToRgba } from '@djangocfg/ui-core/styles/palette';
-
-hslToHex('217 91% 60%');        // '#3b82f6'
-hslToRgbString('217 91% 60%'); // 'rgb(59, 130, 246)'
-hslToRgba('217 91% 60%', 0.5); // 'rgba(59, 130, 246, 0.5)'
-```
+`@djangocfg/ui-tools/json-form` accepts these directly (it's a union with `RJSFSchema`).
 
-## Dialog Service
-
-Zustand-powered dialog service replacing native `window.alert`, `window.confirm`, `window.prompt` with shadcn dialogs. Also provides `window.dialog.auth()` for triggering authentication dialogs.
+## Dialog service
 
 ```tsx
-import { DialogProvider, useDialog } from '@djangocfg/ui-core/lib/dialog-service';
-
-// Wrap your app with DialogProvider (already included in BaseApp)
-function App() {
-  return (
-    <DialogProvider>
-      <YourApp />
-    </DialogProvider>
-  );
-}
-
-// Use via React hook
-function Component() {
-  const { alert, confirm, prompt, auth } = useDialog();
-
-  const handleDelete = async () => {
-    const confirmed = await confirm({
-      title: 'Delete item?',
-      message: 'This action cannot be undone.',
-      variant: 'destructive',
-    });
-    if (confirmed) {
-      // Delete...
-    }
-  };
-
-  const handleProtected = async () => {
-    const didAuth = await auth({ message: 'Please sign in to continue' });
-    if (didAuth) {
-      // User navigated to auth
-    }
-  };
-}
-
-// Or use globally from anywhere (vanilla JS, libraries, etc.)
-window.dialog.alert({ message: 'Hello!' });
-const ok = await window.dialog.confirm({ message: 'Are you sure?' });
-const name = await window.dialog.prompt({ message: 'Enter your name:' });
-const didAuth = await window.dialog.auth({ message: 'Session expired' });
-```
-
-## Usage
+import { DialogProvider, useDialog, dialog } from '@djangocfg/ui-core/lib/dialog-service';
 
-```tsx
-import { Button, Card, Input } from '@djangocfg/ui-core';
-import { toast } from '@djangocfg/ui-core/hooks';
-
-function Example() {
-  return (
-    <Card>
-      <Input placeholder="Email" />
-      <Button onClick={() => toast.success('Saved!')}>
-        Submit
-      </Button>
-    </Card>
-  );
-}
+dialog.confirm({ title: 'Delete?', description: 'This is permanent.' });
 ```
 
-## Electron Usage
+## Logger
 
 ```tsx
-// In Electron renderer process
-import { Button, Dialog, useMediaQuery } from '@djangocfg/ui-core';
-import '@djangocfg/ui-core/styles/globals';
-
-function App() {
-  const isMobile = useMediaQuery('(max-width: 768px)');
-
-  return (
-    <Dialog>
-      <Button>Open Dialog</Button>
-    </Dialog>
-  );
-}
+import { createLogger } from '@djangocfg/ui-core/lib';
+const log = createLogger('MyComponent');
+log.info('user logged in', { userId: 123 });
 ```
 
-## Styling (Next.js / Tailwind v4)
-
-In your app's `globals.css`, import the package styles and add `@source` directives for every workspace package that ships Tailwind classes. Tailwind v4 does **not** scan `node_modules` automatically.
+## Styles
 
 ```css
-/* globals.css */
-@import "@djangocfg/ui-nextjs/styles";   /* ui-core + ui-nextjs tokens & theme */
-@import "@djangocfg/layouts/styles";     /* layout tokens */
-@import "@djangocfg/ui-tools/styles";    /* heavy tool components */
-@import "@djangocfg/debuger/styles";     /* debug panel (if used) */
-@import "tailwindcss";
-```
-
-Each package that ships Tailwind classes exposes a `./styles` entry containing a single `@source` directive — no manual path configuration needed.
-
-For non-Next.js (Electron, Vite):
-
-```tsx
-import '@djangocfg/ui-core/styles/globals';
-```
-
-## Exports
-
-| Path | Content |
-|------|---------|
-| `@djangocfg/ui-core` | All components & hooks |
-| `@djangocfg/ui-core/components` | Components only |
-| `@djangocfg/ui-core/hooks` | Hooks only (incl. router hooks) |
-| `@djangocfg/ui-core/adapters/nextjs` | `<NextRouterAdapter>` + `<NextLinkProvider>` for Next.js apps (optional peer: `next`) |
-| `@djangocfg/ui-core/lib` | Utilities (cn, etc.) |
-| `@djangocfg/ui-core/lib/dialog-service` | Dialog service |
-| `@djangocfg/ui-core/utils` | Runtime utilities (emitRuntimeError) |
-| `@djangocfg/ui-core/styles` | CSS |
-| `@djangocfg/ui-core/styles/palette` | Theme palette hooks & utilities |
-
-## Persisted UI State
-
-Centralized localStorage-backed store for component preferences. One zustand+persist store under `djangocfg.ui.state`, scoped by category. Single migration surface, single «reset all» button.
-
-### Per-component hooks
-
-```tsx
-// Drawer size
-const drawer = useDrawerSize('settings', { min: 320, max: 900 });
-<DrawerContent resizable resizedSize={drawer.size} onSizeChange={drawer.setSize} />
-
-// Tabs
-const { tab, setTab } = useTabsState('settings-page', 'general', {
-  allowed: ['general', 'appearance', 'advanced'],
-});
-<Tabs value={tab} onValueChange={setTab}>...</Tabs>
-
-// Accordion
-const { value, setValue } = useAccordionMultipleState('sidebar', ['general']);
-<Accordion type="multiple" value={value} onValueChange={setValue}>...</Accordion>
+@import '@djangocfg/ui-core/styles/globals.css';
 ```
 
-Need persist for something not on this list (table prefs, sidebar state, etc.)? Use the generic `useUIPersistedState` directly — it's the same API every per-component hook is built on top of.
-
-### Generic API
-
-```tsx
-import {
-  useUIPersistedState,
-  useUIPersistedStateThrottled,
-  useUIPersistStore,
-} from '@djangocfg/ui-core';
-
-// Build your own per-component hook
-const { value, setValue, reset, hydrated } = useUIPersistedState(
-  'my-scope', 'instance-key', defaultValue,
-  { sanitize: (raw) => /* clamp / validate / migrate */ raw },
-);
-
-// Throttled writes for high-frequency updates (live splitter, etc.)
-useUIPersistedStateThrottled('splitter', 'main', 50, 200 /* ms */);
-```
-
-### Inspection / DevTools
-
-```tsx
-useUIPersistStore.getState().getAll();        // snapshot of all scopes
-useUIPersistStore.getState().listScopes();    // ['drawer-size:width', 'tabs', ...]
-useUIPersistStore.getState().clearScope('tabs');
-useUIPersistStore.getState().clearAll();      // reset all UI preferences
-```
-
-## Runtime Error Emitter
-
-Emit runtime errors as events (caught by ErrorTrackingProvider in layouts):
-
-```tsx
-import { emitRuntimeError } from '@djangocfg/ui-core/utils';
-
-try {
-  doSomething();
-} catch (error) {
-  emitRuntimeError('MyComponent', 'Operation failed', error, { extra: 'context' });
-}
-```
-
-## Links
-
-`<Link>` and `<ButtonLink>` ship in `ui-core` itself — no Next.js required.
-Default behavior renders `<a>` and routes clicks through `useNavigate`.
-
-In Next.js apps, mount `NextLinkProvider` (from `@djangocfg/ui-core/adapters/nextjs`)
-near the root and the same components delegate to `next/link` automatically.
-`@djangocfg/layouts/BaseApp` does this for you.
-
-```tsx
-import { Link, ButtonLink } from '@djangocfg/ui-core/components';
-
-<Link href="/about">About</Link>
-<ButtonLink href="/docs" variant="outline">Docs</ButtonLink>
-```
-
-## What's NOT included (use ui-nextjs)
-
-These features require Next.js or browser storage APIs:
-
-- `Sidebar` — `'use client'` heavy, lives in ui-nextjs
-- `Breadcrumb`, `BreadcrumbNavigation` — same
-- `Pagination`, `SSRPagination` — same
-- `DownloadButton` — uses localStorage
-- `useTheme` — uses next-themes
-
 ## Requirements
 
-- React >= 18 or >= 19
-- Tailwind CSS >= 4
+- React ≥ 19
+- Tailwind CSS ≥ 4
 
 ---
 
-**[Full documentation & examples](https://djangocfg.com/demo/)**
+**[djangocfg.com](https://djangocfg.com)**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.320",
+  "version": "2.1.322",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -91,7 +91,7 @@
     "playground": "playground dev"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.320",
+    "@djangocfg/i18n": "^2.1.322",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -160,9 +160,9 @@
     "vaul": "1.1.2"
   },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.320",
+    "@djangocfg/i18n": "^2.1.322",
     "@djangocfg/playground": "workspace:*",
-    "@djangocfg/typescript-config": "^2.1.320",
+    "@djangocfg/typescript-config": "^2.1.322",
     "@types/node": "^24.7.2",
     "@types/react": "^19.1.0",
     "@types/react-dom": "^19.1.0",

package/src/components/index.ts

@@ -66,6 +66,57 @@ export { Collapsible, CollapsibleContent, CollapsibleTrigger } from './navigatio
 export { Command, CommandDialog, CommandEmpty, CommandGroup, CommandInput, CommandItem, CommandList, CommandSeparator, CommandShortcut } from './navigation/command';
 export { Link, LinkProvider, LinkComponentContext, useLinkComponent } from './navigation/link';
 export type { LinkProps, LinkComponent, LinkComponentProps, LinkProviderProps } from './navigation/link';
+export {
+  Breadcrumb,
+  BreadcrumbEllipsis,
+  BreadcrumbItem,
+  BreadcrumbLink,
+  BreadcrumbList,
+  BreadcrumbPage,
+  BreadcrumbSeparator,
+  BreadcrumbNavigation,
+} from './navigation/breadcrumb';
+export type { BreadcrumbNavigationItem, BreadcrumbNavigationProps } from './navigation/breadcrumb';
+export {
+  Pagination,
+  PaginationContent,
+  PaginationEllipsis,
+  PaginationItem,
+  PaginationLink,
+  PaginationNext,
+  PaginationPrevious,
+  StaticPagination,
+  SSRPagination,
+  useDRFPagination,
+  useDRFPaginationInfo,
+} from './navigation/pagination';
+export type { DRFPaginatedResponse } from './navigation/pagination';
+export {
+  Sidebar,
+  SidebarContent,
+  SidebarFooter,
+  SidebarGroup,
+  SidebarGroupAction,
+  SidebarGroupContent,
+  SidebarGroupLabel,
+  SidebarHeader,
+  SidebarInput,
+  SidebarInset,
+  SidebarMenu,
+  SidebarMenuAction,
+  SidebarMenuBadge,
+  SidebarMenuButton,
+  SidebarMenuItem,
+  SidebarMenuSkeleton,
+  SidebarMenuSub,
+  SidebarMenuSubButton,
+  SidebarMenuSubItem,
+  SidebarProvider,
+  SidebarRail,
+  SidebarSeparator,
+  SidebarTrigger,
+  useSidebar,
+} from './navigation/sidebar';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Layout