@textui/widgets 0.7.0 → 0.8.0

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"}