Documentation
¶
Overview ¶
Package reportdesign is the one definition of a report design: the theme document version 2 that sets the look of a person's PDF reports. The server validates a design with it before storing one on the account, the CLI before the runner's template reads one, and the desktop before it saves one; the site's editor reads the same rules through the openapi's ReportDesign schema, which a core test holds to Schema.
A design is data, never markup: colours are #rrggbb, fonts, title blocks, heading treatments, quote styles, paper and page numbers are names from closed lists, and the two free texts (the design's name and the footer line) are one line of plain text that the template sets as content, never evaluates. There is no path, URL or file name in it. A logo, when the person has one, is the pixels themselves (logo.go).
The look stays restrained: one accent and its tint, which Tint derives; body text is near-black whatever the design. Where the accent touches text it must reach 4.5:1 on white, and where it colours only graphics 3:1. Which it is follows from the design, and the runner's template must draw it so (AccentOnText):
- titleBlock "band" sets the title in white on a full-width accent band;
- headings "smallcaps" and "numbered" set level 1 and 2 headings in the accent;
- every other choice colours only rules, bars, tinted cells and callout edges, and keeps text near-black.
Index ¶
- Constants
- Variables
- func BuiltinDocument(id string) ([]byte, bool)
- func BuiltinIDs() []string
- func Contrast(a, b string) (float64, error)
- func FontsFor(role string) []string
- func NearestPassing(colour string, min float64) (string, error)
- func Schema() []byte
- func Tint(accent string) (string, error)
- type Design
- type Family
- type FieldError
- type Fonts
- type Footer
- type Kind
- type Logo
- type Tables
Constants ¶
const ( // TextContrast is the least contrast for an accent that touches text. TextContrast = 4.5 // GraphicsContrast is the least for an accent on graphics only. GraphicsContrast = 3.0 )
The contrast a design's accent must reach on white (WCAG 2.2 1.4.3 and 1.4.11).
const ( // MaxLogoUploadBytes caps an uploaded image before a byte of it is // decoded. MaxLogoUploadBytes = 512 << 10 // MaxLogoBytes caps a design's logo, the PNG itself: a PNG encoder // can write more than the upload was, and a logo too detailed for // this is refused rather than degraded. MaxLogoBytes = 512 << 10 // MaxLogoSide caps a logo's width and height in pixels. A larger upload // is scaled down to fit; a title block draws a logo a few centimetres // wide, and this is past 300 dpi at that size. MaxLogoSide = 1024 // MaxLogoUploadPixels caps what an upload may make the decoder // allocate, as the registry's image proxy does. MaxLogoUploadPixels = 4096 * 4096 )
The logo: a person's own image, drawn only in the title block. It comes from the person, never from the model and never from a URL: a design carries its pixels, as a PNG this package wrote from them.
An upload is a PNG or a JPEG, at most MaxLogoUploadBytes; NormalizeLogo decodes it, scales it down to fit MaxLogoSide and encodes it again as PNG from the decoded pixels, so no chunk, profile or metadata of the upload survives. A design's logo field is held by Validate to a PNG within the same bounds; the server stores only what NormalizeLogo wrote.
const ( // MaxDocumentBytes caps a design document as it is sent, not counting // its logo's field. A canonical design is well under it; the cap // bounds what a client may make the server parse. MaxDocumentBytes = 16 << 10 // MaxNameRunes caps the design's name, a label the person sees. MaxNameRunes = 60 MaxFooterTextRunes = 120 // MaxVersion caps the design's revision number. MaxVersion = 1_000_000 )
Bounds on a design.
const DefaultID = "plain"
DefaultID is the theme a run takes when nothing else chose one.
const DocumentVersion = 2
DocumentVersion is the value of "agentryTheme" this package reads. Version 1 (the earlier theme document) is refused, with no mapping.
const TintMix = 0.12
TintMix is the accent's share of its tint, the rest white (the tint is derived, never stored). The site's editor mixes the same.
const White = "#ffffff"
White is the page.
Variables ¶
var ( // ErrLogoTooLarge is an upload or a logo over a byte or pixel bound. ErrLogoTooLarge = errors.New("logo too large") // ErrLogoFormat is an image that is not a PNG or a JPEG (an upload), // not a PNG (a design's logo), or does not decode. ErrLogoFormat = errors.New("logo not a PNG or JPEG") )
The kinds of a logo's refusal, for errors.Is on a *FieldError: a server answers an upload over a bound differently from one in no format it reads.
var ( Papers = []string{"a4", "letter"} TitleBlocks = []string{"band", "bar", "ruled", "none"} HeadingStyles = []string{"rule", "bar", "smallcaps", "numbered", "plain"} QuoteStyles = []string{"callout", "plain"} PageNumberStyles = []string{"none", "n", "nOfN"} )
The closed lists. Each is the whole set of accepted names, in the order an editor offers them.
Functions ¶
func BuiltinDocument ¶
BuiltinDocument is a built-in theme's embedded document, as shipped.
func BuiltinIDs ¶
func BuiltinIDs() []string
BuiltinIDs is the built-in themes' ids, in the order they are offered.
func NearestPassing ¶
NearestPassing is the shade of a colour that reaches min contrast on white with the least change: the colour itself when it passes, else the lightest darkening of it (the same hue and saturation, a lower lightness) that does. The editor offers it when it refuses an accent.
func Schema ¶
func Schema() []byte
Schema is the theme document's JSON Schema (draft 2020-12), built from the same lists Validate reads, so it cannot drift from them. schema.json beside this file is its committed copy, which a test holds equal; the openapi's ReportDesign schema is held to it by the core's api tests.
The schema says what a document may hold, the families each role takes included. Two rules it cannot say are Validate's alone: the accent's contrast on white (MinContrast), and that a text is one line of plain text (not only spaces, no control, line-break or invisible format characters). Nor can it say what a logo's base64 must hold: a PNG within the pixel bounds.
Types ¶
type Design ¶
type Design struct {
// AgentryTheme is the document version, always DocumentVersion.
AgentryTheme int `json:"agentryTheme"`
// Name is the design's label: a built-in's own name, or the person's.
Name string `json:"name"`
// BasedOn is the id of the built-in theme the design started from.
BasedOn string `json:"basedOn"`
// Version is the design's revision, a positive integer. A built-in
// carries Agentry's revision of it; an edited design keeps the number
// it was loaded with unless its editor says otherwise.
Version int `json:"version"`
// Paper is a Papers value: "a4" or "letter" (US Letter).
Paper string `json:"paper"`
Fonts Fonts `json:"fonts"`
// Accent is the one colour, #rrggbb in lower case. Its tint is
// derived (Tint), never stored.
Accent string `json:"accent"`
// TitleBlock is a TitleBlocks value, the title's treatment on page 1.
TitleBlock string `json:"titleBlock"`
// Headings is a HeadingStyles value, the treatment of level 1 and 2.
Headings string `json:"headings"`
Tables Tables `json:"tables"`
// Quotes is a QuoteStyles value.
Quotes string `json:"quotes"`
// Logo is the person's logo, drawn only in the title block; the zero
// Logo is none, and is not written.
Logo Logo `json:"logo,omitzero"`
}
Design is a report design: the theme document, version 2. Field order is the canonical JSON's key order.
func Builtins ¶
func Builtins() []Design
Builtins is every built-in theme, in the order they are offered.
func Parse ¶
Parse reads a design document and validates it: every field present but the optional logo (a "logo": null is no logo, as if the key were left out), no other key, no second value after it, at most MaxDocumentBytes besides the logo's field, and every rule of Validate. A refusal is a *FieldError.
func (Design) AccentOnText ¶
AccentOnText reports whether the design sets text in its accent or on it: a band title block (the title in white on the accent) or headings set in the accent (smallcaps, numbered). The runner's template draws exactly these with the accent on text; everything else colours only graphics.
func (Design) Canonical ¶
Canonical is the design's canonical document: its JSON in field order, indented by two spaces, with a final newline. A built-in's embedded document is exactly its Canonical, and the receipt hashes it, the logo's bytes included. A design with no logo has no "logo" key. Characters such as "&" and "<" are written as they are, not escaped.
func (Design) MinContrast ¶
MinContrast is the contrast the design's accent must reach on white: 4.5:1 where it touches text, 3:1 where it colours only graphics.
func (Design) SHA256 ¶
SHA256 is the lower-case hex SHA-256 of Canonical, the design's identity in a run's receipt.
type Family ¶
type Family struct {
// Name is the family's name as Typst and the web fonts know it.
Name string
Kind Kind
// HeadingsOnly marks a display face, offered for headings only.
HeadingsOnly bool
}
Family is a font family the Typst image carries. The runner sets it with Noto behind it for the scripts it lacks.
func Families ¶
func Families() []Family
Families is every family a design may name, in the order an editor offers them. The runner image must carry each one.
func FamilyByName ¶
FamilyByName finds a family by its exact name.
type FieldError ¶
FieldError is a design's refusal: the field, as a dotted path into the document ("fonts.body"; "" for the document as a whole), and what is wrong. The message never quotes the value back, beyond a colour.
func (*FieldError) Error ¶
func (e *FieldError) Error() string
func (*FieldError) Unwrap ¶
func (e *FieldError) Unwrap() error
Unwrap is the refusal's kind, where it has one (ErrLogoTooLarge, ErrLogoFormat), for errors.Is.
type Fonts ¶
type Fonts struct {
// Headings is any family.
Headings string `json:"headings"`
// Body is a sans or serif family that is not headings-only.
Body string `json:"body"`
// Code is a mono family.
Code string `json:"code"`
}
Fonts names the three faces, each a family of Families.
type Footer ¶
type Footer struct {
PageNumbers string `json:"pageNumbers"`
// content; "" for none.
Text string `json:"text"`
}
Footer is the page footer.
type Logo ¶
type Logo struct {
// PNG is the image, standard base64 with padding: a PNG of at most
// MaxLogoBytes and at most MaxLogoSide pixels each way.
PNG string `json:"png"`
}
Logo is a design's logo. The zero Logo is none, and a design without one has no "logo" key, so every design saved before logos existed keeps its canonical form and its SHA-256.
func NormalizeLogo ¶
NormalizeLogo turns an uploaded image into a design's logo: a PNG or a JPEG (what the bytes are, not what a file name or a header said), at most MaxLogoUploadBytes and MaxLogoUploadPixels, decoded, scaled down to fit MaxLogoSide by averaging, and encoded again as PNG from the pixels. A refusal is a *FieldError on "logo" whose kind is ErrLogoTooLarge or ErrLogoFormat. A JPEG's orientation tag is not read: its pixels are drawn as they are stored.