@open-press/cli 0.8.0 → 1.1.0

package/template/core/src/openpress/manuscript/index.tsx

@@ -1,238 +0,0 @@
-// @open-press/core/manuscript — long-form section-flow helpers.
-//
-// Manuscript helpers cover the "paper / report / book / monograph" pattern:
-// a source resolves into a sequence of sections, each section becomes one
-// content frame (with overflow auto-cloning across pages), and a TOC frame
-// summarizes the outline.
-//
-// These helpers are conventions only. Core never knows about them. Any
-// document type that wants section flow imports from here; documents that
-// do not (slides, folios, calendars) skip this module entirely.
-
-import { Fragment, useContext, type ComponentType, type ReactNode } from "react";
-import { Frame, FrameContext, MdxArea, PressContext, useSource } from "../core";
-import type { MdxAreaOverflow, ResolvedSource } from "../core";
-import { createMdxAreaObjectEntityId } from "../document-model/objectEntityModel";
-
-// ---------------------------------------------------------------------------
-// <Sections>
-// ---------------------------------------------------------------------------
-
-export interface SectionsPageProps {
-  frameKey: string;
-  chainId: string;
-  pageIndex: number;
-  totalPages: number;
-  sectionSlug: string;
-  sectionTitle: string;
-  sectionTone?: string;
-  sectionMeta: Record<string, unknown>;
-}
-
-export interface SectionsOpenerProps {
-  frameKey: string;
-  sectionSlug: string;
-  sectionTitle: string;
-  sectionIndex: number;
-  sectionMeta: Record<string, unknown>;
-}
-
-export interface SectionsProps {
-  source: string;
-  page?: ComponentType<SectionsPageProps>;
-  opener?: ComponentType<SectionsOpenerProps>;
-}
-
-export function Sections({ source: sourceId, page: Page = DefaultSectionPage, opener: Opener }: SectionsProps) {
-  const source = useSource(sourceId);
-  const press = useContext(PressContext);
-  const hints = press?.hints ?? null;
-  return (
-    <Fragment>
-      {source.tree.map((section, index) => {
-        const chainId = `${sourceId}:${section.slug}`;
-        const meta = (section.meta ?? {}) as Record<string, unknown>;
-        const tone = typeof meta.tone === "string" ? meta.tone : undefined;
-        const totalPages = Math.max(1, hints?.totalPagesPerChain?.[chainId] ?? 1);
-        const pages: ReactNode[] = [];
-        for (let i = 0; i < totalPages; i++) {
-          pages.push(
-            <Page
-              key={i}
-              frameKey={`${sourceId}:${section.slug}:content:${i}`}
-              chainId={chainId}
-              pageIndex={i}
-              totalPages={totalPages}
-              sectionSlug={section.slug}
-              sectionTitle={section.title}
-              sectionTone={tone}
-              sectionMeta={meta}
-            />,
-          );
-        }
-        return (
-          <Fragment key={section.slug}>
-            {Opener ? (
-              <Opener
-                frameKey={`${sourceId}:${section.slug}:opener`}
-                sectionSlug={section.slug}
-                sectionTitle={section.title}
-                sectionIndex={index}
-                sectionMeta={meta}
-              />
-            ) : null}
-            {pages}
-          </Fragment>
-        );
-      })}
-    </Fragment>
-  );
-}
-
-// Compatibility alias for chapter vocabulary.
-export const Chapters = Sections;
-export type ChaptersProps = SectionsProps;
-
-export function DefaultSectionPage({
-  frameKey,
-  chainId,
-  pageIndex,
-  totalPages,
-  sectionSlug,
-  sectionTitle,
-  sectionTone,
-}: SectionsPageProps) {
-  return (
-    <Frame
-      frameKey={frameKey}
-      role="manuscript.content"
-      className="reader-page--content"
-      data-page-index={pageIndex}
-      data-total-pages={totalPages}
-      data-section-id={sectionSlug}
-      data-chapter-tone={sectionTone}
-    >
-      <div className="page-frame">
-        <header className="page-header" aria-hidden="true" />
-        <main className="page-body">
-          <MdxArea chainId={chainId} />
-        </main>
-        <footer className="page-footer" aria-hidden="true">
-          <span className="footer-left">{sectionTitle}</span>
-          <span className="footer-right">
-            {totalPages > 1 ? `${pageIndex + 1}/${totalPages}` : pageIndex + 1}
-          </span>
-        </footer>
-      </div>
-    </Frame>
-  );
-}
-
-// ---------------------------------------------------------------------------
-// <Toc>
-// ---------------------------------------------------------------------------
-
-export interface TocProps {
-  source: string;
-  className?: string;
-  heading?: ReactNode;
-  frameKey?: string;
-  maxLevel?: 2 | 3;
-  overflow?: MdxAreaOverflow;
-  page?: React.ComponentType<TocPageProps>;
-}
-
-export interface TocPageProps {
-  frameKey: string;
-  chainId: string;
-  pageIndex: number;
-  totalPages: number;
-  sourceId: string;
-  heading?: ReactNode;
-  className?: string;
-  maxLevel?: 2 | 3;
-  overflow?: MdxAreaOverflow;
-}
-
-export interface TocAreaProps {
-  chainId: string;
-  maxLevel?: 2 | 3;
-  overflow?: MdxAreaOverflow;
-  className?: string;
-}
-
-export function Toc({ source: sourceId, className, heading, frameKey = "toc", maxLevel = 3, overflow = "extend", page: Page = DefaultTocPage }: TocProps) {
-  useSource(sourceId) as ResolvedSource;
-  const press = useContext(PressContext);
-  const chainId = maxLevel <= 2 ? `toc:${sourceId}:h2` : `toc:${sourceId}`;
-  const totalPages = Math.max(1, press?.hints?.totalPagesPerChain?.[chainId] ?? 1);
-  const pages: ReactNode[] = [];
-  for (let i = 0; i < totalPages; i++) {
-    pages.push(
-      <Page
-        key={i}
-        frameKey={i === 0 ? frameKey : `${frameKey}:page:${i}`}
-        chainId={chainId}
-        pageIndex={i}
-        totalPages={totalPages}
-        sourceId={sourceId}
-        heading={heading}
-        className={className}
-        maxLevel={maxLevel}
-        overflow={overflow}
-      />,
-    );
-  }
-  return <Fragment>{pages}</Fragment>;
-}
-
-function DefaultTocPage({ frameKey, chainId, pageIndex, totalPages, heading, className, maxLevel, overflow }: TocPageProps) {
-  const isContinuation = pageIndex > 0;
-  const tocClassName = ["reader-page--toc", isContinuation ? "toc-continuation" : null, className].filter(Boolean).join(" ") || undefined;
-  return (
-    <Frame
-      frameKey={frameKey}
-      role="manuscript.toc"
-      chrome={false}
-      className={tocClassName}
-    >
-      <div className="page-frame">
-        <header className="page-header toc-header">
-          {heading ?? (
-            <h2 className={isContinuation ? "toc-heading toc-heading--continuation" : "toc-heading"} id={isContinuation ? `${frameKey}-title` : "toc-title"}>
-              {isContinuation ? "目錄續" : "目錄"}
-            </h2>
-          )}
-        </header>
-        <main className="page-body">
-          <TocArea chainId={chainId} maxLevel={maxLevel} overflow={overflow} />
-        </main>
-      </div>
-    </Frame>
-  );
-}
-
-export function TocArea({ chainId, maxLevel, overflow = "extend", className }: TocAreaProps) {
-  const frame = useContext(FrameContext);
-  const consumed = frame?.consumeArea(chainId) ?? null;
-  const blocks = consumed?.blocks ?? null;
-  const objectId = frame && consumed
-    ? createMdxAreaObjectEntityId(frame.frameKey, chainId, consumed.indexInFrame)
-    : undefined;
-  return (
-    <div
-      className="openpress-mdx-area openpress-toc-area"
-      data-openpress-mdx-area="true"
-      data-openpress-mdx-area-chain={chainId}
-      data-openpress-mdx-area-index={consumed?.indexInFrame}
-      data-openpress-object-id={objectId}
-      data-openpress-toc-max-level={maxLevel}
-      data-openpress-mdx-area-overflow={overflow}
-      data-openpress-mdx-area-empty={blocks == null ? "true" : "false"}
-    >
-      <ol className={["toc-list", className].filter(Boolean).join(" ") || undefined}>
-        {blocks}
-      </ol>
-    </div>
-  );
-}

package/template/core/src/openpress/mdx/index.ts

@@ -1,88 +0,0 @@
-// @open-press/core/mdx — pure source descriptor factories.
-//
-// These factories MUST stay pure: they construct descriptor objects only.
-// They must not touch the filesystem, fetch the network, or execute
-// workspace logic at module load. Resolution happens in Layer 1 inside the
-// engine, where IO is allowed.
-
-import type {
-  MdxSourceDescriptor,
-  MdxSourceDescriptorFileList,
-  MdxSourceDescriptorSectionFiles,
-  MdxSourceDescriptorSectionFolders,
-} from "../core/types";
-
-export type {
-  MdxSourceDescriptor,
-  MdxSourceDescriptorFileList,
-  MdxSourceDescriptorSectionFiles,
-  MdxSourceDescriptorSectionFolders,
-} from "../core/types";
-
-export type {
-  OutlineItem,
-  ResolvedSource,
-  SourceBlock,
-  SourceFileRecord,
-  SourceNode,
-} from "../core/types";
-
-type MdxSourceOptions =
-  | { preset: "section-folders"; root?: string }
-  | { preset: "section-files"; root?: string }
-  | { preset: "file-list"; files: string[] };
-
-const VALID_PRESETS = new Set(["section-folders", "section-files", "file-list"]);
-
-export function mdxSource(options: MdxSourceOptions): MdxSourceDescriptor {
-  if (!options || typeof options !== "object") {
-    throw new Error("mdxSource() requires an options object.");
-  }
-  if (!VALID_PRESETS.has(options.preset)) {
-    throw new Error(
-      `mdxSource() preset must be one of: section-folders, section-files, file-list. Got "${
-        (options as { preset?: unknown }).preset
-      }".`,
-    );
-  }
-
-  if (options.preset === "section-folders") {
-    return normalizeRooted("section-folders", options.root, "chapters") as MdxSourceDescriptorSectionFolders;
-  }
-  if (options.preset === "section-files") {
-    return normalizeRooted("section-files", options.root, "content") as MdxSourceDescriptorSectionFiles;
-  }
-
-  // file-list
-  if (!Array.isArray(options.files)) {
-    throw new Error('mdxSource({ preset: "file-list" }) requires `files: string[]`.');
-  }
-  const files: string[] = [];
-  for (const raw of options.files) {
-    if (typeof raw !== "string") {
-      throw new Error('mdxSource({ preset: "file-list" }) `files` entries must be strings.');
-    }
-    const trimmed = raw.trim();
-    if (!trimmed) continue;
-    files.push(trimmed);
-  }
-  if (files.length === 0) {
-    throw new Error('mdxSource({ preset: "file-list" }) requires at least one file.');
-  }
-  return { type: "mdx", preset: "file-list", files };
-}
-
-function normalizeRooted(
-  preset: "section-folders" | "section-files",
-  root: string | undefined,
-  defaultRoot: string,
-): MdxSourceDescriptor {
-  if (root !== undefined && typeof root !== "string") {
-    throw new Error(`mdxSource() \`root\` must be a string if provided. Got ${typeof root}.`);
-  }
-  return {
-    type: "mdx",
-    preset,
-    root: (root ?? defaultRoot).trim() || defaultRoot,
-  };
-}

package/template/core/src/openpress/numbering/index.ts

@@ -1,294 +0,0 @@
-// @open-press/core/numbering — label formatters for AI authoring layer.
-//
-// Core stays neutral about how chapter / section / topic numbers should look.
-// Source resolution exposes raw integers via outline items
-// (`chapterNumber`, `sectionIndex`, `topicIndex`). This module is a toolbox
-// of pure functions that turn those integers into human-readable labels —
-// Chinese numerals, Roman numerals, alphabet letters, padded decimals, etc.
-//
-// Workspaces import what they need and compose them inside their own
-// `<Page>` / `<Toc>` components. The core engine never calls these.
-
-// ---------------------------------------------------------------------------
-// CJK numeral systems
-// ---------------------------------------------------------------------------
-
-const CJK_INFORMAL = ["〇", "一", "二", "三", "四", "五", "六", "七", "八", "九"];
-const CJK_FORMAL = ["零", "壹", "貳", "參", "肆", "伍", "陸", "柒", "捌", "玖"];
-const CJK_HEAVENLY_STEMS = ["甲", "乙", "丙", "丁", "戊", "己", "庚", "辛", "壬", "癸"];
-const CJK_EARTHLY_BRANCHES = ["子", "丑", "寅", "卯", "辰", "巳", "午", "未", "申", "酉", "戌", "亥"];
-
-/**
- * Informal CJK numerals (一二三...). Handles 0 to 9999.
- *
- *   toCjk(1)   → "一"
- *   toCjk(10)  → "十"
- *   toCjk(15)  → "十五"
- *   toCjk(23)  → "二十三"
- *   toCjk(100) → "一百"
- *   toCjk(108) → "一百零八"
- *   toCjk(2024) → "二千零二十四"
- */
-export function toCjk(n: number): string {
-  if (!Number.isFinite(n) || n < 0) return String(n);
-  return formatCjkDigits(Math.floor(n), CJK_INFORMAL);
-}
-
-/**
- * Formal CJK numerals (壹貳參...). Used in legal / financial contexts.
- *
- *   toCjkFormal(1)   → "壹"
- *   toCjkFormal(100) → "壹佰"
- */
-export function toCjkFormal(n: number): string {
-  if (!Number.isFinite(n) || n < 0) return String(n);
-  return formatCjkDigits(Math.floor(n), CJK_FORMAL, { formal: true });
-}
-
-/**
- * Heavenly Stems cycle (甲乙丙丁戊己庚辛壬癸 — 10 only).
- * Cycles for n > 10; n=11 → 甲 again.
- *
- *   toCjkHeavenlyStem(1) → "甲"
- *   toCjkHeavenlyStem(10) → "癸"
- *   toCjkHeavenlyStem(11) → "甲"
- */
-export function toCjkHeavenlyStem(n: number): string {
-  if (!Number.isFinite(n) || n < 1) return String(n);
-  return CJK_HEAVENLY_STEMS[(Math.floor(n) - 1) % 10]!;
-}
-
-/**
- * Earthly Branches cycle (子丑寅卯辰巳午未申酉戌亥 — 12 only).
- * Cycles for n > 12.
- */
-export function toCjkEarthlyBranch(n: number): string {
-  if (!Number.isFinite(n) || n < 1) return String(n);
-  return CJK_EARTHLY_BRANCHES[(Math.floor(n) - 1) % 12]!;
-}
-
-// ---------------------------------------------------------------------------
-// Roman numerals
-// ---------------------------------------------------------------------------
-
-const ROMAN_TABLE: Array<[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"],
-];
-
-/**
- * Roman numerals (I, II, III, …, MMXX). Uppercase by default.
- * Pass `{ upper: false }` for lowercase (typical front-matter page numbering).
- *
- *   toRoman(1)     → "I"
- *   toRoman(4)     → "IV"
- *   toRoman(2024)  → "MMXXIV"
- *   toRoman(3, { upper: false }) → "iii"
- */
-export function toRoman(n: number, opts: { upper?: boolean } = {}): string {
-  if (!Number.isFinite(n) || n < 1) return String(n);
-  let value = Math.floor(n);
-  let out = "";
-  for (const [num, sym] of ROMAN_TABLE) {
-    while (value >= num) {
-      out += sym;
-      value -= num;
-    }
-  }
-  return opts.upper === false ? out.toLowerCase() : out;
-}
-
-// ---------------------------------------------------------------------------
-// Latin alphabet (a, b, c, …, z, aa, ab, …)
-// ---------------------------------------------------------------------------
-
-/**
- * Spreadsheet-column-style alphabet labels.
- *
- *   toAlpha(1)  → "a"
- *   toAlpha(26) → "z"
- *   toAlpha(27) → "aa"
- *   toAlpha(53) → "ba"
- *   toAlpha(1, { upper: true }) → "A"
- */
-export function toAlpha(n: number, opts: { upper?: boolean } = {}): string {
-  if (!Number.isFinite(n) || n < 1) return String(n);
-  let value = Math.floor(n);
-  let out = "";
-  while (value > 0) {
-    const rem = (value - 1) % 26;
-    out = String.fromCharCode(97 + rem) + out;
-    value = Math.floor((value - 1) / 26);
-  }
-  return opts.upper ? out.toUpperCase() : out;
-}
-
-// ---------------------------------------------------------------------------
-// Zero-padded decimal
-// ---------------------------------------------------------------------------
-
-/**
- * Zero-padded decimal — `width` is the minimum number of digits.
- *
- *   toPadded(1)              → "01"
- *   toPadded(1, { width: 3 }) → "001"
- *   toPadded(123)            → "123"
- */
-export function toPadded(n: number, opts: { width?: number } = {}): string {
-  if (!Number.isFinite(n)) return String(n);
-  const width = Math.max(1, opts.width ?? 2);
-  return String(Math.floor(n)).padStart(width, "0");
-}
-
-// ---------------------------------------------------------------------------
-// Composable label templates
-// ---------------------------------------------------------------------------
-
-export type NumberFormat =
-  | "decimal"
-  | "decimal-padded"
-  | "cjk"
-  | "cjk-formal"
-  | "cjk-heavenly-stem"
-  | "cjk-earthly-branch"
-  | "roman"
-  | "roman-lower"
-  | "alpha"
-  | "alpha-upper";
-
-export interface ChapterLabelOptions {
-  format?: NumberFormat;
-  prefix?: string;
-  suffix?: string;
-  width?: number;
-}
-
-/**
- * Compose a chapter label like "第一章" / "Chapter 1" / "01" / "Part IV".
- *
- *   chapterLabel(1)
- *     → "第一章" (default: cjk informal, prefix 第, suffix 章)
- *   chapterLabel(1, { format: "decimal-padded", prefix: "Chapter " })
- *     → "Chapter 01"
- *   chapterLabel(4, { format: "roman", prefix: "Part " })
- *     → "Part IV"
- *   chapterLabel(2, { prefix: "", suffix: "" })
- *     → "二"
- */
-export function chapterLabel(n: number, opts: ChapterLabelOptions = {}): string {
-  const { format = "cjk", prefix = "第", suffix = "章", width } = opts;
-  return `${prefix}${formatNumber(n, format, width)}${suffix}`;
-}
-
-export interface SectionLabelOptions {
-  format?: NumberFormat;
-  separator?: string;
-  prefix?: string;
-  suffix?: string;
-}
-
-/**
- * Compose a section label like "1.1" / "1.1.2" / "一-1".
- *
- * Accepts variadic counters for nesting:
- *   sectionLabel(1, 2)
- *     → "1.2"
- *   sectionLabel(1, 2, 3)
- *     → "1.2.3"
- *   sectionLabel(1, 2, { format: "cjk", separator: "之" })
- *     ⚠ note: pass options as last argument when using variadic counters;
- *     prefer `sectionLabelOf([1, 2], { … })` below for clarity.
- */
-export function sectionLabel(...counters: number[]): string {
-  return sectionLabelOf(counters);
-}
-
-/**
- * Explicit-array variant of `sectionLabel` so options can be passed cleanly.
- *
- *   sectionLabelOf([1, 2], { separator: "-" })   → "1-2"
- *   sectionLabelOf([1, 2, 3], { format: "alpha" }) → "a.b.c"
- *   sectionLabelOf([1, 1], { format: "cjk", separator: "-" }) → "一-一"
- */
-export function sectionLabelOf(counters: number[], opts: SectionLabelOptions = {}): string {
-  const { format = "decimal", separator = ".", prefix = "", suffix = "" } = opts;
-  const parts = counters.map((c) => formatNumber(c, format));
-  return `${prefix}${parts.join(separator)}${suffix}`;
-}
-
-// ---------------------------------------------------------------------------
-// Generic dispatch — `format` -> formatter
-// ---------------------------------------------------------------------------
-
-/**
- * Format a single number using one of the named formats. Useful when the
- * caller already knows which format string to use (e.g. from config).
- *
- *   formatNumber(7, "cjk")           → "七"
- *   formatNumber(7, "roman-lower")   → "vii"
- *   formatNumber(3, "decimal-padded", 3) → "003"
- */
-export function formatNumber(n: number, format: NumberFormat, width?: number): string {
-  switch (format) {
-    case "decimal": return String(Math.floor(n));
-    case "decimal-padded": return toPadded(n, { width });
-    case "cjk": return toCjk(n);
-    case "cjk-formal": return toCjkFormal(n);
-    case "cjk-heavenly-stem": return toCjkHeavenlyStem(n);
-    case "cjk-earthly-branch": return toCjkEarthlyBranch(n);
-    case "roman": return toRoman(n, { upper: true });
-    case "roman-lower": return toRoman(n, { upper: false });
-    case "alpha": return toAlpha(n);
-    case "alpha-upper": return toAlpha(n, { upper: true });
-    default: return String(n);
-  }
-}
-
-// ---------------------------------------------------------------------------
-// CJK digit formatter (internal)
-// ---------------------------------------------------------------------------
-
-const CJK_UNITS = ["", "十", "百", "千"];
-const CJK_UNITS_FORMAL = ["", "拾", "佰", "仟"];
-
-// Gap-zero indicator used between non-zero digits when reading aloud
-// (e.g. 一百零八). Distinct from 〇/零 as a literal zero digit.
-const CJK_GAP_ZERO = "零";
-
-function formatCjkDigits(n: number, digits: string[], opts: { formal?: boolean } = {}): string {
-  if (n === 0) return digits[0]!;
-  if (n < 0) return `負${formatCjkDigits(-n, digits, opts)}`;
-  if (n >= 10000) {
-    const wan = Math.floor(n / 10000);
-    const rest = n % 10000;
-    if (rest === 0) return `${formatCjkDigits(wan, digits, opts)}萬`;
-    const restStr = formatCjkDigits(rest, digits, opts);
-    const padded = rest < 1000 ? `${CJK_GAP_ZERO}${restStr}` : restStr;
-    return `${formatCjkDigits(wan, digits, opts)}萬${padded}`;
-  }
-  const units = opts.formal ? CJK_UNITS_FORMAL : CJK_UNITS;
-  const str = String(n);
-  let out = "";
-  let zeroPending = false;
-  for (let i = 0; i < str.length; i++) {
-    const digit = Number(str[i]);
-    const unit = str.length - 1 - i;
-    if (digit === 0) {
-      zeroPending = true;
-      continue;
-    }
-    if (zeroPending && out.length > 0) {
-      out += CJK_GAP_ZERO;
-      zeroPending = false;
-    }
-    // Special case: leading "一十" usually written as just "十" in informal CJK
-    if (!opts.formal && digit === 1 && unit === 1 && i === 0) {
-      out += units[unit];
-    } else {
-      out += digits[digit] + units[unit];
-    }
-  }
-  return out;
-}