markdown.gdw raw

; The markdown view's interface, declared for the compiler.
;
; The implementation is `guiduck-markdown`, a crate outside the framework that
; depends on guiduck-core and pulldown-cmark and nothing else guiduck ships.
; That is the point of this file existing: a document view is exactly the kind
; of widget that would have had to be a builtin, and it is not one. Nothing in
; guiduck-core, guiduck-component-core, or either back end knows the word
; "markdown"; it is spelled here, and here only.

(widget markdown
  ; Carried verbatim; the component compiler never resolves it, rustc does.
  (type "::guiduck_markdown::MarkdownView")

  ; The document. A `String` — the whole interface.
  ;
  ; The blocks it parses to never appear in this file and cannot be written from
  ; a `.gdc`, because a document is a widget's business and not a declaration.
  ; The same reason `(text :text "hi")` does not declare glyph runs.
  (prop source String)

  ; A clicked link names its target. What the string means is the
  ; application's: `(markdown :on-link (navigate payload))`.
  (event on-link :payload String)

  ; An image source the widget wants resolved. Unlike an event, the handler
  ; returns a value — the pixels (or "still loading", or "none") — installed as
  ; a resolver: `(markdown :get-image (load payload))`. The app interprets the
  ; URL exactly as it interprets a link target, but with an answer coming back.
  (query get-image :payload String :setter set_image_resolver
         :returns "::guiduck_markdown::ImageResult")

  ; --- Appearance ---------------------------------------------------------
  ;
  ; Every one of these is a convention rather than a law, which is the test for
  ; whether something is a token or code. A document that hardcoded them would
  ; be a document that cannot be themed, and per M17/M23-A that is not a choice
  ; the widget gets to make.

  ; Body prose.
  (token color Brush)
  (token font-size Number)
  (token font-family Str)

  ; What a `[text](target)` looks like. The same two names a `text` reads, for
  ; the same reason and through the same `LinkStyle`: "blue and underlined" is
  ; a convention, and one that should not mean two different things depending
  ; on which widget the prose is in.
  (token link-color Brush)
  (token link-underline-width Number)

  ; The type scale, as a table rather than a ratio: a geometric progression is
  ; one particular scale, and choosing it in code is the thing tokens exist to
  ; prevent.
  (token heading-1-font-size Number)
  (token heading-2-font-size Number)
  (token heading-3-font-size Number)
  (token heading-4-font-size Number)
  (token heading-5-font-size Number)
  (token heading-6-font-size Number)
  (token heading-color Brush)
  ; That a heading is bold at all is a convention. 400 regular, 700 bold.
  (token heading-weight Number)

  ; Code. A block has a background because it is a block; the family is a
  ; token because "monospace" is a preference, not a law.
  (token code-color Brush)
  (token code-background Brush)
  (token code-font-family Str)
  (token code-font-size Number)
  (token code-padding Number)

  ; A block quote: the rule down its left, and how far its content sits in.
  (token quote-color Brush)
  (token quote-width Number)
  (token quote-indent Number)

  ; A thematic break.
  (token rule-color Brush)
  (token rule-width Number)

  ; A table: its grid, the header's shading, the inset inside a cell, and the
  ; narrowest a column is squeezed before its text wraps.
  (token table-border-color Brush)
  (token table-border-width Number)
  (token table-header-background Brush)
  (token table-cell-padding Number)
  (token table-min-column-width Number)

  ; Document metrics.
  (token block-gap Number)
  (token list-indent Number)
  ; The marker of an unordered item. A glyph, so a theme wanting "–" does not
  ; need a rebuild to say so.
  (token bullet Str))