Nodes

Het nodemodel

Wat alle nodes gemeen hebben, waarin ze verschillen, en waar elk van hen is gedocumenteerd.

Een document is een boom van nodes. Elke node is drie dingen: een id, een soort, en een regel om content te produceren.

paragraph<MemberData>({
  id: "greeting",                                // the address
  render: (data) => `Dear ${data.memberName},`,  // the rule
});                                              // the helper is the kind

Opgelost tegen jouw data wordt het pure JSON:

{ "id": "greeting", "kind": "paragraph", "mode": "static", "text": "Dear Adaeze Nkemelu," }

Geen opmaak, geen lay-out. Die horen bij de renderer.

De catalogus

Elk type heeft een eigen pagina, met elke optie die het aanneemt en een preview van elke manier waarop het geschreven kan worden.

Structuur

section Groups nodes under a titled heading.

The only construct that nests today. Its title carries into the document outline, so the structure you write is the structure the reader sees.

Helpers: section, Section

export const Opening = section<SampleData>({ id: "opening", title: "Your renewal" }, [
  Greeting,
  PriceChange,
]);

Section-referentie, met previews →

tableOfContents A marker for a contents list, ahead of the renderers that build one. Nog geen helper

The kind is part of the letter schema and both renderers accept it, but no authoring helper is exported yet. Writing the component by hand works — a node component is a function returning a definition, and the helpers are conveniences over exactly that shape.

export const Contents: NodeComponent<SampleData> = () => ({
  kind: "tableOfContents",
  id: "contents",
  title: "What is in this letter",
});

Table of contents-referentie, met previews →

Tekst

paragraph A block of prose, rendered from your data or from prompts.

The workhorse. A static paragraph returns a string from your typed data; a dynamic one carries prompts and a placeholder, and is filled at request time. Both land as the same node kind, differing only by `mode`.

export const Greeting = paragraph<SampleData>({
  id: "greeting",
  render: (data) => `Dear ${data.memberName},`,
});

Paragraph-referentie, met previews →

Media

image A picture resolved from your data or described by a prompt.

A static image points at something you hold — a signature, a logo, a site photograph — with every field able to vary per recipient. A dynamic image describes what is wanted and leaves the endpoint to make it.

export const Signature = image<SampleData>({
  id: "signature",
  src: (data) => data.signatureUrl,
  alt: (data) => `Signed by ${data.managerName}`,
  width: 180,
  height: 60,
});

Image-referentie, met previews →

clipArt Named visual blocks — rules, marks, callouts — drawn by the renderer. Gepland

Not built yet. Nothing is fetched: the node names a shape and the renderer draws it, so it stays sharp in the DOCX and ships no asset.

Data

graph A bar, line or pie chart declared as data.

Charts are declared, never drawn: `graphType` fixes the form, `data` returns the payload. Holding numbers rather than an image means one declaration serves every renderer and stays diffable in the artifact.

export const VisitsByMonth = graph<SampleData>({
  id: "visits-by-month",
  graphType: "bar",
  data: (data) => ({
    labels: data.visitsByMonth.map((entry) => entry.month),
    series: [{ name: "Visits", values: data.visitsByMonth.map((entry) => entry.visits) }],
  }),
  caption: (data) => `Your visits to ${data.centreName}, last six months`,
});

Graph-referentie, met previews →

table Rows and columns, with cells that are themselves nodes. Gepland

Not built yet. The intent is a node whose cells hold other nodes, so a table composes the way a section does rather than becoming a second content model beside it.

Ids zijn adressen

Het id van een node is hoe een generatie-endpoint die alinea aanwijst, en hoe twee buildartefacten in een diff naast elkaar komen te liggen. Een id hernoemen breekt wat er van buitenaf naar wijst, net zoals het hernoemen van een API-route dat doet.

Houd ze uniek binnen het document. Het kost niets en maakt logs leesbaar.

Statisch en dynamisch

Een statische node berekent zijn content lokaal uit je data. Een dynamische node draagt prompts en een placeholder, en wordt op het moment van de aanvraag ingevuld.

Je declareert nooit welke je wilt. Er is één helper per soort — paragraph, image, graph — en de modus wordt afgeleid uit de opties die je meegeeft: geef je het lid voor lokale oplossing (render, src, data), dan is de node statisch; geef je in plaats daarvan prompts, dan is hij dynamisch. Beide lossen op naar dezelfde kind en verschillen in het gebouwde document door mode.

Beide meegeven is een compileerfout, dus mode heeft precies één bron van waarheid. Statisch en dynamisch behandelt waar de grens ligt en waarom.

Nesteling

section is vandaag de enige node die kinderen bevat, en hij accepteert elke soort, ook andere secties. Een tabelnode met nodes in zijn cellen is de volgende, volgens hetzelfde principe: containers bevatten de componenten die je toch al schrijft, in plaats van een tweede contentmodel ernaast.

Over deze previews

Elke preview hier is een echte build. src/nodes/ in de repository van deze site bevat één bestand per variant, geschreven tegen het gepubliceerde package; een buildstap lost elk daarvan op via buildDocument en rendert het met de renderer die dxcl dev serveert. De getoonde broncode is het bestand dat gedraaid heeft, en de JSON is wat eruit kwam — zodat deze pagina’s luid stukgaan in plaats van stilletjes te verouderen.

Deze pagina bewerken op GitHub ↗