@boba-cli/chapstick 0.1.0-alpha.2

package/dist/index.d.ts

@@ -0,0 +1,348 @@
+import { EnvironmentAdapter, ColorSupport, TerminalBackground, StyleFn } from '@boba-cli/machine';
+export { ColorSupport, TerminalBackground } from '@boba-cli/machine';
+
+/**
+ * Horizontal alignment options for rendered content.
+ * @public
+ */
+type HAlign = 'left' | 'center' | 'right';
+/**
+ * Vertical alignment options for rendered content.
+ * @public
+ */
+type VAlign = 'top' | 'center' | 'bottom';
+/**
+ * Alias for horizontal alignment (backwards compatibility).
+ * @public
+ */
+type Align = HAlign;
+/**
+ * Spacing descriptor for padding or margin.
+ * @public
+ */
+interface Spacing {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+}
+/**
+ * Characters used to render borders around content.
+ * @public
+ */
+interface BorderStyle {
+    top: string;
+    bottom: string;
+    left: string;
+    right: string;
+    topLeft: string;
+    topRight: string;
+    bottomLeft: string;
+    bottomRight: string;
+}
+/**
+ * A color string or adaptive light/dark color choice.
+ * Accepts hex colors (#ff0000), named colors (red), or adaptive objects.
+ * @public
+ */
+type ColorInput = string | {
+    light?: string;
+    dark?: string;
+};
+/**
+ * Options used internally to represent a Style.
+ * @public
+ */
+interface StyleOptions {
+    foreground?: ColorInput;
+    background?: ColorInput;
+    bold?: boolean;
+    italic?: boolean;
+    underline?: boolean;
+    strikethrough?: boolean;
+    width?: number;
+    height?: number;
+    maxWidth?: number;
+    maxHeight?: number;
+    padding?: Partial<Spacing>;
+    margin?: Partial<Spacing>;
+    borderStyle?: BorderStyle;
+    borderColor?: ColorInput;
+    alignHorizontal?: HAlign;
+    alignVertical?: VAlign;
+    inline?: boolean;
+}
+
+/**
+ * Name of a border style.
+ * @public
+ */
+type BorderStyleName = 'normal' | 'rounded' | 'bold' | 'double';
+/**
+ * Predefined border styles matching common terminal box characters.
+ * @public
+ */
+declare const borderStyles: Record<BorderStyleName, BorderStyle>;
+/**
+ * Default border style (single line).
+ * @public
+ */
+declare const defaultBorderStyle: BorderStyle;
+
+/**
+ * Detect terminal color support levels using an environment adapter.
+ * @param env - Environment adapter to query color support
+ * @returns Color support information
+ * @public
+ */
+declare function getColorSupport(env: EnvironmentAdapter): ColorSupport;
+/**
+ * Detect whether the terminal is using a dark or light background.
+ * @param env - Environment adapter to query terminal background
+ * @returns Terminal background mode
+ * @public
+ */
+declare function getTerminalBackground(env: EnvironmentAdapter): TerminalBackground;
+/**
+ * Resolve a color input (string or adaptive light/dark) to a hex string when available.
+ * @param input - Color input to resolve
+ * @param env - Environment adapter for detecting terminal background
+ * @returns Resolved color string or undefined
+ * @public
+ */
+declare function resolveColor(input: ColorInput | undefined, env: EnvironmentAdapter): string | undefined;
+
+/**
+ * Compute ANSI-aware display width.
+ * @public
+ */
+declare function width(text: string): number;
+/**
+ * Truncate text to a maximum width per line, ANSI-aware.
+ * @public
+ */
+declare function clampWidth(text: string, maxWidth?: number): string;
+/**
+ * Wrap text to a maximum width, ANSI-aware.
+ * @public
+ */
+declare function wrapWidth(text: string, maxWidth?: number): string;
+/**
+ * Pad every line with left/right spaces.
+ * @public
+ */
+declare function padLines(text: string, left?: number, right?: number): string;
+
+/**
+ * Keys that can be explicitly set on a style.
+ * Used to track which properties have been set vs using defaults.
+ * @public
+ */
+type StyleKey = keyof StyleOptions;
+/**
+ * Context required for rendering styles.
+ * @public
+ */
+interface StyleContext {
+    /** Environment adapter for detecting terminal capabilities. */
+    readonly env: EnvironmentAdapter;
+    /** Style function for applying ANSI styling. */
+    readonly styleFn: StyleFn;
+}
+/**
+ * Create a default StyleContext for layout-only styling (no ANSI colors).
+ * This is used internally when no context is provided.
+ * @public
+ */
+declare function createDefaultContext(): StyleContext;
+/**
+ * Set the default StyleContext used when no context is explicitly provided.
+ * This is useful for browser environments (xterm.js) where colors should always be enabled.
+ * @param context - The context to use as default, or undefined to reset to no-colors default
+ * @public
+ */
+declare function setDefaultContext(context: StyleContext | undefined): void;
+/**
+ * Fluent style builder for terminal strings.
+ * @public
+ */
+declare class Style {
+    private readonly options;
+    /** Track which properties have been explicitly set */
+    private readonly setKeys;
+    /** Optional context for rendering - if not set, rendering will throw */
+    private readonly context?;
+    constructor(options?: StyleOptions, setKeys?: Set<StyleKey>, context?: StyleContext);
+    /**
+     * Create a deep copy of this style.
+     */
+    copy(): Style;
+    /**
+     * Create a copy of this style with a new context.
+     * @param context - The new context to use for rendering
+     */
+    withContext(context: StyleContext): Style;
+    /**
+     * Inherit unset properties from another style.
+     * Only copies properties that are set in `other` but not set in `this`.
+     * Margins and padding are NOT inherited (matching Go Lip Gloss behavior).
+     */
+    inherit(other: Style): Style;
+    /**
+     * Check if a property has been explicitly set.
+     */
+    isSet(key: StyleKey): boolean;
+    /**
+     * Unset a property, reverting to default behavior.
+     */
+    unset(...keys: StyleKey[]): Style;
+    foreground(color: ColorInput): Style;
+    background(color: ColorInput): Style;
+    bold(value?: boolean): Style;
+    italic(value?: boolean): Style;
+    underline(value?: boolean): Style;
+    strikethrough(value?: boolean): Style;
+    padding(all: number): Style;
+    padding(vertical: number, horizontal: number): Style;
+    padding(top: number, right: number, bottom: number, left: number): Style;
+    margin(all: number): Style;
+    margin(vertical: number, horizontal: number): Style;
+    margin(top: number, right: number, bottom: number, left: number): Style;
+    width(value: number): Style;
+    height(value: number): Style;
+    maxWidth(value: number): Style;
+    maxHeight(value: number): Style;
+    /**
+     * Enable borders with the default or specified style.
+     * Use borderStyle() to change the border characters without re-enabling.
+     */
+    border(enabled: boolean): Style;
+    border(style: BorderStyle): Style;
+    /**
+     * Set the border style characters.
+     */
+    borderStyle(style: BorderStyle): Style;
+    /**
+     * Set the border foreground color.
+     */
+    borderForeground(color: ColorInput): Style;
+    /**
+     * Set horizontal alignment.
+     * @deprecated Use alignHorizontal() instead.
+     */
+    align(value: HAlign): Style;
+    /**
+     * Set horizontal alignment (left, center, right).
+     */
+    alignHorizontal(value: HAlign): Style;
+    /**
+     * Set vertical alignment (top, center, bottom).
+     * Only applies when height is set.
+     */
+    alignVertical(value: VAlign): Style;
+    /**
+     * Enable inline mode. When true:
+     * - Newlines are stripped from the input
+     * - Padding and margins are not applied
+     */
+    inline(value?: boolean): Style;
+    /**
+     * Render the style to a string.
+     * Uses the default no-op context if none was provided.
+     */
+    render(text: string): string;
+    /**
+     * Render the style to a string with an explicit context.
+     * @param text - Text to render
+     * @param ctx - Context for rendering
+     */
+    renderWithContext(text: string, ctx: StyleContext): string;
+    private with;
+}
+
+/**
+ * Common semantic styles for terminal output.
+ * @public
+ */
+interface SemanticStyles {
+    success: Style;
+    error: Style;
+    warning: Style;
+    info: Style;
+    muted: Style;
+    highlight: Style;
+    header: Style;
+}
+/**
+ * Provider interface for creating styles.
+ * Enables dependency injection for better testability.
+ * @public
+ */
+interface StyleProvider {
+    /**
+     * Create a new style instance.
+     */
+    createStyle(): Style;
+    /**
+     * Get semantic styles for common use cases.
+     */
+    readonly semanticStyles: SemanticStyles;
+    /**
+     * Get the style context used by this provider.
+     */
+    readonly context: StyleContext;
+}
+/**
+ * Implementation using Chapstick's Style class with injected adapters.
+ * @public
+ */
+declare class ChapstickStyleProvider implements StyleProvider {
+    readonly context: StyleContext;
+    /**
+     * Create a new style provider.
+     * @param env - Environment adapter for detecting terminal capabilities
+     * @param styleFn - Style function for applying ANSI styling
+     */
+    constructor(env: EnvironmentAdapter, styleFn: StyleFn);
+    createStyle(): Style;
+    get semanticStyles(): SemanticStyles;
+}
+
+/**
+ * Join blocks side-by-side, padding heights and inserting spacing columns.
+ * @param spacing - The spacing between blocks.
+ * @param blocks - The blocks to join.
+ * @public
+ */
+declare function joinHorizontal(spacing: number, ...blocks: string[]): string;
+/**
+ * Join blocks side-by-side, padding heights and inserting spacing columns.
+ * @param blocks - The blocks to join.
+ * @public
+ */
+declare function joinHorizontal(...blocks: string[]): string;
+/**
+ * Join blocks vertically with optional blank line spacing.
+ * @param spacing - The spacing between blocks.
+ * @param blocks - The blocks to join.
+ * @public
+ */
+declare function joinVertical(spacing: number, ...blocks: string[]): string;
+/**
+ * Join blocks vertically with optional blank line spacing.
+ * @param blocks - The blocks to join.
+ * @public
+ */
+declare function joinVertical(...blocks: string[]): string;
+/**
+ * Place content inside a fixed rectangle with alignment.
+ * @param width - The width of the rectangle.
+ * @param height - The height of the rectangle.
+ * @param hAlign - Horizontal alignment (left, center, right).
+ * @param vAlign - Vertical alignment (top, center, bottom).
+ * @param content - The content to place.
+ * @public
+ */
+declare function place(width: number, height: number, hAlign: HAlign, vAlign: VAlign, content: string): string;
+
+export { type Align, type BorderStyle, ChapstickStyleProvider, type ColorInput, type HAlign, type SemanticStyles, type Spacing, Style, type StyleContext, type StyleKey, type StyleOptions, type StyleProvider, type VAlign, borderStyles, clampWidth, createDefaultContext, defaultBorderStyle, getColorSupport, getTerminalBackground, joinHorizontal, joinVertical, padLines, place, resolveColor, setDefaultContext, width, wrapWidth };