@zakmandhro/bunti 0.1.4 → 0.2.0

package/dist/layout.d.ts

@@ -0,0 +1,194 @@
+/**
+ * Bunti Functional Layout & Drawing
+ * Strictly functional primitives for buffer manipulation and layout generation.
+ */
+import type { Rect } from './geometry';
+import type { Cell, RGB, ScreenState } from './state';
+import type { ThemeColor } from './theme';
+/**
+ * Writes one cell into the back buffer (bounds-checked). Wide glyphs mark
+ * their tail cells as skip so the differ keeps columns aligned.
+ */
+export declare function setCell(state: ScreenState, x: number, y: number, cell: Partial<Cell>): void;
+/**
+ * Repaints existing back-buffer cells inside `area` at reduced luminance.
+ * Each cell's current fg/bg is resolved to exact RGB (numeric ANSI-256 codes
+ * via the xterm table) and scaled toward black by `amount` (0 = unchanged,
+ * 1 = fully black). Cells with an undefined bg keep their transparent
+ * background (fg-only dim); undefined fg is left alone (there is no color to
+ * scale). Wide-glyph tail cells (skip) are dimmed too so they stay in sync
+ * with their head cell. No-op on the mono tier — there is no color to dim.
+ */
+export declare function dimRect(state: ScreenState, area: Rect, amount: number): void;
+import type { Gradient } from './colors';
+/** Fill style for rect(). */
+export interface RectOptions {
+    /** Fill glyph; omitted = pure background fill that keeps existing chars. */
+    char?: string;
+    /** Foreground color for the fill glyphs. */
+    fg?: string | number | RGB | ThemeColor;
+    /** Background color (Gradients resolve per-cell across the rect). */
+    bg?: string | number | RGB | Gradient | ThemeColor;
+}
+/**
+ * Fills a w×h cell rectangle at absolute coordinates — bars, panels,
+ * charts, backgrounds. Pure-background fills (no `char`) preserve the
+ * characters already painted underneath.
+ * @example rect(state, 0, 0, state.width, 3, { bg: 'midnight' });
+ */
+export declare function rect(state: ScreenState, x: number, y: number, w: number, h: number, style: RectOptions): void;
+/**
+ * Paints a multi-line, ANSI-styled string into the back buffer at absolute
+ * cell coordinates, parsing SGR codes into per-cell attributes. Grapheme-
+ * aware: emoji and wide glyphs occupy their real column width.
+ * @example blit(state, 2, 1, fg('gold', 'FPS 60'));
+ */
+export declare function blit(state: ScreenState, startX: number, startY: number, content: string, style?: Partial<Cell>): void;
+/**
+ * Border glyph sets. Wireframe: 'default' | 'rounded' | 'double' |
+ * 'dashed' | 'dotted'. Block: 'frame' | 'thick-frame'. ASCII: 'classic'.
+ * 'none' keeps the box purely structural.
+ */
+export type BorderStyle = 'default' | 'rounded' | 'double' | 'dashed' | 'dotted' | 'frame' | 'thick-frame' | 'classic' | 'none';
+/** Per-side border colors; missing sides inherit top (or left/right). */
+export interface SideColors {
+    top?: any;
+    bottom?: any;
+    left?: any;
+    right?: any;
+}
+/**
+ * A dimension: absolute cells (20), percent of parent ('50%'), or fill
+ * fraction ('1fr'). undefined/'auto' sizes to content.
+ */
+export type SizeUnit = number | string;
+/**
+ * Box styling shared by box()/table()/components.
+ */
+export interface StyleOptions {
+    /** Outer width: cells, '50%', '1fr', or 'auto' (content-sized). */
+    width?: SizeUnit;
+    /** Lower bound on the outer width in cells. */
+    minWidth?: number;
+    /** Upper bound on the outer width in cells. */
+    maxWidth?: number;
+    /** Outer height: rows, '50%', '1fr', or 'auto' (content-sized). */
+    height?: SizeUnit;
+    /** Lower bound on the outer height in rows. */
+    minHeight?: number;
+    /** Upper bound on the outer height in rows. */
+    maxHeight?: number;
+    /**
+     * [vertical, horizontal] padding INSIDE the border, in cells —
+     * [1, 2] = 1 blank row above/below, 2 blank columns left/right.
+     * Note the order: rows first (a 2:1 h:v ratio usually looks balanced
+     * because terminal cells are taller than wide).
+     */
+    padding?: [number, number];
+    /** Border glyph set (default 'none'). */
+    border?: BorderStyle;
+    /** Border color: color value, styler function, or per-side SideColors. */
+    borderColor?: string | number | RGB | ThemeColor | ((s: string) => string) | SideColors;
+    /** Background fill (Gradient backgrounds apply in direct/rect mode). */
+    bgColor?: string | number | RGB | Gradient | ThemeColor;
+    /** Horizontal content alignment (default 'left'). */
+    align?: 'left' | 'center' | 'right';
+    /** Vertical content alignment (default 'top'). */
+    valign?: 'top' | 'middle' | 'bottom';
+    /** Word-wraps content to the inner width instead of truncating. */
+    wrap?: boolean;
+    /** Title rendered into the top border. */
+    title?: string;
+    /** Styler applied to the rendered title. */
+    titleStyle?: (s: string) => string;
+}
+/**
+ * Resolves a SizeUnit to an absolute integer based on parent dimensions.
+ */
+export declare function resolveSize(unit: SizeUnit | undefined, parentDim: number, contentDim: number): number;
+/**
+ * Generates a styled box string with perfect alignment and optional
+ * wrapping. This is the pure string-building form; ctx.box() adds
+ * placement and painting on top of it.
+ * @example box('hello', { width: 20, border: 'rounded', padding: [0, 1] });
+ */
+export declare function box(content: string, options?: StyleOptions, parentW?: number, parentH?: number): string;
+/** Joins rendered blocks side-by-side, padding each to its own width. */
+export declare function joinHorizontal(...blocks: string[]): string;
+/** Stacks rendered blocks vertically (skips empty strings). */
+export declare function joinVertical(...blocks: string[]): string;
+/** Returns a box() partially applied with default StyleOptions. */
+export declare function createStyle(defaults: StyleOptions): (content: string, overrides?: StyleOptions) => string;
+/** Uppercased ` TEXT ` chip, wrapped by the given styler. */
+export declare function badge(text: string, colorFn?: (s: string) => string): string;
+/** Options for table() / ctx.table(). */
+export interface TableOptions {
+    /** Overall table width: cells, '50%', or '100%' (default 80 cells). */
+    width?: SizeUnit;
+    /** Per-column width/alignment overrides, by column index. */
+    columns?: {
+        width?: SizeUnit;
+        align?: 'left' | 'center' | 'right';
+    }[];
+    /** Outer border glyph set (default 'default'). */
+    border?: BorderStyle;
+    /** [vertical, horizontal] cell padding (default [0, 1]). */
+    padding?: [number, number];
+}
+/**
+ * Renders a data table with perfectly aligned columns and shared borders.
+ */
+export declare function table(rows: string[][], options?: TableOptions, parentW?: number): string;
+/**
+ * Computes the scroll window that keeps `selectedIndex` visible in
+ * `maxVisible` rows (used by list windowing).
+ */
+export declare function getWindow<T>(items: T[], selectedIndex: number, maxVisible: number): {
+    visible: T[];
+    start: number;
+    hasMoreAbove: boolean;
+    hasMoreBelow: boolean;
+};
+/** Options for list() / ctx.list(). */
+export interface ListOptions {
+    /** Prefix rendered before every item (e.g. '• '). */
+    bullet?: string;
+    /** Leading spaces before each row. */
+    indent?: number;
+    /** Row rendered as selected (ctx.list manages this from state). */
+    focusedIndex?: number;
+    /** Styler for the selected row's text (default theme.focus). */
+    focusStyle?: (s: string) => string;
+    /** Background wash behind the selected row (default theme.selection). */
+    selectedBg?: string | number | RGB | ThemeColor;
+    /** Mouse-hovered row (styled with hoverBg; selection wins over hover). */
+    hoveredIndex?: number;
+    /** Background wash for the hovered row. */
+    hoverBg?: string | number | RGB | ThemeColor;
+    /** Row width for background washes: cells, '50%', or '100%'. */
+    width?: SizeUnit;
+    /** Windows the list to N rows, scrolled to keep the selection visible. */
+    maxVisible?: number;
+    /** Set false to disable ctx.list's built-in keyboard/mouse handling. */
+    interactive?: boolean;
+}
+/**
+ * Renders items as list rows with selection/hover washes and optional
+ * maxVisible windowing. Pure string form; ctx.list() adds the keyboard
+ * and mouse behavior on top.
+ */
+export declare function list(items: string[], options?: ListOptions, parentW?: number): string;
+/**
+ * Crops a multi-line string to a width×height window starting at
+ * `scrollY` — the primitive for scrollable content.
+ */
+export declare function viewport(content: string, width: number, height: number, scrollY?: number): string;
+/** Fills the whole screen background with a solid color. */
+export declare function wallpaper(state: any, options: {
+    bg: any;
+}): void;
+/** Fills the whole screen background with a multi-stop gradient. */
+export declare function gradient(state: any, colors: any[], options?: {
+    direction?: 'vertical' | 'horizontal';
+}): void;
+//# sourceMappingURL=layout.d.ts.map

package/dist/layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"layout.d.ts","sourceRoot":"","sources":["../src/layout.ts"],"names":[],"mappings":"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"}