@flyingrobots/bijou-tui 7.0.0 → 7.2.0

package/dist/overlay.d.ts

@@ -1,233 +1,9 @@
-/**
- * Overlay compositing primitives for TUI apps.
- *
- * - `composite()` — paint overlays onto a background string (ANSI-safe)
- * - `compositeSurface()` — paint overlays onto a background surface
- * - `modal()` — centered dialog overlay with title, body, hint
- * - `toast()` — anchored notification overlay with variant icons
- * - `tooltip()` — positioned overlay relative to a target element
- */
-import type { BijouContext, Surface, TokenValue } from '@flyingrobots/bijou';
-import type { LayoutRect } from './layout-rect.js';
-/**
- * Positioned content block that can be composited onto a background.
- */
-export interface Overlay {
-    /** Rendered content string (newline-delimited lines). */
-    readonly content: string;
-    /** Optional cell-accurate overlay surface used by surface-first render paths. */
-    readonly surface?: Surface;
-    /** Top-left row position (0-based). */
-    readonly row: number;
-    /** Top-left column position (0-based). */
-    readonly col: number;
-}
-/**
- * Options for the {@link composite} function.
- */
-export interface CompositeOptions {
-    /** Wrap background lines in dim (ANSI 2m). */
-    readonly dim?: boolean;
-}
-/** Structured overlay content accepted by the surface-native overlay family. */
-export type OverlayContent = string | Surface;
-/**
- * Configuration for the {@link modal} overlay.
- */
-export interface ModalOptions {
-    /** Optional title displayed at the top of the modal (bolded when ctx provided). */
-    readonly title?: string;
-    /** Body content of the modal. Accepts plain text or a structured surface. */
-    readonly body: OverlayContent;
-    /** Optional hint content displayed below the body (muted when ctx provided). */
-    readonly hint?: OverlayContent;
-    /** Screen width in columns, used for centering. */
-    readonly screenWidth: number;
-    /** Screen height in rows, used for centering. */
-    readonly screenHeight: number;
-    /** Preferred minimum width — shorter lines are padded but longer lines are not truncated (default: auto from content). */
-    readonly width?: number;
-    /** Preferred edge inset from the viewport when the dialog is centered. */
-    readonly margin?: number;
-    /** Design token for the border color. */
-    readonly borderToken?: TokenValue;
-    /** Background fill token for the overlay interior. */
-    readonly bgToken?: TokenValue;
-    /** Bijou context for styled output. */
-    readonly ctx?: BijouContext;
-}
-/** Visual variant controlling the toast icon and border color. */
-export type ToastVariant = 'success' | 'error' | 'info';
-/** Screen corner where the toast is anchored. */
-export type ToastAnchor = 'top-right' | 'bottom-right' | 'bottom-left' | 'top-left';
-/**
- * Configuration for the {@link toast} overlay.
- */
-export interface ToastOptions {
-    /** Message text displayed beside the variant icon. */
-    readonly message: string;
-    /** Visual variant controlling icon and border color. Default: 'info'. */
-    readonly variant?: ToastVariant;
-    /** Screen corner to anchor the toast. Default: 'bottom-right'. */
-    readonly anchor?: ToastAnchor;
-    /** Screen width in columns, used for positioning. */
-    readonly screenWidth: number;
-    /** Screen height in rows, used for positioning. */
-    readonly screenHeight: number;
-    /** Rows/cols from edge. Default: 1. */
-    readonly margin?: number;
-    /** Background fill token for the toast interior. */
-    readonly bgToken?: TokenValue;
-    /** Bijou context for styled output. */
-    readonly ctx?: BijouContext;
-}
-/**
- * Paint one or more overlays onto a background string.
- *
- * Overlay content replaces background characters at the specified position.
- * Overlays are applied in array order (later overlays paint over earlier ones).
- * ANSI escape sequences are preserved correctly at splice boundaries.
- *
- * @param background - Background content string (newline-delimited).
- * @param overlays - Positioned overlays to composite onto the background.
- * @param options - Optional compositing settings (e.g., dim background).
- * @returns Composited string with all overlays applied.
- */
-export declare function composite(background: string, overlays: readonly Overlay[], options?: CompositeOptions): string;
-/**
- * Paint one or more overlays onto a background surface.
- *
- * Overlays are applied in array order, with later overlays painting over
- * earlier ones. String-only overlays are normalized through an explicit
- * ANSI-to-surface bridge at the composition edge.
- */
-export declare function compositeSurface(background: Surface, overlays: readonly Overlay[], options?: CompositeOptions): Surface;
-/**
- * Paint overlays onto an existing target surface, optionally starting from an
- * existing background surface.
- *
- * When `background` and `target` are the same object, the surface is
- * composited in place without an extra clone.
- */
-export declare function compositeSurfaceInto(background: Surface, target: Surface, overlays: readonly Overlay[], options?: CompositeOptions): Surface;
-/**
- * Create a centered modal dialog overlay.
- *
- * Build a bordered box with optional title, body, and hint text,
- * then center it on screen.
- *
- * @param options - Modal configuration including content and screen dimensions.
- * @returns Overlay positioned at the center of the screen.
- */
-export declare function modal(options: ModalOptions): Overlay;
-/**
- * Create an anchored toast notification overlay.
- *
- * Render a bordered box with a variant icon and message, positioned
- * at the specified screen corner with configurable margin.
- *
- * @param options - Toast configuration including message, variant, and screen dimensions.
- * @returns Overlay positioned at the specified screen corner.
- */
-export declare function toast(options: ToastOptions): Overlay;
-/** Side of the screen (or region) where the drawer is anchored. */
-export type DrawerAnchor = 'left' | 'right' | 'top' | 'bottom';
-/**
- * Configuration for the {@link drawer} overlay.
- */
-interface DrawerBaseOptions {
-    /** Content to display inside the drawer. Accepts plain text or a structured surface. */
-    readonly content: OverlayContent;
-    /** Screen width in columns, used for positioning. */
-    readonly screenWidth: number;
-    /** Screen height in rows, used for sizing. */
-    readonly screenHeight: number;
-    /** Optional region rectangle to attach inside, instead of full screen. */
-    readonly region?: LayoutRect;
-    /** Optional title displayed in the top border. */
-    readonly title?: string;
-    /** Design token for the border color. */
-    readonly borderToken?: TokenValue;
-    /** Background fill token for the drawer interior. */
-    readonly bgToken?: TokenValue;
-    /** Bijou context for styled output. */
-    readonly ctx?: BijouContext;
-}
-/** Drawer options with default (right) anchor and required width. */
-interface DrawerDefaultOptions extends DrawerBaseOptions {
-    /** Side of the screen/region to anchor the drawer. Default: 'right'. */
-    readonly anchor?: undefined;
-    /** Total drawer width including borders and padding. */
-    readonly width: number;
-    readonly height?: never;
-}
-/** Drawer options for left/right anchor with required width. */
-interface DrawerHorizontalOptions extends DrawerBaseOptions {
-    /** Side of the screen/region to anchor the drawer. */
-    readonly anchor: 'left' | 'right';
-    /** Total drawer width including borders and padding. */
-    readonly width: number;
-    readonly height?: never;
-}
-/** Drawer options for top/bottom anchor with required height. */
-interface DrawerVerticalOptions extends DrawerBaseOptions {
-    /** Side of the screen/region to anchor the drawer. */
-    readonly anchor: 'top' | 'bottom';
-    /** Total drawer height including borders and padding. */
-    readonly height: number;
-    readonly width?: never;
-}
-/** Union of all drawer anchor variants (default/right, left/right, top/bottom). */
-export type DrawerOptions = DrawerDefaultOptions | DrawerHorizontalOptions | DrawerVerticalOptions;
-/**
- * Create a drawer overlay anchored to a screen edge.
- *
- * Supports horizontal anchors (`left`/`right`) that span the full screen height,
- * and vertical anchors (`top`/`bottom`) that span the full screen width.
- * Defaults to the right edge when no anchor is specified.
- * Renders a bordered panel with optional title in the top border.
- *
- * When an optional `region` is provided, the drawer is constrained to that
- * sub-region rectangle instead of spanning the full screen dimensions.
- *
- * @param options - Drawer configuration including content, anchor, and dimensions.
- * @returns Overlay positioned at the specified screen edge.
- */
-export declare function drawer(options: DrawerOptions): Overlay;
-/** Direction to place the tooltip relative to its target element. */
-export type TooltipDirection = 'top' | 'bottom' | 'left' | 'right';
-/**
- * Configuration for the {@link tooltip} overlay.
- */
-export interface TooltipOptions {
-    /** Content to display inside the tooltip. Accepts plain text or a structured surface. */
-    readonly content: OverlayContent;
-    /** Row of the target element (0-based). */
-    readonly row: number;
-    /** Column of the target element (0-based). */
-    readonly col: number;
-    /** Direction to place the tooltip relative to the target. Default: 'top'. */
-    readonly direction?: TooltipDirection;
-    /** Screen width in columns, used for clamping. */
-    readonly screenWidth: number;
-    /** Screen height in rows, used for clamping. */
-    readonly screenHeight: number;
-    /** Design token for the border color. */
-    readonly borderToken?: TokenValue;
-    /** Background fill token for the tooltip interior. */
-    readonly bgToken?: TokenValue;
-    /** Bijou context for styled output. */
-    readonly ctx?: BijouContext;
-}
-/**
- * Create a tooltip overlay positioned relative to a target element.
- *
- * Render a bordered box containing the content, placed in the specified
- * direction from the target. Clamp to screen bounds to prevent overflow.
- *
- * @param options - Tooltip configuration including content, target position, and direction.
- * @returns Overlay positioned relative to the target, clamped to screen bounds.
- */
-export declare function tooltip(options: TooltipOptions): Overlay;
-export {};
+export type { CompositeOptions, ModalOptions, Overlay, OverlayContent, ToastAnchor, ToastOptions, ToastVariant } from './overlay.part01.js';
+export { composite, compositeSurface, compositeSurfaceInto } from './overlay.part02.js';
+export { modal } from './overlay.part05.js';
+export { toast } from './overlay.part06.js';
+export type { DrawerAnchor, DrawerOptions } from './overlay.part06.js';
+export { drawer } from './overlay.part07.js';
+export type { TooltipDirection, TooltipOptions } from './overlay.part08.js';
+export { tooltip } from './overlay.part09.js';
 //# sourceMappingURL=overlay.d.ts.map

package/dist/overlay.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"overlay.d.ts","sourceRoot":"","sources":["../src/overlay.ts"],"names":[],"mappings":"AAAA,YAAY,EAAE,gBAAgB,EAAE,YAAY,EAAE,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC5I,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,oBAAoB,EAAE,MAAM,qBAAqB,CAAC;AACxF,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,OAAO,EAAE,KAAK,EAAE,MAAM,qBAAqB,CAAC;AAC5C,YAAY,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAC;AAC7C,YAAY,EAAE,gBAAgB,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAC;AAC5E,OAAO,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAC"}