ColorText: a colour per cell, and the ink example

A `text` takes one colour for the whole run, which is right for nearly
everything and no answer at all where the colour *is* the content - a
banner, a ramp across a title, a palette walked down a block of ascii
art. `ColorText` is that case: it paints on a canvas and asks an `ink`
for a colour per cell.

An ink is spelled three ways. A ramp between stops, across the columns,
down the lines or corner to corner. A palette walked in runs, so
`every: [4, 3]` is four cells of one colour and three of the next. Or a
function handed the cell, which is the escape hatch - and the one that
cannot be written in a JSON screen, the same trade canvas makes with
draw.

Two things the building of it decided:

  * the cell carries a `col` and an `index`, because they stop being the
    same number the moment the text is not plain ascii, and the walk
    advances by grapheme width - colour by index and paint at col, and a
    gradient shears through the first wide character it meets;

  * `alignBlock`, because textAlign centres every line over its own
    middle. That is right for prose and it shears a picture: five rows
    of block letters do not have equal widths once the trailing spaces
    are gone, so each row lands somewhere slightly different and the
    letters lean.

A block that wraps asks for no width and takes what it is given; one
that does not is as wide as its widest line and says so. Reporting the
unwrapped width in both cases pushed every sibling off the row.

The examples/ink example is the demonstration and the test. A field, a
list of inks, a font, and a panel that scrolls - and a switch that
swaps the block letters for three paragraphs of prose, because the
component has no idea which it is looking at. Its fonts are one
hand-drawn table with both cases on one baseline, plus three transforms
of it: wide, slant and shadow. A bitmap font is a grid of characters,
and a grid of characters can be sheared, doubled or duplicated by ten
lines of code.

ScrollView takes a `focusId`. It was the only focusable control without
one, so the example had no way to name the panel it scrolls - and the
test that scrolls it was passing for the wrong reason until it did.

Author: softov

docs/components/README.md

@@ -31,7 +31,7 @@ Every node also accepts `role`, `label`, `focusable`, `onKey`, `onClick`, `disab
 
 <!-- props:start -->
 
-~96 components, and growing.
+~97 components, and growing.
 
 ### The four primitives
 
@@ -65,6 +65,7 @@ Every node also accepts `role`, `label`, `focusable`, `onKey`, `onClick`, `disab
 | [`Badge`](display/badge.md) | Small status marker; carries a glyph as well as a colour. |
 | [`StatusDot`](display/status-dot.md) | The shared status vocabulary: up, degraded, down. |
 | [`Card`](display/card.md) | Bordered block with a title. |
+| [`ColorText`](display/color-text.md) | Multiline text coloured cell by cell - a ramp, a palette per line, or a function. |
 | [`Marquee`](display/marquee.md) | Text too long for its box, read by sliding it while it has the cursor. |
 
 ### Data

docs/components/display.md

@@ -11,10 +11,12 @@ What shows a value: a label, a table of them, or a shape drawn from a series.
 
 ## Display
 
-`Heading` `Label` `Badge` `StatusDot` `Card` `KeyValue` `Timeline`
+`Heading` `Label` `Badge` `StatusDot` `Card` `ColorText` `Marquee` `KeyValue` `Timeline`
 
 `StatusDot` is the shared status vocabulary. A status is a glyph *and* a colour, because a 16-colour session, a colourblind reader and a piped log all lose the colour and keep the glyph.
 
+`ColorText` is the exception that proves that rule: it colours a block of text cell by cell - a ramp, a palette walked in runs, or a function handed each cell - and everything it does is decoration. A banner, a title, ascii art. What a reader has to know still has to be in the words, because the ramp is the first thing an ssh session flattens.
+
 ## Data
 
 `List` `Table` `Tree` `Pagination` `LogViewer` `CodeViewer` `MarkdownView` `Feed`

docs/components/display/color-text.md

@@ -0,0 +1,102 @@
+---
+title: ColorText
+parent: Display and data
+grand_parent: Components
+---
+
+# ColorText
+{: .no_toc }
+
+Multiline text coloured cell by cell - a ramp, a palette per line, or a function.
+
+<!-- docs:setup
+declare const banner: string;
+-->
+
+```tsx
+import { ColorText } from '@textui/widgets';
+
+<ColorText ink={{ gradient: ['cyan', 'magenta'] }} content={banner} alignBlock />
+```
+
+## Props
+
+<!-- props:start -->
+| Prop | Type | Default | |
+| --- | --- | --- | --- |
+| `ink` | `Ink` |  | Left unset, this is an ordinary block of text. |
+| `alignBlock` | `boolean` |  | Align the block as one thing, rather than each line on its own. `textAlign` centres every line over its own middle, which is right for prose and shears a picture: five rows of block letters do not have equal widths once the trailing spaces are gone, so each row lands somewhere slightly different and the letters lean. Under this, the whole block is placed once and the lines keep their offsets from each other. Off by default, because that is what `text` does and the two are supposed to mean the same thing by the same prop. |
+
+Plus everything on [`TextProps`](../base-props.md).
+<!-- props:end -->
+
+A `text` takes one colour for the whole run, which is right for nearly
+everything and no answer at all where the colour *is* the content - a banner, a
+ramp across a title, a palette walked down a block of ascii art. Everything else
+about this is a `text`: `wrap`, `truncate`, `textAlign` and the style keys
+all mean here what they mean there.
+
+`ink` is spelled three ways, and the first two are data:
+
+<!-- docs:local
+import { ColorText } from '@textui/widgets';
+import type { Color } from '@textui/core';
+declare const text: string;
+declare const palette: Color[];
+-->
+
+```tsx
+<box direction="column">
+  <ColorText ink={{ gradient: ['#ff5f6d', '#ffc371'], axis: 'y' }} content={text} />
+  <ColorText ink={['danger', 'warning', 'success']} content={text} />
+  <ColorText ink={{ cycle: palette, every: [4, 3] }} content={text} />
+  <ColorText ink={(cell) => (cell.index % 2 ? 'muted' : 'accent')} content={text} />
+</box>
+```
+
+A **ramp** runs across the columns, down the lines, or corner to corner. It is
+measured against the widest line of the block, so the rows of a banner share one
+gradient and the colours line up down it; `per: 'line'` restarts it on each
+line, which is what ragged prose wants.
+
+A **cycle** walks a palette. An array on its own is the short spelling of one
+colour per line. `every` is how much of the text each colour takes - a number,
+or a repeating pattern of runs, so `[4, 3]` is four cells then three. The count
+restarts on each line, which is what keeps the bands vertical; `continuous`
+carries it over the line breaks and leans them into a diagonal. `unit` picks
+what advances the colour: `cell` (the default, and the one that keeps a block
+aligned), `grapheme`, `letter`, `word` or `line`.
+
+A **function** is handed each cell and answers with a colour, a whole
+`CellStyle`, or nothing - and nothing means "leave this one alone", which is
+what makes an ink that colours only the vowels two lines long. The cell carries
+a `col` *and* an `index` because they stop being the same number the moment
+the text is not plain ascii: colour by `index` and paint at `col`, or a
+gradient shears through the first wide character it meets.
+
+Only the data forms survive being written in a JSON screen. A function prop
+cannot be serialized - the same trade [`canvas`](../primitives/canvas.md)
+makes with `draw`, and for the same reason: this paints on one.
+
+Two consequences of that canvas are worth knowing. **Inherited colour stops
+here**: a cell the ink declines takes this component's own `fg`, not the one a
+parent row would have handed a `text`, so a `ColorText` inside something that
+recolours its children when selected has to be told. And **a block that wraps
+asks for no width** - it fills what it is given, the way anything that wraps
+must; a block that does not wrap is as wide as its widest line and says so.
+
+`alignBlock` is for pictures. `textAlign` centres every line over its own
+middle, which is right for prose and shears a banner, because five rows of block
+letters do not have equal widths once the trailing spaces are gone. Under
+`alignBlock` the whole block is placed once and the lines keep their offsets
+from each other.
+
+The colour is decoration and never the message. A 16-colour session flattens a
+six-stop ramp into a couple of bands and a piped log loses all of it, so
+anything the reader has to know has to be in the words.
+
+## See also
+
+- [text](../primitives/text.md) - one colour, and the right answer nearly always
+- [canvas](../primitives/canvas.md) - the primitive underneath, for cells that are not text
+- [Themes](../../themes/tokens.md) - the tokens an ink can name

docs/components/layout/scroll-view.md

@@ -27,6 +27,7 @@ import { ScrollView } from '@textui/widgets';
 | `scrollbar` | `boolean` | `true` | Draw a scrollbar on the right when the content overflows. |
 | `focusable` | `boolean` | `true` | A tab stop, so the keys that scroll it can reach it. On by default: a viewport had the arrow handlers all along and registered nothing, so unless the caller happened to make it focusable itself the only way to scroll was the wheel - which is to say, on a keyboard, not at all. Turn it off for a view that scrolls inside something already focused. |
 | `autoFocus` | `boolean` |  |  |
+| `focusId` | `string` |  | A stable focus id, so a command - or the screen that owns this - can put the reader here by name. Without one the id comes from the instance, which nothing outside the render can know: "scroll the preview" has nothing to name and the key that would do it cannot be written. Every other focusable control takes one; this was the exception, and there was no reason for it. |
 
 Plus everything on [`BoxProps`](../base-props.md).
 <!-- props:end -->

examples/README.md

@@ -54,7 +54,7 @@ Bigger programs, bundled by esbuild because they are many files rather than
 because textui needs it.
 
 ```bash
-pnpm example todo        # or arcade, chat, surfaces
+pnpm example todo        # or arcade, chat, surfaces, ink
 ```
 
 | | |
@@ -63,4 +63,5 @@ pnpm example todo        # or arcade, chat, surfaces
 | [`arcade`](arcade) | Frame loops, canvas painting, input timing |
 | [`chat`](chat) | `Feed`, `TextArea`, markdown, and a fake host |
 | [`surfaces`](surfaces) | An application with no shell, arranging its own chrome |
+| [`ink`](ink) | `ColorText`: a colour per cell, over a banner and over prose |
 | [`showcase`](showcase) | The catalog on one screen, as a row that wraps. Writes its own screenshot |

examples/ink/.gitignore

@@ -0,0 +1,2 @@
+.dev
+dist

examples/ink/README.md

@@ -0,0 +1,78 @@
+# ink
+
+```bash
+pnpm example ink
+pnpm example ink -- --colors 4      # what an ssh session makes of it
+pnpm example ink -- --unicode ascii # and a terminal with no block glyph
+```
+
+Type in the field - enter starts a second line - pick an ink and a font, and
+watch the same component colour a banner or a paragraph. The panel scrolls, so
+a tall font or three paragraphs of prose is not a clipped screen.
+
+## What it is for
+
+`ColorText` colours a block of text cell by cell. The example is a banner
+because that is where per-cell colour is worth anything, but **the component
+has no idea what a banner is** - `ctrl+p` swaps the block letters for ordinary
+prose and every ink in the list still applies, unchanged. The fonts are
+[`src/fonts.ts`](src/fonts.ts), which is application data and deliberately not
+something the library ships.
+
+## The three ways to write an ink
+
+The list runs top to bottom through all of them, and
+[`src/inks.ts`](src/inks.ts) is where they are written.
+
+**A ramp.** `{ gradient: ['#ff5f6d', '#ffc371'] }`, with an `axis` of `x`, `y`
+or `xy`. The ramp is measured against the widest line of the block by default,
+so five rows of block letters share one gradient and the colours line up down
+the block; `per: 'line'` restarts it on each line instead, which is what
+ragged prose wants.
+
+**A palette.** An array is one colour per line. `{ cycle, every: [4, 3] }` is
+four cells of one colour, three of the next, and round again - and the run
+restarts on each line, which is what keeps the bands vertical. `continuous`
+carries the count over the line breaks and leans them into a diagonal.
+`unit` picks what advances the colour: cells, graphemes, letters, words, lines.
+
+**A function.** `(cell, ctx) => colour`. The cell carries `char`, `col`,
+`line`, `index`, `offset`, `width`, `height` and `blockWidth` - a column *and*
+an index, because they stop being the same number the moment the text is not
+plain ascii. Returning nothing leaves that cell the component's own colour,
+which is what makes `vowels` two lines long.
+
+The first two are data and would survive being written in a JSON screen. The
+third would not, and that is the trade: it is the same one `canvas` makes with
+`draw`.
+
+## The fonts are one table and three transforms
+
+`block` is hand-drawn: five rows, one cell to a stroke, and **both cases on one
+baseline** - lowercase sits on the bottom four rows and the ascenders reach up
+into the fifth, so a cap is visibly taller than an x. Nothing descends below
+the baseline, because five rows is not enough to put a tail under a `g` and
+keep the line spacing honest.
+
+The other three are that table, transformed:
+
+| | |
+|---|---|
+| `wide` | every column drawn twice |
+| `slant` | sheared half a column per row - an italic |
+| `shadow` | the letter, and a copy one cell down and right in a second glyph |
+
+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. `shadow` has one subtlety - the shadow is kept only *outside* the letter,
+found by a flood fill from the border, because a shadow that fell into the
+counter of an `A` turned a five-row capital into a smudge.
+
+## What the flags are for
+
+Nothing in here is allowed to depend on the colour, and the flags are how that
+gets checked rather than asserted. `--colors 4` reduces every 24-bit ink to the
+sixteen the terminal has, and a six-stop spectrum comes out as a few bands.
+`--unicode ascii` takes away the full block, and the banner is drawn in `#`
+with a `-` shadow, because the fill glyphs came from the theme rather than from
+the font.

examples/ink/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@textui/example-ink",
+  "version": "0.0.0",
+  "private": true,
+  "type": "module",
+  "description": "Text coloured cell by cell: ramps, palettes, and an ink you write yourself",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  },
+  "dependencies": {
+    "@textui/core": "workspace:*",
+    "@textui/terminal": "workspace:*",
+    "@textui/widgets": "workspace:*"
+  },
+  "devDependencies": {
+    "@textui/testing": "workspace:*"
+  }
+}