@textui/widgets 0.6.1 → 0.8.0

package/dist/display/font-text.d.ts

@@ -0,0 +1,72 @@
+import type { BoxProps } from '@textui/core';
+import type { Font } from './fonts.js';
+/**
+ * `wrap` is not `BoxProps.wrap`.
+ *
+ * On a `text` it means where a line of *characters* is cut, and the whole point
+ * of this component is that the block it draws is not a line of characters: its
+ * rows are the rows of the letters, so cutting one at column sixty cuts every
+ * letter in it in half. `wrap` here means the one thing that can be done
+ * instead - break the *text* between its words, measured in the font - and it
+ * has no `char`, because a banner broken mid-word is not a banner. The drawn
+ * rows are handed to the `text` node as `wrap: 'none'` always; a caller cannot
+ * reach that.
+ */
+export interface FontTextProps extends Omit<BoxProps, 'wrap'> {
+    /** The text to draw. A newline is a line, and each is a line of banner. */
+    content: string;
+    /**
+     * The font to draw it in. The shipped `block` table by default.
+     *
+     * A font may name a substitute for a terminal that cannot draw its glyphs -
+     * `fallback` - and that is used here in place of it. There is no guessing one
+     * for a table the library has never seen, which is why the font says.
+     */
+    font?: Font;
+    /**
+     * Break the text between its words so the drawn banner fits the box.
+     *
+     * `'none'` - the default - draws the text as it was written, however wide
+     * that is: a banner is usually a size somebody picked, and at a width the
+     * caller did not intend, letters that reflow are worse than letters that
+     * overflow. `'word'` asks the box for its width and breaks the text to it,
+     * words first and a word too wide for a line of its own spent a character at
+     * a time, which is the only place a letter boundary is ever crossed.
+     *
+     * It measures the box, so the first frame - which has no width yet - draws
+     * one unbroken line, exactly as `'none'` would.
+     */
+    wrap?: 'none' | 'word';
+    /**
+     * Blank rows between one line of the block and the next. One by default.
+     *
+     * Not `gap`, which every box already has and means the space between its
+     * *children*: this is the space between the rows of one drawing. `0` butts
+     * the lines together, which for a font with a ground of its own - `pagga`'s
+     * `░`, `tmplt`'s rules - merges them into one texture; a larger number is air
+     * between them, and reads as two lines rather than as one.
+     *
+     * A newline in `content` is a line, and so is a wrap when `wrap: 'word'` is
+     * breaking the text: the gap is the same one either way.
+     */
+    lineGap?: number;
+}
+/**
+ * Text as block letters.
+ *
+ * The shape only: a string in, the same string drawn in the font's glyphs out,
+ * as a `text` node that inherits its colour like any other. Colouring the
+ * letters cell by cell - a ramp across a banner, a palette down it - is
+ * [`ColorText`](color-text.md), and handing it this output is the pair the two
+ * were split for.
+ *
+ * The letters are laid out by [`banner`](fonts.ts), which measures in the font
+ * rather than in cells, so the tracking is the font's and a glyph is
+ * proportional to what it actually draws. A character the font has no glyph for
+ * becomes a word space, so a missing letter shows as a gap rather than quietly
+ * closing up, and the placeholders a table is written in - `#`, `%`, `^`, `v` -
+ * are filled from the theme's own glyphs, which is what keeps a banner legible
+ * on a terminal that can only do ascii.
+ */
+export declare const FontText: (props: FontTextProps) => import("@textui/core").RenderOutput;
+//# sourceMappingURL=font-text.d.ts.map

package/dist/display/font-text.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"font-text.d.ts","sourceRoot":"","sources":["../../src/display/font-text.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAG7C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAC;AAEvC;;;;;;;;;;;GAWG;AACH,MAAM,WAAW,aAAc,SAAQ,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC3D,2EAA2E;IAC3E,OAAO,EAAE,MAAM,CAAC;IAChB;;;;;;OAMG;IACH,IAAI,CAAC,EAAE,IAAI,CAAC;IACZ;;;;;;;;;;;;OAYG;IACH,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACvB;;;;;;;;;;;OAWG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,QAAQ,+DAmBnB,CAAC"}

package/dist/display/font-text.js

@@ -0,0 +1,35 @@
+import { defineComponent, h, useCapabilities, useMeasure, useTheme } from '@textui/core';
+import { banner, DEFAULT_FONT, fontAt, inkGlyphs } from './fonts.js';
+/**
+ * Text as block letters.
+ *
+ * The shape only: a string in, the same string drawn in the font's glyphs out,
+ * as a `text` node that inherits its colour like any other. Colouring the
+ * letters cell by cell - a ramp across a banner, a palette down it - is
+ * [`ColorText`](color-text.md), and handing it this output is the pair the two
+ * were split for.
+ *
+ * The letters are laid out by [`banner`](fonts.ts), which measures in the font
+ * rather than in cells, so the tracking is the font's and a glyph is
+ * proportional to what it actually draws. A character the font has no glyph for
+ * becomes a word space, so a missing letter shows as a gap rather than quietly
+ * closing up, and the placeholders a table is written in - `#`, `%`, `^`, `v` -
+ * are filled from the theme's own glyphs, which is what keeps a banner legible
+ * on a terminal that can only do ascii.
+ */
+export const FontText = defineComponent('FontText', (props) => {
+    const theme = useTheme();
+    const capabilities = useCapabilities();
+    const measured = useMeasure();
+    const { content, font: chosen, wrap, lineGap, ...rest } = props;
+    const unicode = capabilities.unicode !== 'ascii';
+    const picked = chosen ?? DEFAULT_FONT;
+    const font = !unicode && picked.fallback ? fontAt(picked.fallback) : picked;
+    const width = wrap === 'word' ? measured.width : undefined;
+    const drawn = banner(content, font, inkGlyphs(theme.glyphs, unicode), width ?? Number.POSITIVE_INFINITY, lineGap);
+    // `wrap: 'none'` *after* the spread, so the lines `banner` decided on are the
+    // lines drawn. Every one of them is a row of letters; a text node wrapping
+    // one cuts letters in half, and a caller who passed a `TextWrap` through
+    // `...rest` would be doing exactly that.
+    return h('text', { content: drawn, ...rest, wrap: 'none' });
+});

package/dist/display/fonts.d.ts

@@ -0,0 +1,138 @@
+/**
+ * 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.
+ */
+type Grid = string[];
+export interface Font {
+    id: string;
+    title: string;
+    /** What is different about it, for the panel under the list. */
+    note: string;
+    glyphs: Record<string, Grid>;
+    /** Columns between two letters. */
+    tracking: number;
+    /** Columns a word space takes. */
+    space: number;
+    /**
+     * Two sets of letters, or one.
+     *
+     * Everything off the five-row table has `both`, because the table does and a
+     * transform of it cannot lose a case. `mini` has one set and folds - at three
+     * rows there is no room under a cap for an x-height.
+     */
+    cases: 'both' | 'folded';
+    /**
+     * Whether this font's glyphs are written in placeholders.
+     *
+     * The ones off the five-row table are: `#` and `%` and the two halves, filled
+     * in from the theme at paint time. The hand-drawn tables are not - they are
+     * already what they look like - and it matters, because a literal `#` in one
+     * of them would otherwise be swapped for a full block, which is how the
+     * character `#` would come out as a solid bar.
+     */
+    placeholders?: boolean;
+    /**
+     * Which row of the glyph box the letters sit on.
+     *
+     * Only needed where it is not the last one: `gard` keeps two blank rows
+     * under its baseline for the descenders, so a character drawn on the last
+     * row would hang below every letter beside it. Used for the stand-in a
+     * missing character gets, which has to land on the line like anything else.
+     */
+    baseline?: number;
+    /**
+     * The font to draw instead where this one's characters do not exist.
+     *
+     * Only `tmplt` needs one. Every other font here is made of placeholders the
+     * theme fills in, or of characters a teletype has - box-drawing is neither,
+     * and there is no `#` to downgrade a `┏` to. So it names a stand-in of the
+     * same height rather than putting a row of question marks on the screen.
+     */
+    fallback?: string;
+}
+export declare const FONTS: Font[];
+export declare function fontAt(id: string): Font;
+/** The font that is drawn in when a caller names none: the hand-drawn table. */
+export declare const DEFAULT_FONT: Font;
+/** The tallest glyph in a font, which is how many rows a line of it takes. */
+export declare function heightOf(font: Font): number;
+/**
+ * The four characters a glyph's placeholders are drawn in.
+ *
+ * `fill` and `shade` are theme glyphs; the two halves are not, because the
+ * theme has no name for half a cell. What they all share is that the *font*
+ * names a role and something else decides what the terminal can show - which
+ * is the rule the whole catalog follows, and the reason `half` degrades to
+ * quotes and underscores instead of putting a row of question marks on the
+ * screen that needs the banner most.
+ */
+export interface InkGlyphs {
+    fill: string;
+    shade: string;
+    top: string;
+    bottom: string;
+}
+export declare function inkGlyphs(glyphs: {
+    progressFull: string;
+    progressEmpty: string;
+}, unicode?: boolean): InkGlyphs;
+/** What the fonts are drawn in where nothing has said otherwise. */
+export declare const PLAIN_GLYPHS: InkGlyphs;
+/**
+ * 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 declare function bannerLines(text: string, font: Font, ink?: InkGlyphs, width?: number): string[];
+/**
+ * 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 declare function banner(text: string, font: Font, ink?: InkGlyphs, width?: number, 
+/**
+ * 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?: number): string;
+export {};
+//# sourceMappingURL=fonts.d.ts.map

package/dist/display/fonts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fonts.d.ts","sourceRoot":"","sources":["../../src/display/fonts.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAMH,KAAK,IAAI,GAAG,MAAM,EAAE,CAAC;AAyerB,MAAM,WAAW,IAAI;IACnB,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IAC7B,mCAAmC;IACnC,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,KAAK,EAAE,MAAM,CAAC;IACd;;;;;;OAMG;IACH,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB;;;;;;;;OAQG;IACH,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;;;OAOG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,eAAO,MAAM,KAAK,EAAE,IAAI,EAgHvB,CAAC;AAGF,wBAAgB,MAAM,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAEvC;AAED,gFAAgF;AAChF,eAAO,MAAM,YAAY,EAAE,IAAsB,CAAC;AAElD,8EAA8E;AAC9E,wBAAgB,QAAQ,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAE3C;AAkGD;;;;;;;;;GASG;AACH,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,wBAAgB,SAAS,CACvB,MAAM,EAAE;IAAE,YAAY,EAAE,MAAM,CAAC;IAAC,aAAa,EAAE,MAAM,CAAA;CAAE,EACvD,OAAO,UAAO,GACb,SAAS,CAOX;AAED,oEAAoE;AACpE,eAAO,MAAM,YAAY,EAAE,SAA4D,CAAC;AAExF;;;;;;;GAOG;AACH,wBAAgB,WAAW,CACzB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,EACV,GAAG,GAAE,SAAwB,EAC7B,KAAK,SAAW,GACf,MAAM,EAAE,CAMV;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,MAAM,CACpB,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,IAAI,EACV,GAAG,GAAE,SAAwB,EAC7B,KAAK,SAAW;AAChB;;;;;;;;GAQG;AACH,OAAO,SAAI,GACV,MAAM,CAGR"}