@satzstrom/primitives

Primitives

Die öffentlichen React-Bausteine für physische Seiten, fließenden Satz, Dokumentstruktur und renderbereite Inhalte. Gestaltung und normale Komponenten bleiben vollständig bei dir.

Import

import { Document, Page, PageMaster } from "@satzstrom/primitives";

Jedes direkte Kind von Document ist eine feste Page oder ein fließender PageMaster. Beide dürfen im selben Dokument kombiniert werden.

Document

Wurzel eines Satzstrom-Dokuments. Definiert Sprache, Leserichtung, PDF-Metadaten und optionale Dokumentlabels.

Signatur

function Document(props: DocumentProps): ReactNode

Document Props
Name	Typ	Pflicht	Beschreibung
`children`	`ReactNode`	Ja	Feste Seiten und PageMaster des Dokuments.
`title`	`string`	Ja	Dokumenttitel und PDF-Metadatum.
`author`	`string`	Nein	Optionaler Autor der PDF.
`subject`	`string`	Nein	Optionaler Betreff der PDF.
`keywords`	`string[]`	Nein	Suchbegriffe für die PDF-Metadaten.
`lang`	`string`	Nein	Dokumentsprache; standardmäßig de.
`dir`	`"ltr" \| "rtl"`	Nein	Leserichtung; standardmäßig ltr.
`bookmarks`	`SequenceDefinition<boolean>`	Nein	Sequence, aus der PDF-Bookmarks entstehen.
`labels`	`DocumentLabels`	Nein	Überschreibt lokalisierte zugängliche Labels.
`className`	`string`	Nein	CSS-Klasse des Dokument-Root-Elements.

Beispiel

import { Document, Page } from "@satzstrom/primitives";export default function Invoice() {  return (    <Document title="Rechnung 2026-0718" author="Brückner Studio" lang="de">      <Page size="A4">…</Page>    </Document>  );}

Page

Erzeugt genau eine frei komponierte physische Seite. Kinder können statisch sein oder Seitenwerte als Render-Funktion erhalten.

Signatur

function Page(props: PageProps): ReactNode

Page Props
Name	Typ	Pflicht	Beschreibung
`children`	`ReactNode \| ((PageContext) => ReactNode)`	Ja	Der Seiteninhalt oder eine Render-Funktion mit page und pages.
`size`	`PageSizeName \| { width; height }`	Nein	Papierformat; standardmäßig A4. Eigene Maße sind Millimeter.
`orientation`	`"portrait" \| "landscape"`	Nein	Ausrichtung der Seite.
`bleed`	`number`	Nein	Nichtnegative Beschnittzugabe in Millimetern.
`cropMarks`	`boolean`	Nein	Aktiviert Schnittmarken.
`className`	`string`	Nein	CSS-Klasse der physischen Seite.

Zusätzlich akzeptiert Page die normalen Props eines section-Elements, ausgenommen children.

Beispiel

<Page size="A4" orientation="landscape" bleed={3} cropMarks>  {({ page, pages }) => <footer>{page} / {pages}</footer>}</Page>

PageMaster

Lässt seine Kinder durch einen wiederkehrenden React-Seitenrahmen fließen und erzeugt so viele Seiten wie nötig.

Signatur

function PageMaster(props: PageMasterProps): ReactNode

PageMaster Props
Name	Typ	Pflicht	Beschreibung
`children`	`ReactNode`	Ja	Der zu paginierende Fließinhalt.
`layout`	`ComponentType<PageLayoutProps>`	Ja	Seitenrahmen mit children, page und pages.
`size`	`PageSettings["size"]`	Nein	Papierformat für alle Seiten dieses Masters.
`orientation`	`PageSettings["orientation"]`	Nein	Gemeinsame Seitenausrichtung.
`bleed`	`number`	Nein	Beschnittzugabe in Millimetern.
`cropMarks`	`boolean`	Nein	Aktiviert Schnittmarken.
`className`	`string`	Nein	CSS-Klasse der erzeugten Seiten.

Beispiel

import { Document, PageMaster, type PageLayoutProps } from "@satzstrom/primitives";function ReportPage({ children, page, pages }: PageLayoutProps) {  return (    <div className="report-page">      <header>Jahresbericht</header>      <main>{children}</main>      <footer>{page} / {pages}</footer>    </div>  );}export default function Report() {  return (    <Document title="Jahresbericht">      <PageMaster layout={ReportPage} size="A4">        <h1>Einleitung</h1>        <p>Dieser Inhalt fließt über alle benötigten Seiten.</p>      </PageMaster>    </Document>  );}

PageBreak

Erzwingt im Fließinhalt eines PageMaster den Beginn einer neuen Seite.

Signatur

function PageBreak(): ReactNode

Beispiel

<PageMaster layout={ReportPage}>  <ChapterOne />  <PageBreak />  <ChapterTwo /></PageMaster>

RepeatBox

Markiert eine Box so, dass Rahmen, Hintergrund und Padding auf jedem Fragment der Box wiederholt werden.

Signatur

function RepeatBox<E extends ElementType = "div">(props: RepeatBoxProps<E>): ReactNode

RepeatBox Props
Name	Typ	Pflicht	Beschreibung
`as`	`ElementType`	Nein	Gerendertes HTML-Element; standardmäßig div.
`…props`	`ComponentPropsWithoutRef<E>`	Nein	Alle Props des gewählten Elements.

Beispiel

<RepeatBox as="aside" className="notice">  Ein langer Hinweis, der über eine Seitenkante laufen darf.</RepeatBox>

defineSequence

Definiert ein unveränderliches, unabhängiges Nummerierungssystem für Kapitel, Abbildungen oder Tabellen.

Signatur

function defineSequence(config: {  name: string;  titleRequired?: boolean;}): SequenceDefinition

Beispiel

const chapters = defineSequence({  name: "chapters",  titleRequired: true,});<Sequence sequence={chapters} title="Ergebnisse">  {({ number, title }) => <h2>{number} {title}</h2>}</Sequence>

Sequence

Registriert einen Eintrag in einer Sequence und stellt berechnete Nummer, Titel und Verschachtelungstiefe bereit.

Signatur

function Sequence(props: SequenceProps): ReactNode

Sequence Props
Name	Typ	Pflicht	Beschreibung
`sequence`	`SequenceDefinition`	Ja	Die mit defineSequence erstellte Definition.
`id`	`string`	Nein	Explizites HTML-Ziel für Verweise.
`title`	`string`	Nein	Titel des Eintrags; bei titleRequired verpflichtend.
`numberLabel`	`string`	Nein	Zugängliches Label der ausgegebenen Nummer.
`children`	`(value) => ReactNode`	Ja	Render-Funktion mit number, title und depth.

Erzeugt aus einer Sequence ein Inhaltsverzeichnis mit endgültigen Nummern und Seiten oder übergibt die Einträge an eine eigene Komponente.

Signatur

function Contents(props: ContentsProps): ReactNode

Contents Props
Name	Typ	Pflicht	Beschreibung
`sequence`	`SequenceDefinition`	Ja	Quelle der Inhaltsverzeichniseinträge.
`className`	`string`	Nein	Klasse des Standard-Inhaltsverzeichnisses.
`asChild`	`true`	Nein	Übergibt entries an genau ein eigenes React-Element.

Beispiel

<Contents sequence={chapters} /><Contents sequence={chapters} asChild>  <CustomContents /></Contents>

Ref

Verlinkt auf eine HTML-ID und zeigt deren berechnete Nummer, Titel oder endgültige Seite.

Signatur

function Ref(props: RefProps): ReactNode

Ref Props
Name	Typ	Pflicht	Beschreibung
`target`	`string`	Ja	HTML-ID des referenzierten Ziels.
`value`	`"number" \| "title" \| "page"`	Nein	Ausgabewert; standardmäßig number.
`className`	`string`	Nein	CSS-Klasse des Links.

Beispiel

Siehe <Ref target="results" value="number" /> auf Seite <Ref target="results" value="page" />.

Footnote

Setzt einen nummerierten Fußnotenaufruf im Text und verschiebt den Inhalt in den Fuß der passenden Seite.

Signatur

function Footnote(props: { children: ReactNode; label?: string }): ReactNode

Beispiel

Diese Aussage braucht einen Beleg<Footnote>Quelle: Geschäftsbericht 2025.</Footnote>.

Math

Rendert KaTeX als sichtbares HTML plus zugängliches MathML, inline oder als eigene Formelzeile.

Signatur

function Math(props: {  children: string;  display?: boolean;  label?: string;}): ReactNode

Beispiel

<Math>{String.raw`E = mc^2`}</Math><Math display label="Quadratische Formel">  {String.raw`x = \frac{-b \pm \sqrt{b^2-4ac}}{2a}`}</Math>

Markdown

Rendert GitHub-Flavored Markdown mit Tabellen, Fußnoten und Mathematik. Rohes HTML wird bewusst übersprungen.

Signatur

function Markdown(props: {  children: string;  labels?: MarkdownLabels;}): ReactNode

Beispiel

<Markdown>{`## Ergebnisse| Quartal | Umsatz || --- | ---: || Q1 | 42.000 € |Ein Verweis mit Fußnote.[^1][^1]: Interne Auswertung.`}</Markdown>

useRenderReady

Hält Messung und Render zurück, solange ein asynchroner Browser-Inhalt noch nicht bereit ist.

Signatur

function useRenderReady(ready: boolean): void

Beispiel

function RemoteChart() {  const { data, isLoading } = useReportData();  useRenderReady(!isLoading);  return data ? <Chart data={data} /> : null;}