@djangocfg/ui-core 2.1.417 → 2.1.419

package/README.md

@@ -60,7 +60,7 @@ Organized in `components/` by category — everything re-exported from the root
 | **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*` |
+| **Data** | `Table`, `Badge`, `Avatar`, `Progress`, `Carousel`, `Calendar`, `DatePicker`, `DateRangePicker`, `Toggle`, `ToggleGroup`, `Chart*`, `BalancedText` (pretext-powered line balancing) |
 | **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` |
@@ -97,7 +97,7 @@ import { useNavigate, useLocation, useQueryParams, useRouter, useIsActive } from
 | **Media** | `useIsMobile`, `useIsPhone`, `useIsTabletOrBelow`, `useMediaQuery` |
 | **Device** | `useDeviceDetect`, `useBrowserDetect`, `useShortcutModLabel` |
 | **State** | `useDebounce`, `useDebouncedCallback`, `useCountdown`, `useImageLoader`, `useMounted` |
-| **DOM** | `useEventListener` |
+| **DOM** | `useEventListener`, `useResizeObserver` (shared ResizeObserver store, returns `{ width, height }`) |
 | **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 |
@@ -235,6 +235,33 @@ const log = createLogger('MyComponent');
 log.info('user logged in', { userId: 123 });
 ```
 
+## Lib utilities
+
+```tsx
+import { cn, createLogger, getIntensity } from '@djangocfg/ui-core/lib';
+```
+
+| Utility | Purpose |
+|---|---|
+| `cn` | Tailwind class merger (`tailwind-merge` + `clsx`). |
+| `createLogger` | Tagged console logger. |
+| `getIntensity(value, max, thresholds?)` | Quantize a value to an integer bucket (0–N). Used for heatmaps, gauges, thermal-style visualizations. Default thresholds `[0.25, 0.5, 0.75]` map ratios to four non-zero buckets. |
+| `compose-refs`, `compose-event-handlers`, `get-element-ref` | Radix-style ref/handler helpers. |
+| `dialog-service`, `persist`, `env`, `logger` | See dedicated sections. |
+
+### Pretext
+
+```tsx
+import {
+  usePretext,
+  usePretextLayout,
+  usePretextLines,
+  useBalancedWidth,
+} from '@djangocfg/ui-core/lib/pretext';
+```
+
+DOM-free text measurement hooks wrapping [`@chenglou/pretext`](https://github.com/chenglou/pretext) (optional peer dependency). `useBalancedWidth` powers `<BalancedText>`. Falls back gracefully on SSR or when `@chenglou/pretext` is not installed.
+
 ## Styles & Theming
 
 ```css

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@djangocfg/ui-core",
-  "version": "2.1.417",
+  "version": "2.1.419",
   "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",
@@ -100,7 +105,7 @@
     "check": "tsc --noEmit"
   },
   "peerDependencies": {
-    "@djangocfg/i18n": "^2.1.417",
+    "@djangocfg/i18n": "^2.1.419",
     "consola": "^3.4.2",
     "lucide-react": "^0.545.0",
     "moment": "^2.30.1",
@@ -170,9 +175,12 @@
     "tailwind-merge": "^3.3.1",
     "vaul": "1.1.2"
   },
+  "optionalDependencies": {
+    "@chenglou/pretext": "*"
+  },
   "devDependencies": {
-    "@djangocfg/i18n": "^2.1.417",
-    "@djangocfg/typescript-config": "^2.1.417",
+    "@djangocfg/i18n": "^2.1.419",
+    "@djangocfg/typescript-config": "^2.1.419",
     "@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;
+}

package/src/components/data/BalancedText/index.ts

@@ -0,0 +1,5 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export { BalancedText } from './BalancedText';
+export type { BalancedTextProps, BalancedFont } from './types';
+export { DEFAULT_BALANCED_FONT, DEFAULT_BALANCED_MAX_WIDTH } from './types';

package/src/components/data/BalancedText/types.ts

@@ -0,0 +1,59 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+
+/**
+ * CSS font shorthand for Pretext measurement.
+ *
+ * Must match the actually rendered font, otherwise the balanced width will be
+ * off. When `font` is omitted, the component reads `getComputedStyle()` on the
+ * element after mount and falls back to {@link DEFAULT_BALANCED_FONT} on the
+ * server.
+ */
+export type BalancedFont = string;
+
+export interface BalancedTextOwnProps {
+  /** Text to balance. Required as a string — pretext measures runs of glyphs, not React trees. */
+  children: string;
+  /** CSS font shorthand (`'16px Inter, sans-serif'`). When omitted, reads `getComputedStyle`. */
+  font?: BalancedFont;
+  /**
+   * Hard cap on width in px. Balanced width never exceeds this. When omitted,
+   * the parent container's measured `clientWidth` is used. `maxLines` cannot
+   * make the text wider than this.
+   * @default 600
+   */
+  maxWidth?: number;
+  /**
+   * Cap on number of lines. When set, the balanced width is the *narrowest*
+   * width that still keeps ≤ `maxLines` lines (instead of preserving the
+   * natural line count at `maxWidth`). Useful for headings.
+   */
+  maxLines?: number;
+  /** Element to render as. @default 'span' */
+  as?: ElementType;
+}
+
+/** Props for {@link BalancedText}. */
+export type BalancedTextProps = BalancedTextOwnProps &
+  Omit<ComponentPropsWithoutRef<'span'>, keyof BalancedTextOwnProps | 'children'> & {
+    children: string;
+  };
+
+/** Fallback used on SSR and when `font` is not provided + measurement hasn't run. */
+export const DEFAULT_BALANCED_FONT: BalancedFont =
+  '16px ui-sans-serif, system-ui, -apple-system, sans-serif';
+
+export const DEFAULT_BALANCED_MAX_WIDTH = 600;
+
+/** Internal: BalancedText render shape (used by subcomponents). */
+export interface InternalRenderProps {
+  Tag: ElementType;
+  balancedWidth: number;
+  hasMeasured: boolean;
+  text: string;
+  className?: string;
+  style?: React.CSSProperties;
+  rest: Record<string, unknown>;
+  textNode: ReactNode;
+}

package/src/components/index.ts

@@ -187,6 +187,8 @@ export { CircularProgress, CircularProgressCombined, CircularProgressIndicator,
 export type { CircularProgressProps } from './data/circular-progress';
 export { RelativeTimeCard, relativeTimeCardVariants } from './data/relative-time-card';
 export type { RelativeTimeCardProps } from './data/relative-time-card';
+export { BalancedText, DEFAULT_BALANCED_FONT, DEFAULT_BALANCED_MAX_WIDTH } from './data/BalancedText';
+export type { BalancedTextProps, BalancedFont } from './data/BalancedText';
 
 // ─────────────────────────────────────────────────────────────────────────────
 // Chart Components

package/src/hooks/dom/index.ts

@@ -12,5 +12,7 @@ export {
 export type { ScrollSnapshot, ScrollDirection, ScrollTarget } from './useScroll';
 export { useLayoutEffect } from './useLayoutEffect';
 export { useSize } from './useSize';
+export { useResizeObserver } from './useResizeObserver';
+export type { Size } from './useResizeObserver';
 export { useFormReset } from './useFormReset';
 export type { UseFormResetParams } from './useFormReset';

package/src/hooks/dom/useResizeObserver.ts

@@ -0,0 +1,117 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Shared ResizeObserver store with refcounting.
+//
+// Why a shared observer (vs one per `useSize`/`useResizeObserver` call):
+//   - A single ResizeObserver instance is cheaper than N when many
+//     components subscribe (charts, sparklines, masonry items, …).
+//   - Avoids "ResizeObserver loop completed with undelivered notifications"
+//     warnings that pile up when many tiny observers fire in the same frame.
+//
+// The store keeps one global RO; per-element listener sets are reference
+// counted so the observer detaches from elements once nobody listens.
+//
+// Inspired by the pattern at activity-graph.tsx:180-188 in jalcoui.
+
+'use client';
+
+import * as React from 'react';
+import { useLayoutEffect } from './useLayoutEffect';
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+type Listener = (size: Size) => void;
+
+interface Entry {
+  listeners: Set<Listener>;
+  last: Size;
+}
+
+let sharedObserver: ResizeObserver | null = null;
+const entries = new WeakMap<Element, Entry>();
+// Mirror keyset so we can resolve elements from RO entries.
+const elementByEntry = new WeakMap<Element, Entry>();
+
+function getObserver(): ResizeObserver {
+  if (sharedObserver) return sharedObserver;
+  sharedObserver = new ResizeObserver((roEntries) => {
+    for (const roEntry of roEntries) {
+      const el = roEntry.target;
+      const entry = elementByEntry.get(el);
+      if (!entry) continue;
+
+      let width: number;
+      let height: number;
+      const box = (roEntry as ResizeObserverEntry).borderBoxSize;
+      if (box) {
+        const b = Array.isArray(box) ? box[0] : box;
+        width = b.inlineSize;
+        height = b.blockSize;
+      } else {
+        width = (el as HTMLElement).offsetWidth;
+        height = (el as HTMLElement).offsetHeight;
+      }
+
+      entry.last = { width, height };
+      for (const listener of entry.listeners) listener(entry.last);
+    }
+  });
+  return sharedObserver;
+}
+
+function subscribe(element: Element, listener: Listener): () => void {
+  const observer = getObserver();
+  let entry = entries.get(element);
+  if (!entry) {
+    entry = {
+      listeners: new Set<Listener>(),
+      last: {
+        width: (element as HTMLElement).offsetWidth ?? 0,
+        height: (element as HTMLElement).offsetHeight ?? 0,
+      },
+    };
+    entries.set(element, entry);
+    elementByEntry.set(element, entry);
+    observer.observe(element);
+  }
+  entry.listeners.add(listener);
+  // Deliver current size synchronously so consumers don't render with 0.
+  listener(entry.last);
+
+  return () => {
+    const e = entries.get(element);
+    if (!e) return;
+    e.listeners.delete(listener);
+    if (e.listeners.size === 0) {
+      observer.unobserve(element);
+      entries.delete(element);
+    }
+  };
+}
+
+/**
+ * Observe an element's border-box size via a shared ResizeObserver.
+ *
+ * Returns `{ width: 0, height: 0 }` until the first measurement lands.
+ * Pass either a ref or a callback-style ref result.
+ *
+ * @example
+ * const ref = React.useRef<HTMLDivElement>(null);
+ * const { width, height } = useResizeObserver(ref);
+ */
+export function useResizeObserver<T extends Element = Element>(
+  ref: React.RefObject<T | null>,
+): Size {
+  const [size, setSize] = React.useState<Size>({ width: 0, height: 0 });
+
+  useLayoutEffect(() => {
+    const el = ref.current;
+    if (!el) return;
+    return subscribe(el, setSize);
+  }, [ref]);
+
+  return size;
+}

package/src/lib/index.ts

@@ -15,3 +15,4 @@ export * from "./compose-refs";
 export * from "./get-element-ref";
 export * from "./compose-event-handlers";
 export { createContext } from "./create-context";
+export { getIntensity } from "./intensity";

package/src/lib/intensity.ts

@@ -0,0 +1,40 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Quantize a numeric value into a discrete intensity bucket. Used by
+// heatmaps (activity-graph), gauges, and any thermal-style visualization
+// that needs N colored steps.
+//
+// `thresholds` are upper bounds in ascending order, expressed as fractions
+// of `max` or as absolute values — caller picks. The returned bucket index
+// is in `[0, thresholds.length]`.
+//
+// Inspired by `getIntensity` at activity-graph.tsx:72-80.
+
+/**
+ * @param value      Current value.
+ * @param thresholds Ascending upper bounds. The returned bucket is the
+ *                   index of the first threshold `value` does not exceed,
+ *                   or `thresholds.length` if it exceeds them all.
+ * @returns Bucket index in `[0, thresholds.length]`. `0` for non-positive
+ *          values (treated as "empty").
+ *
+ * @example
+ *   getIntensity(0, [0.25, 0.5, 0.75])     // 0  (empty)
+ *   getIntensity(0.1, [0.25, 0.5, 0.75])   // 1
+ *   getIntensity(0.5, [0.25, 0.5, 0.75])   // 2
+ *   getIntensity(0.8, [0.25, 0.5, 0.75])   // 3
+ *   getIntensity(1.0, [0.25, 0.5, 0.75])   // 3
+ *
+ * @example
+ *   // Quantize commits/day into 4 buckets relative to the busiest day:
+ *   const max = Math.max(...counts);
+ *   const ratio = count / max;
+ *   const step = getIntensity(ratio, [0.25, 0.5, 0.75]); // 0..3
+ */
+export function getIntensity(value: number, thresholds: number[]): number {
+  if (!(value > 0)) return 0;
+  for (let i = 0; i < thresholds.length; i++) {
+    if (value <= thresholds[i]) return i + 1;
+  }
+  return thresholds.length;
+}

package/src/lib/pretext/index.ts

@@ -0,0 +1,18 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+
+export {
+  usePretext,
+  usePretextWithSegments,
+  usePretextLayout,
+  usePretextLines,
+  useShrinkwrap,
+  useBalancedWidth,
+} from './use-pretext';
+
+export type {
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLinesResult,
+  PrepareOptions,
+} from './use-pretext';

package/src/lib/pretext/pretext.types.ts

@@ -0,0 +1,72 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// Local mirror of the @chenglou/pretext public API. The runtime dependency
+// is declared `optional` (see ui-tools/package.json), so consumers that
+// never use BalancedText / pretext-powered tools don't pay for it. To keep
+// `pnpm check` green without the dependency installed, we redeclare just
+// the types we touch — no `import type from '@chenglou/pretext'`.
+//
+// Mirrors the public surface as of @chenglou/pretext 0.0.7. If the upstream
+// types drift, update here.
+
+export interface PrepareOptions {
+  whiteSpace?: 'normal' | 'pre' | 'pre-wrap' | 'pre-line';
+}
+
+// Opaque handles — internal shape doesn't matter to consumers of the hooks.
+// We brand them so the two flavours don't get accidentally swapped.
+export interface PreparedText {
+  readonly __brand: 'PreparedText';
+}
+
+export interface PreparedTextWithSegments {
+  readonly __brand: 'PreparedTextWithSegments';
+}
+
+export interface LayoutResult {
+  lineCount: number;
+  height: number;
+}
+
+export interface LayoutLine {
+  text: string;
+  width: number;
+  start: number;
+  end: number;
+}
+
+export interface LayoutLinesResult {
+  lineCount: number;
+  height: number;
+  lines: LayoutLine[];
+}
+
+export interface WalkLineRange {
+  width: number;
+  start: number;
+  end: number;
+}
+
+export interface PretextModule {
+  prepare(text: string, font: string, options?: PrepareOptions): PreparedText;
+  prepareWithSegments(
+    text: string,
+    font: string,
+    options?: PrepareOptions,
+  ): PreparedTextWithSegments;
+  layout(
+    prepared: PreparedText,
+    maxWidth: number,
+    lineHeight: number,
+  ): LayoutResult;
+  layoutWithLines(
+    prepared: PreparedTextWithSegments,
+    maxWidth: number,
+    lineHeight: number,
+  ): LayoutLinesResult;
+  walkLineRanges(
+    prepared: PreparedTextWithSegments,
+    maxWidth: number,
+    visit: (line: WalkLineRange) => void,
+  ): void;
+}

package/src/lib/pretext/use-pretext.ts

@@ -0,0 +1,211 @@
+// Adapted from jalcoui (MIT) — github.com/jal-co/ui
+//
+// React hooks wrapping @chenglou/pretext for DOM-free text measurement.
+// Provides prepare/layout lifecycle management, shrinkwrap search,
+// and line-balanced width computation.
+//
+// Powered by Pretext by Cheng Lou — github.com/chenglou/pretext
+//
+// `@chenglou/pretext` is declared as an optionalDependency in
+// `packages/ui-tools/package.json` — consumers that never use BalancedText
+// (or other pretext-based tools) can install ui-tools without it. The
+// `getPretext()` helper uses a CommonJS `require()` so the optional
+// dependency is resolved lazily at first use; if it is missing, the
+// `require` throws at call site, never at module-load.
+
+'use client';
+
+import * as React from 'react';
+import type {
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLinesResult,
+  PrepareOptions,
+  PretextModule,
+} from './pretext.types';
+
+export type {
+  PreparedText,
+  PreparedTextWithSegments,
+  LayoutResult,
+  LayoutLinesResult,
+  PrepareOptions,
+};
+
+const isBrowser = typeof window !== 'undefined';
+
+let cachedPretext: PretextModule | null = null;
+
+function getPretext(): PretextModule {
+  if (cachedPretext) return cachedPretext;
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  cachedPretext = require('@chenglou/pretext') as PretextModule;
+  return cachedPretext;
+}
+
+const EMPTY_LAYOUT: LayoutResult = { lineCount: 0, height: 0 };
+const EMPTY_LINES: LayoutLinesResult = { lineCount: 0, height: 0, lines: [] };
+
+/**
+ * Prepare text for Pretext measurement. Runs `prepare()` once and caches
+ * the result until `text`, `font`, or `options` change.
+ *
+ * The returned handle is opaque — pass it to `usePretextLayout`.
+ */
+export function usePretext(
+  text: string,
+  font: string,
+  options?: PrepareOptions,
+): PreparedText | null {
+  const whiteSpace = options?.whiteSpace ?? 'normal';
+
+  return React.useMemo(() => {
+    if (!isBrowser) return null;
+    return getPretext().prepare(text, font, options);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [text, font, whiteSpace]);
+}
+
+/**
+ * Prepare text with segment data for advanced layout (line-by-line rendering,
+ * shrinkwrap, balancing). Same as `usePretext` but returns the richer handle.
+ */
+export function usePretextWithSegments(
+  text: string,
+  font: string,
+  options?: PrepareOptions,
+): PreparedTextWithSegments | null {
+  const whiteSpace = options?.whiteSpace ?? 'normal';
+
+  return React.useMemo(() => {
+    if (!isBrowser) return null;
+    return getPretext().prepareWithSegments(text, font, options);
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [text, font, whiteSpace]);
+}
+
+/**
+ * Layout prepared text at a given width and line height. Pure arithmetic —
+ * no DOM reads. Returns line count and total height.
+ *
+ * Re-runs on every `maxWidth` or `lineHeight` change (~0.0002ms).
+ */
+export function usePretextLayout(
+  prepared: PreparedText | null,
+  maxWidth: number,
+  lineHeight: number,
+): LayoutResult {
+  return React.useMemo(() => {
+    if (!prepared) return EMPTY_LAYOUT;
+    return getPretext().layout(prepared, maxWidth, lineHeight);
+  }, [prepared, maxWidth, lineHeight]);
+}
+
+/**
+ * Layout prepared text and return full line data (text, width, cursors).
+ * Heavier than `usePretextLayout` — use when you need per-line info
+ * for custom rendering.
+ */
+export function usePretextLines(
+  prepared: PreparedTextWithSegments | null,
+  maxWidth: number,
+  lineHeight: number,
+): LayoutLinesResult {
+  return React.useMemo(() => {
+    if (!prepared) return EMPTY_LINES;
+    return getPretext().layoutWithLines(prepared, maxWidth, lineHeight);
+  }, [prepared, maxWidth, lineHeight]);
+}
+
+/**
+ * Find the tightest width that produces the same line count as `maxWidth`.
+ * Binary-searches widths using `walkLineRanges` — no DOM measurement.
+ *
+ * Returns the shrinkwrapped width in pixels.
+ */
+export function useShrinkwrap(
+  prepared: PreparedTextWithSegments | null,
+  maxWidth: number,
+): number {
+  return React.useMemo(() => {
+    if (!prepared || maxWidth <= 0) return 0;
+
+    const { walkLineRanges } = getPretext();
+
+    let baseLineCount = 0;
+    walkLineRanges(prepared, maxWidth, () => {
+      baseLineCount++;
+    });
+    if (baseLineCount <= 1) {
+      let singleLineWidth = 0;
+      walkLineRanges(prepared, maxWidth, (line) => {
+        singleLineWidth = line.width;
+      });
+      return Math.ceil(singleLineWidth) || 0;
+    }
+
+    let lo = 1;
+    let hi = Math.ceil(maxWidth);
+
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      let midLineCount = 0;
+      walkLineRanges(prepared, mid, () => {
+        midLineCount++;
+      });
+
+      if (midLineCount <= baseLineCount) {
+        hi = mid;
+      } else {
+        lo = mid + 1;
+      }
+    }
+
+    return lo;
+  }, [prepared, maxWidth]);
+}
+
+/**
+ * Find the width where all lines are roughly equal length (balanced text).
+ * Binary-searches for the narrowest width that keeps the same line count
+ * as `maxWidth`, then returns that width.
+ *
+ * CSS `text-wrap: balance` only works up to ~6 lines and is inconsistent
+ * cross-browser. This works on any length and is deterministic.
+ */
+export function useBalancedWidth(
+  prepared: PreparedTextWithSegments | null,
+  maxWidth: number,
+): number {
+  return React.useMemo(() => {
+    if (!prepared || maxWidth <= 0) return 0;
+
+    const { walkLineRanges } = getPretext();
+
+    let baseLineCount = 0;
+    walkLineRanges(prepared, maxWidth, () => {
+      baseLineCount++;
+    });
+    if (baseLineCount <= 1) return maxWidth;
+
+    let lo = 1;
+    let hi = Math.ceil(maxWidth);
+
+    while (lo < hi) {
+      const mid = Math.floor((lo + hi) / 2);
+      let midLineCount = 0;
+      walkLineRanges(prepared, mid, () => {
+        midLineCount++;
+      });
+
+      if (midLineCount <= baseLineCount) {
+        hi = mid;
+      } else {
+        lo = mid + 1;
+      }
+    }
+
+    return lo;
+  }, [prepared, maxWidth]);
+}

package/src/styles/theme/tokens.css

@@ -18,6 +18,12 @@
  * fully-wrapped CSS color (`hsl(0 0% 94%)`, not bare `0 0% 94%`).
  */
 
+/* Tailwind v4: bind the `dark:` variant to the `.dark` class on any
+ * ancestor (Storybook + ThemeToggle set `<html class="dark">`).
+ * Without this, `dark:` defaults to `@media (prefers-color-scheme: dark)`
+ * and every `dark:text-X` utility is a no-op when toggling via class. */
+@custom-variant dark (&:where(.dark, .dark *));
+
 @theme inline {
   /* Base semantic tokens — references into :root / .dark */
   --color-background: var(--background);