mosage 0.2.0 → 0.8.0

package/src/app/components/flow-page.tsx

@@ -0,0 +1,93 @@
+import type { CSSProperties, ReactNode } from 'react';
+import type { DesignSystem } from '../lib/design';
+import type { FlowSection } from '../lib/flow';
+import type { ExtractedNote } from '../lib/footnotes';
+import { PAGE_ATTR, PAGE_INDEX_ATTR } from '../lib/outline';
+import { DocPageProvider, useDocPageCount } from '../lib/page-context';
+import { Footnotes } from './footnote';
+
+export const FLOW_BLOCK_ATTR = 'data-od-flow-block';
+/** Around the section's footer, as `display: contents` so it lays out as if absent. */
+export const FLOW_FOOTER_ATTR = 'data-od-flow-footer';
+
+/**
+ * The page shell a flow section renders into. The framework owns the margin and
+ * base typography here — that is the trade for not hand-splitting pages — while
+ * the blocks keep their own styles.
+ *
+ * It is a column so the footnote area can sit at the foot of the sheet rather
+ * than immediately under the last paragraph. The blocks stay inside one block
+ * container, so their margins collapse exactly as they did when measured.
+ */
+export function flowShellStyle(design: DesignSystem | undefined, padding?: number): CSSProperties {
+  return {
+    width: '100%',
+    height: '100%',
+    boxSizing: 'border-box',
+    padding: padding ?? design?.margin ?? 76,
+    background: 'var(--od-bg)',
+    color: 'var(--od-text)',
+    fontFamily: 'var(--od-font-body)',
+    fontSize: 'var(--od-size-body)',
+    lineHeight: 'var(--od-leading)',
+    position: 'relative',
+    overflow: 'hidden',
+    display: 'flex',
+    flexDirection: 'column',
+  };
+}
+
+/**
+ * With a `sheet`, the block is a page frame of its own: the outline and
+ * numbering scans, and `useDocPageNumber()`, see the sheet it printed on even
+ * when it is laid out in one continuous column.
+ */
+export function FlowBlock({ children, sheet }: { children?: ReactNode; sheet?: number }) {
+  const total = useDocPageCount();
+  if (sheet === undefined) return <div {...{ [FLOW_BLOCK_ATTR]: '' }}>{children}</div>;
+  return (
+    <div {...{ [FLOW_BLOCK_ATTR]: '', [PAGE_ATTR]: '', [PAGE_INDEX_ATTR]: sheet }}>
+      <DocPageProvider index={sheet} total={total}>
+        {children}
+      </DocPageProvider>
+    </div>
+  );
+}
+
+export function FlowPage({
+  section,
+  design,
+  blockIndices,
+  blocks,
+  notes,
+  sheets,
+}: {
+  section: FlowSection;
+  design: DesignSystem | undefined;
+  blockIndices: number[];
+  /** Blocks with footnotes already lifted out; falls back to the authored ones. */
+  blocks?: ReactNode[];
+  notes?: ExtractedNote[];
+  /** Block index → the sheet it printed on, for a copy laid out as one column. */
+  sheets?: ReadonlyMap<number, number>;
+}) {
+  const Footer = section.footer;
+  const source = blocks ?? section.blocks;
+  return (
+    <div style={flowShellStyle(design, section.padding)}>
+      <div style={{ flex: 1, minHeight: 0 }}>
+        {blockIndices.map((index) => (
+          <FlowBlock key={index} sheet={sheets?.get(index)}>
+            {source[index]}
+          </FlowBlock>
+        ))}
+      </div>
+      {notes && notes.length > 0 && <Footnotes notes={notes} />}
+      {Footer && (
+        <div {...{ [FLOW_FOOTER_ATTR]: '' }} style={{ display: 'contents' }}>
+          <Footer />
+        </div>
+      )}
+    </div>
+  );
+}

package/src/app/components/footnote.tsx

@@ -0,0 +1,204 @@
+import {
+  type Context,
+  type CSSProperties,
+  createContext,
+  type ReactNode,
+  useContext,
+  useEffect,
+  useId,
+  useMemo,
+  useRef,
+  useState,
+} from 'react';
+import { LABEL_ATTR, LABEL_ID_ATTR, useDocLabel, useLabelVocabulary } from '../lib/labels';
+
+/** Stands in for a number the scan has not produced yet, or never will. */
+const UNNUMBERED = '\u2022';
+
+export type CollectedNote = { id: string; content: ReactNode };
+
+type Collector = {
+  /** Registration order, which is document order. */
+  ids: string[];
+  /**
+   * Note bodies live outside React state on purpose. A `ReactNode` is a new
+   * object on every render, so storing one in state would make every commit
+   * look like a change — register, re-render, register — and never settle.
+   * Ids are stable, so only they drive a re-render; the bodies are read fresh
+   * from here in whatever render follows.
+   */
+  contents: Map<string, ReactNode>;
+  register: (id: string, content: ReactNode) => void;
+  unregister: (id: string) => void;
+};
+
+// Same globalThis treatment as the page context: a document imports the
+// published bundle while the viewer runs the source copy, and a context created
+// twice registers into one instance and reads from the other.
+const GLOBAL_KEY = '__mosage_footnote_context__';
+type GlobalWithCtx = typeof globalThis & { [GLOBAL_KEY]?: Context<Collector | null> };
+const g = globalThis as GlobalWithCtx;
+if (!g[GLOBAL_KEY]) {
+  g[GLOBAL_KEY] = createContext<Collector | null>(null);
+}
+const FootnoteContext = g[GLOBAL_KEY];
+
+/**
+ * Collects the footnotes a fixed page renders, so `<Footnotes />` can print
+ * them at its foot. Flow sections never use this: their notes are lifted out of
+ * the blocks before measurement, because the space they take decides where the
+ * page breaks land.
+ */
+export function FootnoteCollector({ children }: { children?: ReactNode }) {
+  const contents = useRef<Map<string, ReactNode>>(new Map()).current;
+  const [ids, setIds] = useState<string[]>([]);
+
+  const value = useMemo<Collector>(
+    () => ({
+      ids,
+      contents,
+      register: (id, content) => {
+        contents.set(id, content);
+        setIds((current) => (current.includes(id) ? current : [...current, id]));
+      },
+      unregister: (id) => {
+        contents.delete(id);
+        setIds((current) => (current.includes(id) ? current.filter((x) => x !== id) : current));
+      },
+    }),
+    [ids, contents],
+  );
+
+  return <FootnoteContext.Provider value={value}>{children}</FootnoteContext.Provider>;
+}
+
+export const FOOTNOTE_MARKER_FLAG = '__odFootnote';
+
+export type FootnoteProps = {
+  /** Stable id, so `<Ref to>` can point at the note. Generated when omitted. */
+  id?: string;
+  children?: ReactNode;
+};
+
+export function markerStyle(): CSSProperties {
+  return {
+    fontSize: '0.7em',
+    lineHeight: 0,
+    verticalAlign: 'super',
+    fontVariantNumeric: 'tabular-nums',
+    color: 'var(--od-accent)',
+    padding: '0 1px',
+  };
+}
+
+/**
+ * The superscript in the text. Its position in the document decides the number.
+ *
+ * The placeholder is the one the printed note uses, and deliberately not an
+ * empty string: the two describe the same unresolved state, a note whose number
+ * never arrives has to be visible in both places rather than silently blank,
+ * and the packer measures this glyph — an empty marker is narrower than the
+ * digit that replaces it.
+ */
+export function FootnoteMarker({ id }: { id: string }) {
+  const entry = useDocLabel(id);
+  return (
+    <sup {...{ [LABEL_ATTR]: 'footnote', [LABEL_ID_ATTR]: id }} style={markerStyle()}>
+      {entry?.number ?? UNNUMBERED}
+    </sup>
+  );
+}
+
+/**
+ * A note anchored to this point in the text. Inside a `flow()` section the
+ * framework lifts it to the foot of whatever page the marker lands on; on a
+ * fixed page, put a `<Footnotes />` where you want them printed.
+ */
+export function Footnote({ id, children }: FootnoteProps) {
+  const generated = useId();
+  const noteId = id ?? generated;
+  const collector = useContext(FootnoteContext);
+  const latest = useRef<Collector | null>(null);
+
+  // Runs after every commit so the body stays current; only a new id changes
+  // state, so this settles instead of looping.
+  useEffect(() => {
+    latest.current = collector;
+    collector?.register(noteId, children);
+  });
+
+  useEffect(() => () => latest.current?.unregister(noteId), [noteId]);
+
+  return <FootnoteMarker id={noteId} />;
+}
+
+(Footnote as unknown as Record<string, boolean>)[FOOTNOTE_MARKER_FLAG] = true;
+
+export type FootnotesProps = {
+  /** Notes to print. Omitted on a fixed page, where they are collected from it. */
+  notes?: CollectedNote[];
+  style?: CSSProperties;
+  className?: string;
+};
+
+/** Outside the area's box, so measurement has to add it back by hand. */
+export const FOOTNOTE_AREA_MARGIN_TOP = 12;
+
+export const FOOTNOTE_ROW_ATTR = 'data-od-footnote-row';
+export const FOOTNOTE_BODY_ATTR = 'data-od-footnote-body';
+export const FOOTNOTES_ATTR = 'data-od-footnotes';
+
+export function footnoteAreaStyle(): CSSProperties {
+  return {
+    borderTop: '1px solid var(--od-rule)',
+    paddingTop: 6,
+    marginTop: FOOTNOTE_AREA_MARGIN_TOP,
+    fontSize: 'var(--od-size-caption)',
+    lineHeight: 1.45,
+    color: 'var(--od-muted)',
+  };
+}
+
+/** One note's row. Shared with the measurement pass so the reserved space is real. */
+export function FootnoteRow({ id, content }: CollectedNote) {
+  const entry = useDocLabel(id);
+  return (
+    <div {...{ [FOOTNOTE_ROW_ATTR]: id }} style={{ display: 'flex', gap: 5, marginBottom: 3 }}>
+      <span
+        style={{
+          flex: 'none',
+          fontVariantNumeric: 'tabular-nums',
+          color: 'var(--od-accent)',
+        }}
+      >
+        {entry?.number ?? UNNUMBERED}
+      </span>
+      <span {...{ [FOOTNOTE_BODY_ATTR]: '' }} style={{ minWidth: 0 }}>
+        {content}
+      </span>
+    </div>
+  );
+}
+
+export function Footnotes({ notes, style, className }: FootnotesProps) {
+  const collector = useContext(FootnoteContext);
+  const vocabulary = useLabelVocabulary();
+  const list =
+    notes ?? collector?.ids.map((id) => ({ id, content: collector.contents.get(id) })) ?? [];
+  if (list.length === 0) return null;
+
+  return (
+    <div
+      {...{ [FOOTNOTES_ATTR]: '' }}
+      className={className}
+      style={{ ...footnoteAreaStyle(), ...style }}
+    >
+      {vocabulary.footnotes ? (
+        <div style={{ fontWeight: 600, marginBottom: 3 }}>{vocabulary.footnotes}</div>
+      ) : null}
+      {list.map((note) => (
+        <FootnoteRow key={note.id} id={note.id} content={note.content} />
+      ))}
+    </div>
+  );
+}

package/src/app/components/image-placeholder.tsx

@@ -0,0 +1,50 @@
+import type { CSSProperties } from 'react';
+
+export type ImagePlaceholderProps = {
+  /** What the final image should show — the user reads this when replacing it. */
+  hint: string;
+  width?: number | string;
+  height?: number | string;
+  style?: CSSProperties;
+  className?: string;
+};
+
+/**
+ * Stands in for an image the user has to supply (a chart from their data, a
+ * product screenshot). Use it instead of inventing filler — never for
+ * decoration.
+ */
+export function ImagePlaceholder({
+  hint,
+  width = '100%',
+  height = 200,
+  style,
+  className,
+}: ImagePlaceholderProps) {
+  return (
+    <div
+      data-od-image-placeholder=""
+      className={className}
+      style={{
+        width,
+        height,
+        display: 'flex',
+        alignItems: 'center',
+        justifyContent: 'center',
+        textAlign: 'center',
+        padding: 16,
+        boxSizing: 'border-box',
+        border: '1px dashed var(--od-rule, #d4d4d8)',
+        borderRadius: 'var(--od-radius, 6px)',
+        background: 'repeating-linear-gradient(45deg, rgba(0,0,0,.02) 0 8px, transparent 8px 16px)',
+        color: 'var(--od-muted, #6b7280)',
+        fontFamily: 'var(--od-font-body, system-ui, sans-serif)',
+        fontSize: 'var(--od-size-caption, 10px)',
+        lineHeight: 1.4,
+        ...style,
+      }}
+    >
+      {hint}
+    </div>
+  );
+}