@format.dev/react 0.0.0 → 0.1.0

package/dist/index.cjs

@@ -0,0 +1,468 @@
+let react_dom_server = require("react-dom/server");
+let react_jsx_runtime = require("react/jsx-runtime");
+
+//#region src/utils.ts
+const IMAGE_PRELOAD_LINK = /<link\b(?=[^>]*\brel="preload")(?=[^>]*\bas="image")[^>]*>/g;
+/**
+* Removes the `<link rel="preload" as="image">` tags that React's server
+* renderer emits ahead of every eager `<img>`. The engine allows a `<link>`
+* only when its `rel` is `stylesheet`, and fails the render with an
+* `INVALID_HTML_LINK_ELEMENT` 400 otherwise.
+*/
+function stripImagePreloads(html) {
+	return html.replace(IMAGE_PRELOAD_LINK, "");
+}
+/**
+* Tagged template for authoring CSS, typically inside a `<style>` element.
+* Returns the string from the raw segments, so CSS escapes (`\2014`,
+* icon-font codepoints, escaped selectors) survive intact. Interpolated
+* `null`, `undefined`, and `false` collapse to an empty string for clean
+* conditional rules. The `css` name also lets editors and the Format docs
+* highlighter treat the contents as CSS.
+*/
+function css(parts, ...vals) {
+	let out = parts.raw[0] ?? "";
+	for (let i = 0; i < vals.length; i++) {
+		const v = vals[i];
+		out += (v == null || v === false ? "" : String(v)) + parts.raw[i + 1];
+	}
+	return out;
+}
+
+//#endregion
+//#region src/Template.tsx
+function Template({ children, ...props }) {
+	const html = stripImagePreloads((0, react_dom_server.renderToStaticMarkup)(children));
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("template", {
+		...props,
+		dangerouslySetInnerHTML: { __html: html }
+	});
+}
+
+//#endregion
+//#region src/engine-target.ts
+const engineTarget = "0.1.0";
+
+//#endregion
+//#region src/sdk-version.ts
+const sdkVersion = "0.1.0";
+
+//#endregion
+//#region src/Document.tsx
+function Document({ title, subject, author, keywords, fonts, children }) {
+	const keywordsString = keywords?.join(", ");
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-sdk": sdkVersion,
+		"data-engine": engineTarget,
+		"data-type": "document",
+		"data-title": title,
+		"data-subject": subject,
+		"data-author": author,
+		"data-keywords": keywordsString,
+		"data-fonts": fonts,
+		children
+	});
+}
+
+//#endregion
+//#region src/Layout.tsx
+function Layout({ id, width, height, paginationStrategy, splitGranularity, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "layout",
+		"data-id": id,
+		"data-width": `${width}px`,
+		"data-height": `${height}px`,
+		"data-pagination-strategy": paginationStrategy,
+		"data-split-granularity": splitGranularity,
+		children
+	});
+}
+
+//#endregion
+//#region src/Flow.tsx
+/**
+* A Flow is a region whose content paginates across pages. Everything inside the
+* Flow that isn't its Stream is scaffolding that repeats on every page the
+* content spans; the stream's items appear once and flow.
+*
+* Author the stream two ways:
+*
+* - **bare** — `<Flow>{items}</Flow>`: the Flow's own children are the stream,
+*   injected with no wrapper element.
+* - **scaffolded** — wrap the stream in a `<Stream>` inside surrounding markup,
+*   e.g. `<Flow><table><thead/><Stream>{rows}</Stream><tfoot/></table></Flow>`:
+*   the table, thead, and tfoot repeat per page; the rows flow.
+*
+* Flows nest: a Flow placed inside another Flow's stream paginates against the
+* nearest enclosing sealing region (a Frame, else the page), re-cloning its own
+* scaffolding on each page its content reaches.
+*/
+function Flow({ splitGranularity, paginationStrategy, scope, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "flow",
+		"data-split-granularity": splitGranularity,
+		"data-pagination-strategy": paginationStrategy,
+		"data-scope": scope,
+		children
+	});
+}
+
+//#endregion
+//#region src/Stream.tsx
+/**
+* A Stream marks where a scaffolded Flow's items land. Use it when a Flow wraps
+* its content in repeating scaffolding (a table's header and footer, a titled
+* panel) and you need to say where in that scaffolding the stream flows in:
+*
+* ```tsx
+* <Flow>
+*   <table>
+*     <thead>…</thead>
+*     <Stream>{rows}</Stream>
+*     <tfoot>…</tfoot>
+*   </table>
+* </Flow>
+* ```
+*
+* Omit it for a bare Flow, where the Flow's own children are the stream.
+*/
+function Stream({ children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "stream",
+		children
+	});
+}
+
+//#endregion
+//#region src/PageBreak.tsx
+function PageBreak() {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)("template", { "data-type": "page-break" });
+}
+
+//#endregion
+//#region src/PageCounter.tsx
+function PageCounter({ type, as: Tag = "span", counterStyle, style, ...rest }) {
+	const mergedStyle = counterStyle ? {
+		...style,
+		"--page-counter-style": counterStyle
+	} : style;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Tag, {
+		"data-type": type,
+		style: mergedStyle,
+		...rest
+	});
+}
+
+//#endregion
+//#region src/PageNumber.tsx
+function PageNumber(props) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PageCounter, {
+		...props,
+		type: "page-number"
+	});
+}
+
+//#endregion
+//#region src/PageCount.tsx
+function PageCount(props) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(PageCounter, {
+		...props,
+		type: "page-count"
+	});
+}
+
+//#endregion
+//#region src/Counter.tsx
+/**
+* A counter whose value survives pagination. Unlike a CSS counter, which resets
+* on every page, this is resolved by Format before pages are split, so the
+* number stays correct wherever the content lands.
+*
+* By default it advances the counter and shows the new value — the usual "this
+* is Figure N" case. `peek` reads without advancing, `set` jumps to a value, and
+* `reset` starts the count over. These three are mutually exclusive; when more
+* than one is set, `reset` wins, then `set`, then `peek`. `by` applies only to
+* the default advance.
+*
+* Give the counter an `id` to make it referenceable. A `<Ref to="that-id" />`
+* then prints the exact value this counter showed, and `<Ref to="that-id" page />`
+* the page it landed on — the same way a heading's id yields its section number.
+*/
+function Counter({ name, peek, reset, set, by, join, as: Tag = "span", counterStyle, ...rest }) {
+	if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production" && set !== void 0 && by !== void 0) console.error("<Counter>: `set` and `by` are mutually exclusive; `set` jumps to an exact value and wins, `by` is ignored.");
+	const action = reset ? "reset" : set !== void 0 ? "set" : peek ? "peek" : "next";
+	const value = set !== void 0 ? set : action === "next" ? by : void 0;
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Tag, {
+		"data-type": "counter",
+		"data-name": name,
+		"data-action": action,
+		"data-value": value,
+		"data-join": join,
+		"data-counter-style": counterStyle,
+		...rest
+	});
+}
+
+//#endregion
+//#region src/Numbering.tsx
+/**
+* Turns on document-wide numbering. With no children it numbers headings `h1`
+* through `h6` hierarchically — `1`, `1.1`, `1.1.1` — with each level resetting
+* the ones beneath it. Add <NumberingRule> children to number other things or
+* change the format.
+*
+* Numbers are resolved before pages are split, so they stay correct across page
+* breaks where plain CSS counters would reset.
+*
+* ```tsx
+* <Document title="Report">
+*   <Numbering />
+*   ...
+* </Document>
+* ```
+*/
+function Numbering({ counterStyle, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "numbering",
+		"data-counter-style": counterStyle,
+		children
+	});
+}
+/**
+* One numbering rule, used as `<NumberingRule>` inside `<Numbering>`. Each rule
+* matches a selector and advances (and optionally inserts) a counter. Add rules
+* to number things beyond the default headings, or to change the heading format.
+*/
+function NumberingRule({ match, counter, format, increment, set, counterStyle, insert }) {
+	if (typeof process !== "undefined" && process.env?.NODE_ENV !== "production" && set !== void 0 && increment !== void 0) console.error("<NumberingRule>: `set` and `increment` are mutually exclusive; `set` forces an exact value and wins, `increment` is ignored.");
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "numbering-rule",
+		"data-match": match,
+		"data-counter": counter,
+		"data-format": format,
+		"data-increment": increment,
+		"data-set": set,
+		"data-counter-style": counterStyle,
+		"data-insert": insert
+	});
+}
+/**
+* Declares one counter's behaviour, used as `<CounterDef>` inside `<Numbering>`. Name
+* the counter and, optionally, the owner counter it restarts under. A counter with an
+* owner returns to 0 every time the owner's value changes; one with no owner restarts
+* only when you reset or set it yourself.
+*
+* ```tsx
+* <Numbering>
+*   <CounterDef name="figure" resetEach="chapter" />
+*   <NumberingRule match="figcaption" counter="figure" format="Figure {chapter}.{figure}: " />
+* </Numbering>
+* ```
+*/
+function CounterDef({ name, resetEach }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "counter-def",
+		"data-name": name,
+		"data-reset-each": resetEach
+	});
+}
+
+//#endregion
+//#region src/Scope.tsx
+/**
+* Opens a counter scope around its children and adds no element to the output: a
+* `<Scope>` is the fallback for nesting content that has no element of its own to carry
+* the scope. When the content already sits in a container or a `<Flow>`, mark that
+* directly (`<ol data-scope="item">`, `<Flow scope="item">`) instead of wrapping.
+*
+* ```tsx
+* <Scope counter="item">
+*   <Counter name="item" join="." /> First
+*   <Scope counter="item">
+*     <Counter name="item" join="." /> Nested
+*   </Scope>
+* </Scope>
+* ```
+*/
+function Scope({ counter, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-scope": counter,
+		children
+	});
+}
+
+//#endregion
+//#region src/Ref.tsx
+/**
+* A cross-reference to a numbered element — "see Section 2.1" or "Figure 3".
+* Point it at an `id`: a heading's id yields its section number, a `<Counter>`'s
+* id yields the value that counter printed. Add `page` for the page the target
+* landed on, or `counter` to read a named counter's running value at the target.
+*
+* References resolve before pages are split and can point forward to an element
+* that appears later in the document.
+*
+* ```tsx
+* <figcaption>Figure <Counter name="figure" id="flow" />: the data flow</figcaption>
+* // ...anywhere else in the document:
+* <p>The method (see Section <Ref to="method" />) reads Figure <Ref to="flow" />,
+*    shown in full on page <Ref to="flow" page />.</p>
+* ```
+*/
+function Ref({ to, counter, page, as: Tag = "span", counterStyle, ...rest }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Tag, {
+		"data-type": "ref",
+		"data-to": to,
+		"data-counter": page ? void 0 : counter,
+		"data-page": page ? "" : void 0,
+		"data-counter-style": counterStyle,
+		...rest
+	});
+}
+
+//#endregion
+//#region src/TableOfContents.tsx
+/**
+* A table of contents. Format fills it after laying out the document: one entry
+* per heading the `collect` selector matches, each with the heading's number, its
+* title, and the page it landed on.
+*
+* The entries are flat anchors in a `<div data-type="toc-entries">` inside a
+* `<nav data-type="toc">`: each is an `<a data-type="toc-entry" data-depth="N">`
+* (depth 0 at the top of the outline) holding `toc-number`, `toc-title`, and
+* `toc-page` spans. Depth is data, not nesting, so the stylesheet indents and sizes
+* by depth and a long contents paginates by breaking between anchors. Style it through
+* the `data-type` hooks and the `--toc-*` custom properties (root size, per-depth size
+* and indent, page-number size, leader, and vertical rhythm), or set a `className` (or
+* `styled(TableOfContents)`) on the nav. Set `leader="none"` to omit the dot leader
+* entirely, so no leader is drawn between a title and its page number.
+*
+* Children are leading content shown above the entries — put a "Contents" heading there.
+* It shows once by default; set `repeatHead` to repeat it with the nav on every page.
+*
+* Give a collected heading a `data-toc-description` and its entry gains a
+* `toc-description` line under the title (a one-line summary, as on a magazine or
+* report contents):
+*
+* ```tsx
+* <TableOfContents collect="h1, h2">
+*   <h2>Contents</h2>
+* </TableOfContents>
+*
+* <h1 data-toc-description="Defining the studio's personality and direction.">
+*   Visual Positioning
+* </h1>
+* ```
+*/
+function TableOfContents({ collect, leader, repeatHead, className, style, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "toc",
+		"data-collect": collect,
+		"data-leader": leader,
+		"data-repeat-head": repeatHead === void 0 ? void 0 : repeatHead ? "true" : "false",
+		className,
+		style,
+		children
+	});
+}
+
+//#endregion
+//#region src/Footnote.tsx
+/**
+* A footnote. Write the note's text as the children, at the point it's
+* referenced; Format leaves a numbered marker inline and moves the text to the
+* footer of whichever page the marker lands on. Footnotes are numbered
+* continuously through the document.
+*
+* Pair it with a `<Footnotes />` region in the Layout to control where the notes
+* sit; without one, Format adds a footer area to each page that needs it.
+*
+* ```tsx
+* <p>The result holds<Footnote>under the stated assumptions</Footnote>.</p>
+* ```
+*/
+function Footnote({ children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "footnote",
+		children
+	});
+}
+
+//#endregion
+//#region src/Footnotes.tsx
+/**
+* The region that collects a page's footnotes, authored as a `<template>` Format
+* fills. In a Layout it is a per-page footer gathering the notes whose markers
+* landed there; in a flow's content it is an endnotes list. Format renders it as an
+* `<aside data-type="footnotes">` holding a `<dl data-type="footnote-entries">`, where
+* each note is a `<dt data-type="footnote-number">` term and a
+* `<dd data-type="footnote-content">` definition; style the list as a grid with your
+* own CSS.
+*
+* Put a heading or rule inside `<Footnotes>` to render it above the generated list,
+* the way a table of contents renders its leading content above the entries:
+*
+* ```tsx
+* <Footnotes>
+*   <h4>Notes</h4>
+* </Footnotes>
+* ```
+*
+* Omit it and Format adds a plain footer to each page that has footnotes.
+*/
+function Footnotes({ counterStyle, restartEachPage, repeatHead, className, style, children }) {
+	return /* @__PURE__ */ (0, react_jsx_runtime.jsx)(Template, {
+		"data-type": "footnotes",
+		"data-counter-style": counterStyle,
+		"data-restart-each-page": restartEachPage ? "" : void 0,
+		"data-repeat-head": repeatHead === void 0 ? void 0 : repeatHead ? "true" : "false",
+		className,
+		style,
+		children
+	});
+}
+
+//#endregion
+//#region src/types.ts
+/**
+* How a Flow splits content that overflows a page: at a `sentence`, `word`, or
+* `grapheme` boundary, or `none` to keep the block whole and move it to the next
+* page intact. Use the constant (`SplitGranularity.None`) or the plain string
+* (`'none'`); both are accepted.
+*/
+const SplitGranularity = {
+	Sentence: "sentence",
+	Word: "word",
+	Grapheme: "grapheme",
+	None: "none"
+};
+/**
+* The dot leader between a contents entry's title and its page number. The default,
+* `dots`, draws it; `none` leaves the run between them blank. Use the constant
+* (`TocLeader.None`) or the plain string (`'none'`); both are accepted.
+*/
+const TocLeader = {
+	Dots: "dots",
+	None: "none"
+};
+
+//#endregion
+exports.Counter = Counter;
+exports.CounterDef = CounterDef;
+exports.Document = Document;
+exports.Flow = Flow;
+exports.Footnote = Footnote;
+exports.Footnotes = Footnotes;
+exports.Layout = Layout;
+exports.Numbering = Numbering;
+exports.NumberingRule = NumberingRule;
+exports.PageBreak = PageBreak;
+exports.PageCount = PageCount;
+exports.PageNumber = PageNumber;
+exports.Ref = Ref;
+exports.Scope = Scope;
+exports.SplitGranularity = SplitGranularity;
+exports.Stream = Stream;
+exports.TableOfContents = TableOfContents;
+exports.TocLeader = TocLeader;
+exports.css = css;