Documentation
¶
Overview ¶
Package theme is the theme layer of bide's visual pages: a theme is a small JSON file of typed values (colours, enums, numbers in ranges), never CSS. Parse reads and checks one, Check measures it against the contrast and distinctness rules, and Load does the same for a file. A Go program that serves bide's pages passes the checked themes to planview.WithThemes or flowedit.WithThemes (and to the matching WithDefaultTheme and WithThemeLock); the handler turns them into the one generated stylesheet of custom properties its pages load. The package exports no way to get that stylesheet, to build a Theme from fields, or to pass CSS: a *Theme exists only if it passed the checks. See docs/design/themes.md and docs/guides/themes.md.
A theme holds two layers of tokens. The semantic tokens (ok, info, warning, alert, gated, effect, idem, idle, on) have a meaning bide fixes; a theme supplies their values and is refused if the values fail the checks. The surface tokens (backgrounds, text, borders, accent, syntax colours, fonts, density, radius) a theme sets freely inside ranges.
Index ¶
Examples ¶
Constants ¶
const MaxSize = 16 << 10
MaxSize is the largest theme file Parse reads.
const Version = 1
Version is the only value of the bide_theme key.
Variables ¶
This section is empty.
Functions ¶
func Load ¶
Load reads and checks a custom theme file: Parse on the file's bytes. The path must name a regular file of at most MaxSize bytes; a named pipe or a device is refused, not waited on. The report is returned with an error from a failed check as well as with success.
func Parse ¶
Parse reads a custom theme: strict JSON of at most MaxSize bytes that names a shipped base and overrides some of its values. Whatever is left out comes from the base, and the checks run on the resolved theme, so inheriting cannot dodge them. It returns the checked theme and its report (which carries the advisory warnings), or an error naming every problem: a format error, or the failed checks, each key and value quoted.
Example ¶
A theme names a shipped base and overrides some of its values. Parse checks the result against the contrast and distinctness rules; a theme that fails a check is refused, with each failure.
package main
import (
"fmt"
"github.com/bide-ai/bide/theme"
)
func main() {
th, report, err := theme.Parse([]byte(`{"bide_theme": 1, "name": "acme-night", "base": "dark",
"surface": {"bg": "#0e1116", "accent": "#79b8ff"}}`))
fmt.Println(th.Name(), th.Dark(), th.Shipped(), err, len(report.Failures(theme.Error)))
_, _, err = theme.Parse([]byte(`{"bide_theme": 1, "name": "acme-faint", "base": "light",
"surface": {"text": "#f6f6f2"}}`))
fmt.Println(err != nil)
}
Output: acme-night true false <nil> 0 true
Types ¶
type CheckError ¶
type CheckError struct{ Report Report }
CheckError is the error of a theme that failed its checks; Report holds every measure.
func (*CheckError) Error ¶
func (e *CheckError) Error() string
Error lists every failed measure, one to a line.
type Measure ¶
type Measure struct {
Check string // C1 ... C8, see docs/design/themes.md
Subject string // the pair, for example "text on bg"
Value float64
Threshold float64
Pass bool
Severity Severity // what a failure counts as; meaningful when !Pass
}
Measure is one pair a check looked at: what was measured, the threshold, and whether it holds.
type Report ¶
Report holds every measure of a theme.
func Check ¶
Check measures a resolved theme against every check (C1 to C6 and C8; C7, the ranges, is enforced while parsing) and returns all measures, passing and failing. The colour-blindness check C6 fails as an error for a shipped theme and as a warning for a custom one.
type Severity ¶
type Severity int
Severity is how a failed measure counts: an Error refuses the theme, a Warning is reported.
type Theme ¶
type Theme struct {
// contains filtered or unexported fields
}
Theme is a parsed, resolved and checked theme: every token has a value. The zero value is not a theme; get one from Parse or Shipped.
func Lookup ¶
Lookup returns the shipped theme called name.
Example ¶
The shipped themes are always available by name.
package main
import (
"fmt"
"github.com/bide-ai/bide/theme"
)
func main() {
th, ok := theme.Lookup("high-contrast")
fmt.Println(th.Name(), ok, th.Shipped())
_, ok = theme.Lookup("nope")
fmt.Println(ok)
}
Output: high-contrast true true false
func Shipped ¶
func Shipped() []*Theme
Shipped returns the shipped themes (light, dark, high-contrast), in that order. A shipped theme is checked by the same rules as a custom one, and its colour-blindness result is an error rather than a warning. It panics if the embedded data does not parse, which a test rules out.
func (*Theme) Dark ¶
Dark reports whether the theme's ground is dark: the relative luminance of its background is below 0.18. It sets color-scheme, so the browser's own controls agree with the colours.
Source Files