@djangocfg/ui-core 2.1.418 → 2.1.420

package/README.md

@@ -6,9 +6,9 @@
 
 # @djangocfg/ui-core
 
-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.
+Framework-agnostic React UI library: 70+ shadcn/Radix components on Tailwind v4, semantic theme tokens, palette hooks for Canvas/SVG, plus a router-adapter system that lets the same `<Link>` / `<Sidebar>` / `<SSRPagination>` work under Next.js, Vite, Electron, Wails, or plain React.
 
-**Part of [DjangoCFG](https://djangocfg.com).** **[Live demo](https://djangocfg.com/demo/)**.
+**Part of [DjangoCFG](https://djangocfg.com). [Live demo](https://djangocfg.com/demo/).**
 
 ## Install
 
@@ -16,287 +16,123 @@ Framework-agnostic React UI library: 70+ components on Radix + Tailwind v4, plus
 pnpm add @djangocfg/ui-core
 ```
 
-## Imports
+Next.js apps should import from [`@djangocfg/ui-nextjs`](../ui-nextjs) instead — it re-exports everything here plus Next-specific bindings.
 
-```tsx
-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';
-import { UiProviders } from '@djangocfg/ui-core/providers';
-```
-
-## Root providers
-
-Mount `<UiProviders>` once at the top of your app — it bundles the overlay
-and imperative services every ui-core / ui-tools component expects:
-
-```tsx
-import { UiProviders } from '@djangocfg/ui-core/providers';
+Import styles once at the app root — use the golden path, which pins everything
+to the right cascade layers so import order can't break layout utilities:
 
-export function Root({ children }: { children: React.ReactNode }) {
-  return <UiProviders>{children}</UiProviders>;
-}
+```css
+/* FIRST style import in your app entry CSS */
+@import "@djangocfg/ui-core/styles/full";   /* Tailwind v4 + tokens + base + utilities, layer-safe */
 ```
 
-Includes:
-- `<TooltipProvider>` (Radix tooltip root, `delayDuration={100}` by default)
-- `<DialogProvider>` (installs `window.dialog.*` + renders active dialogs)
-- `<Toaster>` (Sonner toast portal)
-
-Opt out per-service: `<UiProviders noToaster noDialogService>`.
-
-**Do not nest a second `<TooltipProvider>` inside library components** —
-that creates a separate context scope and breaks the tooltip↔provider link.
+The plain `@djangocfg/ui-core/styles` entry does NOT import Tailwind and emits
+its CSS unlayered — if you use it you own the layer ordering (import
+`tailwindcss` first). See `src/styles/README.md` § App setup for why. Prefer
+`…/styles/full`.
 
-## Components
-
-Organized in `components/` by category — everything re-exported from the root barrel.
-
-| Category | Examples |
-|---|---|
-| **Forms** | `Button`, `ButtonLink`, `ButtonGroup`, `Input`, `Textarea`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `Label`, `Form`, `Field`, `InputOTP`, `PhoneInput`, `InputGroup`, `DownloadButton` |
-| **Select** | `Select`, `Combobox`, `ComboboxAsync`, `MultiSelect`, `MultiSelectPro`, `MultiSelectProAsync`, `CountrySelect`, `LanguageSelect` (all support icons + badges; `Select` accepts empty-string values; `ComboboxAsync` is the single-select counterpart to `MultiSelectProAsync` for server-side typeahead) |
-| **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`, `MenuBuilder` (declarative data-driven menu) |
-| **Theme** | `ThemeProvider`, `ThemeToggle`, `ForceTheme`, `ThemeOverride`, `useThemeContext`, `useForcedTheme` — framework-agnostic theme runtime |
-| **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) |
-| **Boundary** | `Boundary` (React error boundary with `silent`/`inline`/`card`/`fullscreen` variants, `resetKeys`, custom `fallback`) |
-| **Specialized** | `Kbd`, `CopyButton`, `CopyField`, `TokenIcon`, `Item`, `Portal`, `ImageWithFallback`, `Flag`, `LanguageFlag` |
-| **Effects** | `GlowBackground` |
-
-### Boundary
+## Quick start
 
 ```tsx
-import { Boundary, useBoundary } from '@djangocfg/ui-core';
+import { UiProviders, Button, Card } from '@djangocfg/ui-core';
 
-<Boundary variant="silent"><ChatLauncher /></Boundary>
-<Boundary variant="card" resetKeys={[pathname]}><Panel /></Boundary>
+<UiProviders>
+  <Card><Button>Hello</Button></Card>
+</UiProviders>
 ```
 
-Variants: `silent` / `inline` / `card` / `fullscreen`. Plus `useBoundary()` hook for async errors, `resetKeys`, `onReset`, custom `fallback` / `FallbackComponent`, and safe re-render guarantees.
-
-Full docs and patterns: [`src/components/boundary/README.md`](./src/components/boundary/README.md).
-
-For automatic backend reporting use `MonitorBoundary` from `@djangocfg/layouts`.
-
-
-> Pagination, breadcrumb and sidebar live here (not in ui-nextjs). `SSRPagination` reads URL state through `useLocation` + `useQueryParams`, so it works under any router adapter.
+`<UiProviders>` mounts Tooltip / Dialog / Toast / Theme provider in the right order. **Mount it once at the root** — library components (and everything in `@djangocfg/ui-tools`) trust it to be there and never nest their own (a second `TooltipProvider` is the canonical "Tooltip must be used within TooltipProvider" trap).
 
-## Hooks
+## Catalogue
 
-```tsx
-import { useIsMobile, useMediaQuery, useShortcutModLabel } from '@djangocfg/ui-core/hooks';
-import { useNavigate, useLocation, useQueryParams, useRouter, useIsActive } from '@djangocfg/ui-core/hooks/router';
-```
-
-| Group | Hooks |
+| Group | Examples |
 |---|---|
-| **Router** (adapter-driven) | `useNavigate`, `useLocation`, `useLocationProperty`, `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** | `useResolvedTheme` (light/dark detection), `useThemeColor`, `useThemePalette` (palette-aware hex colors for Canvas/SVG) |
-| **Hotkey** | `useHotkey` (smart `inInput` + `preventDefault` policy), `useHotkeyChord` (sequences), `formatHotkey('mod+k') → ⌘K`, `useHotkeyHelp` (auto cheat-sheet) |
-| **Audio** | `createSoundBus`, `useNotificationSounds`, `useAudioPrefs`, `useSoundEffect` — Safari unlock, mute persist, per-event toggles + volume scale, native-host bridge |
-| **Tabs** | `useActiveTab`, `useIsTabActive`, `useIsTabLeader` — cross-tab focus + leader election via BroadcastChannel |
-| **Feedback** | `useToast`, `toast` (Sonner) |
-| **Debug** | `useDebugTools` |
+| `components/data/` | Avatar · Badge · Card · Table · BalancedText · Skeleton |
+| `components/forms/` | Button · Input · Textarea · Select · Switch · Checkbox · Slider · Form |
+| `components/feedback/` | Alert · Toast · Banner · Progress · Spinner |
+| `components/overlay/` | Dialog · Drawer · Popover · Tooltip · HoverCard · Sheet · ContextMenu · DropdownMenu |
+| `components/navigation/` | Sidebar · Tabs · Breadcrumb · Pagination · NavigationMenu · Command |
+| `components/layout/` | Container · Grid · Stack · Separator · ScrollArea · Sticky |
+| `components/select/` | Combobox · MultiSelect |
+| `components/effects/` | Glass · Marquee · Backdrop |
+| `components/specialized/` | Accordion · Collapsible · Toggle · Calendar · DatePicker |
+| `components/boundary/` | ErrorBoundary |
+
+Imports stay flat — group folders are organisational.
+
+## Hooks (`/hooks`)
+
+| Topic | Hooks |
+|---|---|
+| `dom/` | `useSize` · `useResizeObserver` · `useMeasure` · `useMutationObserver` · `useIntersection` |
+| `device/` | `useIsMobile` · `useMediaQuery` · `useOnline` · `useViewportSize` · `useOrientation` |
+| `state/` | `useLocalStorage` · `useSessionStorage` · `useToggle` · `useCounter` · `useDebouncedValue` |
+| `events/` | `useEventListener` · `useClickOutside` · `useKeyPress` · `useFocusWithin` |
+| `theme/` | `useTheme` · `useResolvedTheme` · `useThemePreset` |
+| `feedback/` | `useToast` · `useDialog` · `useClipboard` · `useConfirm` |
+| `hotkey/` | `useHotkey` (single key + chord) |
+| `audio/` | `useBeep` · `useSpeak` (Web Speech) |
+| `tabs/` | `useCrossTab` (BroadcastChannel coordination) |
+| `media/` | `useMediaPermissions` · `useUserMedia` · `useDevices` |
+| `time/` | `useNow` · `useInterval` · `useTimeout` |
+| `router/` | `useLink` · `useRouter` (router-adapter consumer) |
+
+## Lib utilities (`/lib`)
+
+- `cn(...)` — `clsx` + `tailwind-merge` shortcut
+- `getIntensity(value, thresholds)` — quantise values into discrete bins (heatmaps, gauges)
+- `createLogger()` — leveled console logger
+- `dialog-service` — imperative `confirm()` / `alert()` / `prompt()` returning promises
+- `persist` — typed localStorage / sessionStorage hooks
+- `pretext` (subpath `@djangocfg/ui-core/lib/pretext`) — DOM-free text measurement via [@chenglou/pretext](https://github.com/chenglou/pretext); powers `<BalancedText>` and is the primitive for non-CSS line balancing
 
 ## Router adapters
 
-`<Link>`, `<Sidebar>`, `<SSRPagination>` and friends are wired through a small adapter system, so the same component renders correctly under any router.
-
-```tsx
-// Next.js host (e.g. apps/demo)
-import { LinkProvider } from '@djangocfg/ui-core/components';
-import NextLink from 'next/link';
-
-<LinkProvider value={NextLink}>{children}</LinkProvider>
-```
-
-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.
-
-## Hotkeys
-
-```tsx
-import { useHotkey, formatHotkey, useHotkeyChord } from '@djangocfg/ui-core/hooks';
-
-// Smart defaults — auto-detects modifiers vs bare keys:
-useHotkey('mod+k', openPalette);          // ⌘K everywhere, incl. inputs; preventDefault auto
-useHotkey('/', focusSearch);              // bare key — skipped inside inputs
-useHotkey('escape', closeModal);          // always fires in inputs (blur / close pattern)
-useHotkey('?', openHelp, { description: 'Show shortcuts' });  // registers in cheat-sheet
-
-// Linear-style chords:
-useHotkeyChord(['g', 't'], () => router.push('/tasks'));
-
-// OS-aware tooltips:
-formatHotkey('mod+/')   // → '⌘/' on Mac, 'Ctrl+/' elsewhere
-formatHotkey('g t')     // → 'G then T'
-```
-
-Built on `react-hotkeys-hook` with an opinionated policy: modifier-combos and `escape` fire inside `<input>` / `<textarea>` / `[contenteditable]` by default; bare keys don't, so they won't hijack typing. Override per-call with `inInput: true | false`.
-
-`useHotkeyHelp()` reads a module-level registry populated by every `useHotkey(..., { description })` call — drop it into a `?` cheat-sheet dialog with two lines.
-
-## Audio
-
-Notification sounds with Safari unlock, persisted mute, and a side-channel for native hosts.
-
-```tsx
-import { useNotificationSounds, useSoundEffect } from '@djangocfg/ui-core/hooks';
-
-// Map event → URL + persisted mute + per-event toggles
-type Event = 'received' | 'mention' | 'error';
-const sounds = useNotificationSounds<Event>({
-  storageKey: 'myapp.audio',
-  sounds: { received: '/sfx/r.mp3', mention: '/sfx/m.mp3', error: '/sfx/e.mp3' },
-});
-
-onMessage = (m) => sounds.play('received');
-toggle    = () => sounds.toggleMute();
-sounds.muted    // boolean, persisted
-sounds.isSilent // true if no sounds wired or silenced
-
-// One-shot single asset (no persistence, no toggles)
-const ding = useSoundEffect('/sfx/ding.mp3');
-<Button onClick={() => { ding.play(); submit(); }} />
-```
-
-**Native-host bridge.** When a wrapper (Electron / Wails / Tauri) plays sounds outside the browser, set `silenced: true` and pipe `onSoundEvent` to your bridge — web playback stays silent while the backend gets the trigger:
-
-```tsx
-useNotificationSounds({
-  storageKey: 'cmdop.audio',
-  silenced: true,
-  onSoundEvent: (event) => window.go.playSound(event),
-});
-```
-
-**Per-event volume scale.** Master volume is multiplied by an optional per-event factor so different sounds can be balanced without juggling source files:
-
-```tsx
-useNotificationSounds<Event>({
-  storageKey: 'myapp.audio',
-  sounds: { received: '/r.mp3', error: '/e.mp3', mention: '/m.mp3' },
-  eventVolumes: {
-    error: 0.25,    // soft ack — destructive UI is the loud signal
-    mention: 1,     // personal — louder than baseline
-    received: 0.7,
-  },
-});
-```
-
-The bus respects `prefers-reduced-motion`, `prefers-reduced-data`, and `visibilityState === 'hidden'` by default (each is an opt-out). Multi-component sync: same `storageKey` from different surfaces shares the same store.
-
-Lower level: `createSoundBus<E>({ sounds, getMuted, getVolume, isEnabled })` exposes the raw bus if you need to wire your own React state. `getVolume(event)` receives the event so you can scale per-fire.
-
-For an opinionated, fully-wired example with bundled audio assets see `useChatAudio` in [`@djangocfg/ui-tools`](../../ui-tools/src/tools/Chat/README.md#audio) — it inlines six notification mp3s into the lazy chat chunk as `data:`-URLs so consumers need no asset setup.
-
-## Cross-tab coordination
-
-```tsx
-import { useActiveTab, useIsTabLeader } from '@djangocfg/ui-core/hooks';
-
-const { isActive, isLeader, tabId } = useActiveTab();
-// isActive  — this tab has user focus (visibilitychange + focus/blur)
-// isLeader  — elected leader among open tabs (stable; oldest tab wins)
-// tabId     — stable per-tab id (sessionStorage, survives in-tab reload)
-```
-
-Single shared coordinator over `BroadcastChannel` — leader election runs locally on every tab from the same peer-set view, no server. Use the leader flag to dedupe side-effects across tabs: only the leader mutates `document.title` / favicon, holds the websocket, plays a sound; followers stay silent but still read state. Zustand-backed, SSR-safe, single-tab fallback when `BroadcastChannel` is unavailable.
-
-## Schema-driven configurators
-
-`@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 type { CustomJsonSchema7, CustomJsonUiSchema7 } from '@djangocfg/ui-core/lib';
-```
-
-`@djangocfg/ui-tools/json-form` accepts these directly (it's a union with `RJSFSchema`).
+The router-aware components (`Sidebar`, `Link`, `SSRPagination`) read the active router via `RouterAdapterProvider`. Ship the adapter that matches your host:
 
-## Dialog service
-
-```tsx
-import { DialogProvider, useDialog, dialog } from '@djangocfg/ui-core/lib/dialog-service';
-
-dialog.confirm({ title: 'Delete?', description: 'This is permanent.' });
-```
-
-## Logger
-
-```tsx
-import { createLogger } from '@djangocfg/ui-core/lib';
-const log = createLogger('MyComponent');
-log.info('user logged in', { userId: 123 });
-```
-
-## Styles & Theming
-
-```css
-/* In your app's globals.css — import BEFORE @import "tailwindcss" */
-@import '@djangocfg/ui-nextjs/styles'; /* re-exports ui-core styles */
-```
-
-### Semantic color tokens
+| Adapter | Source |
+|---|---|
+| Next.js App Router | `@djangocfg/ui-nextjs` (auto-wired) |
+| Vite / SPA (`react-router`) | `@djangocfg/ui-core/adapters/react-router` |
+| Plain `<a>` fallback | default (no adapter) |
 
-All colors are CSS custom properties registered in `@theme` so Tailwind generates utility classes.
-**Never use raw Tailwind color-scale classes** (`amber-500`, `green-100`) in components — use
-semantic tokens that adapt to both light and dark themes automatically.
+## Theming (`/styles`)
 
-#### Status surfaces — banners and alerts
+Tailwind v4 with semantic tokens, not raw color scales:
 
 ```tsx
-{/* Warning */}
-<div className="flex gap-2 rounded-md border border-warning-border/40
-                bg-warning-background px-3 py-2 text-xs text-warning-foreground">
-  <Icon className="text-warning" />
-  <span>You're on a preview plan.</span>
-</div>
+<Card className="bg-card border-border text-foreground" />
+<Button className="bg-primary text-primary-foreground" />
+<Alert className="bg-warning-background text-warning-foreground border-warning-border" />
 ```
 
-Each status (`warning` · `success` · `destructive` · `info`) exposes four classes:
+Tokens live in `:root` / `.dark` as fully-wrapped CSS colors; `@theme inline` exposes them as `--color-X` references, so opacity modifiers (`bg-card/40`, `border-foreground/20`) resolve via `color-mix` for **every** semantic token.
 
-| Class | Role |
-|---|---|
-| `bg-*-background` | Banner fill |
-| `text-*-foreground` | Readable body text |
-| `border-*-border` | Border ring |
-| `text-*` / `bg-*` | Icon / accent color |
-
-#### Code surface
+`@custom-variant dark (&:where(.dark, .dark *))` binds the `dark:` variant to the `.dark` class on `<html>` (not `prefers-color-scheme`) — every theme-switcher in this monorepo toggles that class.
 
-`bg-code` · `text-code-foreground` · `border-code-border` — used by PrettyCode, MarkdownMessage code fences.
-`bg-code-inline` · `text-code-inline-foreground` — for inline `<code>` chips.
+**Programmatic theme colors** for Canvas / SVG / Mermaid:
 
-### Playground
+```ts
+import { useThemeColor, alpha, useStylePresets } from '@djangocfg/ui-core/styles/palette';
 
-```bash
-pnpm playground   # opens component explorer with live theme preview
+const primary = useThemeColor('primary');           // #00d9ff (hex, not oklch)
+const dim = alpha(primary, 0.15);                   // 'rgba(0, 217, 255, 0.15)'
+const { success, warning, danger } = useStylePresets();
 ```
 
-The **Theme / Tokens** story shows every semantic token in both themes — use it to validate
-changes before syncing CSS to consumers. See `src/styles/README.md` for the full token reference
-and the manual sync workflow for local package development.
+Always hex-strings — `color-mix(...)` / `oklch(...)` syntax is rejected by Canvas2D fillStyle.
 
-### Programmatic colors (Canvas / SVG)
+[Live playground](https://djangocfg.com/demo/) covers all tokens, presets, and dark-mode pairs.
 
-```tsx
-import { useThemePalette, alpha } from '@djangocfg/ui-core/styles/palette';
+## Maintenance rule
 
-const palette = useThemePalette();
-ctx.fillStyle = alpha(palette.primary, 0.3); // hex → rgba, updates on theme switch
-```
+After any change to components or hooks — update this README and bump the package patch version. Consumers pin to npm versions; surface drift in this file is the canonical changelog.
 
 ## Requirements
 
-- React ≥ 19
-- Tailwind CSS ≥ 4
+- React 18 or 19
+- Tailwind CSS v4 (host imports `@djangocfg/ui-core/styles`)
 
----
+## License
 
-**[djangocfg.com](https://djangocfg.com)**
+MIT — © djangocfg.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.418",
+  "version": "2.1.420",
   "description": "Pure React UI component library without Next.js dependencies - for Electron, Vite, CRA apps",
   "keywords": [
     "ui-components",
@@ -63,6 +63,11 @@
       "import": "./src/lib/dialog-service/index.ts",
       "require": "./src/lib/dialog-service/index.ts"
     },
+    "./lib/pretext": {
+      "types": "./src/lib/pretext/index.ts",
+      "import": "./src/lib/pretext/index.ts",
+      "require": "./src/lib/pretext/index.ts"
+    },
     "./providers": {
       "types": "./src/providers/index.ts",
       "import": "./src/providers/index.ts",
@@ -74,6 +79,7 @@
       "require": "./src/utils/index.ts"
     },
     "./styles": "./src/styles/index.css",
+    "./styles/full": "./src/styles/full.css",
     "./styles/globals": "./src/styles/globals.css",
     "./styles/theme": "./src/styles/theme.css",
     "./styles/base": "./src/styles/base.css",
@@ -100,7 +106,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.418",
+    "@djangocfg/i18n": "^2.1.420",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -170,9 +176,12 @@
     "tailwind-merge": "^3.3.1",
     "vaul": "1.1.2"
   },
+  "optionalDependencies": {
+    "@chenglou/pretext": "*"
+  },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.418",
-    "@djangocfg/typescript-config": "^2.1.418",
+    "@djangocfg/i18n": "^2.1.420",
+    "@djangocfg/typescript-config": "^2.1.420",
     "@types/node": "^25.2.3",
     "@types/react": "^19.2.15",
     "@types/react-dom": "^19.2.3",

package/src/components/data/BalancedText/BalancedText.tsx

@@ -0,0 +1,74 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Pretext-powered balanced text. CSS `text-wrap: balance` only works up to
+// ~6 lines and is inconsistent cross-browser; this is deterministic and
+// scales to any length. On SSR / before measurement we fall back to the
+// CSS rule so the first paint is never visibly off — once pretext has
+// measured a width, the inline `maxWidth` style takes over.
+//
+// Powered by Pretext by Cheng Lou — github.com/chenglou/pretext
+
+'use client';
+
+import * as React from 'react';
+import { cn } from '../../../lib/utils';
+import {
+  usePretextWithSegments,
+  useBalancedWidth,
+} from '../../../lib/pretext';
+import {
+  DEFAULT_BALANCED_FONT,
+  DEFAULT_BALANCED_MAX_WIDTH,
+  type BalancedTextProps,
+} from './types';
+import { useMeasuredFont } from './hooks/useMeasuredFont';
+import { useMaxLinesWidth } from './hooks/useMaxLinesWidth';
+
+function BalancedTextImpl({
+  children,
+  font,
+  maxWidth = DEFAULT_BALANCED_MAX_WIDTH,
+  maxLines,
+  as,
+  className,
+  style,
+  ...rest
+}: BalancedTextProps) {
+  const Tag = (as ?? 'span') as React.ElementType;
+  const ref = React.useRef<HTMLElement | null>(null);
+
+  // Resolve the font: explicit prop wins; otherwise read computed style after mount.
+  const measuredFont = useMeasuredFont(ref, font);
+  const effectiveFont = font ?? measuredFont ?? DEFAULT_BALANCED_FONT;
+
+  const prepared = usePretextWithSegments(children, effectiveFont);
+  // Balanced width that preserves the natural line count at maxWidth.
+  const balancedAtMax = useBalancedWidth(prepared, maxWidth);
+  // If maxLines is set, search the narrower width that yields ≤ maxLines lines.
+  const lineCappedWidth = useMaxLinesWidth(prepared, maxWidth, maxLines);
+
+  const hasMeasured = balancedAtMax > 0 || lineCappedWidth > 0;
+  const finalWidth = lineCappedWidth || balancedAtMax;
+
+  // SSR / pre-measurement: rely on CSS `text-wrap: balance`. After measurement,
+  // the inline `maxWidth` provides a deterministic balanced layout.
+  const inlineStyle: React.CSSProperties = hasMeasured
+    ? { maxWidth: finalWidth, ...style }
+    : { textWrap: 'balance', ...style };
+
+  return (
+    <Tag
+      ref={ref}
+      data-slot="balanced-text"
+      data-measured={hasMeasured ? 'true' : 'false'}
+      className={cn(className)}
+      style={inlineStyle}
+      {...rest}
+    >
+      {children}
+    </Tag>
+  );
+}
+
+export const BalancedText = React.memo(BalancedTextImpl);
+BalancedText.displayName = 'BalancedText';

package/src/components/data/BalancedText/README.md

@@ -0,0 +1,29 @@
+# BalancedText
+
+Deterministic line-balancing for headings and short paragraphs. Wraps `@chenglou/pretext`'s `useBalancedWidth` to compute the narrowest container width that preserves the natural line count (or `maxLines`).
+
+CSS `text-wrap: balance` is used as the SSR fallback — the balanced width takes over after mount.
+
+```tsx
+import { BalancedText } from '@djangocfg/ui-core';
+
+<BalancedText as="h1" maxLines={2}>
+  A balanced heading that never produces an orphan word
+</BalancedText>
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `children` | `string` | — | Text to balance. **Must be a plain string** — pretext measures glyphs, not React trees. |
+| `font` | `string` | computed style | CSS font shorthand for measurement (e.g. `'16px Inter, sans-serif'`). |
+| `maxWidth` | `number` | parent `clientWidth` or `600` | Hard cap on container width in px. |
+| `maxLines` | `number` | — | Cap on rendered lines. Forces the narrowest width that keeps line count ≤ `maxLines`. |
+| `as` | `ElementType` | `'span'` | Element to render as. |
+
+Storybook: `apps/storybook/stories/ui-core/data/BalancedText.stories.tsx`
+
+---
+
+Adapted from jalcoui (MIT). Powered by [`@chenglou/pretext`](https://github.com/chenglou/pretext) (optional peer dependency).

package/src/components/data/BalancedText/hooks/useMaxLinesWidth.ts

@@ -0,0 +1,79 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// When `maxLines` is set we want the narrowest width that produces ≤ maxLines.
+// `useBalancedWidth` only preserves the *natural* line count at maxWidth — it
+// won't push the text into fewer lines than the user typed by accident.
+// This hook complements it: it walks line counts and binary-searches for a
+// width ≤ maxWidth that yields exactly `min(natural, maxLines)` lines.
+
+'use client';
+
+import * as React from 'react';
+import type { PreparedTextWithSegments } from '../../../../lib/pretext';
+
+// We replicate the structure of `useBalancedWidth` so that pretext stays an
+// optionalDependency: import the runtime lazily via require, mirror the
+// minimal `walkLineRanges` surface.
+interface WalkLineRange {
+  width: number;
+  start: number;
+  end: number;
+}
+interface PretextWalker {
+  walkLineRanges(
+    prepared: PreparedTextWithSegments,
+    maxWidth: number,
+    visit: (line: WalkLineRange) => void,
+  ): void;
+}
+
+let cached: PretextWalker | null = null;
+function getPretext(): PretextWalker {
+  if (cached) return cached;
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  cached = require('@chenglou/pretext') as PretextWalker;
+  return cached;
+}
+
+export function useMaxLinesWidth(
+  prepared: PreparedTextWithSegments | null,
+  maxWidth: number,
+  maxLines: number | undefined,
+): number {
+  return React.useMemo(() => {
+    if (!prepared || !maxLines || maxLines <= 0 || maxWidth <= 0) return 0;
+
+    const { walkLineRanges } = getPretext();
+
+    // Natural line count at maxWidth. If it's already within the cap, defer
+    // to `useBalancedWidth` (returning 0 means "don't use my value").
+    let naturalCount = 0;
+    walkLineRanges(prepared, maxWidth, () => {
+      naturalCount++;
+    });
+    if (naturalCount <= maxLines) return 0;
+
+    // Binary search: find the narrowest width that produces ≤ maxLines lines.
+    // Wider width → fewer lines, narrower width → more lines.
+    let lo = 1;
+    let hi = Math.ceil(maxWidth);
+    let best = hi;
+
+    while (lo <= hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      let count = 0;
+      walkLineRanges(prepared, mid, () => {
+        count++;
+      });
+
+      if (count <= maxLines) {
+        best = mid;
+        hi = mid - 1; // try narrower
+      } else {
+        lo = mid + 1;
+      }
+    }
+
+    return best;
+  }, [prepared, maxWidth, maxLines]);
+}

package/src/components/data/BalancedText/hooks/useMeasuredFont.ts

@@ -0,0 +1,35 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Read the host element's computed font shorthand after mount so the caller
+// doesn't have to duplicate the design tokens that style the element.
+// Returns `null` until the effect has run (SSR + first render), at which point
+// the BalancedText component falls back to a literal default font string.
+
+'use client';
+
+import * as React from 'react';
+
+export function useMeasuredFont(
+  ref: React.RefObject<HTMLElement | null>,
+  explicitFont: string | undefined,
+): string | null {
+  const [font, setFont] = React.useState<string | null>(null);
+
+  React.useEffect(() => {
+    if (explicitFont) return; // caller wins; skip measurement
+    const el = ref.current;
+    if (!el) return;
+    const cs = getComputedStyle(el);
+    // `font` shorthand is the most compact; some browsers return '' when
+    // individual properties were set separately — fall back to a manual build.
+    const shorthand = cs.font;
+    if (shorthand && shorthand.trim() !== '') {
+      setFont(shorthand);
+      return;
+    }
+    const composed = `${cs.fontStyle} ${cs.fontWeight} ${cs.fontSize} / ${cs.lineHeight} ${cs.fontFamily}`;
+    setFont(composed);
+  }, [ref, explicitFont]);
+
+  return font;
+}