@santjc/react-pretext 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,157 @@
+import { P as PrepareOptions, u as usePreparedText } from './usePreparedText-DmUr2kss.js';
+export { U as UsePreparedTextInput, a as UsePreparedTextResult } from './usePreparedText-DmUr2kss.js';
+import * as react from 'react';
+import { CSSProperties } from 'react';
+import { PreparedTextWithSegments, PreparedText } from '@chenglou/pretext';
+
+type ElementWidthResult<T extends HTMLElement> = {
+    ref: (node: T | null) => void;
+    width: number;
+    node: T | null;
+};
+declare function useElementWidth<T extends HTMLElement = HTMLDivElement>(): ElementWidthResult<T>;
+
+type PretextTypographyShorthandInput = {
+    font: string;
+    lineHeight: number;
+    width?: number;
+    family?: never;
+    size?: never;
+    weight?: never;
+};
+type PretextTypographyObjectInput = {
+    family: string;
+    size: number;
+    weight?: number | string;
+    lineHeight: number;
+    width?: number;
+    font?: never;
+};
+type PretextTypographyInput = PretextTypographyShorthandInput | PretextTypographyObjectInput;
+type PretextTypography = {
+    font: string;
+    lineHeight: number;
+    width?: number;
+    style: CSSProperties;
+};
+declare function createPretextTypography(input: PretextTypographyInput): PretextTypography;
+
+type UseMeasuredTextInput = {
+    text: string;
+    width?: number;
+    font?: string;
+    lineHeight?: number;
+    typography?: PretextTypography;
+    prepareOptions?: PrepareOptions;
+    enableProfiling?: boolean;
+    enabled?: boolean;
+};
+type UseMeasuredTextResult = {
+    prepared: ReturnType<typeof usePreparedText>['prepared'];
+    height: number;
+    lineCount: number;
+    prepareMs?: number;
+    isReady: boolean;
+};
+declare function useMeasuredText({ text, width, font, lineHeight, typography, prepareOptions, enableProfiling, enabled, }: UseMeasuredTextInput): UseMeasuredTextResult;
+
+type UsePreparedSegmentsInput = {
+    text: string;
+    font: string;
+    options?: PrepareOptions;
+    enabled?: boolean;
+};
+type UsePreparedSegmentsResult = {
+    prepared: PreparedTextWithSegments | null;
+    isReady: boolean;
+};
+declare function usePreparedSegments({ text, font, options, enabled }: UsePreparedSegmentsInput): UsePreparedSegmentsResult;
+
+type UsePretextLayoutInput = {
+    prepared: PreparedText | null;
+    width: number;
+    lineHeight: number;
+    enabled?: boolean;
+};
+type UsePretextLayoutResult = {
+    height: number;
+    lineCount: number;
+    isReady: boolean;
+};
+declare function usePretextLayout({ prepared, width, lineHeight, enabled }: UsePretextLayoutInput): UsePretextLayoutResult;
+
+type UsePretextLinesInput = {
+    prepared: PreparedTextWithSegments | null;
+    width: number;
+    lineHeight: number;
+    enabled?: boolean;
+};
+type UsePretextLinesResult = {
+    height: number;
+    lineCount: number;
+    lines: Array<{
+        text: string;
+        width: number;
+        start: {
+            segmentIndex: number;
+            graphemeIndex: number;
+        };
+        end: {
+            segmentIndex: number;
+            graphemeIndex: number;
+        };
+    }>;
+    isReady: boolean;
+};
+declare function usePretextLines({ prepared, width, lineHeight, enabled }: UsePretextLinesInput): UsePretextLinesResult;
+
+type UseTruncatedTextInput = {
+    text: string;
+    width?: number;
+    font?: string;
+    lineHeight?: number;
+    typography?: PretextTypography;
+    prepareOptions?: PrepareOptions;
+    maxLines: number;
+    ellipsis?: string;
+    enabled?: boolean;
+};
+type UseTruncatedTextResult = {
+    text: string;
+    didTruncate: boolean;
+    visibleLineCount: number;
+    fullLineCount: number;
+    height: number;
+    isReady: boolean;
+};
+declare function useTruncatedText({ text, width, font, lineHeight, typography, prepareOptions, maxLines, ellipsis, enabled, }: UseTruncatedTextInput): UseTruncatedTextResult;
+
+type PTextTag = 'p' | 'div' | 'span' | 'h1' | 'h2' | 'h3';
+type PTextMeasure = {
+    width: number;
+    height: number;
+    lineCount: number;
+};
+type PTextOwnProps = {
+    as?: PTextTag;
+    children: string;
+    prepareOptions?: PrepareOptions;
+    onMeasure?: (result: PTextMeasure) => void;
+};
+type PTextExplicitMeasureProps = {
+    font: string;
+    lineHeight: number;
+    width?: number;
+    typography?: PretextTypography;
+};
+type PTextTypographyProps = {
+    typography: PretextTypography;
+    font?: string;
+    lineHeight?: number;
+    width?: number;
+};
+type PTextProps = PTextOwnProps & (PTextExplicitMeasureProps | PTextTypographyProps) & React.HTMLAttributes<HTMLElement>;
+type PTextElement = HTMLParagraphElement | HTMLDivElement | HTMLSpanElement | HTMLHeadingElement;
+declare const PText: react.ForwardRefExoticComponent<PTextProps & react.RefAttributes<PTextElement>>;
+
+export { type ElementWidthResult, PText, type PTextMeasure, type PTextProps, type PTextTag, PrepareOptions, type PretextTypography, type PretextTypographyInput, type PretextTypographyObjectInput, type PretextTypographyShorthandInput, type UseMeasuredTextInput, type UseMeasuredTextResult, type UsePreparedSegmentsInput, type UsePreparedSegmentsResult, type UsePretextLayoutInput, type UsePretextLayoutResult, type UsePretextLinesInput, type UsePretextLinesResult, type UseTruncatedTextInput, type UseTruncatedTextResult, createPretextTypography, useElementWidth, useMeasuredText, usePreparedSegments, usePreparedText, usePretextLayout, usePretextLines, useTruncatedText };

package/dist/index.js

@@ -0,0 +1,393 @@
+import {
+  useElementWidth,
+  usePreparedSegments
+} from "./chunk-6P7OEVAC.js";
+
+// src/core/hooks/usePreparedText.ts
+import { prepare, profilePrepare } from "@chenglou/pretext";
+import { useMemo } from "react";
+function usePreparedText({ text, font, options, enableProfiling = false, enabled = true }) {
+  const whiteSpace = options?.whiteSpace;
+  return useMemo(() => {
+    if (!enabled || text.length === 0 || font.length === 0) {
+      return {
+        prepared: null,
+        isReady: false
+      };
+    }
+    const normalizedOptions = whiteSpace === void 0 ? void 0 : { whiteSpace };
+    return {
+      prepared: prepare(text, font, normalizedOptions),
+      ...enableProfiling ? { prepareMs: profilePrepare(text, font, normalizedOptions).totalMs } : {},
+      isReady: true
+    };
+  }, [enableProfiling, enabled, font, text, whiteSpace]);
+}
+
+// src/core/hooks/usePretextLayout.ts
+import { layout } from "@chenglou/pretext";
+import { useMemo as useMemo2 } from "react";
+function usePretextLayout({ prepared, width, lineHeight, enabled = true }) {
+  return useMemo2(() => {
+    if (!enabled || prepared === null || width <= 0) {
+      return {
+        height: 0,
+        lineCount: 0,
+        isReady: false
+      };
+    }
+    const result = layout(prepared, width, lineHeight);
+    return {
+      height: result.height,
+      lineCount: result.lineCount,
+      isReady: true
+    };
+  }, [enabled, lineHeight, prepared, width]);
+}
+
+// src/core/hooks/useMeasuredText.ts
+function useMeasuredText({
+  text,
+  width,
+  font,
+  lineHeight,
+  typography,
+  prepareOptions,
+  enableProfiling = false,
+  enabled = true
+}) {
+  const resolvedFont = font ?? typography?.font;
+  const resolvedLineHeight = lineHeight ?? typography?.lineHeight;
+  const resolvedWidth = width ?? typography?.width;
+  if (resolvedFont === void 0 || resolvedLineHeight === void 0) {
+    throw new Error("useMeasuredText requires `font` and `lineHeight`, either directly or via `typography`.");
+  }
+  if (resolvedWidth === void 0) {
+    throw new Error("useMeasuredText requires `width`, either directly or via `typography`.");
+  }
+  const prepared = usePreparedText({
+    text,
+    font: resolvedFont,
+    options: prepareOptions,
+    enableProfiling,
+    enabled
+  });
+  const layout3 = usePretextLayout({
+    prepared: prepared.prepared,
+    width: resolvedWidth,
+    lineHeight: resolvedLineHeight,
+    enabled
+  });
+  return {
+    prepared: prepared.prepared,
+    height: layout3.height,
+    lineCount: layout3.lineCount,
+    prepareMs: prepared.prepareMs,
+    isReady: layout3.isReady
+  };
+}
+
+// src/core/hooks/usePretextLines.ts
+import { layoutWithLines } from "@chenglou/pretext";
+import { useMemo as useMemo3 } from "react";
+function usePretextLines({ prepared, width, lineHeight, enabled = true }) {
+  return useMemo3(() => {
+    if (!enabled || prepared === null || width <= 0) {
+      return {
+        height: 0,
+        lineCount: 0,
+        lines: [],
+        isReady: false
+      };
+    }
+    const result = layoutWithLines(prepared, width, lineHeight);
+    return {
+      height: result.height,
+      lineCount: result.lineCount,
+      lines: result.lines,
+      isReady: true
+    };
+  }, [enabled, lineHeight, prepared, width]);
+}
+
+// src/core/hooks/useTruncatedText.ts
+import { layout as layout2, prepare as prepare2 } from "@chenglou/pretext";
+import { useMemo as useMemo4 } from "react";
+var graphemeSegmenter = new Intl.Segmenter(void 0, { granularity: "grapheme" });
+var wordLikePattern = /[\p{L}\p{N}\p{M}]/u;
+var whitespacePattern = /\s/u;
+function getSegmentGraphemes(segment, cache) {
+  const cached = cache.get(segment);
+  if (cached !== void 0) {
+    return cached;
+  }
+  const graphemes = Array.from(graphemeSegmenter.segment(segment), ({ segment: grapheme }) => grapheme);
+  cache.set(segment, graphemes);
+  return graphemes;
+}
+function getTextUpToCursor(prepared, end) {
+  const graphemeCache = /* @__PURE__ */ new Map();
+  let result = "";
+  for (let segmentIndex = 0; segmentIndex < end.segmentIndex; segmentIndex += 1) {
+    result += prepared.segments[segmentIndex] ?? "";
+  }
+  if (end.graphemeIndex > 0) {
+    const segment = prepared.segments[end.segmentIndex];
+    if (segment !== void 0) {
+      result += getSegmentGraphemes(segment, graphemeCache).slice(0, end.graphemeIndex).join("");
+    }
+  }
+  return result;
+}
+function isWordLike(grapheme) {
+  return grapheme !== void 0 && wordLikePattern.test(grapheme);
+}
+function preferWordBoundary(graphemes, count) {
+  if (count <= 0 || count >= graphemes.length) {
+    return count;
+  }
+  if (!isWordLike(graphemes[count - 1]) || !isWordLike(graphemes[count])) {
+    return count;
+  }
+  let boundary = count;
+  while (boundary > 0 && isWordLike(graphemes[boundary - 1])) {
+    boundary -= 1;
+  }
+  while (boundary > 0 && whitespacePattern.test(graphemes[boundary - 1] ?? "")) {
+    boundary -= 1;
+  }
+  return boundary === 0 ? count : boundary;
+}
+function buildCandidateText(graphemes, count, ellipsis) {
+  const base = graphemes.slice(0, count).join("").trimEnd();
+  if (ellipsis.length === 0) {
+    return base;
+  }
+  return base.length === 0 ? ellipsis : `${base}${ellipsis}`;
+}
+function useTruncatedText({
+  text,
+  width,
+  font,
+  lineHeight,
+  typography,
+  prepareOptions,
+  maxLines,
+  ellipsis = "\u2026",
+  enabled = true
+}) {
+  const resolvedFont = font ?? typography?.font;
+  const resolvedLineHeight = lineHeight ?? typography?.lineHeight;
+  const resolvedWidth = width ?? typography?.width;
+  if (resolvedFont === void 0 || resolvedLineHeight === void 0) {
+    throw new Error("useTruncatedText requires `font` and `lineHeight`, either directly or via `typography`.");
+  }
+  if (resolvedWidth === void 0) {
+    throw new Error("useTruncatedText requires `width`, either directly or via `typography`.");
+  }
+  if (!Number.isInteger(maxLines) || maxLines <= 0) {
+    throw new Error("useTruncatedText requires `maxLines` to be a positive integer.");
+  }
+  const prepared = usePreparedSegments({
+    text,
+    font: resolvedFont,
+    options: prepareOptions,
+    enabled
+  });
+  const fullLayout = usePretextLines({
+    prepared: prepared.prepared,
+    width: resolvedWidth,
+    lineHeight: resolvedLineHeight,
+    enabled
+  });
+  const normalizedWhiteSpace = prepareOptions?.whiteSpace;
+  return useMemo4(() => {
+    if (!enabled || !prepared.isReady || !fullLayout.isReady || prepared.prepared === null) {
+      return {
+        text: "",
+        didTruncate: false,
+        visibleLineCount: 0,
+        fullLineCount: 0,
+        height: 0,
+        isReady: false
+      };
+    }
+    if (fullLayout.lineCount <= maxLines) {
+      return {
+        text,
+        didTruncate: false,
+        visibleLineCount: fullLayout.lineCount,
+        fullLineCount: fullLayout.lineCount,
+        height: fullLayout.height,
+        isReady: true
+      };
+    }
+    const lastVisibleLine = fullLayout.lines[maxLines - 1];
+    if (lastVisibleLine === void 0) {
+      return {
+        text: "",
+        didTruncate: true,
+        visibleLineCount: 0,
+        fullLineCount: fullLayout.lineCount,
+        height: 0,
+        isReady: true
+      };
+    }
+    const visibleText = getTextUpToCursor(prepared.prepared, lastVisibleLine.end);
+    const graphemes = Array.from(graphemeSegmenter.segment(visibleText), ({ segment }) => segment);
+    const measurementCache = /* @__PURE__ */ new Map();
+    const normalizedOptions = normalizedWhiteSpace === void 0 ? void 0 : { whiteSpace: normalizedWhiteSpace };
+    const measureCandidate = (candidateText) => {
+      const cached = measurementCache.get(candidateText);
+      if (cached !== void 0) {
+        return cached;
+      }
+      const nextResult = candidateText.length === 0 ? { lineCount: 0, height: 0 } : layout2(prepare2(candidateText, resolvedFont, normalizedOptions), resolvedWidth, resolvedLineHeight);
+      measurementCache.set(candidateText, nextResult);
+      return nextResult;
+    };
+    let low = 0;
+    let high = graphemes.length;
+    let bestCount = 0;
+    while (low <= high) {
+      const mid = Math.floor((low + high) / 2);
+      const candidate = buildCandidateText(graphemes, mid, ellipsis);
+      const candidateResult = measureCandidate(candidate);
+      if (candidateResult.lineCount <= maxLines) {
+        bestCount = mid;
+        low = mid + 1;
+      } else {
+        high = mid - 1;
+      }
+    }
+    const preferredCount = preferWordBoundary(graphemes, bestCount);
+    const truncatedText = buildCandidateText(graphemes, preferredCount, ellipsis);
+    const truncatedLayout = measureCandidate(truncatedText);
+    return {
+      text: truncatedText,
+      didTruncate: true,
+      visibleLineCount: truncatedLayout.lineCount,
+      fullLineCount: fullLayout.lineCount,
+      height: truncatedLayout.height,
+      isReady: true
+    };
+  }, [
+    ellipsis,
+    enabled,
+    fullLayout.height,
+    fullLayout.isReady,
+    fullLayout.lineCount,
+    fullLayout.lines,
+    maxLines,
+    normalizedWhiteSpace,
+    prepared.isReady,
+    prepared.prepared,
+    resolvedFont,
+    resolvedLineHeight,
+    resolvedWidth,
+    text
+  ]);
+}
+
+// src/core/lib/typography.ts
+function isShorthandInput(input) {
+  return "font" in input;
+}
+function resolveFont(input) {
+  if (isShorthandInput(input)) {
+    if (input.font.trim().length === 0) {
+      throw new Error("createPretextTypography requires a non-empty `font` string.");
+    }
+    return input.font;
+  }
+  if (input.family.trim().length === 0) {
+    throw new Error("createPretextTypography requires a non-empty `family` value.");
+  }
+  if (!Number.isFinite(input.size) || input.size <= 0) {
+    throw new Error("createPretextTypography requires `size` to be a positive number.");
+  }
+  return [input.weight === void 0 ? void 0 : `${input.weight}`, `${input.size}px`, input.family].filter(Boolean).join(" ");
+}
+function createPretextTypography(input) {
+  const font = resolveFont(input);
+  const { lineHeight, width } = input;
+  if (!Number.isFinite(lineHeight) || lineHeight <= 0) {
+    throw new Error("createPretextTypography requires `lineHeight` to be a positive number.");
+  }
+  const style = {
+    font,
+    lineHeight: `${lineHeight}px`
+  };
+  if (width !== void 0) {
+    style.width = `${width}px`;
+  }
+  return {
+    font,
+    lineHeight,
+    width,
+    style
+  };
+}
+
+// src/core/components/PText.tsx
+import { forwardRef, useCallback, useEffect } from "react";
+import { jsx } from "react/jsx-runtime";
+function assignRef(ref, value) {
+  if (typeof ref === "function") {
+    ref(value);
+    return;
+  }
+  if (ref) {
+    ref.current = value;
+  }
+}
+function PTextInner({ as, children, font, lineHeight, prepareOptions, typography, width, onMeasure, style, ...rest }, forwardedRef) {
+  const { ref: observedRef, width: observedWidth } = useElementWidth();
+  const explicitWidth = width ?? typography?.width;
+  const resolvedWidth = explicitWidth ?? observedWidth;
+  const resolvedFont = font ?? typography?.font;
+  const resolvedLineHeight = lineHeight ?? typography?.lineHeight;
+  if (resolvedFont === void 0 || resolvedLineHeight === void 0) {
+    throw new Error("PText requires `font` and `lineHeight`, either directly or via `typography`.");
+  }
+  const { prepared } = usePreparedText({ text: children, font: resolvedFont, options: prepareOptions });
+  const result = usePretextLayout({ prepared, width: resolvedWidth, lineHeight: resolvedLineHeight });
+  const typographyStyle = createPretextTypography({
+    font: resolvedFont,
+    lineHeight: resolvedLineHeight,
+    width: explicitWidth
+  }).style;
+  const composedRef = useCallback(
+    (node) => {
+      if (explicitWidth === void 0) {
+        observedRef(node);
+      }
+      assignRef(forwardedRef, node);
+    },
+    [explicitWidth, forwardedRef, observedRef]
+  );
+  useEffect(() => {
+    if (onMeasure === void 0) {
+      return;
+    }
+    onMeasure({
+      width: resolvedWidth,
+      height: result.height,
+      lineCount: result.lineCount
+    });
+  }, [onMeasure, resolvedWidth, result.height, result.lineCount]);
+  const Tag = as ?? "p";
+  return /* @__PURE__ */ jsx(Tag, { ref: composedRef, style: { ...typographyStyle, ...style }, ...rest, children });
+}
+var PText = forwardRef(PTextInner);
+export {
+  PText,
+  createPretextTypography,
+  useElementWidth,
+  useMeasuredText,
+  usePreparedSegments,
+  usePreparedText,
+  usePretextLayout,
+  usePretextLines,
+  useTruncatedText
+};

package/dist/pretext.d.ts

@@ -0,0 +1 @@
+export * from '@chenglou/pretext';

package/dist/pretext.js

@@ -0,0 +1,2 @@
+// src/pretext.ts
+export * from "@chenglou/pretext";

package/dist/usePreparedText-DmUr2kss.d.ts

@@ -0,0 +1,20 @@
+import { PreparedText } from '@chenglou/pretext';
+
+type PrepareOptions = {
+    whiteSpace?: 'normal' | 'pre-wrap';
+};
+type UsePreparedTextInput = {
+    text: string;
+    font: string;
+    options?: PrepareOptions;
+    enableProfiling?: boolean;
+    enabled?: boolean;
+};
+type UsePreparedTextResult = {
+    prepared: PreparedText | null;
+    prepareMs?: number;
+    isReady: boolean;
+};
+declare function usePreparedText({ text, font, options, enableProfiling, enabled }: UsePreparedTextInput): UsePreparedTextResult;
+
+export { type PrepareOptions as P, type UsePreparedTextInput as U, type UsePreparedTextResult as a, usePreparedText as u };

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "@santjc/react-pretext",
+  "version": "0.1.0",
+  "description": "Simple React wrapper over @chenglou/pretext for deterministic text measurement before paint, with an advanced editorial subpath.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./pretext": {
+      "types": "./dist/pretext.d.ts",
+      "import": "./dist/pretext.js"
+    },
+    "./editorial": {
+      "types": "./dist/editorial.d.ts",
+      "import": "./dist/editorial.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "react",
+    "pretext",
+    "text-measurement",
+    "typography",
+    "layout",
+    "line-count",
+    "virtualized-list",
+    "accordion-height",
+    "masonry-layout",
+    "responsive-text",
+    "editorial-layout",
+    "newspaper-layout",
+    "text-flow"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts src/pretext.ts src/editorial.ts --format esm --dts",
+    "lint": "eslint src",
+    "test": "vitest run --config vitest.config.ts"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@chenglou/pretext": "^0.0.3"
+  }
+}