@flyingrobots/bijou-tui 7.0.0 → 7.2.0

package/dist/viewport.d.ts

@@ -1,214 +1,8 @@
-/**
- * Scrollable content viewport for TUI apps.
- *
- * Renders a visible window into content that may be larger than the
- * available screen space, with optional scrollbar indicator.
- */
-import { clipToWidth as coreClipToWidth, type Cell, type LayoutNode, type Surface } from '@flyingrobots/bijou';
-/** Scrollbar ownership model for the viewport edge. */
-export type ScrollbarMode = 'gutter' | 'overlay';
-/**
- * Configuration for rendering a scrollable viewport window.
- */
-export interface ViewportOptions {
-    /** Visible width in columns. Content lines longer than this are clipped. */
-    readonly width: number;
-    /** Visible height in rows. */
-    readonly height: number;
-    /** Full content string (may be taller/wider than the viewport). */
-    readonly content: string;
-    /** Vertical scroll offset (0-based line index). Default: 0. */
-    readonly scrollY?: number;
-    /** Horizontal scroll offset (0-based column index). Default: 0. */
-    readonly scrollX?: number;
-    /** Show a scrollbar track on the right edge. Default: true. */
-    readonly showScrollbar?: boolean;
-    /** Reserve a gutter column or overlay the rightmost content cell. Default: `'gutter'`. */
-    readonly scrollbarMode?: ScrollbarMode;
-    /** Character used for the scrollbar track in string rendering. Default: `'│'`. */
-    readonly scrollbarTrackChar?: string;
-    /** Character used for the scrollbar thumb in string rendering. Default: `'█'`. */
-    readonly scrollbarThumbChar?: string;
-}
-/**
- * Configuration for rendering a viewport directly into a Surface.
- */
-export interface ViewportSurfaceOptions extends Omit<ViewportOptions, 'content'> {
-    /** Full content payload, either plain/ANSI text, a pre-rendered surface, or a layout tree. */
-    readonly content: ViewportContent;
-    /** Cell used for the scrollbar track in surface rendering. */
-    readonly scrollbarTrackCell?: Cell;
-    /** Cell used for the scrollbar thumb in surface rendering. */
-    readonly scrollbarThumbCell?: Cell;
-}
-/** Content payload that can be masked by a viewport. */
-export type ViewportContent = string | Surface | LayoutNode;
-/**
- * Immutable snapshot of scroll position and bounds for a viewport.
- */
-export interface ScrollState {
-    /** Current vertical scroll offset. */
-    readonly y: number;
-    /** Maximum vertical scroll offset. */
-    readonly maxY: number;
-    /** Current horizontal scroll offset. */
-    readonly x: number;
-    /** Maximum horizontal scroll offset. */
-    readonly maxX: number;
-    /** Total number of content lines. */
-    readonly totalLines: number;
-    /** Number of visible lines (viewport height). */
-    readonly visibleLines: number;
-}
-/**
- * Strip all SGR ANSI escape sequences from a string.
- *
- * @param str - Input string possibly containing ANSI escapes.
- * @returns Plain text with all ANSI color/style sequences removed.
- */
-export declare function stripAnsi(str: string): string;
-/**
- * Compute the terminal display width of a string.
- *
- * Grapheme-cluster aware: handles emoji, CJK (2 columns), ZWJ sequences,
- * skin tones, flag pairs, and combining marks correctly.
- *
- * @param str - Input string (may contain ANSI escapes).
- * @returns Display width in terminal columns.
- */
-export declare function visibleLength(str: string): number;
-/**
- * Clip a string to a maximum visible width, preserving ANSI escapes.
- * Grapheme-cluster aware: won't split multi-codepoint sequences.
- * Appends a reset sequence if the string was clipped mid-style.
- *
- * Re-exported from `@flyingrobots/bijou` core for backward compatibility.
- *
- * @param str - Input string (may contain ANSI escapes).
- * @param maxWidth - Maximum visible width in terminal columns.
- * @returns Clipped string, at most `maxWidth` columns wide.
- */
-export declare const clipToWidth: typeof coreClipToWidth;
-/**
- * Extract a visible-column substring from an ANSI-styled string.
- * Return characters between visible columns [startCol, endCol).
- * Grapheme-cluster aware. Preserve any active ANSI styles seen before startCol.
- *
- * O(n): pre-segment stripped text once, then walk the original string
- * with a grapheme pointer instead of re-segmenting per character.
- *
- * @param str - ANSI-styled input string.
- * @param startCol - Start visible column (inclusive, 0-based).
- * @param endCol - End visible column (exclusive).
- * @returns Substring spanning the requested visible columns with ANSI styles preserved.
- */
-export declare function sliceAnsi(str: string, startCol: number, endCol: number): string;
-/**
- * Extract all individual visible character cells from an ANSI-styled string.
- * Each cell is returned as a fully-styled string (including resets).
- *
- * @param str - ANSI-styled input string.
- * @param width - Number of cells to extract (pads with spaces if shorter).
- * @returns Array of exactly `width` strings, each a single-column styled character.
- */
-export declare function tokenizeAnsi(str: string, width: number): string[];
-/**
- * Render a scrollable viewport into content.
- *
- * Return a string with exactly `height` lines, each at most `width`
- * visible columns wide (including optional scrollbar when enabled).
- *
- * @param options - Viewport configuration including dimensions, content, and scroll offsets.
- * @returns Rendered viewport string with lines joined by newlines.
- */
-export declare function viewport(options: ViewportOptions): string;
-/**
- * Render a scrollable viewport directly into a Surface.
- *
- * This is the canonical viewport primitive for rich TUI composition. It acts
- * like a mask over text, an existing `Surface`, or a `LayoutNode` tree and
- * reveals only the visible scroll window. String content still routes through
- * {@link viewport} so the explicit text helper stays consistent.
- *
- * @param options - Viewport configuration including dimensions, content, and scroll offsets.
- * @returns Surface sized exactly to the requested viewport rectangle.
- */
-export declare function viewportSurface(options: ViewportSurfaceOptions): Surface;
-/**
- * Create initial scroll state for any viewport-maskable content.
- *
- * Use this when the viewport is wrapping an existing `Surface` or `LayoutNode`
- * instead of plain text. String content can still use `createScrollState()`,
- * but this helper accepts all viewport content types.
- */
-export declare function createScrollStateForContent(content: ViewportContent, viewportHeight: number, viewportWidth?: number): ScrollState;
-/**
- * Create initial scroll state for content within a viewport.
- *
- * @param content - Full content string (newline-delimited).
- * @param viewportHeight - Visible height in rows.
- * @param viewportWidth - Visible width in columns (used to compute maxX).
- * @returns Initial scroll state positioned at top-left (y=0, x=0).
- */
-export declare function createScrollState(content: string, viewportHeight: number, viewportWidth?: number): ScrollState;
-/**
- * Scroll vertically by a relative amount, clamping to valid range.
- *
- * @param state - Current scroll state.
- * @param dy - Relative vertical offset (positive = down, negative = up).
- * @returns New scroll state with updated y position.
- */
-export declare function scrollBy(state: ScrollState, dy: number): ScrollState;
-/**
- * Scroll vertically to an absolute position, clamping to valid range.
- *
- * @param state - Current scroll state.
- * @param y - Absolute vertical offset (0-based line index).
- * @returns New scroll state with updated y position.
- */
-export declare function scrollTo(state: ScrollState, y: number): ScrollState;
-/**
- * Scroll horizontally by a relative amount, clamping to valid range.
- *
- * @param state - Current scroll state.
- * @param dx - Relative horizontal offset (positive = right, negative = left).
- * @returns New scroll state with updated x position.
- */
-export declare function scrollByX(state: ScrollState, dx: number): ScrollState;
-/**
- * Scroll horizontally to an absolute position, clamping to valid range.
- *
- * @param state - Current scroll state.
- * @param x - Absolute horizontal offset (0-based column index).
- * @returns New scroll state with updated x position.
- */
-export declare function scrollToX(state: ScrollState, x: number): ScrollState;
-/**
- * Scroll to the top (y = 0).
- *
- * @param state - Current scroll state.
- * @returns New scroll state positioned at the top.
- */
-export declare function scrollToTop(state: ScrollState): ScrollState;
-/**
- * Scroll to the bottom (y = maxY).
- *
- * @param state - Current scroll state.
- * @returns New scroll state positioned at the bottom.
- */
-export declare function scrollToBottom(state: ScrollState): ScrollState;
-/**
- * Page down (scroll by one viewport height).
- *
- * @param state - Current scroll state.
- * @returns New scroll state scrolled down by `visibleLines` rows.
- */
-export declare function pageDown(state: ScrollState): ScrollState;
-/**
- * Page up (scroll by one viewport height).
- *
- * @param state - Current scroll state.
- * @returns New scroll state scrolled up by `visibleLines` rows.
- */
-export declare function pageUp(state: ScrollState): ScrollState;
+export { clipToWidth, stripAnsi, visibleLength } from './viewport.part01.js';
+export type { ScrollState, ScrollbarMode, ViewportContent, ViewportOptions, ViewportSurfaceOptions } from './viewport.part01.js';
+export { sliceAnsi } from './viewport.part02.js';
+export { tokenizeAnsi } from './viewport.part03.js';
+export { viewport } from './viewport.part04.js';
+export { createScrollStateForContent, viewportSurface } from './viewport.part05.js';
+export { createScrollState, pageDown, pageUp, scrollBy, scrollByX, scrollTo, scrollToBottom, scrollToTop, scrollToX } from './viewport.part06.js';
 //# sourceMappingURL=viewport.d.ts.map

package/dist/viewport.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../src/viewport.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"viewport.d.ts","sourceRoot":"","sources":["../src/viewport.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC;AAC7E,YAAY,EAAE,WAAW,EAAE,aAAa,EAAE,eAAe,EAAE,eAAe,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AACjI,OAAO,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC;AACjD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AAChD,OAAO,EAAE,2BAA2B,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC;AACpF,OAAO,EAAE,iBAAiB,EAAE,QAAQ,EAAE,MAAM,EAAE,QAAQ,EAAE,SAAS,EAAE,QAAQ,EAAE,cAAc,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,sBAAsB,CAAC"}