@santjc/react-pretext 0.1.0

package/README.md

@@ -0,0 +1,347 @@
+# @santjc/react-pretext
+
+Simple React wrapper over [`@chenglou/pretext`](https://www.npmjs.com/package/@chenglou/pretext) for deterministic text measurement before paint, without DOM reads.
+
+`@santjc/react-pretext` is intentionally a small React layer over `@chenglou/pretext`. It lets you predict text height and line count from text, typography, and width before the browser renders the final layout. The core use case is measurement-driven UI: accordions, cards, virtualized lists, previews, and any responsive layout where text height affects placement.
+
+The package keeps the original `pretext` model intact and adds React-facing hooks, types, and semantic rendering helpers where React actually helps.
+
+The intended adoption path is:
+
+- define typography once
+- measure text with `useMeasuredText()`
+- render semantic DOM with `PText`
+- use predicted heights in normal UI like accordions, cards, lists, and previews
+- opt into editorial flow only when you need custom line routing
+
+## Installation
+
+```bash
+npm install @santjc/react-pretext react react-dom
+```
+
+Peer dependencies: React 18 or 19.
+
+## Why use it
+
+- Predict text height before paint
+- Avoid hidden measurement nodes and `scrollHeight` reads
+- Truncate text to a known number of lines without DOM reads
+- Keep measurement inputs and render styles aligned
+- Re-layout from width changes without leaving the arithmetic path
+- Drop down to lower-level hooks only when you need more control
+
+## Start Here
+
+### Measure text with one hook
+
+```tsx
+import { createPretextTypography, useMeasuredText } from '@santjc/react-pretext'
+
+function Example({ text }: { text: string }) {
+  const typography = createPretextTypography({
+    family: 'Inter, sans-serif',
+    size: 18,
+    weight: 400,
+    lineHeight: 28,
+    width: 320,
+  })
+
+  const { height, lineCount } = useMeasuredText({ text, typography })
+
+  return <div>{height}px / {lineCount} lines</div>
+}
+```
+
+Use this for the common case where a component needs a known text height, line count, or both.
+
+### Use shared typography with `PText`
+
+```tsx
+import { PText, createPretextTypography } from '@santjc/react-pretext'
+
+function Example() {
+  const body = createPretextTypography({
+    family: 'Inter, sans-serif',
+    size: 18,
+    weight: 400,
+    lineHeight: 28,
+    width: 320,
+  })
+
+  return (
+    <PText as="p" typography={body}>
+      Semantic text with one source of truth for measurement and render output.
+    </PText>
+  )
+}
+```
+
+`PText` is a semantic rendering helper for the shared typography object. It is useful when you want real DOM output to stay aligned with the same measurement inputs, but the main measurement story still starts with hooks.
+
+### Let `PText` observe responsive width
+
+```tsx
+import { PText, createPretextTypography } from '@santjc/react-pretext'
+
+function Example() {
+  const body = createPretextTypography({
+    family: 'Inter, sans-serif',
+    size: 18,
+    weight: 400,
+    lineHeight: 28,
+  })
+
+  return (
+    <div style={{ width: 'min(100%, 36rem)' }}>
+      <PText as="p" typography={body}>
+        This paragraph does not receive an explicit width. PText observes the element width and remeasures as the container changes.
+      </PText>
+    </div>
+  )
+}
+```
+
+### Replace hidden measurement or `scrollHeight`
+
+Before:
+
+```tsx
+const ref = useRef<HTMLDivElement>(null)
+
+useLayoutEffect(() => {
+  setHeight(ref.current?.scrollHeight ?? 0)
+}, [text, width])
+```
+
+After:
+
+```tsx
+import { createPretextTypography, useMeasuredText, PText } from '@santjc/react-pretext'
+
+function AccordionBody({ isOpen, text }: { isOpen: boolean; text: string }) {
+  const typography = createPretextTypography({
+    family: 'Inter, sans-serif',
+    size: 18,
+    weight: 400,
+    lineHeight: 28,
+    width: 360,
+  })
+
+  const { height } = useMeasuredText({ text, typography })
+
+  return (
+    <div style={{ height: isOpen ? `${height}px` : '0px', overflow: 'hidden' }}>
+      <PText as="p" typography={typography}>
+        {text}
+      </PText>
+    </div>
+  )
+}
+```
+
+### Predict measured card or list heights
+
+```tsx
+import { createPretextTypography, useMeasuredText } from '@santjc/react-pretext'
+
+function ResultCard({ text, width }: { text: string; width: number }) {
+  const typography = createPretextTypography({
+    family: 'Inter, sans-serif',
+    size: 16,
+    weight: 400,
+    lineHeight: 26,
+    width: width - 32,
+  })
+
+  const { height, lineCount } = useMeasuredText({ text, typography })
+
+  return (
+    <div>
+      <div>{lineCount} lines</div>
+      <div>predicted body height: {height}px</div>
+    </div>
+  )
+}
+```
+
+This pattern works well for feeds, search results, CMS previews, issue lists, and any responsive grid where text height affects placement.
+
+### Truncate text for previews and teasers
+
+```tsx
+import { PText, createPretextTypography, useTruncatedText } from '@santjc/react-pretext'
+
+function ResultPreview({ text }: { text: string }) {
+  const typography = createPretextTypography({
+    family: 'Inter, sans-serif',
+    size: 16,
+    lineHeight: 24,
+    width: 280,
+  })
+
+  const preview = useTruncatedText({
+    text,
+    typography,
+    maxLines: 3,
+  })
+
+  return (
+    <>
+      <PText as="p" typography={typography}>{preview.text}</PText>
+      {preview.didTruncate ? <button>Read more</button> : null}
+    </>
+  )
+}
+```
+
+`useTruncatedText()` is meant for cards, snippets, collapsed previews, and compact list rows where the visible text itself needs to be deterministic before render.
+
+## Typography input
+
+`createPretextTypography()` accepts either a CSS font shorthand string or a structured typography object.
+
+Structured input:
+
+```tsx
+const typography = createPretextTypography({
+  family: 'Inter, sans-serif',
+  size: 18,
+  weight: 400,
+  lineHeight: 28,
+  width: 320,
+})
+```
+
+Font shorthand input:
+
+```tsx
+const typography = createPretextTypography({
+  font: '400 18px Inter, sans-serif',
+  lineHeight: 28,
+  width: 320,
+})
+```
+
+The structured form is the recommended default because it is easier to read, easier to derive from design tokens, and less fragile in application code. Internally, both forms resolve to the same `font` string and matching render styles.
+
+## Stable root API
+
+The root package is the intentional React-facing surface.
+
+- `createPretextTypography`
+- `useElementWidth`
+- `useMeasuredText`
+- `usePreparedText`
+- `usePreparedSegments`
+- `usePretextLayout`
+- `usePretextLines`
+- `useTruncatedText`
+- `PText`
+
+Drop down to `usePreparedText()` and `usePretextLayout()` when you want to control the prepare and layout phases separately. Use `usePreparedSegments()` with `usePretextLines()` when you need actual line output.
+
+## Low-level pretext API
+
+Raw `@chenglou/pretext` exports live on a dedicated `pretext` subpath:
+
+```ts
+import {
+  prepare,
+  prepareWithSegments,
+  layout,
+  layoutWithLines,
+  layoutNextLine,
+  walkLineRanges,
+} from '@santjc/react-pretext/pretext'
+```
+
+Use this subpath when you want the original low-level pretext model without the React-first root entrypoint.
+
+## Editorial API
+
+Editorial helpers live on the advanced `editorial` subpath:
+
+```ts
+import {
+  FlowLines,
+  useTextFlow,
+  flowText,
+  carveLineSlots,
+  createLineSlotResolver,
+  getCircleBlockedLineRangeForRow,
+  pickWidestLineSlot,
+  EditorialColumns,
+  EditorialSurface,
+  type EditorialTrack,
+  type EditorialFigure,
+} from '@santjc/react-pretext/editorial'
+```
+
+These APIs are public and tested, but they are not part of the default adoption path. Reach for them when you need custom line rendering, obstacle-aware flow, or multi-column continuation.
+
+## SSR and runtime guidance
+
+Measurement depends on canvas-backed text metrics, so the measurement hooks are a client-side feature.
+
+- In Next.js and other SSR frameworks, call the hooks from client components.
+- If you need a server-rendered fallback, render with a placeholder height and replace it after hydration.
+- Keep measurement logic at the edge of the UI that actually needs it instead of pushing it into shared server code.
+
+Example with a client component boundary:
+
+```tsx
+'use client'
+
+import { createPretextTypography, useMeasuredText } from '@santjc/react-pretext'
+
+export function MeasuredPreview({ text }: { text: string }) {
+  const typography = createPretextTypography({
+    family: 'Inter, sans-serif',
+    size: 16,
+    lineHeight: 24,
+    width: 320,
+  })
+
+  const { height } = useMeasuredText({ text, typography })
+
+  return <div style={{ minHeight: `${height}px` }}>{text}</div>
+}
+```
+
+## Webfont guidance
+
+Measurement is only as accurate as the font you actually render.
+
+- Keep the measurement typography aligned with the real DOM font.
+- Expect differences until a webfont finishes loading.
+- If first-render accuracy matters, wait for the font before measuring or remeasure once the font is ready.
+
+Example:
+
+```tsx
+useEffect(() => {
+  document.fonts.ready.then(() => {
+    setFontsReady(true)
+  })
+}, [])
+```
+
+## Caveats
+
+- `createPretextTypography()` is the recommended way to keep measurement inputs and render styles aligned.
+- `PText` currently supports `string` children only.
+- `prepareOptions` currently map directly to pretext preparation options, such as `whiteSpace`.
+- `useTextFlow` expects a reference-stable `getLineSlotAtY` callback. Memoize custom resolvers in React.
+- Editorial `lineRenderMode="justify"` uses pretext-derived `word-spacing` and will skip justification for unsupported whitespace patterns instead of delegating wrapping back to the browser.
+- `EditorialFigure` treats explicit `x` and `y` as overrides over `placement`, and clamps the result within available bounds.
+
+## Source layout
+
+The repository keeps package boundaries visible in the source tree:
+
+- `src/core/*` backs the root package exports
+- `src/editorial/*` backs `@santjc/react-pretext/editorial`
+- `src/test/*` holds cross-entrypoint package tests
+
+Playground helpers stay in `apps/playground/src/lib/*` unless they are intentionally promoted into the package with matching tests and docs.

package/dist/chunk-4TMIB6R6.js

@@ -0,0 +1,51 @@
+// src/hooks/useElementWidth.ts
+import { useCallback, useEffect, useState } from "react";
+function useElementWidth() {
+  const [node, setNode] = useState(null);
+  const [width, setWidth] = useState(0);
+  const ref = useCallback((nextNode) => {
+    setWidth(nextNode?.getBoundingClientRect().width ?? 0);
+    setNode(nextNode);
+  }, []);
+  useEffect(() => {
+    if (node === null) {
+      return;
+    }
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry === void 0) {
+        return;
+      }
+      setWidth((currentWidth) => currentWidth === entry.contentRect.width ? currentWidth : entry.contentRect.width);
+    });
+    observer.observe(node);
+    return () => {
+      observer.disconnect();
+    };
+  }, [node]);
+  return { ref, width, node };
+}
+
+// src/hooks/usePreparedSegments.ts
+import { prepareWithSegments } from "@chenglou/pretext";
+import { useMemo } from "react";
+function usePreparedSegments({ text, font, options, enabled = true }) {
+  const whiteSpace = options?.whiteSpace;
+  return useMemo(() => {
+    if (!enabled || text.length === 0 || font.length === 0) {
+      return {
+        prepared: null,
+        isReady: false
+      };
+    }
+    return {
+      prepared: prepareWithSegments(text, font, whiteSpace === void 0 ? void 0 : { whiteSpace }),
+      isReady: true
+    };
+  }, [enabled, font, text, whiteSpace]);
+}
+
+export {
+  useElementWidth,
+  usePreparedSegments
+};

package/dist/chunk-6P7OEVAC.js

@@ -0,0 +1,51 @@
+// src/core/hooks/useElementWidth.ts
+import { useCallback, useEffect, useState } from "react";
+function useElementWidth() {
+  const [node, setNode] = useState(null);
+  const [width, setWidth] = useState(0);
+  const ref = useCallback((nextNode) => {
+    setWidth(nextNode?.getBoundingClientRect().width ?? 0);
+    setNode(nextNode);
+  }, []);
+  useEffect(() => {
+    if (node === null) {
+      return;
+    }
+    const observer = new ResizeObserver((entries) => {
+      const entry = entries[0];
+      if (entry === void 0) {
+        return;
+      }
+      setWidth((currentWidth) => currentWidth === entry.contentRect.width ? currentWidth : entry.contentRect.width);
+    });
+    observer.observe(node);
+    return () => {
+      observer.disconnect();
+    };
+  }, [node]);
+  return { ref, width, node };
+}
+
+// src/core/hooks/usePreparedSegments.ts
+import { prepareWithSegments } from "@chenglou/pretext";
+import { useMemo } from "react";
+function usePreparedSegments({ text, font, options, enabled = true }) {
+  const whiteSpace = options?.whiteSpace;
+  return useMemo(() => {
+    if (!enabled || text.length === 0 || font.length === 0) {
+      return {
+        prepared: null,
+        isReady: false
+      };
+    }
+    return {
+      prepared: prepareWithSegments(text, font, whiteSpace === void 0 ? void 0 : { whiteSpace }),
+      isReady: true
+    };
+  }, [enabled, font, text, whiteSpace]);
+}
+
+export {
+  useElementWidth,
+  usePreparedSegments
+};

package/dist/editorial.d.ts

@@ -0,0 +1,163 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { CSSProperties, ReactNode } from 'react';
+import { P as PrepareOptions } from './usePreparedText-DmUr2kss.js';
+import { LayoutCursor, PreparedTextWithSegments } from '@chenglou/pretext';
+
+type LineSlot = {
+    left: number;
+    right: number;
+};
+type BlockedLineRange = {
+    left: number;
+    right: number;
+};
+type GetBlockedLineRanges = (lineTop: number, lineBottom: number) => BlockedLineRange[];
+type LineSlotResolver = (y: number) => LineSlot | null;
+type CreateLineSlotResolverInput = {
+    baseLineSlot: LineSlot;
+    lineHeight: number;
+    minWidth?: number;
+    getBlockedLineRanges?: GetBlockedLineRanges;
+};
+type CircleLineRangeInput = {
+    cx: number;
+    cy: number;
+    radius: number;
+    lineTop: number;
+    lineBottom: number;
+    horizontalPadding?: number;
+    verticalPadding?: number;
+};
+declare function carveLineSlots(baseLineSlot: LineSlot, blockedLineRanges: BlockedLineRange[], minWidth?: number): LineSlot[];
+declare function getCircleBlockedLineRangeForRow({ cx, cy, radius, lineTop, lineBottom, horizontalPadding, verticalPadding, }: CircleLineRangeInput): BlockedLineRange | null;
+declare function pickWidestLineSlot(lineSlots: LineSlot[]): LineSlot | null;
+declare function createLineSlotResolver({ baseLineSlot, lineHeight, minWidth, getBlockedLineRanges, }: CreateLineSlotResolverInput): LineSlotResolver;
+
+type EditorialPlacement = 'top-left' | 'top-center' | 'top-right' | 'center-left' | 'center' | 'center-right' | 'bottom-left' | 'bottom-center' | 'bottom-right';
+type EditorialFigure = {
+    shape: 'circle' | 'rect';
+    width: number;
+    height: number;
+    placement?: EditorialPlacement;
+    x?: number;
+    y?: number;
+    linePadding?: number;
+    className?: string;
+    style?: CSSProperties;
+    content?: ReactNode;
+};
+
+type EditorialTrack = {
+    width?: number;
+    fr?: number;
+    minHeight?: number;
+    paddingInline?: number;
+    paddingBlock?: number;
+    className?: string;
+    style?: CSSProperties;
+    figures?: EditorialFigure[];
+};
+
+type EditorialColumnsProps = {
+    text: string;
+    font: string;
+    lineHeight: number;
+    gap?: number;
+    lineRenderMode?: 'natural' | 'justify';
+    prepareOptions?: PrepareOptions;
+    className?: string;
+    style?: CSSProperties;
+    tracks: EditorialTrack[];
+};
+declare function EditorialColumns({ text, font, lineHeight, gap, lineRenderMode, prepareOptions, className, style, tracks: trackDefs, }: EditorialColumnsProps): react_jsx_runtime.JSX.Element;
+
+type EditorialSurfaceProps = {
+    text: string;
+    font: string;
+    lineHeight: number;
+    startY?: number;
+    maxY?: number;
+    minHeight?: number;
+    lineRenderMode?: 'natural' | 'justify';
+    prepareOptions?: PrepareOptions;
+    className?: string;
+    style?: CSSProperties;
+    figures?: EditorialFigure[];
+};
+declare function EditorialSurface({ text, font, lineHeight, startY, maxY, minHeight, lineRenderMode, prepareOptions, className, style, figures, }: EditorialSurfaceProps): react_jsx_runtime.JSX.Element;
+
+type PositionedLine = {
+    text: string;
+    x: number;
+    y: number;
+    width: number;
+    slotLeft: number;
+    slotRight: number;
+    slotWidth: number;
+    start: LayoutCursor;
+    end: LayoutCursor;
+};
+type TextFlowInput = {
+    prepared: PreparedTextWithSegments;
+    lineHeight: number;
+    getLineSlotAtY: (y: number) => LineSlot | null;
+    startY?: number;
+    startCursor?: LayoutCursor;
+    maxLines?: number;
+    maxY?: number;
+    maxSteps?: number;
+};
+type TextFlowResult = {
+    lines: PositionedLine[];
+    height: number;
+    exhausted: boolean;
+    truncated: boolean;
+    endCursor: LayoutCursor;
+};
+declare function flowText({ prepared, lineHeight, getLineSlotAtY, startY, startCursor, maxLines, maxY, maxSteps, }: TextFlowInput): TextFlowResult;
+
+type EditorialPositionedLine = PositionedLine & {
+    justifyWordSpacing: number | null;
+    isTerminal: boolean;
+    isParagraphTerminal: boolean;
+};
+
+type FlowRenderableLine = PositionedLine & Partial<Pick<EditorialPositionedLine, 'justifyWordSpacing'>>;
+type FlowLineRenderInput<TLine extends FlowRenderableLine = FlowRenderableLine> = {
+    key: string;
+    line: TLine;
+    text: string;
+    style: CSSProperties;
+};
+type FlowLinesProps<TLine extends FlowRenderableLine = FlowRenderableLine> = {
+    lines: TLine[];
+    font: string;
+    lineHeight: number;
+    lineClassName?: string;
+    lineRenderMode?: 'natural' | 'justify';
+    renderLine?: (input: FlowLineRenderInput<TLine>) => ReactNode;
+};
+declare function FlowLines<TLine extends FlowRenderableLine = FlowRenderableLine>({ lines, font, lineHeight, lineClassName, lineRenderMode, renderLine, }: FlowLinesProps<TLine>): react_jsx_runtime.JSX.Element;
+
+type UseTextFlowInput = {
+    prepared: PreparedTextWithSegments | null;
+    lineHeight: number;
+    getLineSlotAtY: (y: number) => LineSlot | null;
+    startY?: number;
+    startCursor?: LayoutCursor;
+    maxLines?: number;
+    maxY?: number;
+    maxSteps?: number;
+    enabled?: boolean;
+};
+type UseTextFlowResult = {
+    lines: PositionedLine[];
+    height: number;
+    exhausted: boolean;
+    truncated: boolean;
+    isReady: boolean;
+    endCursor: LayoutCursor;
+};
+declare function useTextFlow({ prepared, lineHeight, getLineSlotAtY, startY, startCursor, maxLines, maxY, maxSteps, enabled, }: UseTextFlowInput): UseTextFlowResult;
+
+export { EditorialColumns, type EditorialColumnsProps, type EditorialFigure, type EditorialPlacement, EditorialSurface, type EditorialSurfaceProps, type EditorialTrack, type FlowLineRenderInput, FlowLines, type FlowLinesProps, type FlowRenderableLine, type LineSlot, type PositionedLine, type TextFlowInput, type TextFlowResult, type UseTextFlowInput, type UseTextFlowResult, carveLineSlots, createLineSlotResolver, flowText, getCircleBlockedLineRangeForRow, pickWidestLineSlot, useTextFlow };