Colour
The colour vocabulary an author writes and a surface resolves: hues and their tones, the ramps, the surface paints, and the CSS each becomes.
@internote/canvas-sdk#Functions
blendedColourCss
Converts a colour attribute to CSS, blending from the old colour to the new one while a
!cue.to change is under way.(
resolved: unknown,
transition: TrackTransition | null | undefined,
fallback: string,
): stringblendedToneCss
Returns the CSS for one tone of a surface's hue, blending while a
!cue.to colour change is under way, or an empty string if the colour has no hue.(
resolved: unknown,
transition: TrackTransition | null | undefined,
tone: Tone,
): stringcolourCss
Converts a colour attribute value such as
blue or hex(0064FA) to a CSS colour, or returns fallback if it is not a colour.(value: unknown, fallback?: string): stringcolourToneCss
Converts a colour attribute value to the CSS for its hue at another tone, so
blue at light gives var(--blue-pale).(value: unknown, tone: Tone, fallback?: string): stringcolourTypeWith
Builds the compiler's type declaration for a colour attribute, with options to drop tones, accept a list, or add keywords of your own.
({ extra, tones, list, }?: {
extra?: readonly string[];
tones?: boolean;
list?: boolean;
}): TypeSpecflatOpacity
Returns the opacity for position
t (0 to 1) along a single-colour surface's range: floor at the low end, fully opaque at the high end.(t: number, floor?: number): numberhueHover
Returns step 2 of a colour's hue as CSS, the hover background for a control tinted with
hueTint.(colour: string | undefined, fallback?: string): stringhueOf
Returns the hue of a colour attribute value without its tone, so
dark-blue gives 'blue'.(value: unknown): Hue | nullhueStep
Returns any numbered step (1 to 10) of a colour's hue as CSS.
(colour: string | undefined, step: number, fallback?: string): stringhueStopsOf
Returns the three CSS colours a hue's scale runs through, lightest to darkest, or null if the value is not a hue.
(value: unknown): [string, string, string] | nullhueText
Returns step 10 of a colour's hue as CSS, the text colour for a label on a
hueTint background.(colour: string | undefined, fallback?: string): stringhueTint
Returns the palest step of a colour's hue as CSS (step 1), the background for a chip or row in that colour.
(colour: string | undefined, fallback?: string): stringhueToneVar
Returns the CSS variable for a hue at a tone:
hueToneVar('blue', 'dark') is 'var(--blue-deep)'.(hue: Hue, tone: Tone): stringparseColour
Parses a colour attribute value such as
light-blue or hex(0064FA) into a Colour, or returns null if it is not a colour.(value: unknown, { tones }?: ColourVocabulary): Colour | nullparseSurfacePaint
Parses a
surface-colour value into the colour scale a heatmap or contour draws with, or returns null if it is not a valid colour.(value: unknown): SurfacePaint | nullrampCss
Returns the CSS colour at position
t (0 to 1) along a list of colour stops, blending linearly between neighbours.(stops: readonly string[], t: number): stringrampStopsOf
Returns the hex stops for
multicolour or temperature, or null for any other value; an empty value counts as multicolour.(colour: unknown): string[] | nullresolvedColourCss
(colour: Colour): stringsurfacePaintAt
Returns the
fill and opacity a heatmap or contour draws at position t (0 to 1) of its value range, blending across a !cue.to colour change.(
resolved: unknown,
transition: TrackTransition | null | undefined,
t: number,
fallback: string,
): {
fill: string;
opacity: number;
}surfacePaintOf
Parses a heatmap, contour or choropleth's colour into the scale it draws with, accepting
multicolour and temperature as well as colours.(value: unknown): SurfacePaint | nullwrittenColour
Turns a parsed
Colour back into the text an author would write, the inverse of parseColour.(colour: Colour): string#Constants
COLOUR_NAMES
Every colour name a
colour attribute accepts: each hue in its three tones, then neutral.readonly string[]colourTypeSpec
The compiler's declaration of the language's
colour type: any name in COLOUR_NAMES, or a hex(…) or rgb(…) literal.TypeSpecHEX_PATTERN
A regular expression source matching a hex colour as authors write it:
hex(0064FA) or hex(fff).stringHUES
The nine colour names an author can write, such as
blue or teal, in the order the editor's swatch picker lists them.readonly [
"blue",
"red",
"orange",
"yellow",
"teal",
"green",
"pink",
"purple",
"grey"
]NEUTRAL
The colour name
neutral, which paints a mark in the same colour as body text.stringRAINBOW_STOPS
The hex colours of the
multicolour scale for heatmaps and contours, violet for low values through to red for high.string[]RAMP_NAMES
The two named colour scales
surface-colour accepts on top of ordinary colours.readonly ["multicolour", "temperature"]RGB_PATTERN
A regular expression source matching an RGB colour as authors write it:
rgb(123, 42, 23).stringSURFACE_NAMES
The colour names a heatmap, contour or other value-mapped surface accepts: the nine plain hues, with no tones and no
neutral.readonly string[]TEMPERATURE_STOPS
The hex colours of the
temperature scale for heatmaps and contours: dark blue → light blue → white → light red → dark red.string[]TONE_PREFIXES
The prefixes an author puts before a hue to pick a shade, as in
light-blue and dark-blue.readonly ["light", "dark"]TONES
The three shades a hue comes in:
light, base and dark.readonly ["light", "base", "dark"]#Interfaces
ColourVocabulary
Options for
parseColour: whether to accept every colour name, or only those a value-mapped surface allows.tonesWhether
light-/dark- names and neutral are admitted. False is the surface vocabulary: neutral goes with the tones, naming one token rather than a scale.booleanHueColour
A parsed named colour such as
blue, light-blue or dark-blue.hueThe colour name without its tone prefix:
'blue' for light-blue.blueredorangeyellowtealgreenpinkpurplegreykindAlways
'hue'; tells the three Colour forms apart.'hue'toneThe shade:
'light', 'dark', or 'base' when there was no prefix.lightbasedarkLiteralColour
A parsed
hex(…) or rgb(…) colour, which is drawn exactly as written in both themes.cssThe colour as CSS:
hex(0064FA) becomes '#0064fa', rgb(1,2,3) becomes 'rgb(1, 2, 3)'.stringkindAlways
'literal'; tells the three Colour forms apart.'literal'NeutralColour
The parsed colour
neutral, the body-text colour.kindAlways
'neutral'; tells the three Colour forms apart.'neutral'SurfacePaint
The colour scale a heatmap or contour draws with, as returned by
parseSurfacePaint.flatTrue when there is only one colour and no range to show, as with a
hex(…). The surface then shows value as opacity instead: faint at the low end, solid at the high end.booleanstopsCSS colours from the lowest value to the highest; the surface blends between neighbours.
string[]#Types
Colour
A colour attribute value after parsing: a named hue at a tone,
neutral, or a literal hex or RGB colour.HueColour | NeutralColour | LiteralColour```ts
parseColour('light-blue'); // { kind: 'hue', hue: 'blue', tone: 'light' }
parseColour('neutral'); // { kind: 'neutral' }
parseColour('hex(0064FA)'); // { kind: 'literal', css: '#0064fa' }
```Hue
A colour name from
HUES, such as 'blue'.blueredorangeyellowtealgreenpinkpurplegreyTone
lightbasedark