@vyaz/core 0.0.3 → 0.0.5

package/src/utils/env.ts

@@ -0,0 +1,18 @@
+/**
+ * Runtime environment detection.
+ * Used to guard Node.js–only code paths (fontkit, fs, get-system-fonts)
+ * from being executed in the browser.
+ *
+ * ⚠️ Uses `globalThis.process` instead of bare `process` to avoid
+ * triggering bundler static analysis that could externalize the
+ * Node.js `process` global for browser targets.
+ */
+
+const _process: any =
+  typeof globalThis !== 'undefined' ? (globalThis as any).process : undefined;
+
+/** `true` when running on Node.js or Bun (has `process.versions.node`) */
+export const isNodeLike: boolean =
+  _process != null &&
+  _process.versions != null &&
+  typeof _process.versions.node === 'string';

package/src/utils/font.ts

@@ -0,0 +1,28 @@
+/**
+ * Font utility helpers.
+ *
+ * Provides cross‑environment helpers for loading font data in the browser
+ * (where there is no local filesystem).
+ */
+
+/**
+ * Download a font file from a URL and return its bytes.
+ *
+ * Works in browser environments.  In Node.js you'd typically read the file
+ * via `fs.readFileSync()` instead.
+ *
+ * @param fontUrl  URL of the font file (.ttf, .otf, .woff, .woff2)
+ * @returns        Font file bytes as an ArrayBuffer
+ */
+export async function getFontBuffer(fontUrl: string): Promise<ArrayBuffer> {
+  const response = await fetch(fontUrl);
+
+  if (!response.ok) {
+    throw new Error(
+      `[vyaz] Failed to download font from "${fontUrl}": ${response.status} ${response.statusText}`,
+    );
+  }
+
+  const buffer = await response.arrayBuffer();
+  return buffer;
+}

package/src/utils/groupLinesByParagraph.ts

@@ -0,0 +1,74 @@
+/**
+ * groupLinesByParagraph.ts — Group lines by paragraph index.
+ *
+ * Collects all lines with the same `pIdx` into one group,
+ * regardless of their order in the array (handles multi-column
+ * where lines of the same paragraph may be split across columns).
+ *
+ * @see {@link https://www.w3.org/TR/css-text-3/ | CSS Text Module Level 3}
+ */
+
+import type { Line } from '../types/LayoutTypes.js';
+
+/**
+ * A group of lines belonging to one paragraph.
+ */
+export interface ParagraphGroup {
+  /** Lines in this paragraph. */
+  lines: Line[];
+  /** Paragraph index in TextFrame.paragraphs[]. */
+  pIdx: number;
+  /** Optional user-assigned tag (from Paragraph.id). */
+  tag?: string;
+}
+
+/**
+ * Group lines by `pIdx` (paragraph index).
+ *
+ * Collects **all** lines with the same `pIdx` into one group,
+ * even if they are not consecutive in the array (multi-column layout
+ * may interleave lines of different paragraphs across columns).
+ *
+ * Returns groups sorted by `pIdx` in document order.
+ * Lines without a valid `pIdx` (e.g. `pIdx === undefined`) are grouped
+ * as index `-1`.
+ *
+ * @param lines — flat array of lines from `layoutTextFrame`
+ * @returns groups of lines grouped by paragraph
+ *
+ * @example
+ * ```ts
+ * const result = layoutTextFrame(frame);
+ * const groups = groupLinesByParagraph(result.lines);
+ * // groups[0].lines  → all lines for paragraph 0 (across all columns)
+ * // groups[0].pIdx   → 0
+ * ```
+ */
+export function groupLinesByParagraph(lines: Line[]): ParagraphGroup[] {
+  // Collect lines per paragraph using a Map
+  const map = new Map<number, { lines: Line[]; tag?: string }>();
+
+  for (const line of lines) {
+    const idx = line.spans[0]?.pIdx ?? -1;
+    let entry = map.get(idx);
+    if (!entry) {
+      entry = { lines: [] };
+      map.set(idx, entry);
+    }
+    entry.lines.push(line);
+    if (!entry.tag) {
+      entry.tag = line.spans[0]?.tag;
+    }
+  }
+
+  // Convert to array sorted by pIdx
+  const groups: ParagraphGroup[] = [];
+  const sortedKeys = Array.from(map.keys()).sort((a, b) => a - b);
+  for (const key of sortedKeys) {
+    if (key === -1) continue; // skip invalid
+    const entry = map.get(key)!;
+    groups.push({ lines: entry.lines, pIdx: key, tag: entry.tag });
+  }
+
+  return groups;
+}

package/src/utils/list.ts

@@ -0,0 +1,107 @@
+/**
+ * list.ts — helper utilities for list marker generation.
+ *
+ * Provides:
+ * - `formatListNumber()` — format a number according to `NumberFormat`
+ * - `defaultBulletChar()` — pick a bullet character based on nesting level
+ * - `BULLET_CHARACTERS` — the Unicode characters for disc/circle/square
+ */
+
+import type { NumberFormat } from '../types/Document.js';
+
+/**
+ * Unicode characters used for CSS `disc`, `circle`, `square` list-style-type
+ * values at different nesting levels.
+ *
+ * @see {@link https://www.w3.org/TR/css-lists-3/#ua-stylesheet | CSS Lists UA defaults}
+ */
+export const BULLET_CHARACTERS: Record<number, string> = {
+  0: '\u2022', // • BULLET  (disc)
+  1: '\u25CB', // ○ WHITE CIRCLE (circle)
+  2: '\u25AA', // ▪ BLACK SMALL SQUARE (square)
+};
+
+/** Fallback for deeper levels — same as level 2 */
+const FALLBACK_BULLET = '\u25AA';
+
+/**
+ * Get the default bullet character for a given nesting level.
+ *
+ * CSS UA stylesheet uses:
+ * - Level 0 (ul): disc (•)
+ * - Level 1 (ul ul): circle (○)
+ * - Level 2+ (ul ul ul): square (▪)
+ */
+export function defaultBulletChar(level: number): string {
+  return BULLET_CHARACTERS[level] ?? FALLBACK_BULLET;
+}
+
+/**
+ * Format a number according to the given numbering format.
+ *
+ * Supports the same formats as CSS `list-style-type`:
+ * - `decimal`: 1, 2, 3, …
+ * - `upper-roman`: I, II, III, …
+ * - `lower-roman`: i, ii, iii, …
+ * - `upper-alpha`: A, B, C, …
+ * - `lower-alpha`: a, b, c, …
+ *
+ * Follows CSS Counter Styles Level 3 algorithms.
+ * Roman numerals support the range 1–3999.
+ *
+ * @see {@link https://www.w3.org/TR/css-counter-styles-3/ | CSS Counter Styles Level 3}
+ */
+export function formatListNumber(n: number, format: NumberFormat): string {
+  switch (format) {
+    case 'decimal':
+      return String(n);
+    case 'upper-roman':
+      return toRoman(n).toUpperCase();
+    case 'lower-roman':
+      return toRoman(n).toLowerCase();
+    case 'upper-alpha':
+      return toAlpha(n).toUpperCase();
+    case 'lower-alpha':
+      return toAlpha(n).toLowerCase();
+    default:
+      return String(n);
+  }
+}
+
+/**
+ * Convert 1-based integer to lowercase roman numeral.
+ * Supports 1–3999.
+ */
+function toRoman(n: number): string {
+  if (n < 1 || n > 3999) return String(n);
+  const romanMap: [number, string][] = [
+    [1000, 'm'], [900, 'cm'], [500, 'd'], [400, 'cd'],
+    [100, 'c'], [90, 'xc'], [50, 'l'], [40, 'xl'],
+    [10, 'x'], [9, 'ix'], [5, 'v'], [4, 'iv'], [1, 'i'],
+  ];
+  let result = '';
+  for (const [value, symbol] of romanMap) {
+    while (n >= value) {
+      result += symbol;
+      n -= value;
+    }
+  }
+  return result;
+}
+
+/**
+ * Convert 1-based integer to alpha format (a, b, c, …, z, aa, ab, …).
+ * Uses the same algorithm as CSS `lower-alpha` (CSS Counter Styles §3.1.2).
+ */
+function toAlpha(n: number): string {
+  if (n < 1) return String(n);
+  const base = 26;
+  const offset = 'a'.charCodeAt(0);
+  let result = '';
+  while (n > 0) {
+    n--;
+    result = String.fromCharCode(offset + (n % base)) + result;
+    n = Math.floor(n / base);
+  }
+  return result;
+}

package/src/utils/textTransform.ts

@@ -0,0 +1,96 @@
+/**
+ * textTransform.ts — pure text transformation functions.
+ *
+ * Implements CSS `text-transform` for: none, uppercase, lowercase, capitalize.
+ *
+ * Explicit capitalization contract (edge cases):
+ * - Apostrophe (') is NOT a word boundary: "don't stop" → "Don't Stop"
+ * - Hyphen (-) IS a word boundary: "hello-world" → "Hello-World"
+ * - Leading whitespace is preserved: "  hello" → "  Hello"
+ * - Numbers are not capitalized: "3d model" → "3d Model"
+ * - Unicode full-range: first `\p{L}` in each word segment gets .toUpperCase()
+ * - Empty string → ""
+ * - No letters → unchanged: "123" → "123"
+ *
+ * @see {@link https://www.w3.org/TR/css-text-3/#text-transform-property | CSS Text: text-transform}
+ */
+
+import type { TextTransform } from '../types/Document.js';
+
+/**
+ * Apply text-transform to a string.
+ *
+ * @param text — input text
+ * @param transform — transform type ('none' | 'uppercase' | 'lowercase' | 'capitalize')
+ * @returns transformed text
+ *
+ * @example
+ * ```ts
+ * transformText("hello world", 'uppercase')  // → "HELLO WORLD"
+ * transformText("HELLO", 'lowercase')         // → "hello"
+ * transformText("don't stop", 'capitalize')   // → "Don't Stop"
+ * ```
+ */
+export function transformText(text: string, transform?: TextTransform): string {
+  if (!transform || transform === 'none' || !text) {
+    return text;
+  }
+
+  switch (transform) {
+    case 'uppercase':
+      return text.toUpperCase();
+
+    case 'lowercase':
+      return text.toLowerCase();
+
+    case 'capitalize': {
+      // Capitalize first letter of each word.
+      // Word = sequence of Unicode letters (\p{L}).
+      // Non-letter characters (including hyphen, but NOT apostrophe) are delimiters.
+      //
+      // Strategy: split on non-letter sequences (\P{L}+), but preserve delimiters
+      // by using a capturing group. Then for each letter-segment, capitalize its first \p{L}.
+      // Non-letter segments pass through unchanged.
+      //
+      // The regex splits on non-letters (excluding apostrophe) but keeps delimiters.
+      // Apostrophe (') is NOT a word boundary: "don't stop" → ["don't", " ", "stop", ""]
+      // Hyphen IS: "hello-world" → ["hello", "-", "world", ""]
+      const segments = text.split(/([^\p{L}']+)/u);
+
+      // Pre-allocate with same length
+      const result: string[] = new Array(segments.length);
+
+      for (let i = 0; i < segments.length; i++) {
+        const seg = segments[i];
+        if (!seg) {
+          result[i] = seg;
+          continue;
+        }
+
+        // If this segment is a non-letter (excluding apostrophe) delimiter — pass through unchanged
+        if (/^[^\p{L}']+$/u.test(seg)) {
+          result[i] = seg;
+          continue;
+        }
+
+        // This is a letter-segment. Capitalize its first letter.
+        const firstLetter = seg.match(/\p{L}/u);
+        if (!firstLetter) {
+          result[i] = seg;
+          continue;
+        }
+
+        const idx = firstLetter.index!;
+        const before = seg.slice(0, idx);
+        const letter = seg[idx].toUpperCase();
+        const after = seg.slice(idx + 1);
+        result[i] = `${before}${letter}${after}`;
+      }
+
+      return result.join('');
+    }
+
+    default:
+      return text;
+  }
+}