ansimax 1.4.0 → 1.4.2

package/dist/index.d.ts

@@ -1,3 +1,76 @@
+/** Visual theme for rendered output. */
+type MarkdownTheme = 'dark' | 'light';
+interface MarkdownOptions {
+    /**
+     * Maximum width in columns. Long lines wrap. Default: terminal width
+     * or 80 if unavailable.
+     */
+    width?: number;
+    /**
+     * Color theme. `'dark'` (default) uses bright colors for dark backgrounds.
+     * `'light'` uses dimmer/contrast colors for light backgrounds.
+     */
+    theme?: MarkdownTheme;
+    /**
+     * Override the gradient used for top-level (`# H1`) headings. Receives
+     * a list of hex colors. Default uses the dracula palette.
+     */
+    headingGradient?: string[];
+    /**
+     * Render code blocks inside an ASCII box. Default `true`. If `false`,
+     * code blocks render as indented dim text.
+     */
+    boxCodeBlocks?: boolean;
+    /**
+     * Inline code background tint. Default `true`. If `false`, inline code
+     * shows only as dim text (cleaner in some terminals).
+     */
+    inlineCodeBackground?: boolean;
+}
+/**
+ * Internal options shape passed to `parseInline`. Exposed for advanced
+ * use cases that bypass `render` (custom block handlers, etc.).
+ *
+ * @since 1.4.0
+ */
+interface InlineOptions {
+    theme: MarkdownTheme;
+    inlineCodeBackground: boolean;
+}
+/**
+ * Block-level token after parsing the markdown into structural pieces.
+ * Tokens contain raw inline text — inline parsing happens at render time.
+ *
+ * @since 1.4.0
+ */
+type Block = {
+    type: 'heading';
+    level: number;
+    text: string;
+} | {
+    type: 'paragraph';
+    text: string;
+} | {
+    type: 'codeblock';
+    lang: string;
+    code: string;
+} | {
+    type: 'list';
+    ordered: boolean;
+    items: string[];
+} | {
+    type: 'blockquote';
+    text: string;
+} | {
+    type: 'table';
+    headers: string[];
+    rows: string[][];
+} | {
+    type: 'hr';
+} | {
+    type: 'blank';
+};
+
 /** Color rendering capability. 'none' suppresses all color output. */
 type ColorMode = 'none' | 'basic' | '256' | 'truecolor' | 'auto';
 /** Animation pacing multiplier preset. */
@@ -204,6 +277,60 @@ declare const clampPercent: (p: unknown) => number;
  * @since 1.3.7
  */
 declare const clampInt: (value: unknown, min: number, max: number, fallback?: number) => number;
+/**
+ * Coerce any value to a string. Non-strings go through `String()`. `null`
+ * and `undefined` become `''` (not `'null'`/`'undefined'`). Consolidates
+ * the `typeof v === 'string' ? v : String(v ?? '')` pattern previously
+ * duplicated across 5 modules (components, frames, loaders, trees, ansi).
+ *
+ * @example
+ * ```ts
+ * ensureString('hello')      // → 'hello'
+ * ensureString(42)           // → '42'
+ * ensureString(null)         // → ''
+ * ensureString(undefined)    // → ''
+ * ensureString({})           // → '[object Object]'
+ * ```
+ *
+ * @since 1.4.2
+ */
+declare const ensureString: (v: unknown) => string;
+/**
+ * Coerce to a non-negative integer (≥ 0). Falls back to `fallback` for
+ * non-finite input. Floors fractional values.
+ *
+ * Consolidates the `Math.max(0, Math.floor(n))` pattern previously
+ * duplicated as a private `clampNonNeg` in components + trees.
+ *
+ * @example
+ * ```ts
+ * clampNonNeg(5.7)            // → 5
+ * clampNonNeg(-3)             // → 0
+ * clampNonNeg(NaN, 10)        // → 10
+ * clampNonNeg('abc', 5)       // → 5
+ * ```
+ *
+ * @since 1.4.2
+ */
+declare const clampNonNeg: (n: unknown, fallback?: number) => number;
+/**
+ * Coerce to a positive integer (≥ 1). Falls back to `fallback` for
+ * non-finite input. Floors fractional values.
+ *
+ * Consolidates the `Math.max(1, Math.floor(n))` pattern previously
+ * duplicated as private `clampPositive` / `clampPositiveInt` in
+ * components + loaders.
+ *
+ * @example
+ * ```ts
+ * clampPositiveInt(5.7)       // → 5
+ * clampPositiveInt(0)         // → 1 (clamped up)
+ * clampPositiveInt(NaN, 10)   // → 10
+ * ```
+ *
+ * @since 1.4.2
+ */
+declare const clampPositiveInt: (n: unknown, fallback?: number) => number;
 /** Returns true when a string is a valid 3- or 6-digit hex color. */
 declare const isHexColor: (hex: string) => boolean;
 /**
@@ -2713,6 +2840,46 @@ interface GridOptions {
      * use the max width of the widest block in their column.
      */
     cellWidth?: number | null;
+    /**
+     * **v1.4.1+** Fix each row to this height (in lines). When the block has
+     * fewer lines, it is padded (using `alignY`). When it has more lines, it
+     * is truncated. If omitted (default), rows take the natural height of
+     * their tallest block.
+     *
+     * @since 1.4.1
+     */
+    cellHeight?: number | null;
+    /**
+     * **v1.4.1+** Per-block column span. `colSpan[i]` is the number of
+     * columns block `i` occupies. Defaults to `1` for every block when
+     * omitted or shorter than `blocks`.
+     *
+     * The auto-flow algorithm wraps to the next row when the current row's
+     * remaining capacity is less than the next block's span. Spans that
+     * exceed `columns` are clamped to `columns`.
+     *
+     * @example
+     * ```js
+     * // Header spans full width, then 2 cells in a row
+     * panels.grid([header, left, right], {
+     *   columns: 2,
+     *   colSpan: [2, 1, 1],
+     * });
+     * ```
+     *
+     * @since 1.4.1
+     */
+    colSpan?: number[];
+    /**
+     * **v1.4.1+** Auto-flow direction. `'row'` (default) fills cells
+     * left-to-right then wraps to the next row — matches CSS Grid's
+     * `grid-auto-flow: row`. `'column'` fills top-to-bottom then wraps to
+     * the next column. Not applicable when `colSpan` is set with any
+     * span > 1 (forces 'row' mode).
+     *
+     * @since 1.4.1
+     */
+    flow?: 'row' | 'column';
 }
 /**
  * Arrange blocks in a grid of N columns, flowing left-to-right then
@@ -2887,63 +3054,6 @@ declare const json: {
     pretty: (value: unknown, opts?: PrettyOptions) => string;
 };
 
-/** Visual theme for rendered output. */
-type MarkdownTheme = 'dark' | 'light';
-interface MarkdownOptions {
-    /**
-     * Maximum width in columns. Long lines wrap. Default: terminal width
-     * or 80 if unavailable.
-     */
-    width?: number;
-    /**
-     * Color theme. `'dark'` (default) uses bright colors for dark backgrounds.
-     * `'light'` uses dimmer/contrast colors for light backgrounds.
-     */
-    theme?: MarkdownTheme;
-    /**
-     * Override the gradient used for top-level (`# H1`) headings. Receives
-     * a list of hex colors. Default uses the dracula palette.
-     */
-    headingGradient?: string[];
-    /**
-     * Render code blocks inside an ASCII box. Default `true`. If `false`,
-     * code blocks render as indented dim text.
-     */
-    boxCodeBlocks?: boolean;
-    /**
-     * Inline code background tint. Default `true`. If `false`, inline code
-     * shows only as dim text (cleaner in some terminals).
-     */
-    inlineCodeBackground?: boolean;
-}
-/** Block-level token after parsing the markdown into structural pieces. */
-type Block = {
-    type: 'heading';
-    level: number;
-    text: string;
-} | {
-    type: 'paragraph';
-    text: string;
-} | {
-    type: 'codeblock';
-    lang: string;
-    code: string;
-} | {
-    type: 'list';
-    ordered: boolean;
-    items: string[];
-} | {
-    type: 'blockquote';
-    text: string;
-} | {
-    type: 'table';
-    headers: string[];
-    rows: string[][];
-} | {
-    type: 'hr';
-} | {
-    type: 'blank';
-};
 /**
  * Parse markdown source into a flat sequence of block tokens.
  * Tokens contain raw inline text — inline parsing happens at render time.
@@ -2951,15 +3061,14 @@ type Block = {
  * @since 1.4.0
  */
 declare const parseBlocks: (source: string) => Block[];
+
 /**
  * Apply inline markdown markup (bold/italic/code/links/etc.) to a string.
  *
  * @since 1.4.0
  */
-declare const parseInline: (text: string, opts?: {
-    theme: MarkdownTheme;
-    inlineCodeBackground: boolean;
-}) => string;
+declare const parseInline: (text: string, opts?: InlineOptions) => string;
+
 /**
  * Render a markdown source string to a terminal-ready string with ANSI
  * styling. Handles headings, paragraphs, code blocks, lists, blockquotes,
@@ -2988,6 +3097,7 @@ declare const parseInline: (text: string, opts?: {
  * @since 1.4.0
  */
 declare const render: (source: string, opts?: MarkdownOptions) => string;
+
 /**
  * Markdown → terminal renderer. Use `markdown.render(source, opts?)` to
  * convert a markdown string to an ANSI-styled string ready for
@@ -3001,10 +3111,7 @@ declare const render: (source: string, opts?: MarkdownOptions) => string;
 declare const markdown: {
     render: (source: string, opts?: MarkdownOptions) => string;
     parseBlocks: (source: string) => Block[];
-    parseInline: (text: string, opts?: {
-        theme: MarkdownTheme;
-        inlineCodeBackground: boolean;
-    }) => string;
+    parseInline: (text: string, opts?: InlineOptions) => string;
 };
 
 type EasingFunction = (t: number) => number;
@@ -3220,38 +3327,9 @@ declare const ansimax: {
     };
     markdown: {
         render: (source: string, opts?: MarkdownOptions) => string;
-        parseBlocks: (source: string) => ({
-            type: "heading";
-            level: number;
-            text: string;
-        } | {
-            type: "paragraph";
-            text: string;
-        } | {
-            type: "codeblock";
-            lang: string;
-            code: string;
-        } | {
-            type: "list";
-            ordered: boolean;
-            items: string[];
-        } | {
-            type: "blockquote";
-            text: string;
-        } | {
-            type: "table";
-            headers: string[];
-            rows: string[][];
-        } | {
-            type: "hr";
-        } | {
-            type: "blank";
-        })[];
-        parseInline: (text: string, opts?: {
-            theme: MarkdownTheme;
-            inlineCodeBackground: boolean;
-        }) => string;
+        parseBlocks: (source: string) => Block[];
+        parseInline: (text: string, opts?: InlineOptions) => string;
     };
 };
 
-export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSpace, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingFunction, type EasingLibraryName, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type GridOptions, type HSL, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MarkdownOptions, type MarkdownTheme, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type Oklab, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clampByte, clampInt, clampPercent, clearAnsiCache, clearColorCache, clearLine, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, easings, escapeForRegex, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, gradientStops, graphemes, grid, hasFont, hexToRgb, hideCursor, hslToRgb, hsplit, hyperlink, images, isFiniteNumber, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, markdown, measureBlock, measureTree, memoize, mixColors, nextTick, oklabToRgb, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, parseBlocks as parseMarkdownBlocks, parseInline as parseMarkdownInline, pauseListeners, presetNames, presets, quantizeColor, rainbow, registerFont, registerPreset, render as renderMarkdown, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resolveEasingByName, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rgbToHsl, rgbToOklab, rotate90, safeInt, safeJson, screen, setConfigValue, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$2 as stripAnsi, stripAnsi$1 as stripAnsiCodes, stripAnsi as stripAnsiColors, subscribeConfig, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };
+export { ASCII_RAMPS, type Alignment, type AnimateGradientController, type AnimateGradientOptions, type AnimationHooks, type AnimationSpeed, type AnsiCode, type AnsimaxConfig, type AsciiRamp, BEL, BG, type BadgeOptions, type BallOptions, type BannerOptions, type BoxOptions, type BoxStyle, type BreatheOptions, DEFAULTS as CONFIG_DEFAULTS, CSI, type Canvas, type CanvasRenderOptions, type CenterOptions, type ColorChain, type ColorFn, type ColorLevel, type ColorMode, type ColorSpace, type ColorSupport, type ColumnsOptions, type ConfigChangeListener, type ConfigKey, type ConfigKeyListener, type ConfigureOptions, type CountdownOptions, type CustomOptions, DEFAULT_TERM_COLS, DEFAULT_TERM_ROWS, type DebounceOptions, type DiffType, type Dimensions, type DividerOptions, type DotsOptions, ESC, type EasingFn, type EasingFunction, type EasingLibraryName, type EasingName, type EraseMode, FG, FRAME_MS, type FadeOptions, type FigletFont, type FigletOptions, type FontMap, type FontName, type FrameCallback, type FrameHandle, type FrameOptions, type FromImageOptions, type GlitchOptions, type Glyph, type GradientOptions, type GradientRectOptions, type GridOptions, type HSL, type HsplitOptions, type PrettyOptions as JsonPrettyOptions, type LineDiff, type LiveController, type LiveOptions, type LoadingBarOptions, type LogoOptions, MENU_CANCELLED, type MarkdownOptions, type MarkdownTheme, type MemoizeOptions, type MenuInput, type MenuOptions, type MenuOutput, type MenuResult, type MultiLoader, type MultiLoaderItem, OSC, type Oklab, type OnResizeOptions, type OutputBuffer, type ParallelOptions, type ParallelStep, type Pixel, type PixelGrid, type PlayController, type PlayOptions, type PresetName, type ProgressAnimateOptions, type ProgressBarOptions, type ProgressOptions, type PulseOptions, type RGB, type RGBA, type RegisterFontOptions, type RenderOptions$1 as RenderOptions, type ResizeListener, type ReusableGradient, type RevealOptions, SPINNERS, SPRITES, ST, STYLE, type SectionOptions, type SleepOptions, type SlideOptions, type SpinOptions, type SpinnerType, type StatusOptions, type StatusType, type StopFn, type StreamOptions, type TableBorderStyle, type TableOptions, type Task, type TaskResult, type TasksOptions, type Theme, type BannerOpts as ThemeBannerOpts, type ThemeChangeListener, type ThemeInstance, type ThemeStyleName, type TimelineEvent, type TimelineOptions, type TreeData, type TreeDimensions, type TreeNode, type RenderOptions as TreeRenderOptions, type TreeStyle, type TypeDeleteOptions, type TypewriterOptions, type VsplitOptions, type WalkVisitor, type WaveOptions, type WriteAsyncOptions, animate, animateGradient, ascii, bell, bg256, bgRgb, box, canAnimate, cancelTerminalFrame, center$1 as center, center as centerBlock, chain, charWidth, clamp, clampByte, clampInt, clampNonNeg, clampPercent, clampPositiveInt, clearAnsiCache, clearColorCache, clearLine, clearRenderCache, clearThemeColorCache, color, colorLevel, presets as colorPresets, components, compose, configure, countNodes, createCanvas, createGradient, createOutputBuffer, createTheme, cursor, debounce, ansimax as default, diffLines, easings, ensureString, escapeForRegex, escapeRegex, fg256, fgRgb, figletText, filterTree, findInTree, flipHorizontal, flipVertical, frame, frames, fromImage, getConfig, getConfigValue, getRenderCacheSize, getSpeedMultiplier, getTerminalHeight, getTerminalWidth, gradient, gradientColor, gradientRect, gradientStops, graphemes, grid, hasFont, hexToRgb, hideCursor, hslToRgb, hsplit, hyperlink, images, isFiniteNumber, isHexColor, isNoColor, json, pretty as jsonPretty, lerp, lerpColor, link, listFonts, listPresets, loader, mapTree, markdown, measureBlock, measureTree, memoize, mixColors, nextTick, oklabToRgb, onConfigChange, onConfigKeyChange, onResize, once, padBoth, padEnd, padStart, panels, parseFiglet, parseBlocks as parseMarkdownBlocks, parseInline as parseMarkdownInline, pauseListeners, presetNames, presets, quantizeColor, rainbow, registerFont, registerPreset, render as renderMarkdown, renderPixelArt, renderTree, renderTreeStream, repeatVisible, requestTerminalFrame, reset, resetColorSupportCache, resetConfig, resetCursorRefCount, resetFramesCursorCount, resetLoaderCursorCount, resetNoColor, resolveEasingByName, resumeListeners, reverseGradient, rgbTo256, rgbToHex, rgbToHsl, rgbToOklab, rotate90, safeInt, safeJson, screen, setConfigValue, setNoColor, setTitle, sgr, showCursor, sleep, sleepFrame, sliceAnsi, stripAnsi$2 as stripAnsi, stripAnsi$1 as stripAnsiCodes, stripAnsi as stripAnsiColors, subscribeConfig, supportsColor, supportsColorLevel, termSize, themes, throttle, tree, trees, truncateAnsi, visibleLen, vsplit, walkTree, withConfig, wordWrap, wrapAnsi, write, writeAsync, writeErr, writeln, writelnErr };