reportdesign

package
v0.7.8-dev.1 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 2, 2026 License: MIT Imports: 20 Imported by: 0

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

View Source
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).

View Source
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.

View Source
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 caps the footer's one line of text.
	MaxFooterTextRunes = 120
	// MaxVersion caps the design's revision number.
	MaxVersion = 1_000_000
)

Bounds on a design.

View Source
const DefaultID = "plain"

DefaultID is the theme a run takes when nothing else chose one.

View Source
const DocumentVersion = 2

DocumentVersion is the value of "agentryTheme" this package reads. Version 1 (the earlier theme document) is refused, with no mapping.

View Source
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.

View Source
const White = "#ffffff"

White is the page.

Variables

View Source
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.

View Source
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

func BuiltinDocument(id string) ([]byte, bool)

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 Contrast

func Contrast(a, b string) (float64, error)

Contrast is the WCAG contrast ratio of two #rrggbb colours, from 1 to 21.

func FontsFor

func FontsFor(role string) []string

FontsFor lists the family names a role accepts: "headings", "body" or "code".

func NearestPassing

func NearestPassing(colour string, min float64) (string, error)

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.

func Tint

func Tint(accent string) (string, error)

Tint is the accent's tint: TintMix of the accent over white, for tinted table headers, banded rows and callouts.

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"`
	Footer Footer `json:"footer"`
	// 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 Builtin

func Builtin(id string) (Design, bool)

Builtin is the built-in theme with that id.

func Builtins

func Builtins() []Design

Builtins is every built-in theme, in the order they are offered.

func Default

func Default() Design

Default is the Plain theme.

func Parse

func Parse(data []byte) (Design, error)

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

func (d Design) AccentOnText() bool

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

func (d Design) Canonical() []byte

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

func (d Design) MinContrast() float64

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

func (d Design) SHA256() string

SHA256 is the lower-case hex SHA-256 of Canonical, the design's identity in a run's receipt.

func (Design) Validate

func (d Design) Validate() error

Validate holds a design to every rule: the version, the closed lists, the fonts' roles, the colour's form and contrast, the two texts, and the logo when it has one. A refusal is a *FieldError naming the first field found wrong, in document order.

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

func FamilyByName(name string) (Family, bool)

FamilyByName finds a family by its exact name.

type FieldError

type FieldError struct {
	Field   string
	Message string
	// contains filtered or unexported fields
}

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 struct {
	// PageNumbers is a PageNumberStyles value.
	PageNumbers string `json:"pageNumbers"`
	// Text is one line of plain text, at most MaxFooterTextRunes, set as
	// content; "" for none.
	Text string `json:"text"`
}

Footer is the page footer.

type Kind

type Kind string

Kind is a family's kind.

const (
	Sans  Kind = "sans"
	Serif Kind = "serif"
	Mono  Kind = "mono"
)

The kinds of family.

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(upload []byte) (Logo, error)

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.

func (Logo) Decode

func (l Logo) Decode() ([]byte, error)

Decode is the logo's PNG bytes. The base64 must be one unbroken line: the decoder would skip a CR or LF, and the same logo would then have more than one canonical form, and hash.

type Tables

type Tables struct {
	Tinted bool `json:"tinted"`
	Banded bool `json:"banded"`
}

Tables are the table styles: a tinted header row, and alternate rows tinted.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL