Soup of the day
\n" assert post_body( "[menu](https://example.com/menu) or [prize](javascript:steal())" ) == "\n" } test "pasted HTML keeps only what is safe" { assert about_section("Chef
") == "Chef
" assert preview( about_section("` it keeps the lines as written, less blank ones at either end. A
list item gets no bullet or number.
`text.format` shows the text people read: an `Html` value's
`markup.to_plain_text`, and a `Markdown` text's once rendered. An `Html`
value's `text.from` is the HTML itself.
## `RichText`
A `RichText` is a document as a rich text editor holds one, in Portable
Text's flat shape with its default schema. It is a list of blocks, each
holding spans of text. A block is a paragraph, a heading of level 1 to 6,
a quote, or a bulleted or numbered list item with its level, 1 to 9.
There is no code block, rule, image or table.
A span has its marks and at most one link. The marks are `strong`,
`emphasis`, `code`, `underline` and `strike_through`: Portable Text's
default decorators, with its `em` and `strike-through` renamed. An HTML
link can't hold another, so the link is a part of the span, not a mark.
Nothing nests, so no type refers to itself. A list item's level says how
deep it sits, as Portable Text's `level` does and as Word and Google Docs
nest lists.
Its parts are three standard types, since a part must be a standard type
to be read, sent and stored: `RichTextBlock`, a choice; `RichTextSpan`,
an object sent as its members; and `RichTextMark`, an enum.
It is sent in Jadpo's own form, not with Portable Text's `_type`, `_key`,
`children` and `markDefs`. The form is an array of its blocks, each in
the tagged form an enum variant with fields takes in JSON
([Enums](enums.md)). Each span is an object of
`text`, `marks` and `link`, leaving out the link when it has none:
```json
[
{"tag": "heading", "level": 2, "spans": [{"text": "Method", "marks": []}]},
{"tag": "paragraph", "spans": [{"text": "our mill", "marks": ["emphasis"], "link": "https://example.com/mill"}]}
]
```
Every block and mark is an element the sanitiser keeps. A link must be
one the sanitiser keeps as it is, which is either:
- an `https:` URL whose host is ASCII labels of letters, digits and
single hyphens, the last beginning with a letter (never an IP address
or punycode), with a port up to 65535; or
- a `mailto:` address,
each in the characters a URL writes unescaped. That refuses some links
the sanitiser would keep, such as a host written in Unicode, and none it
would drop; a test of random links holds the two together.
A link that isn't one of these is refused where the document is built or
read, breaking `pattern`, rather than dropped. A literal that breaks it
is `type.invalid_literal`, which says the rule in words rather than as
its pattern. A span's text is never empty, and has no control character
but a tab or a line feed.
`markup.rich_to_html` writes ``, `
` to ``, ``,
list items in `` or `` (a deeper item in a list inside the item
before it), ``, ``, ``, `` and ``, links with
`rel="noopener noreferrer nofollow"`, a line feed as `
`, and text
escaped as the sanitiser's serialiser escapes it. It writes no white
space between elements. A span's marks are written once each, in one
nesting order, `strong` outermost and `strike_through` innermost, inside
the link, whatever order the span lists them in. So it writes nothing the
sanitiser would change, which tests hold it to, and it sanitises the
result all the same: an `Html` is only ever what the sanitiser keeps.
A recipe site keeps each method as its editor sends it:
```jadpo
type EditorJson = Text {}
type MethodUnreadable = Failure {
kind: FailureKind.invalid_value
}
/// A recipe's method as the editor sent it: its blocks and marks, with
/// links only to `https:` and `mailto:` addresses.
function method_from(sent: EditorJson) fails MethodUnreadable -> RichText {
return attempt json.read(sent, as: RichText) {
malformed: MethodUnreadable
mismatch: MethodUnreadable
}
}
/// The method on the recipe's page.
function method_page(recipe_method: RichText) -> Html {
return markup.rich_to_html(recipe_method)
}
```
```jadpo
test "a recipe's method becomes safe HTML" {
var oat_method: RichText = attempt method_from(
"[{\"tag\":\"heading\",\"level\":2,\"spans\":[{\"text\":\"Method\",\"marks\":[]}]},{\"tag\":\"numbered_item\",\"level\":1,\"spans\":[{\"text\":\"Soak the oats\",\"marks\":[]}]},{\"tag\":\"numbered_item\",\"level\":1,\"spans\":[{\"text\":\"Bake for \",\"marks\":[]},{\"text\":\"40 minutes\",\"marks\":[\"strong\"]}]},{\"tag\":\"paragraph\",\"spans\":[{\"text\":\"Flour from \",\"marks\":[]},{\"text\":\"our mill\",\"marks\":[\"emphasis\"],\"link\":\"https://example.com/mill\"}]}]"
)
assert method_page(
oat_method
) == "Method
- Soak the oats
- Bake for 40 minutes
Flour from our mill
"
assert text.format(
oat_method,
locale: Locale.en_gb
) == "Method\nSoak the oats\nBake for 40 minutes\nFlour from our mill"
}
test "a link goes only to https: and mailto:" {
assert method_from(
"[{\"tag\":\"paragraph\",\"spans\":[{\"text\":\"prize\",\"marks\":[],\"link\":\"javascript:steal()\"}]}]"
) fails MethodUnreadable
var note: RichText = RichText(
[
RichTextBlock.paragraph {
spans: [
RichTextSpan {
text: "Write to us"
marks: []
link: "mailto:hello@example.com"
}
]
}
]
)
assert method_page(
note
) == ""
}
```
## `LocalisedText`
A `LocalisedText` maps locales to text, such as a product's name in each
language a shop sells in. It is a named map, `Map`, and may
be empty. It is sent as JSON-LD sends a language map: an object keyed by
each locale's tag, `{"en-GB": "Rye loaf", "fr-FR": "Pain
de seigle"}`, rather than a list of entries, so each locale has one entry
by construction.
Code builds one from a map, `LocalisedText(map.with(...))`, as it builds
any named map of your application's, since there is no map literal with
entries ([Named collection construction](collections.md#named-collection-construction)).
Its keys are `Locale`s like any other. One read from a request or from
JSON is a locale your application supports: an unsupported tag breaks
`variant`, and OpenAPI lists only the supported tags as its keys. One
written in code may be any locale.
`text.pick` chooses an entry by the fallback chain
[Locales](locales.md) describes: the locale's
own entry, else one in its language (the locale CLDR's likely subtags
give for the language first, then in the canonical order), else the
entry of the application's default locale. Text with none of those gives
its first entry in the canonical order, so text that has any entry always
shows one. An empty one gives `""`.
`text.pick`'s `locale:` is checked as `text.format`'s is, since it
chooses text for a person. One written out must be a locale the
application supports (`type.locale_unsupported`), and an application with
no `locales { }` is `type.temporal_locales_required`:
```jadpo
application {}
locales {
default: Locale.en_gb
supported: [Locale.en_gb, Locale.en_us, Locale.fr_fr, Locale.fr_ca, Locale.de_de]
}
```
```jadpo
type ShelfName = Text {}
/// A loaf's name in the shopper's language: their locale's entry, else
/// one in their language, else the shop's default locale's.
action shelf_name(name: LocalisedText, shopper: Locale) -> ShelfName {
return ShelfName(text.pick(name, locale: shopper))
}
```
```jadpo
test "a loaf's name in the shopper's language" {
var rye: LocalisedText = LocalisedText(
map.with(map.with([], Locale.fr_fr, "Pain de seigle"), Locale.en_gb, "Rye loaf")
)
assert shelf_name(rye, Locale.fr_fr) == "Pain de seigle" // its own entry
assert shelf_name(rye, Locale.fr_ca) == "Pain de seigle" // its language's
assert shelf_name(rye, Locale.de_de) == "Rye loaf" // the default locale's
var roggen: LocalisedText = LocalisedText(map.with([], Locale.de_de, "Roggenbrot"))
assert shelf_name(roggen, Locale.fr_fr) == "Roggenbrot" // the only one it has
}
```
## Showing, sending and storing rich and localised text
`text.format` shows a `RichText`, a block or a span as the text people
read in it (its HTML's `markup.to_plain_text`), each block on its own
line. It shows a `LocalisedText` as `text.pick` gives it in that locale.
Neither type has a single text form, so `text.from` and `text.parse`
refuse them, and neither is ordered.
Each is a named collection the standard library declares, as a standard
type may be a list or a map of parts. It is sent as JSON's own
collection, and a `RichText`, a `RichTextBlock` and a `LocalisedText` are
each stored as that JSON in one `jsonb` column.