IF Commons GitHub

palette

Written to: 1 requirement: 1 proved, 0 partly, 0 failing, 0 with no test recorded. 0001-terminal FR-003

The console's one palette (commons 0006-signals FR-022): the colour roles as a union type, and the marks a person reads at a glance, each with an ASCII fallback for a terminal with no emoji. Whether colour and emoji may be used is the terminal's (commons 0001-system FR-018, runtime/tty.ts's lookOf); this module only obeys it: paint writes SGR sequences only where colour is allowed, and mark an emoji only where emoji are.

Capabilities has the fields of the runtime's Look that output depends on (colour, emoji, columns, the same names), so a Look is a Capabilities as it is.

import { label, mark, paint } from "./palette.ts";
mark("done", { emoji: true }); // "✅"
mark("done", { emoji: false }); // "[ok]"
paint("failure", "3 failed", { colour: true }); // "\u001b[31m3 failed\u001b[0m"
label("warning", "slow", { colour: false, emoji: false }); // "[!] slow"

Source: commons/terminal/src/palette.ts

10 of 22 exports are imported by a test of the run. A test that imports an export may not call it or check what it returns.

palettenamespace
namespace palette
palette.Capabilitiestypeno test imports it
type Capabilities = { readonly colour: boolean; readonly emoji: boolean; readonly columns: number };

What the terminal written to can show: colour, emoji, and its width in columns (the fields of the runtime's Look).

palette.Roletypeno test imports it
type Role = "success" | "failure" | "skipped" | "cancelled" | "hint" | "warning" | "dim" | "accent" | "plain";

What a piece of output means, and so its colour.

palette.ROLESconstno test imports it
const ROLES: readonly Role[]

Every role, in a fixed order.

palette.MarkKindtypeno test imports it
type MarkKind = "done" | "failed" | "skipped" | "cancelled" | "hint" | "warning" | "pending" | "action";

A mark at the start of a line: how something ended, or what a line is.

palette.MARK_KINDSconstno test imports it
const MARK_KINDS: readonly MarkKind[]

Every mark, in a fixed order.

palette.MarkStyletypeno test imports it
type MarkStyle = { readonly emoji: string; readonly ascii: string; readonly role: Role };

A mark as an emoji, its ASCII fallback, and the role it is painted in.

palette.MARKSconstno test imports it
const MARKS: Readonly<Record<MarkKind, MarkStyle>>

The marks: ✅ ❌ ⏭️ ⏹️ 👉 ⚠️ ⏳ ⚡, and [ok] [x] [skip] [stop] -> [!] [todo] [you] where there are no emoji. ❌ and ⚠️ are problems; ⏳ (pending) is something not set up yet, expected until someone does it; ⚡ (action) is a step that is the person's to take (send a change, back up, approve): nothing is wrong, so it is neither a warning nor an error (FR-027).

palette.markfunctionno test imports it
function mark(kind: MarkKind, caps: { readonly emoji: boolean; }): string

A mark: its emoji where the terminal shows emoji, else its ASCII fallback.

palette.sgrOffunctionno test imports it
function sgrOf(role: Role): string

The SGR parameters of a role; empty for plain.

palette.paintfunctionno test imports it
function paint(role: Role, text: string, caps: { readonly colour: boolean; }): string

A text in a role's colour, followed by a reset, where colour is allowed; the text as it is where it is not, for the role plain, and for an empty text. Painted texts are put side by side, not inside one another: the inner reset would end the outer colour.

palette.labelfunctionno test imports it
function label(kind: MarkKind, text: string, caps: { readonly colour: boolean; readonly emoji: boolean; }): string

A line's beginning: the mark painted in its role, a space, and the text.

Capabilitiestype
type Capabilities = { readonly colour: boolean; readonly emoji: boolean; readonly columns: number };

What the terminal written to can show: colour, emoji, and its width in columns (the fields of the runtime's Look).

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Roletype
type Role = "success" | "failure" | "skipped" | "cancelled" | "hint" | "warning" | "dim" | "accent" | "plain";

What a piece of output means, and so its colour.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

ROLESconst
const ROLES: readonly Role[]

Every role, in a fixed order.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

MarkKindtype
type MarkKind = "done" | "failed" | "skipped" | "cancelled" | "hint" | "warning" | "pending" | "action";

A mark at the start of a line: how something ended, or what a line is.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

MARK_KINDSconst
const MARK_KINDS: readonly MarkKind[]

Every mark, in a fixed order.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

MarkStyletypeno test imports it
type MarkStyle = { readonly emoji: string; readonly ascii: string; readonly role: Role };

A mark as an emoji, its ASCII fallback, and the role it is painted in.

MARKSconst
const MARKS: Readonly<Record<MarkKind, MarkStyle>>

The marks: ✅ ❌ ⏭️ ⏹️ 👉 ⚠️ ⏳ ⚡, and [ok] [x] [skip] [stop] -> [!] [todo] [you] where there are no emoji. ❌ and ⚠️ are problems; ⏳ (pending) is something not set up yet, expected until someone does it; ⚡ (action) is a step that is the person's to take (send a change, back up, approve): nothing is wrong, so it is neither a warning nor an error (FR-027).

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

markfunction
function mark(kind: MarkKind, caps: { readonly emoji: boolean; }): string

A mark: its emoji where the terminal shows emoji, else its ASCII fallback.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

sgrOffunction
function sgrOf(role: Role): string

The SGR parameters of a role; empty for plain.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

paintfunction
function paint(role: Role, text: string, caps: { readonly colour: boolean; }): string

A text in a role's colour, followed by a reset, where colour is allowed; the text as it is where it is not, for the role plain, and for an empty text. Painted texts are put side by side, not inside one another: the inner reset would end the outer colour.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

labelfunction
function label(kind: MarkKind, text: string, caps: { readonly colour: boolean; readonly emoji: boolean; }): string

A line's beginning: the mark painted in its role, a space, and the text.

Imported by 4 tests of the run (4 passed, 0 failed): the library's results

Titles, headings, exports, tables, columns and requirements. Esc closes.