@open-press/core 0.6.0 → 0.7.1

package/src/openpress/core/types.ts

@@ -1,29 +1,37 @@
 import type { HTMLAttributes, ReactNode } from "react";
 
-export type PageKind = "cover" | "toc" | "content" | "back-cover";
+// ---------------------------------------------------------------------------
+// Frame / MdxArea / Press primitives
+// ---------------------------------------------------------------------------
 
-export interface PageProps {
-  pageIndex: number;
-  totalPages: number;
-  chapterSlug?: string;
-  chapterTone?: string;
-  children: ReactNode;
-}
+// `role` is opaque to core. Helpers and themes interpret it; the engine
+// never branches on its value. Format convention is dotted, e.g.
+// "manuscript.cover", "manuscript.content", "folio.page".
+export type FrameRole = string;
 
-export type BasePageProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
-  kind: PageKind;
-  footer?: boolean;
+export type FrameProps = Omit<HTMLAttributes<HTMLElement>, "role" | "children"> & {
+  frameKey: string;
+  role?: FrameRole;
+  chrome?: boolean;
+  className?: string;
   children?: ReactNode;
 };
 
-export type BaseShellPageProps = Omit<BasePageProps, "kind" | "footer">;
+export type MdxAreaOverflow = "extend" | "truncate" | "error";
 
-export type BaseContentPageProps = Omit<BasePageProps, "kind" | "footer" | "children"> &
-  PageProps & {
-    runningHeader?: ReactNode;
-    footerLeft?: ReactNode;
-    footerRight?: ReactNode;
-  };
+export type MdxAreaProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
+  chainId: string;
+  overflow?: MdxAreaOverflow;
+  className?: string;
+};
+
+export interface PressProps {
+  children: ReactNode;
+}
+
+// ---------------------------------------------------------------------------
+// Content primitives (figure, callout)
+// ---------------------------------------------------------------------------
 
 export type BaseFigureProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
   caption?: ReactNode;
@@ -37,6 +45,105 @@ export type BaseCalloutProps = Omit<HTMLAttributes<HTMLElement>, "children"> & {
   children: ReactNode;
 };
 
+// ---------------------------------------------------------------------------
+// Source descriptors and resolved sources
+// ---------------------------------------------------------------------------
+
+export interface MdxSourceDescriptorSectionFolders {
+  type: "mdx";
+  preset: "section-folders";
+  root?: string;
+}
+
+export interface MdxSourceDescriptorSectionFiles {
+  type: "mdx";
+  preset: "section-files";
+  root?: string;
+}
+
+export interface MdxSourceDescriptorFileList {
+  type: "mdx";
+  preset: "file-list";
+  files: string[];
+}
+
+export type MdxSourceDescriptor =
+  | MdxSourceDescriptorSectionFolders
+  | MdxSourceDescriptorSectionFiles
+  | MdxSourceDescriptorFileList;
+
+export type SourceDescriptor = MdxSourceDescriptor;
+
+export interface SourceNode {
+  id: string;
+  slug: string;
+  title: string;
+  meta?: Record<string, unknown>;
+  children?: SourceNode[];
+}
+
+export interface OutlineItem {
+  id: string;
+  depth: number;
+  title: string;
+  sectionSlug: string;
+  pageNumber?: number;
+}
+
+export interface TocEntry {
+  id: string;
+  blockId: string;
+  sourceId: string;
+  sectionSlug: string;
+  title: string;
+  href: string;
+  level: 2 | 3;
+  label: string;
+  pageNumber?: number;
+}
+
+export interface SourceFileRecord {
+  path: string;
+  absolutePath: string;
+  sectionSlug: string;
+}
+
+export interface SourceBlock {
+  id: string;
+  kind: string;
+  name?: string;
+  chainId: string;
+  sectionSlug: string;
+  path: string;
+  source: {
+    file: string;
+    line?: number;
+    column?: number;
+    offset?: number;
+  };
+}
+
+export interface ResolvedSource {
+  id: string;
+  type: "mdx";
+  tree: SourceNode[];
+  outline: OutlineItem[];
+  chains: Record<string, SourceBlock[]>;
+  files: SourceFileRecord[];
+}
+
+// ---------------------------------------------------------------------------
+// Allocation context shape (engine -> Frame -> MdxArea)
+// ---------------------------------------------------------------------------
+
+// Per-frame, per-chain, ordered list of React nodes assigned to each
+// MdxArea by area index.
+export type FrameAllocation = Record<string, Record<string, ReactNode[]>>;
+
+// ---------------------------------------------------------------------------
+// Manifest
+// ---------------------------------------------------------------------------
+
 export interface Manifest {
   title: string;
   subtitle?: string;
@@ -50,13 +157,18 @@ export interface Manifest {
   designDoc?: string;
   publicDir?: string;
   outputDir?: string;
+  captionNumbering?: {
+    figure?: string;
+    table?: string;
+    separator?: string;
+  };
   pdf?: {
     filename?: string;
   };
   deploy?: {
     adapter?: string;
     source?: string;
-    projectName?: string;
+    projectName?: string | null;
     commitDirty?: boolean;
     requiresConfirmation?: boolean;
   };

package/src/openpress/core/useSource.ts

@@ -0,0 +1,28 @@
+import { useContext } from "react";
+import { PressContext } from "./Press";
+import type { ResolvedSource } from "./types";
+
+// Read a resolved source by its registered key. The engine populates the
+// PressContext before rendering, so this is synchronous and safe to call
+// from any component inside <Press>.
+//
+// Throws if the source is missing, with a hint listing known sources.
+export function useSource<T extends ResolvedSource = ResolvedSource>(id: string): T {
+  const ctx = useContext(PressContext);
+  if (!ctx) {
+    throw new Error(
+      `useSource("${id}") called outside <Press> tree. ` +
+        `Source hooks only work inside the default-exported <Press> component.`,
+    );
+  }
+  const source = ctx.sources[id];
+  if (!source) {
+    const known = Object.keys(ctx.sources).sort();
+    const knownText = known.length > 0 ? known.join(", ") : "(none)";
+    throw new Error(
+      `Unknown source "${id}". Available sources: ${knownText}. ` +
+        `Register it under \`export const sources\` in document/index.tsx.`,
+    );
+  }
+  return source as T;
+}

package/src/openpress/manuscript/index.tsx

@@ -0,0 +1,196 @@
+// @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 ReactNode } from "react";
+import { Frame, FrameContext, PressContext, useSource } from "../core";
+import type { MdxAreaOverflow, ResolvedSource } from "../core";
+
+// ---------------------------------------------------------------------------
+// <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: React.ComponentType<SectionsPageProps>;
+  opener?: React.ComponentType<SectionsOpenerProps>;
+}
+
+export function Sections({ source: sourceId, page: Page, 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;
+
+// ---------------------------------------------------------------------------
+// <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 blocks = frame?.consumeArea(chainId) ?? null;
+  return (
+    <div
+      className="openpress-mdx-area openpress-toc-area"
+      data-openpress-mdx-area="true"
+      data-openpress-mdx-area-chain={chainId}
+      data-openpress-toc-max-level={maxLevel}
+      data-openpress-mdx-area-overflow={overflow}
+      data-openpress-mdx-area-empty={blocks == null ? "true" : undefined}
+    >
+      <ol className={["toc-list", className].filter(Boolean).join(" ") || undefined}>
+        {blocks}
+      </ol>
+    </div>
+  );
+}

package/src/openpress/mdx/index.ts

@@ -0,0 +1,88 @@
+// @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,
+  };
+}