@textui/widgets 0.7.0 → 0.9.0

package/dist/display/fonts.js

@@ -0,0 +1,893 @@
+/**
+ * Block fonts, and the engine that draws text in them.
+ *
+ * A font is data: a table of glyphs, a tracking and a space width. `banner()`
+ * lays a string out in one and answers with plain text, which is the shape
+ * half only - `ColorText` colours it cell by cell, and the two are deliberately
+ * separate, because a banner wants a ramp across it and prose does not.
+ * [`FontText`](font-text.tsx) is the one-liner over this: text and a font in,
+ * letters out.
+ *
+ * These ship so that component has something to draw with; the tables are data
+ * an application can replace, and `Font` is the whole contract.
+ *
+ * There is one hand-drawn table and three transforms of it, which is the other
+ * thing worth showing: a bitmap font is a grid of characters, and a grid of
+ * characters can be sheared, doubled or duplicated by ten lines of code. Every
+ * font below has both cases, because the table does.
+ *
+ * A glyph is a grid of characters. Four of them are placeholders the renderer
+ * fills in from the theme - `#` a full cell, `%` a lighter one, `^` the top
+ * half of a cell and `v` the bottom half - and every other character is drawn
+ * as itself, which is what lets `dots`, `stars` and `mini` be made of dots,
+ * stars and pipes rather than of blocks. A space is nothing. Blank columns at
+ * either edge are trimmed when a glyph is used, so the letters are
+ * proportional rather than a fixed pitch.
+ */
+import { graphemeWidth, stringWidth } from '@textui/core';
+import { GARD } from './gard.js';
+import { PAGGA } from './pagga.js';
+/**
+ * Capitals, five rows on a five-column body.
+ *
+ * Every stroke is one cell thick, which is what makes these legible at this
+ * size and what makes the `shadow` transform read as a shadow rather than as
+ * a thicker letter.
+ */
+const CAPS = {
+    A: ' ### |#   #|#####|#   #|#   #',
+    B: '#### |#   #|#### |#   #|#### ',
+    C: ' ####|#    |#    |#    | ####',
+    D: '#### |#   #|#   #|#   #|#### ',
+    E: '#####|#    |#### |#    |#####',
+    F: '#####|#    |#### |#    |#    ',
+    G: ' ####|#    |#  ##|#   #| ####',
+    H: '#   #|#   #|#####|#   #|#   #',
+    I: '#####|  #  |  #  |  #  |#####',
+    J: '#####|   # |   # |#  # | ##  ',
+    K: '#   #|#  # |###  |#  # |#   #',
+    L: '#    |#    |#    |#    |#####',
+    M: '#   #|## ##|# # #|#   #|#   #',
+    N: '#   #|##  #|# # #|#  ##|#   #',
+    O: ' ### |#   #|#   #|#   #| ### ',
+    P: '#### |#   #|#### |#    |#    ',
+    Q: ' ### |#   #|#   #|#  # | ## #',
+    R: '#### |#   #|#### |#  # |#   #',
+    S: ' ####|#    | ### |    #|#### ',
+    T: '#####|  #  |  #  |  #  |  #  ',
+    U: '#   #|#   #|#   #|#   #| ### ',
+    V: '#   #|#   #|#   #| # # |  #  ',
+    W: '#   #|#   #|# # #|## ##|#   #',
+    X: '#   #| # # |  #  | # # |#   #',
+    Y: '#   #| # # |  #  |  #  |  #  ',
+    Z: '#####|   # |  #  | #   |#####',
+};
+/**
+ * Lowercase, on the same five rows.
+ *
+ * **One x-height, for all of them.** The body of every lowercase letter sits
+ * on rows two to five and the ascenders reach up into row one, so the two
+ * cases share a baseline and a cap is visibly taller than an x - which is the
+ * whole reason for a second set rather than folding the case away. Letting an
+ * `e` be four rows while the `o` beside it was three is what made `Hello` read
+ * as a ransom note, and it is the kind of thing only a rendered alphabet shows.
+ *
+ * Nothing descends below the baseline: five rows is not enough to put a tail
+ * under a `g` and keep the line spacing honest, so `g` and `y` hook left
+ * instead - which is also what keeps `g` from being a `q`.
+ */
+const LOWER = {
+    a: '    | ###|#  #|#  #| ###',
+    b: '#   |### |#  #|#  #|### ',
+    c: '    | ###|#   |#   | ###',
+    d: '   #| ###|#  #|#  #| ###',
+    e: '    | ## |#  #|### | ###',
+    f: '  ##| #  |### | #  | #  ',
+    g: '    | ###|#  #| ###|##  ',
+    h: '#   |### |#  #|#  #|#  #',
+    i: ' # |   | # | # | # ',
+    j: '  # |    |  # |  # |##  ',
+    k: '#   |#  #|##  |# # |#  #',
+    l: '##  | #  | #  | #  |### ',
+    m: '     |#####|# # #|# # #|# # #',
+    n: '    |### |#  #|#  #|#  #',
+    o: '    | ## |#  #|#  #| ## ',
+    p: '    |### |#  #|### |#   ',
+    q: '    | ###|#  #| ###|   #',
+    r: '    |# ##|##  |#   |#   ',
+    s: '    | ###|##  |  ##|### ',
+    t: ' #  |### | #  | #  | #  ',
+    u: '    |#  #|#  #|#  #| ###',
+    v: '    |#  #|#  #| ## |  # ',
+    w: '     |#   #|# # #|# # #| # # ',
+    x: '    |#  #| ## | ## |#  #',
+    y: '    |#  #|#  #| ###|##  ',
+    z: '    |####|  # | #  |####',
+};
+const REST = {
+    0: ' ### |#  ##|# # #|##  #| ### ',
+    1: '  #  | ##  |  #  |  #  |#####',
+    2: ' ### |#   #|   # |  #  |#####',
+    3: '#### |    #| ### |    #|#### ',
+    4: '#  # |#  # |#####|   # |   # ',
+    5: '#####|#    |#### |    #|#### ',
+    6: ' ### |#    |#### |#   #| ### ',
+    7: '#####|   # |  #  | #   | #   ',
+    8: ' ### |#   #| ### |#   #| ### ',
+    9: ' ### |#   #| ####|    #| ### ',
+    '!': ' # | # | # |   | # ',
+    '?': ' ### |#   #|   # |     |  #  ',
+    '.': '   |   |   |   | # ',
+    ',': '   |   |   | # |#  ',
+    ':': '   | # |   | # |   ',
+    ';': '   | # |   | # |#  ',
+    '-': '    |    |####|    |    ',
+    '+': '     |  #  | ### |  #  |     ',
+    '=': '    |####|    |####|    ',
+    '*': '     |# # | ### |# # |     ',
+    '/': '    #|   # |  #  | #   |#    ',
+    '\\': '#    | #   |  #  |   # |    #',
+    '(': '  #| # | # | # |  #',
+    ')': '#  | # | # | # |#  ',
+    "'": ' # | # |   |   |   ',
+    '"': '# #|# #|   |   |   ',
+    '#': ' # # |#####| # # |#####| # # ',
+    '@': ' ### |#   #|# ## |#    | ### ',
+    '&': ' ##  |##   | ### |#  # | ## #',
+    '<': '  #| # |#  | # |  #',
+    '>': '#  | # |  #| # |#  ',
+    '$': ' ####|# #  | ### |  # #|#### ',
+    '%': '#   #|   # |  #  | #   |#   #',
+    '[': '### |#   |#   |#   |### ',
+    ']': ' ###|   #|   #|   #| ###',
+    '^': '  #  | # # |#   #|     |     ',
+    '`': '#   | #  |    |    |    ',
+    '{': '  ##| #  |##  | #  |  ##',
+    '|': '#|#|#|#|#',
+    '}': '##  |  # |  ##|  # |##  ',
+    '~': '     | ##  |#  ##|     |     ',
+    '_': '    |    |    |    |####',
+};
+/** The one hand-drawn table: every glyph, in both cases. */
+const BLOCK = Object.fromEntries(Object.entries({ ...CAPS, ...LOWER, ...REST }).map(([key, spec]) => [key, pad(spec.split('|'))]));
+/**
+ * A second hand-drawn table: three rows, and drawn in strokes rather than in
+ * cells.
+ *
+ * Three rows of *solid* cells cannot hold an alphabet - at that size an `A` and
+ * an `M` are the same three-by-three block, and so are `G` and `O`. The way out
+ * is the one every small figlet font takes: stop filling cells and start
+ * drawing strokes, so a `|` and a `/` and a `\` each carry a direction the cell
+ * on its own could not. That is why this table is characters rather than `#`,
+ * and why it needs no placeholder - it is already what it looks like.
+ *
+ * One case. At three rows there is no room under a cap for an x-height, so
+ * lowercase folds to these; `banner` does the folding.
+ */
+const MINI = {
+    A: [' _ ', '|_|', '| |'],
+    B: [' _ ', '|_)', '|_)'],
+    C: [' _ ', '/  ', '\\_ '],
+    D: [' _ ', '| \\', '|_/'],
+    E: [' _ ', '|_ ', '|_ '],
+    F: [' _ ', '|_ ', '|  '],
+    G: [' _ ', '/ _', '\\_|'],
+    H: ['   ', '|_|', '| |'],
+    I: [' _ ', ' | ', ' | '],
+    J: [' _ ', '  |', '._|'],
+    K: ['   ', '|/ ', '|\\ '],
+    L: ['   ', '|  ', '|_ '],
+    M: ['    ', '|\\/|', '|  |'],
+    N: ['    ', '|\\ |', '| \\|'],
+    O: [' _ ', '/ \\', '\\_/'],
+    P: [' _ ', '|_)', '|  '],
+    Q: [' _ ', '/ \\', '\\_\\'],
+    R: [' _ ', '|_)', '| \\'],
+    S: [' _ ', '(_ ', '._)'],
+    T: ['___', ' | ', ' | '],
+    U: ['   ', '| |', '╰─╯'],
+    V: ['    ', '\\  /', ' \\/ '],
+    W: ['    ', '|  |', '|\\/|'],
+    X: ['   ', '\\ /', '/ \\'],
+    Y: ['   ', '\\ /', ' | '],
+    Z: ['___', ' / ', '/_ '],
+    // Struck through, or it is the letter `O` again.
+    0: [' _ ', '/|\\', '\\_/'],
+    1: ['   ', ' /|', '  |'],
+    2: [' _ ', ' _)', '(_ '],
+    3: [' _ ', ' _)', ' _)'],
+    4: ['   ', '|_|', '  |'],
+    5: [' _ ', '|_ ', ' _)'],
+    6: [' _ ', '/_ ', '(_)'],
+    7: ['___', '  /', ' / '],
+    8: [' _ ', '(_)', '(_)'],
+    9: [' _ ', '(_)', ' _/'],
+    '!': [' ', '|', '.'],
+    '?': [' _ ', ' _)', ' . '],
+    '.': ['  ', '  ', '. '],
+    ',': ['  ', '  ', ', '],
+    ':': ['  ', '. ', '. '],
+    ';': ['  ', '. ', ', '],
+    '-': ['   ', '___', '   '],
+    '+': ['   ', ' + ', '   '],
+    '=': [' _ ', '___', '   '],
+    '/': ['   ', '  /', ' / '],
+    "'": ['| ', '  ', '  '],
+    '(': [' /', '| ', ' \\'],
+    ')': ['\\ ', ' |', '/ '],
+    '_': ['   ', '   ', '___'],
+    // The rest of printable ascii, in the same strokes. `$ % & @` are not here:
+    // at three rows there is no stroke that says "dollar" rather than "S with a
+    // line", and a stand-in that says `$` is more use than one that lies.
+    '"': ['||', '  ', '  '],
+    '#': ['_|_|', '_|_|', ' | |'],
+    '*': ['   ', '\\|/', '/|\\'],
+    '<': [' /', '< ', ' \\'],
+    '>': ['\\ ', ' >', '/ '],
+    '[': ['|-', '| ', '|_'],
+    ']': ['-|', ' |', '_|'],
+    '{': [' /', '{ ', ' \\'],
+    '}': ['\\ ', ' }', '/ '],
+    '\\': ['\\  ', ' \\ ', '  \\'],
+    '^': ['/\\', '  ', '  '],
+    '`': ['\\ ', '  ', '  '],
+    '|': ['|', '|', '|'],
+    '~': ['   ', '/\\/', '   '],
+};
+/**
+ * A third table: three rows of heavy box-drawing.
+ *
+ * The capitals are transcribed from a font Softov brought, character for
+ * character - which is why `X` is four cells wide and `I` is one, and why they
+ * are not going to be tidied into a grid. The digits and the punctuation are
+ * drawn to match rather than transcribed, because the source had none.
+ *
+ * One case, and it is the only font here that cannot be drawn at all on an
+ * ascii terminal - box-drawing has no `#` to fall back to the way a block does,
+ * so this one names `mini` as what to use instead. Same three rows, same
+ * stroke-drawn idea, characters a teletype could manage.
+ */
+const TMPLT = {
+    A: ["┏┓", "┣┫", "┛┗"],
+    B: ["┳┓", "┣┫", "┻┛"],
+    C: ["┏┓", "┃ ", "┗┛"],
+    D: ["┳┓", "┃┃", "┻┛"],
+    E: ["┏┓", "┣ ", "┗┛"],
+    F: ["┏┓", "┣ ", "┻ "],
+    G: ["┏┓", "┃┓", "┗┛"],
+    H: ["┓┏", "┣┫", "┛┗"],
+    I: ["┳", "┃", "┻"],
+    J: ["┏┳", " ┃", "┗┛"],
+    K: ["┓┏┓", "┃┫ ", "┛┗┛"],
+    L: ["┓ ", "┃ ", "┗┛"],
+    M: ["┳┳┓", "┃┃┃", "┛ ┗"],
+    N: ["┳┓", "┃┃", "┛┗"],
+    O: ["┏┓", "┃┃", "┗┛"],
+    P: ["┏┓", "┃┃", "┣┛"],
+    Q: ["┏┓", "┃┃", "┗┻"],
+    R: ["┳┓", "┣┫", "┛┗"],
+    S: ["┏┓", "┗┓", "┗┛"],
+    T: ["┏┳┓", " ┃ ", " ┻ "],
+    U: ["┳┳", "┃┃", "┗┛"],
+    V: ["┓┏", "┃┃", "┗┛"],
+    W: ["┓ ┏", "┃┃┃", "┗┻┛"],
+    X: ["┏┓┏┓", " ┃┃ ", "┗┛┗┛"],
+    Y: ["┓┏", "┗┫", "┗┛"],
+    Z: ["┏┓", "┏┛", "┗┛"],
+    // Drawn to match, not transcribed. `0` keeps `O`'s shape, which is what a
+    // font this small usually does with them.
+    // A slash through it, or a zero and a letter `O` are the same glyph.
+    0: ["┏┓", "┃╋", "┗┛"],
+    1: [" ┓", " ┃", " ┻"],
+    2: ["┏┓", "┏┛", "┗┻"],
+    3: ["┏┓", " ┫", "┗┛"],
+    4: ["┓┏", "┗╋", " ┃"],
+    5: ["┏┳", "┗┓", "┗┛"],
+    6: ["┏┓", "┣┓", "┗┛"],
+    7: ["┳┳", " ┃", " ┛"],
+    8: ["┏┓", "┣┫", "┗┛"],
+    9: ["┏┓", "┗┫", "┗┛"],
+    'a': ["", "┏┓", "┗┻"],
+    'b': ["┓ ", "┣┓", "┗┛"],
+    'c': ["", "┏", "┗"],
+    'd': [" ┓", "┏┫", "┗┻"],
+    'e': ["", "┏┓", "┗━"],
+    'f': [" ┏", " ╋", " ┛"],
+    'g': ["", "┏┓", "┗┫", " ┛"],
+    'h': ["┓ ", "┣┓ ", "┛┗ ",],
+    'i': ["•", "┓ ", "┗ ",],
+    'j': ["• ", "┓ ", "┃ ", "┛ ",],
+    'k': ["┓ ", "┃┏", "┛┗",],
+    'l': ["┓ ", "┃ ", "┗ ",],
+    'm': ["", "┏┳┓", "┛┗┗",],
+    'n': ["", "┏┓ ", "┛┗ ",],
+    'o': ["", "┏┓", "┗┛",],
+    'p': ["", "┏┓", "┣┛", "┛ ",],
+    'q': ["", "┏┓", "┗┫", " ┗",],
+    'r': ["", "┏┓", "┛ ",],
+    's': ["", "┏ ", "┛ ",],
+    't': ["┃ ", "╋ ", "┗━"],
+    'u': ["", "┓┏", "┗┻",],
+    'v': ["", "┓┏", "┗┛",],
+    'w': ["", "┓┃┏", "┗┻┛"],
+    'x': ["", "┓┏", "┛┗",],
+    'y': [" ", "┓┏", "┗┫", " ┛"],
+    'z': ["", "━┓", "┗━"],
+    '.': [" ", " ", "•"],
+    ',': [" ", " ", "┛"],
+    ':': [" ", "•", "•"],
+    ';': [" ", "•", "┛"],
+    '!': ["┃", "┃", "•"],
+    '?': ["┏┓", " ┛", " •"],
+    '@': ["┏━┓", "┃┗┛", "┗━┛"],
+    '$': ["┏┻┓", "┗━┓", "┗┳┛"],
+    '&': ["•┏", " ┃", " ┛•"],
+    '%': ["┏┓", "┣╋", "┗┻"],
+    '¨': ["••"],
+    '*': [" ", "•"],
+    '-': ["  ", "━━", "  "],
+    '+': ["  ", "╋ ", "  "],
+    '=': ["  ", "━━", "━━"],
+    '/': [" ┏", "┏┛", "┛ "],
+    "'": ["┃", " ", " "],
+    '(': ["┏", "┃", "┗"],
+    ')': ["┓", "┃", "┛"],
+    '_': ["  ", "  ", "━━"],
+    // Also drawn to match. `$ % & @ *` are left out: box-drawing has no stroke
+    // for any of them, and a `╋` standing in for a `*` is a plus sign lying.
+    '"': ["┃┃", "  ", "  "],
+    '#': ["", "╋╋", "╋╋", "  "],
+    '<': [" ┏", "┫ ", " ┗"],
+    '>': ["┓ ", " ┣", "┛ "],
+    // The square pair takes a bar off each corner, so it is not the round pair
+    // drawn a second time - which is what it was until a test said so.
+    '[': ["┏━", "┃ ", "┗━"],
+    ']': ["━┓", " ┃", "━┛"],
+    '{': ["┏", "┫", "┗"],
+    '}': ["┓", "┣", "┛"],
+    '\\': ["┓ ", "┗┓", " ┛"],
+    '^': ["┏┓", "  ", "  "],
+    '`': ["┓ ", "  ", "  "],
+    '|': ["┃", "┃", "┃"],
+    '~': ["  ", "┏┛", "  "],
+};
+// ------------------------------------------------------------- transforms
+/** Every row the same length, so a transform can index a rectangle. */
+function pad(rows) {
+    const width = rows.reduce((w, row) => Math.max(w, row.length), 0);
+    return rows.map((row) => row.padEnd(width, ' '));
+}
+function mapGlyphs(font, fn) {
+    return Object.fromEntries(Object.entries(font).map(([key, rows]) => [key, pad(fn(rows))]));
+}
+/** Every column twice. Twice the letter, the same shape. */
+function wide(rows) {
+    return rows.map((row) => Array.from(row).map((c) => c + c).join(''));
+}
+/**
+ * Sheared right, more the higher up the row is - an italic.
+ *
+ * Half a cell per row rather than one, because a five-row letter leaning five
+ * columns is a letter lying down. The shear is what a bitmap font has instead
+ * of a second table: the letters are the same letters.
+ */
+function slant(rows) {
+    const height = rows.length;
+    return rows.map((row, y) => ' '.repeat(Math.floor((height - 1 - y) / 2)) + row);
+}
+/**
+ * The letter, and a second copy of it down and to the right in `%`.
+ *
+ * Two rules, and the second is the one that took a try to get right. The
+ * letter is drawn over the shadow, so where they overlap the letter wins. And
+ * the shadow is kept only *outside* the letter - the counter of an `A` is
+ * enclosed, a real shadow could not fall into it, and one that did turned a
+ * five-row capital into a smudge. `outside` is a flood fill from the border,
+ * which is the cheapest way to ask whether a hole is a hole.
+ */
+function shadow(rows) {
+    const height = rows.length + 1;
+    const width = rows[0].length + 1;
+    const lit = (y, x) => y >= 0 && y < rows.length && x >= 0 && x < rows[y].length
+        && rows[y][x] !== ' ';
+    const open = outside(height, width, (y, x) => lit(y, x));
+    const out = Array.from({ length: height }, () => Array.from({ length: width }, () => ' '));
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            if (lit(y - 1, x - 1) && open[y * width + x])
+                out[y][x] = '%';
+        }
+    }
+    for (let y = 0; y < rows.length; y++) {
+        for (let x = 0; x < rows[y].length; x++) {
+            if (lit(y, x))
+                out[y][x] = '#';
+        }
+    }
+    return out.map((row) => row.join(''));
+}
+/** Which blank cells a flood fill from the border can reach. */
+function outside(height, width, lit) {
+    const open = new Array(height * width).fill(false);
+    const queue = [];
+    const push = (y, x) => {
+        if (y < 0 || y >= height || x < 0 || x >= width)
+            return;
+        if (open[y * width + x] || lit(y, x))
+            return;
+        open[y * width + x] = true;
+        queue.push([y, x]);
+    };
+    for (let x = 0; x < width; x++) {
+        push(0, x);
+        push(height - 1, x);
+    }
+    for (let y = 0; y < height; y++) {
+        push(y, 0);
+        push(y, width - 1);
+    }
+    while (queue.length > 0) {
+        const [y, x] = queue.pop();
+        push(y - 1, x);
+        push(y + 1, x);
+        push(y, x - 1);
+        push(y, x + 1);
+    }
+    return open;
+}
+/**
+ * Two rows of the table to one row of output, as half cells.
+ *
+ * The only transform that changes the *height*: five rows become three, and a
+ * banner that would not fit a short terminal does. A cell is full where both
+ * source rows are lit, a top or a bottom half where one is, and nothing where
+ * neither - which is four characters standing in for four combinations, and
+ * why it is a substitution rather than a redrawing.
+ */
+function half(rows) {
+    const width = rows[0].length;
+    const out = [];
+    for (let y = 0; y < rows.length; y += 2) {
+        let line = '';
+        for (let x = 0; x < width; x++) {
+            const top = rows[y][x] !== ' ';
+            const bottom = y + 1 < rows.length && rows[y + 1][x] !== ' ';
+            line += top && bottom ? '#' : top ? '^' : bottom ? 'v' : ' ';
+        }
+        out.push(line);
+    }
+    return out;
+}
+/**
+ * Drawn in dots and colons rather than in blocks.
+ *
+ * A cell takes the character of the stroke that owns it, and the two strokes
+ * that can both claim a cell are settled by one question: **does anything come
+ * down into it?**
+ *
+ *   * a neighbour across, and nothing above - the bar owns it, a dot;
+ *   * anything else with a neighbour above or below - a stem owns it, a colon;
+ *   * neither - a dot, which is what a diagonal and a full stop are made of.
+ *
+ * Both halves of that were learnt the hard way and neither is arbitrary. Ask
+ * about the vertical first and the top bar of a `T` comes out `..:..`, because
+ * the stem hangs off its middle - but a stem hanging *below* a bar does not
+ * take a cell out of the bar. Ask only about the horizontal and the bottom bar
+ * of an `I` comes out `.....`, because the stem is above it - and a stem
+ * landing *on* a bar does show where it lands. A `T` and an `I` are the same
+ * two strokes; which one wins depends on which way the stem runs.
+ *
+ * The letters are the same letters. This is a change of pen, not of hand, which
+ * is why it is twenty lines.
+ */
+function dots(rows) {
+    // Both bounds, on both axes. Indexing a string past its end gives
+    // `undefined`, and `undefined !== ' '` reads as lit - so the last column of
+    // every row believed it had a neighbour to the right.
+    const lit = (y, x) => y >= 0 && y < rows.length
+        && x >= 0 && x < rows[y].length
+        && rows[y][x] !== ' ';
+    return rows.map((row, y) => Array.from(row)
+        .map((cell, x) => {
+        if (cell === ' ')
+            return ' ';
+        const across = lit(y, x - 1) || lit(y, x + 1);
+        if (across && !lit(y - 1, x))
+            return '.';
+        return lit(y - 1, x) || lit(y + 1, x) ? ':' : '.';
+    })
+        .join(''));
+}
+/** Every lit cell a star with a gap after it, which is `wide` with one column of two drawn. */
+function stars(rows) {
+    return rows.map((row) => Array.from(row).map((c) => (c === ' ' ? '  ' : '* ')).join(''));
+}
+export const FONTS = [
+    {
+        id: 'block',
+        title: 'block',
+        note: 'The hand-drawn table: five rows, one cell to a stroke, both cases on one baseline.',
+        glyphs: BLOCK,
+        tracking: 1,
+        space: 3,
+        placeholders: true,
+        cases: 'both',
+    },
+    {
+        id: 'wide',
+        title: 'wide',
+        note: 'The same table with every column drawn twice. Twice the letter, the same shape - and twice as much of it for a ramp to run across.',
+        glyphs: mapGlyphs(BLOCK, wide),
+        tracking: 2,
+        space: 4,
+        placeholders: true,
+        cases: 'both',
+    },
+    {
+        id: 'slant',
+        title: 'slant',
+        note: 'The same table sheared half a column per row. A bitmap font gets its italic the way it gets everything else: by moving the cells.',
+        glyphs: mapGlyphs(BLOCK, slant),
+        tracking: 1,
+        space: 3,
+        placeholders: true,
+        cases: 'both',
+    },
+    {
+        id: 'shadow',
+        title: 'shadow',
+        note: 'The same table twice: the letter, and a copy of it one cell down and right in a second glyph. Two characters in one block, which an ink colours without being told there are two.',
+        glyphs: mapGlyphs(BLOCK, shadow),
+        tracking: 1,
+        space: 3,
+        placeholders: true,
+        cases: 'both',
+    },
+    {
+        id: 'half',
+        title: 'half',
+        note: 'Two rows of the table to one row of half cells. The only transform that changes the height - five rows become three, and a banner that would not fit a short terminal does.',
+        glyphs: mapGlyphs(BLOCK, half),
+        tracking: 1,
+        space: 3,
+        placeholders: true,
+        cases: 'both',
+    },
+    {
+        id: 'dots',
+        title: 'dots',
+        note: 'A dot where a bar runs across, a colon where a stem runs down - and the junction goes to whichever one comes down into it. The same letters in a different pen.',
+        glyphs: mapGlyphs(BLOCK, dots),
+        tracking: 1,
+        space: 3,
+        cases: 'both',
+    },
+    {
+        id: 'stars',
+        title: 'stars',
+        note: 'Every lit cell a star with a gap after it, which is `wide` with one column of the two drawn. Airy enough that a per-cell ink reads as a pattern rather than as a wash.',
+        glyphs: mapGlyphs(BLOCK, stars),
+        tracking: 2,
+        space: 4,
+        cases: 'both',
+    },
+    {
+        id: 'pagga',
+        title: 'pagga',
+        note: 'Three rows of half cells on a shaded ground - the difference from half, and the point of it: the letters are knocked out of a block of texture rather than floating on the terminal.',
+        glyphs: PAGGA,
+        tracking: 0,
+        space: 4,
+        cases: 'folded',
+        fallback: 'mini',
+    },
+    {
+        id: 'gard',
+        title: 'gard',
+        note: 'Quotes, pipes and dots, transcribed glyph for glyph - the only font here with two cases of its own rather than a fold, and the only one with letters that hang below the baseline.',
+        glyphs: GARD,
+        tracking: 1,
+        space: 3,
+        baseline: 6,
+        cases: 'both',
+    },
+    {
+        id: 'tmplt',
+        title: 'tmplt',
+        note: 'Heavy box-drawing, transcribed capital for capital, with a lowercase drawn to match - three rows and a fourth for the tails of g, j, p, q and y. Nothing to fall back to on an ascii terminal, so it borrows mini there.',
+        glyphs: TMPLT,
+        tracking: 1,
+        space: 2,
+        // Row two, not row three: the box grew a fourth row for the descenders
+        // and a stand-in belongs on the line the letters sit on, not on the one
+        // their tails reach down to.
+        baseline: 2,
+        cases: 'both',
+        fallback: 'mini',
+    },
+    {
+        id: 'mini',
+        title: 'mini',
+        note: 'A second table, three rows, drawn in strokes rather than in cells - because at three rows a solid A and a solid M are the same block. One case: lowercase folds to it.',
+        glyphs: MINI,
+        tracking: 1,
+        space: 2,
+        cases: 'folded',
+    },
+];
+export function fontAt(id) {
+    return FONTS.find((f) => f.id === id) ?? FONTS[0];
+}
+/** The font that is drawn in when a caller names none: the hand-drawn table. */
+export const DEFAULT_FONT = fontAt('block');
+/** The tallest glyph in a font, which is how many rows a line of it takes. */
+export function heightOf(font) {
+    return Object.values(font.glyphs).reduce((h, rows) => Math.max(h, rows.length), 0);
+}
+// ----------------------------------------------------------------- render
+/**
+ * The glyph for a character, or nothing.
+ *
+ * Its own, or the other case's - folding is what lets a font with one set of
+ * letters take either - and trimmed of blank edge columns, so a `1` is narrow
+ * and an `M` is wide. Shared by the drawing and the measuring, because a wrap
+ * that measured a letter differently from the way it is drawn is a wrap that
+ * is wrong by however much they disagree.
+ */
+function glyphOf(font, char) {
+    if (invisible(char))
+        return undefined;
+    const found = font.glyphs[char]
+        ?? font.glyphs[char.toUpperCase()]
+        ?? font.glyphs[char.toLowerCase()];
+    if (found !== undefined)
+        return trim(found);
+    return char === ' ' ? undefined : standIn(font, char);
+}
+/**
+ * A character the font has no glyph for, drawn as itself.
+ *
+ * Not a gap. A gap is indistinguishable from a space, so a font missing its
+ * punctuation renders `hello, world!` as `hello  world` and looks like it
+ * worked - the reader has no way to tell a missing glyph from a word break.
+ * One cell with the character in it is legible, obviously not part of the
+ * font, and says exactly which character is absent.
+ *
+ * On the baseline, so it sits on the line with the letters beside it rather
+ * than under them.
+ */
+function standIn(font, char) {
+    const height = heightOf(font);
+    const line = font.baseline ?? height - 1;
+    // Padded to the cells it actually occupies. A wide character is one string
+    // index and two columns, and a stand-in measured by index put every letter
+    // after it one column to the left of where it was drawn.
+    const width = Math.max(1, stringWidth(char));
+    return Array.from({ length: height }, (_, y) => (y === line ? char : ' '.repeat(width)));
+}
+/**
+ * A character that draws nothing and takes no room, because it is not there.
+ *
+ * Zero-width and control characters arrive by paste - a byte-order mark off a
+ * web page, a zero-width space out of a code block - and they used to come out
+ * as a *word gap*, because a character with no glyph gets one. So `AB` pasted
+ * with a joiner between the letters rendered as `A B`, and the banner had a
+ * word break in it that the field it was typed in did not.
+ *
+ * Invisible in the text, invisible in the banner. It is the only reading that
+ * cannot surprise anyone.
+ */
+const INVISIBLE = /^[\p{Cf}\p{Cc}\p{Mn}\p{Me}]$/u;
+function invisible(char) {
+    return graphemeWidth(char) === 0 || INVISIBLE.test(char);
+}
+/**
+ * A character that is a space, whatever its code point.
+ *
+ * A non-breaking space is a space: it arrives by paste out of anything that
+ * has ever been near a web page, and it was drawing as a stand-in - one blank
+ * cell where a word gap belonged, so the words either side ran together.
+ */
+const SPACE = /^\p{Zs}$/u;
+/** The columns a character takes, not counting the gap before it. */
+function widthOf(font, char) {
+    if (invisible(char))
+        return 0;
+    if (SPACE.test(char))
+        return font.space;
+    const glyph = glyphOf(font, char);
+    return glyph ? stringWidth(glyph[0]) : font.space;
+}
+/**
+ * Blank edge columns removed, so a `1` is narrow and an `M` is wide.
+ *
+ * The width is the widest row and not the first one. A table written by hand
+ * has rows of whatever length they happened to be typed at, and `gard` has a
+ * blank first row on every letter - so taking row zero's length trimmed every
+ * one of them to nothing at all.
+ */
+function trim(rows) {
+    const width = rows.reduce((w, row) => Math.max(w, row.length), 0);
+    const padded = rows.map((row) => row.padEnd(width, ' '));
+    let start = 0;
+    let end = width - 1;
+    const blank = (x) => padded.every((row) => row[x] === ' ');
+    while (start < width && blank(start))
+        start++;
+    while (end >= start && blank(end))
+        end--;
+    return padded.map((row) => row.slice(start, end + 1));
+}
+export function inkGlyphs(glyphs, unicode = true) {
+    return {
+        fill: glyphs.progressFull,
+        shade: glyphs.progressEmpty,
+        top: unicode ? '▀' : '"',
+        bottom: unicode ? '▄' : '_',
+    };
+}
+/** What the fonts are drawn in where nothing has said otherwise. */
+export const PLAIN_GLYPHS = { fill: '#', shade: '-', top: '"', bottom: '_' };
+/**
+ * Text as block letters.
+ *
+ * Newlines are lines: each one becomes its own block of rows, stacked with
+ * `lineGap` blank rows between them so two lines of banner do not read as one.
+ * A character with no glyph becomes a word space, so a missing one shows as a
+ * gap the reader can see rather than silently closing up.
+ */
+export function bannerLines(text, font, ink = PLAIN_GLYPHS, width = Infinity) {
+    const height = heightOf(font);
+    return text
+        .split('\n')
+        .flatMap((line) => wrapToWidth(line, font, width))
+        .map((line) => bannerLine(line, font, height, ink));
+}
+/**
+ * The same banner, one string per line.
+ *
+ * For a caller that has to place the lines itself, and the case that makes it
+ * necessary is centring: a multi-line block is centred once, as a block, so its
+ * shorter lines start at the widest line's edge and read as left-aligned. One
+ * `ColorText` per line - each `alignBlock` and `textAlign="center"` - centres
+ * every line over its own width while keeping the rows of each in step.
+ *
+ * The catch is the ink: a [`ColorText`](color-text.md) starts its ink at its
+ * own first cell, so a block drawn as several pieces restarts a `cycle` (and a
+ * `{ gradient }` measures each piece rather than the lot). That is a reason to
+ * keep one component for a continuous ramp, and this for centring.
+ */
+export function banner(text, font, ink = PLAIN_GLYPHS, width = Infinity, 
+/**
+ * Blank rows between one line and the next. One by default.
+ *
+ * Counts the *empty* rows, so `0` butts two lines together and `2` leaves two
+ * rows of air. It applies to every line the block has, wrapped or written -
+ * the break between two lines of a sentence is the same break as the one
+ * between two paragraphs, which is what makes a wrapped banner read as a
+ * block of its own rather than as one long line that ran out of room.
+ */
+lineGap = 1) {
+    const gap = `\n${'\n'.repeat(Math.max(0, Math.floor(lineGap)))}`;
+    return bannerLines(text, font, ink, width).join(gap);
+}
+/**
+ * Break a line of text into lines that fit, measured in this font.
+ *
+ * The wrapping has to happen *here*, on the text, and not on the drawn block:
+ * a line of block letters cut at column sixty is a line of half letters, and
+ * five rows each cut in a different place is not a word at all. So the letters
+ * are measured before they are drawn, and the break goes between them.
+ *
+ * Words first, characters only when one word cannot fit on a line of its own -
+ * because breaking `Deployment` in half is bad and dropping the second half is
+ * worse, and one of those has to happen.
+ */
+function wrapToWidth(text, font, width) {
+    if (!Number.isFinite(width) || width <= 0)
+        return [text];
+    const lines = [];
+    let line = '';
+    let used = 0;
+    const flush = () => { lines.push(line); line = ''; used = 0; };
+    /**
+     * Put a piece on the line, or on the next one.
+     *
+     * `sep` is the gap it needs from what is already there - a word space
+     * between words, tracking between the letters of one word - and `gap` is
+     * what that gap is spelled as in the text, which is a space for the first
+     * and nothing for the second.
+     */
+    const add = (piece, cost, sep, gap) => {
+        if (line !== '' && used + sep + cost > width)
+            flush();
+        if (line === '') {
+            line = piece;
+            used = cost;
+            return;
+        }
+        line += gap + piece;
+        used += sep + cost;
+    };
+    for (const word of text.split(' ')) {
+        const cost = costOf(word, font);
+        if (cost === 0)
+            continue;
+        if (cost <= width) {
+            add(word, cost, font.space, ' ');
+            continue;
+        }
+        // Wider than a whole line even on its own, so it is spent a character at a
+        // time - starting in whatever room is left on this line rather than on a
+        // fresh one, because a line holding three letters and a lot of air is not
+        // an improvement on a broken word.
+        let first = true;
+        for (const char of Array.from(word)) {
+            add(char, widthOf(font, char), first ? font.space : font.tracking, first ? ' ' : '');
+            first = false;
+        }
+    }
+    if (line !== '' || lines.length === 0)
+        lines.push(line);
+    return lines;
+}
+/** The columns a word takes, letters and the tracking between them. */
+function costOf(word, font) {
+    // Invisible characters are dropped before the tracking is counted, or a
+    // word of nothing but a byte-order mark would still be charged for the gaps
+    // between the letters it does not have.
+    const chars = Array.from(word).filter((char) => !invisible(char));
+    return chars.reduce((total, char, i) => total + (i === 0 ? 0 : font.tracking) + widthOf(font, char), 0);
+}
+function bannerLine(text, font, height, ink) {
+    const rows = Array.from({ length: height }, () => '');
+    let first = true;
+    for (const char of Array.from(text)) {
+        if (invisible(char))
+            continue;
+        // A space is a gap unless the font draws one. `pagga` does: its ground has
+        // to run through the gap between two words, and a gap would be a hole in
+        // it - so the table has a glyph for `' '` and that glyph wins.
+        const glyph = SPACE.test(char)
+            ? (font.glyphs[' '] === undefined ? undefined : trim(font.glyphs[' ']))
+            : glyphOf(font, char);
+        if (!glyph) {
+            for (let y = 0; y < height; y++)
+                rows[y] += ' '.repeat(font.space);
+            first = true;
+            continue;
+        }
+        // Top-aligned: row nought of a glyph is row nought of the line, and a
+        // glyph shorter than the font is short at the *bottom*.
+        //
+        // Which is what lets a descender be written as one row taller than
+        // everything else and nothing else be touched. An `a` says where it starts
+        // with a blank first row; a `g` says where it ends by having a fourth. Line
+        // them up from the bottom instead and adding a tail to `g` silently pushes
+        // every three-row capital down a row, so `A` comes to rest on the same line
+        // as the tail rather than on the same line as the `g` itself.
+        const width = glyph.reduce((w, row) => Math.max(w, row.length), 0);
+        for (let y = 0; y < height; y++) {
+            const row = y < glyph.length ? glyph[y] : ' '.repeat(width);
+            rows[y] += (first ? '' : ' '.repeat(font.tracking)) + row;
+        }
+        first = false;
+    }
+    // Blank rows off the top and the bottom, so a line of nothing but x-height
+    // letters is four rows rather than five with a gap over it. Per line, which
+    // is the unit that is stacked - the letters inside one still share a
+    // baseline, and that is the alignment that has to hold.
+    // Only where the font said its glyphs are placeholders. A hand-drawn table
+    // is already what it looks like, and running this over one would turn its
+    // literal `#` into a full block and its `v` into half a cell.
+    const ink_ = (row) => (font.placeholders
+        ? row.replace(/#/g, ink.fill).replace(/%/g, ink.shade)
+            .replace(/\^/g, ink.top).replace(/v/g, ink.bottom)
+        : row);
+    const drawn = rows.map((row) => ink_(row).trimEnd());
+    while (drawn.length > 0 && drawn[0] === '')
+        drawn.shift();
+    while (drawn.length > 0 && drawn[drawn.length - 1] === '')
+        drawn.pop();
+    return drawn.join('\n');
+}