Writing a diagram

In a page#

Write the text between the tags of sds-diagram. The element draws it inline, in the page's tokens and faces, so it turns with the mode. The indent that the whole text shares does not count.

<sds-diagram>
  tiles
  title "Where the needs come from"
  description "The number of needs from each source."
  tile "27" "Market"
    emphasis
  tile "15" "Field test"
</sds-diagram>

With a caption, or to open it large#

The drawing has no frame and no caption of its own. Put the element in sds-figure for both. zoomable lets a press open the drawing at the size of the window, for a drawing too dense to read in the column.

<sds-figure caption="The first lookup reads the file, the second stops at the array.">
  <sds-diagram zoomable>
    flow
    …
  </sds-diagram>
</sds-figure>

On a slide#

Put the element in the figure region of sds-slide. Write slide=width,height on the first line of the text, in the pixels of the room that the layout leaves. Slides states those rooms. The engine then draws with no margin, and refuses a drawing taller than the room. A slide has no zoom.

A text without slide= gets the room from the slide. The slide measures the room its layout leaves in the frame's pixels, and lends the drawing that room a tenth larger. A reader sees a slide from further away than a page, so the drawing's type stands near the slide's own scale. A text too dense for that room first lowers the screens of its sketches in steps, down to 0.7 of their height. Then it takes the same shape up to twice as large, and the slide shrinks it whole. A text that still does not fit draws as on a page.

The engine sets a drawing dense in a room that the slide lends. The type keeps its sizes, and never goes under 13. The controls, rows, pads and gaps are lower. A field or a button is 24 high, not 28, and a row of a list 20, not 24. So a figure of a page fits the room of a slide at its full width, and the slide does not shrink its type.

A text that writes slide= keeps the page's metrics, because its author measured it in them. A page drawing does not change.

A chain of a flow folds on a slide. That is one row, with each connector to the next column. The engine tries one, two and three rows and takes the fold that wraps its cards the least. Each row runs left to right, and the connector at its end runs down to the start of the next.

<sds-slide kind="figure">
  <h2 slot="heading">One key for two languages</h2>
  <sds-diagram slot="figure">
    flow slide=877,354 columns=340,370 gap=167,16
    …
  </sds-diagram>
</sds-slide>

In a Guides document#

Write the text as the body of .. diagram::. The directive takes the body as it is, and Directives lists its options. A text in a .diagram file of its own is :file: diagrams/flow.diagram, relative to the document.

.. diagram::
   :zoomable:

   tiles
   title "Where the needs come from"
   description "The number of needs from each source."
   tile "27" "Market"
     emphasis
   tile "15" "Field test"

As a file to keep#

A drawing for a README, an image or another tool is an SVG file. The file carries a cut of its faces, so it reads the same with no page around it. Each way below writes the same bytes:

• In this tree. Write <name>.diagram in packages/frontend/assets/diagrams/ and run make diagrams. It writes <name>.svg beside the text, and make verify ARGS=diagrams holds the two together.
• In a project. npx soul-diagram figures/ writes an .svg beside each .diagram under the directory. -o <dir> writes into another directory, and --stdout writes one file to the output. The command stops with an error at the first text that the engine refuses.
• From a script. parse() and diagram() from @typo3/soul-frontend/diagram run in Node and in a browser.
• From Storybook. Each story under Diagrams has a Download SVG press under the drawing. It saves the text in the controls. Change the text there, look at the drawing, then save it.

import { diagram, parse } from '@typo3/soul-frontend/diagram';

const { svg } = diagram(parse(text), { name: 'cache-key' });

flow#

Nodes on a grid, joined by connectors, in boundaries.

.. diagram::

   flow
     columns 1,1,1
   title "A request passes the cache first"
   description "A request reaches the cache. On a miss, the cache asks the store."

   request "Request"
     at 0,0
     person
   cache `cache[]`
     at 1,0
     body "one entry per key"
     new
   store "Store"
     at 2,0
     store

   request -> cache
   cache => store "miss"

• <id> "Title" is a node. at=column,row places it, from 0. body= adds a line under the title, and value= a value at the right. span= gives it more than one column, and rows= more than one row.
• The flags of a node are new, changed, person, store, absent, degraded, emphasis, ink, strong and plain. strong draws the outline in ink, 2 wide: one of several peers. eyebrow= sets a word in mono capitals over the title: the kind of part. tag= sets an identifier in mono before the title. dashed draws a dashed outline, and the text stays in ink. That is a way out of the path, such as an error.
• group "label" draws a boundary around the nodes indented under it. group <id> "label" gives it an id that a connector can use. emphasis under a group draws its outline in the claim colour. A group indented under a group stands inside it, with its own pad: a part of a part.
• A connector takes via=h or via=v and bend= to steer its path.
• row 0 "Label" note="…" names a row at the left. column 0 "Head" sets a head over a column: what the column holds. A head names the column of a flow with no boundary around it. letter=B makes it the title of a part, the letter in the colour of the claim. eyebrow= sets a word in mono capitals over the head, and the head is then a title in bold. emphasis sets the head in the claim colour, the same claim as a boundary with the emphasis.
• plain on a node draws no box: a note beside the boxes, its title at the size of a body. A connector stops short of its text.
• item "text" lines under a node are its list, under its title and its body. A node with items needs no title. body= sets a line under an entry, and the entry is then a name in bold. value= sets a figure at its right. across=2 on the node sets the list in two columns, the first filled first. An entry that opens with a sign hangs its other lines under its words. So a list of checks beside a boundary is one node, and rows= lets it stand beside several rows.
• The first line takes columns=, the relative widths, and gap=, the space across and down. fan on the first line sends the connectors that leave one side of one node out apart. Each leaves at its own height and bends at its own place, so no two share a line. With fan curve, each connector across a gap is a curve from the middle of its source. So the connectors from one source spread as a fan.
• even on the first line makes every row as high as the highest. Peers in a column then have boxes of one height.
• A text with no room does not stop a page drawing at once. That is a word in a box, a label on a connector, or the name of a boundary. The column that is too narrow takes room from the others. Where they have none to give, the flow grows, up to twice its width, and the page shrinks it. On a slide, the room stays the room.
• A name in a box stays whole where the other columns can spare the width, such as page-resolver. A column takes that width from the others before it breaks a name. With no room, a word breaks after a slash first. A part still too wide breaks after a hyphen, a dot or an underscore.

sequence#

Lanes and numbered steps in phases, time down the page.

.. diagram::

   sequence
   title "A link opens a preview once"
   description "Two lanes, the browser and the site, in one phase."

   lane browser "Browser"
     person
   lane site "Site"
   phase "Redeem"
     browser -> site "/news?_preview=token"
     site => browser "page with hidden content"

• lane <id> "Name" takes sub=, person or store.
• host "label" <lane> <lane> draws a boundary over the lanes it names.
• phase "Title" holds its steps indented under it. tone ok colours the phase.
• A step is a connector between lanes. A step from a lane to itself stands beside the lane. note "text" over=a,b adds a note over lanes.

matrix#

Rows against columns, with a sign in each cell.

.. diagram::

   matrix
   title "Where an editor changes a page"
   description "Two products against two editing places."

   column "In the page"
   column "In a panel"
   emphasis column="In the page"

   row "Product A": yes partly
   row "Product B": no unknown

• column "Label" takes group=, sign= and split, which draws a rule before the column. letter=B stands over the label at the size of a node, and sub= under it: an example of the column. weight=3 gives the column three shares of the width.
• row "Label": lists a cell for each column after the colon, or on a cells … line under it. sub= adds a line under the label.
• A cell is a sign (yes, partly, no, unknown), - for none, a text, or dot="8 d". partly^1 adds note 1, and note "…" gives the notes in order.
• path="Click the text › Type › Save" puts a click path in a cell: each step in an outline, joined by ›. A path goes on to the next line where the column ends.
• chip="A1,A2" puts identifiers in a cell. They go on to the next line where the column ends. A text in a cell wraps too, and the row is as high as its fullest cell.
• group "Name" holds the rows indented under it.
• emphasis row= or column= names the emphasis. A second line names a peer of the same claim. Rows or columns side by side share one frame.
• The first line takes row-groups=beside, and figures for cells that hold figures. left sets the heads in capitals. It also sets the texts at the left of their columns: a table that reads as a list. end on a column of such a table sets its head and its texts at the right. ids sets the first word of each row's label in mono, in a column of its own. The name after it is in the regular weight. head="Task" puts a head over the labels of the rows. blocks draws each text cell as a block across its column, as a bar of a plan. A text in parentheses is an outlined block: a smaller piece of work.
• A rule stands under the heads, between two row groups and at the foot. The alignment carries the rows. rules on the first line adds a rule between every two rows.
• A row group says its name in bold capitals. A head over a letter or over blocks names a thing, and takes the ink of a row's label.
• legend yes="good" note="…" adds a sentence after the words of the legend, on its line. notes=outside keeps the number on a cell and leaves the text of each note to the page around the drawing.

bars#

Lengths on one scale, in segments, against a dashed target.

.. diagram::

   bars
     max 10
     unit steps
   title "Integration passes the fewest steps"
   description "One bar per area, in steps that pass and fail, against all steps of the area."

   row "Editing"
     target 8
     segments ok=7 warn=1
   row "Integration"
     target 9
     segments ok=2 error=4
     emphasis

   legend
     ok "passes"
     warn "passes in part"
     error "fails"

• row "Label" takes target=, value= and group=. Its segments are ok=, warn=, error=, or a bare number in ink. absent= is a dashed stretch that the row does not have yet.
• A label in backticks is an identifier, with sub= under it.
• legend takes one line for each tone it names.
• The first line takes max=, unit= and ticks=. For a scale of named steps, it takes bands="a,b,c" and axis=.

units#

Counts as unit squares, a missing part as dashed squares in its place.

.. diagram::

   units
   title "A fallback answers less"
   description "Each square is one entry. The fallback returns the declared entries and none of the dynamic ones."

   row "The booted runtime"
     parts 40
   row "The package files"
     missing "dynamic registrations"
     parts 28 degraded=12

• row "Label" takes sub=, note= and missing=, the name of the part that is not there.
• parts is a count, then absent= or degraded= for the part that is not there.
• The first line takes lines=, head= and key=.

cells#

Things as cells in named groups, each with its sign.

.. diagram::

   cells
   title "Gap map"
   description "The needs in two groups, each a cell with its state."

   group "Edit"
     F1.1 yes
     F1.2 partly
   group "Compose"
     sub "1 of 3 missing"
     F2.1 partly
     F2.2 yes
     F2.3 no

• group "Title" takes sub=, and one cell on each line under it: its id, then its sign. tone=ok, warn or error sets the sub line in that status colour: the verdict of the group.
• legend partly="19 partly met" names a sign with its count.
• boxed on the first line puts each group in a box, in one line. Its cells stand bare in it, each id over its sign. Its sub line stands at its foot: the verdict of the group.

chips#

Identifiers as chips, in rows or in columns.

.. diagram::

   chips
   title "Feature map"
   description "Features in two rows. A filled chip is in the first release, an outlined one is a small first version, a bare one comes later."

   row "Baseline"
     chips A1 A2 (B1) ~B2
   row "Common"
     chips C1 (C2)* ~D1!

   legend
     filled "first release"
     outline "small first version"
     plain "later"
     ring "only with workspaces"

• A1 is a filled chip, (B1) an outlined one, ~B2 a bare identifier. * after a chip adds the ring, and ! makes it the emphasis.
• row "Label" takes sub="a|b" and chips lines under it. All chips of the rows have one width, so they line up as columns. Where the longest row does not fit, the chips and the gaps narrow. A row wraps only where the widest id no longer fits.
• With direction=columns on the first line, column "Head" holds task "…" and chips … under it.

tiles#

Figures side by side, the value largest.

.. diagram::

   tiles
   title "Where the needs come from"
   description "The number of needs from each source."

   tile "27" "Market"
     emphasis
   tile "15" "Field test"
   tile "9" "Core rule"

• tile "value" "Label" takes unit=, body= and sign=.
• The first line takes columns=. aside sets the value at the right of the label, the unit under the label, and a rule under both.

columns#

The parts of a whole, as columns of items.

.. diagram::

   columns
   title "Three parts, one chain"
   description "Three columns, each with the identifiers it holds."

   column "Requirements"
     item "Functional needs" id=F1
     item "Technical needs" id=T1
   column "Target"
     emphasis
     item "Architecture" id=A1
   column "Appendix"
     absent
     item "Descriptions" absent

• column "Title" takes eyebrow=, value=, sub=, id=, place=, body=, note= and foot=. place= draws a screen of the editing interface at the right of the head. Its parts have a quiet fill, and the part of the case is ink. The parts are docheader, nav, bar, page, panel, both and form. any fills no part. value= is a figure at a tile's size. A figure too wide for its column steps down in size. A sub= that wraps beside the screen stands under it, where it then takes fewer lines.
• badge="…" on a column stands white on ink across its top edge, at the right. It names a condition of the whole case.
• item "text" takes id= and sign=. mark=ok sets a status mark before it, marks=ok,warn after it, and boxed gives it a box. An item in backticks is mono.
• strong on a column or an item draws its outline in ink, 2 wide. It marks one of several peers. The emphasis stays the one claim of the drawing.
• line "…" adds a line of a terminal. A column also holds the controls below.
• key "…" chip=, sign=, badge= or pill= adds a line to the legend under the columns. sign=any is a place that each case fills in for itself.
• letter= puts the letter of a part before the title, in the colour of the claim. It spends no emphasis. A column whose head has nothing under it has no rule.
• chain on the first line joins each column to the next with an arrow: the steps of one argument.
• rise on the first line sets the columns as a staircase. Each column starts a step higher than the one before. All end on one line: each level includes the levels before it.
• In a chain or a staircase, a column with the emphasis sets its eyebrow in the claim colour. The eyebrow names the step of the claim.
• In a staircase, the items and the controls of a column stand at its foot. So a picture of each level stands on the line all levels end on.
• bare on the first line draws no card. The items stand as plain text, and an id is a key in the body's size and the muted ink. That is the key under a sketch.
• rows="core,extension" on the first line names the items of every column at the left, in order. Each item then draws only its sign, and the items of all columns line up. The key under the drawing starts at its left edge, under the names.
• centred on the first line sets the title and the body of each column in its middle. No rule stands under them. That is a level, and its signs stand under it.
• A column is as wide as the longest word it sets. It also holds whole each control that cannot wrap, such as tabs or a row of buttons. The columns are peers and keep one width. Where one needs more than its share, the drawing grows, up to twice its width.

sketch#

Screens as nested regions, with numbered places.

.. diagram::

   sketch
     height 240
   title "A panel beside the page"
   description "A screen with a toolbar, the page and a panel on the right."

   screen "Panel on the right"
     column
       region "toolbar"
         size 30
         surface raised
       row
         region "page" lines=6 surface=raised
           emphasis
         region "panel" lines=4 size=90

• screen "Title" takes caption= and holds exactly one region. device draws a phone: an ink outline, a wide edge and a bar at its foot.
• row and column split a region. region "label" takes size=, lines=, surface=, marker=, flow=row and icons=, small squares down a folded column. across=2 sets its controls in a grid of two columns of one width.
• band "Label" under the region of a screen draws a dashed strip under it. The strip holds what the interface keeps out of sight. Its label stands at its left, and its controls share one row after it. across= breaks them into more rows.
• A region holds the controls below. strong draws its outline in ink, absent a dashed one, and hidden hatches it. head sets its label as the region's name, in the body's size, bold and in ink. plain sets the label in the sans face: a name of a part, not an identifier.
• A row whose lines are all controls sets them side by side. A row of regions splits the screen.
• A region narrower than 40 is a rail. It sets its controls closer to its edge, so an icon such as text "{page}" stays whole in it.
• The first line takes height=. heads sets the title of each screen over it, in capitals. The head of a screen whose region is the claim stands in the claim colour.

A page grid is a screen of this kind. The toolbar runs across the top. Under it, the left column, the page and the panel stand side by side. A band holds what lies under the surface, and each place holds its items.

.. diagram::

   sketch
     height 200
   title "Features by place"
   description "The page grid of an editing interface: the toolbar holds C3 viewport switch and D1 save state, the page holds A1 text with a live preview, which is the emphasis, and B4 insert at a position, the panel holds A4 element fields, and the band under the surface holds D3 drafts and E1 permissions."

   screen
     column
       region
         size 44
         surface raised
         across 2
         chip "C3" "Viewport switch"
         chip "D1" "Save state"
       row
         region "PAGE"
           surface sunken
           chip "A1" "Text, live preview" emphasis
           chip "B4" "Insert at a position"
         region "PANEL"
           size 220
           surface raised
           chip "A4" "Element fields"
     band "UNDER THE SURFACE"
       chip "D3" "Drafts"
       chip "E1" "Permissions"

notes and compose#

notes is the numbered list behind the markers of a sketch. compose puts layouts side by side, with one emphasis for all of them.

.. diagram::

   compose
   title "A place and its principle"
   description "A sketch with one numbered place, and the principle it shows."

   part
     weight 1.4
     sketch
       height 220
     screen
       region "PAGE"
         surface raised
         field lines=2 focus cursor marker=1
   part
     notes
     note 1 "Change with one click"
       body "A click on a text starts the change."

• note 1 "Title" body="…" is a note. Its number is the marker it explains.
• part takes weight= and label=. The layout's first line stands on the line under it, then its statements.
• The first line of compose takes direction=column and gap=. chain draws an arrow across each gap to the head of the next part. The arrow is what one part gives to the next.
• Where two parts name the same signs with the same words, the legend stands once, under the last of them.

The controls#

A region of a sketch and a column hold controls. Each takes marker= for a numbered place.

The controls take these flags and options too:

• chip=A1,A2 sets identifiers at the right end of a control. A text, a field, a button, tabs, a hint, a code, a lock and a toolbar take it. A label and a step set it after their text.
• A field with its text in backticks sets it in mono: an address, a path or an identifier.
• field … slim is one line, as high as a button. A line with no room breaks after a · and only there. So a part such as Hero · Summer offers never splits. Every text that wraps breaks after a · where that takes no more lines, and no line opens with one. strong draws the outline of a field, a code or a lock in ink.
• text … small is the size of a label: the caption under a sketch.
• button … small is the size of a label, as the buttons of a bar are. ink fills it.
• tabs … switch divides the whole width into segments, and the active segment has an outline.
• absent on a field or a frame draws a dashed outline with no fill. That is an empty place, a placeholder or a preview of a drop. hidden hatches it: editors see the part, and visitors do not.
• A text, a field and a row of a list mark a run ~~struck~~, __underlined__, **bold** or **__both__**. The engine measures the text without the marks. A line of a code block in **…** is bold.
• image "label" names what the picture stands for, in its middle.
• ring on a field draws a second outline outside the first: the focus of the keyboard. dim makes it a quiet band with no outline: a part that the interface dims. inplace draws no box, but a dashed line around the text: a text that changes in place.
• dot on a field or a frame sets a dot at its top right. On a field with a tag, the dot stands at its foot. The dot marks a change that the core has not saved or a user has not published. On a page, a round mark in its corner is the marker of the element.
• thumb … show=person is a round picture with no frame, its name under it in the middle: a person.
• A text sets a small sign in its line. Write the name of the sign in braces, such as {clock}. The signs for things are {people}, {person}, {lock}, {site}, {page} and {blocked}. The signs for states and actions are {dot}, {ring}, {plus}, {up} and {down}. The signs for types are {text}, {image}, {media} and {list}. The sign takes the room of one letter and the colour of its text. {yes}, {no} and {partly} are the signs of a matrix, in their own colours. sign= on an entry takes the same names. A line never breaks after a sign, so {dot} Saved stays on one line.
• corner puts the marker of a control on its top right corner, not beside it. pointer puts a pointer over the control, near its right end.
• id= names a control or a row of a list. join a b in a column draws a line from the edge of one to the facing edge of the other. Where the two overlap, the line runs straight down the middle of the overlap. Where they stand side by side, the line runs across. dashed makes it a weaker tie, and arrow adds a head at b. right runs it near the right end of both.
• tabs … switch small sets the labels of a switch at the size of a label.

.. diagram::

   columns
   title "A save in two steps"
   description "A bar with the save state and a dialog that asks before a save."

   column "Live page"
     place bar
     row
       button "Live" strong small
       text "Unsaved · 1" strong
       chip "D1,D3" push
     frame "Save to the live page?" close strong
       text "Visitors see this change at once."
       row
         button "Cancel" small push
         button "Save live" ink small
   column "Structure"
     list handle
       row "Teaser cards" selected chip=B1
       row "  Card · Summer"
       row "Holiday notice" muted right="24.12."
     row
       keycap "Ctrl"
       keycap "↑"
       text "one position up"