reportdesign

package
v0.7.36-dev.2 Latest Latest
Warning

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

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

Documentation

Overview

Package reportdesign is the one definition of a report design: the theme document version 3 that sets the look of a person's PDF reports, a whole brand. The server validates a design with it before storing one in the account's library, 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, with one bounded exception. Colours are #rrggbb; fonts, title blocks, heading treatments, heading scales, margins, quote styles, paper, page numbers, header styles, cover styles and cover facts are names from closed lists; every free text (the design's name, the brand block's lines, the header's and the footer's slots) is one line of plain text that the template sets as content, never evaluates. A slot may name a token of a closed set ({title}, {page}, …), which the template substitutes before it sets the text; anything else between braces is literal. There is no path, URL or file name in a design: the brand's website is drawn as text. The one exception is the custom cover's Typst source, which is code: bounded, compiled only under the renderer's confinement with the render root as its whole world, and carried only inside a document this package validated (cover.go).

The images (the logo, the cover image, a custom cover's images and thumbnail) are the person's own pixels, as this package re-encoded them (logo.go, image.go), never a URL. They sit outside the document's byte cap and a server answers them only when asked.

The look stays restrained: an accent and an optional secondary colour, each with a derived tint; body text is near-black whatever the design. Where a colour 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, SecondaryOnText):

  • 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;
  • a cover that is drawn (cover.when is not "never") puts text on or in a colour as its style declares (CoverStyles): "band" and "largeType" the accent, "plate" and "custom" the accent too (each draws as "band" when it cannot be drawn as itself), "split" the secondary, or the accent when the design has none;
  • every other choice colours only rules, bars, shapes, 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 (
	// MaxCoverSourceBytes caps the custom cover's Typst source.
	MaxCoverSourceBytes = 32 << 10
	// MaxCoverImages caps the images a custom cover carries.
	MaxCoverImages = 6
	// MaxCoverImagesBytes caps a custom cover's images in all, as encoded
	// again.
	MaxCoverImagesBytes = 2 << 20
	// MaxThumbnailBytes caps the thumbnail, a PNG of the cover's last
	// render, kept for the editors.
	MaxThumbnailBytes = 300 << 10
)

The custom cover: the one field of a design that is code. Its source is Typst, written by the person or by the Report Designer on their behalf, which the runner's template calls as a function of the facts it has (the title, the author, the date, the brand, the design's colours and faces, the logo's and the images' paths) to draw the cover page when the cover style is "custom". The renderer compiles it only under the confinement every export runs in, with the render root as its whole world: it can read the report, the design, the facts and the images copied there, none of which is secret, and it has no shell, no network, no package imports and no file writes. A custom cover that fails to compile, draws more or fewer than one page, or leaves an image untagged is passed over for the design's built-in cover style, and the export goes on.

This package holds the cover to its bounds and carries it only inside a document it validated; it does not read the code.

View Source
const (
	// MaxCoverImageUploadBytes caps an uploaded image before a byte of it
	// is decoded.
	MaxCoverImageUploadBytes = 2 << 20
	// MaxCoverImageBytes caps a design's cover image as encoded again.
	MaxCoverImageBytes = 2 << 20
	// MaxCoverImageSide caps a cover image's width and height in pixels. A
	// larger upload is scaled down to fit; across a page's width this is
	// past 240 dpi.
	MaxCoverImageSide = 2048
	// MaxCoverImageUploadPixels caps what an upload may make the decoder
	// allocate.
	MaxCoverImageUploadPixels = 4096 * 4096
	// JPEGQuality is the quality a JPEG is encoded again at.
	JPEGQuality = 90
)

The images a design carries beyond its logo: the cover image, a custom cover's images and its thumbnail. Each is the person's own upload, never the model's and never a URL: NormalizeCoverImage decodes it, scales it down to fit MaxCoverImageSide and encodes it again from the pixels, a PNG as PNG and a JPEG as JPEG (a photograph stays a photograph's size), so no chunk, segment, profile or metadata of the upload survives.

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 in the title block, on a cover whose facts include it and in a logoLeft header. 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's canonical document without its
	// images and its custom cover. A canonical design is well under it;
	// the cap bounds what a client may make the server parse and store.
	MaxDocumentBytes = 24 << 10
	// MaxNameRunes caps the design's name and the brand's name, labels the
	// person sees.
	MaxNameRunes = 60
	// MaxLineRunes caps every other line of text: the brand's strapline,
	// contact lines, website and confidentiality line, and each header and
	// footer slot.
	MaxLineRunes = 120
	// MaxContactLines caps the brand block's contact lines.
	MaxContactLines = 4
	// SlotCount is the number of slots in the header and in the footer:
	// left, centre, right.
	SlotCount = 3
	// MaxVersion caps the design's revision number.
	MaxVersion = 1_000_000
	// MaxLibrary caps an account's library: how many designs it keeps.
	MaxLibrary = 10
)

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 = 3

DocumentVersion is the value of "agentryTheme" this package reads. A theme document of version 1 or 2 is refused, with no mapping.

View Source
const MaxFooterTextRunes = MaxLineRunes

MaxFooterTextRunes is the cap on the footer's one line in a version-2 document, which Version2 writes from a slot: one slot's worth.

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 Version2Document = 2

Version2Document is the value of "agentryTheme" in a version-2 document, the projection a renderer that reads only version 2 is handed.

View Source
const White = "#ffffff"

White is the page.

Variables

View Source
var (
	// ErrImageTooLarge is an upload or an image over a byte or pixel bound.
	ErrImageTooLarge = errors.New("image too large")
	// ErrImageFormat is an image that is not a PNG or a JPEG, not the
	// format its place takes, or does not decode.
	ErrImageFormat = errors.New("image not a PNG or JPEG")
)

The kinds of an image'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 (
	ErrLogoTooLarge = ErrImageTooLarge
	ErrLogoFormat   = ErrImageFormat
)

ErrLogoTooLarge and ErrLogoFormat are the logo's names for the same two kinds.

View Source
var (
	Papers           = []string{"a4", "letter"}
	TitleBlocks      = []string{"band", "bar", "ruled", "none"}
	HeadingStyles    = []string{"rule", "bar", "smallcaps", "numbered", "plain"}
	HeadingScales    = []string{"compact", "regular", "generous"}
	MarginPresets    = []string{"narrow", "regular", "wide"}
	QuoteStyles      = []string{"callout", "plain"}
	PageNumberStyles = []string{"none", "n", "nOfN"}
	HeaderStyles     = []string{"none", "rule", "brandLine", "titleAndPage", "logoLeft"}
	CoverFacts       = []string{"title", "subtitle", "author", "date", "brand", "logo", "confidentiality"}
	CoverWhens       = []string{"long", "always", "never"}
)

The closed lists. Each is the whole set of accepted names, in the order an editor offers them.

View Source
var ErrNoColour = errors.New("the logo has no colour to suggest")

ErrNoColour is a logo with nothing to read: every pixel transparent or white.

MaxDocumentWithAssets is the most a document may be as sent with every image at its largest and the custom cover at its bounds: the base64 of each image, the source escaped for JSON (a line break or a quote takes two bytes, a control character six) and a margin for the keys around them, over MaxDocumentBytes for the document itself. A server reads a design's body up to this.

View Source
var Tokens = []string{"title", "author", "date", "page", "pages", "brand", "section", "confidentiality"}

Tokens is the closed set a header or footer slot may name, each written between braces ({title}): the report's title, its author, its date, the page number, the page count, the brand's name, the current level-1 heading, and the brand's confidentiality line. The template substitutes them and sets the result as content, never evaluates it; anything else between braces is literal text.

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 CoverStyleNames added in v0.7.22

func CoverStyleNames() []string

CoverStyleNames is the cover styles' names.

func ExpandSlot added in v0.7.22

func ExpandSlot(slot string, facts map[string]string) string

ExpandSlot substitutes a slot's tokens from facts, keyed by token name without the braces, and leaves everything else as it is, braces around an unknown word included: a token is a name of Tokens between a brace pair with no brace inside it. A token facts does not name expands to nothing.

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. 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. The rules it cannot say are Validate's alone: each colour's contrast on white (MinContrast, MinSecondaryContrast), that a text is one line of plain text (not only spaces, no control, line-break or invisible format characters), the brand website's form, that a cover fact is named once, the custom cover's byte bounds (the schema counts characters) and what an image's base64 must hold: a PNG or a JPEG within its 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.

func TokensIn added in v0.7.22

func TokensIn(slot string) []string

TokensIn lists the tokens a slot names, in order, each once.

Types

type Brand added in v0.7.22

type Brand struct {
	// Name is the brand's name, at most MaxNameRunes; the {brand} token.
	Name string `json:"name"`
	// Strapline is one line under the name, at most MaxLineRunes.
	Strapline string `json:"strapline"`
	// Contact is up to MaxContactLines lines (an address, a telephone, an
	// email), each at most MaxLineRunes and none empty.
	Contact []string `json:"contact"`
	// Website is a host name or an https address, at most MaxLineRunes,
	// drawn as text and never made a link by the template.
	Website string `json:"website"`
	// Confidentiality is a line such as "Confidential", at most
	// MaxLineRunes; the {confidentiality} token.
	Confidentiality string `json:"confidentiality"`
}

Brand is the brand block: who the report is from. Every line is optional ("" or no contact lines for none) and is drawn where a header, a footer or a cover asks for it, as text.

type Cover added in v0.7.22

type Cover struct {
	// Style is a CoverStyles value: a built-in layout, or "custom" for the
	// design's custom cover (which falls back to "band" when it cannot be
	// drawn).
	Style string `json:"style"`
	// Shows are the facts the cover carries, each a CoverFacts value, no
	// value twice, in the order given.
	Shows []string `json:"shows"`
	// When is a CoverWhens value: "long" draws the cover for a titled
	// report past the template's length threshold, "always" for every
	// titled report, "never" for none.
	When string `json:"when"`
}

Cover is the cover page.

type CoverStyle added in v0.7.22

type CoverStyle struct {
	// Name is the style's name, a Cover.Style value.
	Name string
	// AccentOnText says the accent carries text: white text on an accent
	// panel, or the title set in the accent.
	AccentOnText bool
	// SecondaryOnText says the secondary carries text, or the accent does
	// when the design has no secondary.
	SecondaryOnText bool
}

CoverStyle is a cover layout and its declaration of which of the design's colours carry text on it, which the contrast rule reads.

func CoverStyleByName added in v0.7.22

func CoverStyleByName(name string) (CoverStyle, bool)

CoverStyleByName finds a cover style by its name.

func CoverStyles added in v0.7.22

func CoverStyles() []CoverStyle

CoverStyles is every cover style with its declaration, in the order an editor offers them.

type CustomCover added in v0.7.22

type CustomCover struct {
	// Source is the Typst source, at most MaxCoverSourceBytes.
	Source string `json:"source"`
	// Images are the images the source may draw, each a PNG or a JPEG the
	// core encoded again, in the order the renderer names them; at most
	// MaxCoverImages, and MaxCoverImagesBytes in all.
	Images []Image `json:"images"`
	// Thumbnail is a PNG of the cover's last render, at most
	// MaxThumbnailBytes; the zero Image is none, and is not written.
	Thumbnail Image `json:"thumbnail,omitzero"`
}

CustomCover is a design's custom cover. The zero CustomCover is none, and a design without one has no "customCover" key.

func (CustomCover) IsZero added in v0.7.22

func (c CustomCover) IsZero() bool

IsZero reports whether the custom cover is none, which the canonical document leaves out.

func (CustomCover) Validate added in v0.7.22

func (c CustomCover) Validate() error

Validate holds the custom cover to its bounds: a source that is not empty, UTF-8 text with no control character but a tab, a line feed or a carriage return, at most MaxCoverSourceBytes; at most MaxCoverImages images, each a PNG or a JPEG within the cover image's pixel bound, and MaxCoverImagesBytes in all; a thumbnail that is a PNG of at most MaxThumbnailBytes.

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 first colour, #rrggbb in lower case. Its tint is
	// derived (Tint), never stored.
	Accent string `json:"accent"`
	// Secondary is the second colour, #rrggbb in lower case, or "" for
	// none. Its tint is derived as the accent's is.
	Secondary string `json:"secondary"`
	// 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"`
	// HeadingScale is a HeadingScales value, how much larger than the
	// body each heading level is set.
	HeadingScale string `json:"headingScale"`
	// Margins is a MarginPresets value, the page's margins.
	Margins string `json:"margins"`
	Tables  Tables `json:"tables"`
	// Quotes is a QuoteStyles value.
	Quotes string `json:"quotes"`
	Brand  Brand  `json:"brand"`
	Header Header `json:"header"`
	Footer Footer `json:"footer"`
	Cover  Cover  `json:"cover"`
	// where its facts include it and in a logoLeft header; the zero Logo
	// is none, and is not written.
	Logo Logo `json:"logo,omitzero"`
	// CoverImage is the design's cover image, drawn by the plate cover
	// style and offered to a custom cover; the zero Image is none, and is
	// not written.
	CoverImage Image `json:"coverImage,omitzero"`
	// CustomCover is the design's custom cover, drawn when the cover style
	// is "custom"; the zero CustomCover is none, and is not written.
	CustomCover CustomCover `json:"customCover,omitzero"`
}

Design is a report design: the theme document, version 3. 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 images and custom cover (a "logo": null is no logo, as if the key were left out, and so for "coverImage" and "customCover"), no other key, no second value after it, at most MaxDocumentBytes in its canonical form besides the images and the custom cover, 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), headings set in the accent (smallcaps, numbered), or a cover that is drawn in a style that declares the accent (band, largeType, plate, custom; split without a secondary). 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 images and the custom cover included. A design without a logo, a cover image or a custom cover has no key for it. 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) MinSecondaryContrast added in v0.7.22

func (d Design) MinSecondaryContrast() float64

MinSecondaryContrast is the contrast the design's secondary must reach on white, by the same rule.

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) SecondaryOnText added in v0.7.22

func (d Design) SecondaryOnText() bool

SecondaryOnText reports whether the design sets text on its secondary: a cover that is drawn in a style that declares it (split), when the design has a secondary.

func (Design) Validate

func (d Design) Validate() error

Validate holds a design to every rule: the version, the closed lists, the fonts' roles, the colours' form and contrast, every line of text, the slots, the cover's facts, and the images and the custom cover when it has them. A refusal is a *FieldError naming the first field found wrong, in document order, the contrast rule last among the document's own fields because the styles that decide it come after the colours.

func (Design) Version2 added in v0.7.22

func (d Design) Version2() []byte

Version2 is the design's version-2 projection, as a canonical version-2 document: what a renderer that reads only version 2 draws in its place. The accent, the faces, the title block, the headings, the tables, the quotes and the page numbers carry over; a family version 2 did not have becomes the nearest of its first fourteen (Family.Version2); a built-in version 2 did not have becomes the nearest of its five; the footer's line is the first slot that has text, its {brand} and {confidentiality} tokens filled from the brand block and its other tokens dropped, cut to MaxFooterTextRunes; the secondary, the brand block, the header, the cover, the heading scale, the margins, the cover image and the custom cover are left out, since version 2 has no place for them. The logo carries over. Version 2's rule on the accent (4.5:1 on white under a band title or smallcaps or numbered headings, 3:1 otherwise) asks no more of it than this version's, so a design that validates projects to one that does.

func (Design) WithoutAssets added in v0.7.22

func (d Design) WithoutAssets() Design

WithoutAssets is the design with no logo, cover image or custom cover: the document a server stores and answers unless asked for its assets.

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
	// Version2 is the family a version-2 projection of a design names in
	// its place: the family itself where version 2 knew it, else the
	// nearest of the first fourteen in the same role.
	Version2 string
}

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", "brand.contact.2", "customCover.images.0"; "" 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 (ErrImageTooLarge, ErrImageFormat), 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"`
	// Slots are the left, centre and right texts, as the header's.
	Slots [SlotCount]string `json:"slots"`
}

Footer is the page footer.

type Header struct {
	// Style is a HeaderStyles value.
	Style string `json:"style"`
	// Slots are the left, centre and right texts, each a template of
	// literal text and tokens (Tokens) of at most MaxLineRunes; "" for an
	// empty slot.
	Slots [SlotCount]string `json:"slots"`
}

Header is the running header, drawn from page 2 on a report, on every page of a memo and never on a letter.

type Image added in v0.7.22

type Image struct {
	// PNG is the image as a PNG.
	PNG string `json:"png,omitempty"`
	// JPEG is the image as a JPEG.
	JPEG string `json:"jpeg,omitempty"`
}

Image is a design's image in one of the two formats, standard base64 with padding, exactly one of the two set. The zero Image is none.

func ImageOf added in v0.7.22

func ImageOf(data []byte, format string) Image

ImageOf is an image from its bytes and format ("png" or "jpeg").

func NormalizeCoverImage added in v0.7.22

func NormalizeCoverImage(upload []byte) (Image, error)

NormalizeCoverImage turns an uploaded image into a design's cover image, or one of a custom cover's: a PNG or a JPEG (what the bytes are, not what a file name or a header said), at most MaxCoverImageUploadBytes and MaxCoverImageUploadPixels, decoded, scaled down to fit MaxCoverImageSide by averaging, and encoded again from the pixels in the format it came in. A refusal is a *FieldError on field whose kind is ErrImageTooLarge or ErrImageFormat. A JPEG's orientation tag is not read: its pixels are drawn as they are stored.

func NormalizeCustomCoverImage added in v0.7.22

func NormalizeCustomCoverImage(upload []byte) (Image, error)

NormalizeCustomCoverImage turns an uploaded image into one of a custom cover's images, by the cover image's rules (NormalizeCoverImage), named for its place in the list.

func NormalizeThumbnail added in v0.7.22

func NormalizeThumbnail(upload []byte) (Image, error)

NormalizeThumbnail turns an uploaded image into a custom cover's thumbnail: a PNG of at most MaxThumbnailBytes, scaled to fit MaxCoverImageSide, encoded again from its pixels.

func (Image) Decode added in v0.7.22

func (i Image) Decode() ([]byte, string, error)

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

func (Image) Format added in v0.7.22

func (i Image) Format() string

Format is "png" or "jpeg", or "" for no image.

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.

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 Suggestion added in v0.7.22

type Suggestion struct {
	// Accent and Secondary pass TextContrast on white.
	Accent, Secondary string
	// FromAccent and FromSecondary are the colours as read, before any
	// darkening.
	FromAccent, FromSecondary string
}

Suggestion is what SuggestColours reads from a logo: its two dominant colours as they are, and the nearest shade of each that passes the contrast rule for text, which passes it for graphics too. Secondary is "" when the logo has one colour.

func SuggestColours added in v0.7.22

func SuggestColours(logo []byte) (Suggestion, error)

SuggestColours reads the two dominant colours of a logo (its PNG or JPEG bytes, as a design carries them) and offers each as a shade that passes the contrast rule for text: the editors show them for the person to take as the accent and the secondary, never apply them unasked. The logo is held to the logo's upload bounds before a pixel is decoded. Transparent and near-white pixels are the background and are not read; the colour read most is the accent, and the next most that is far enough from it, and at least a twentieth as common, is the secondary.

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