@boba-cli/list 0.1.0-alpha.2

package/dist/index.d.cts

@@ -0,0 +1,218 @@
+import { Style } from '@boba-cli/chapstick';
+import { KeyMap, HelpModel } from '@boba-cli/help';
+import { Binding } from '@boba-cli/key';
+import { PaginatorModel } from '@boba-cli/paginator';
+import { SpinnerModel } from '@boba-cli/spinner';
+import { Cmd, Msg } from '@boba-cli/tea';
+
+/**
+ * Items displayed in a list must implement this interface.
+ * @public
+ */
+interface Item {
+    /** Text used for filtering. */
+    filterValue(): string;
+    /** Title shown in the list. */
+    title(): string;
+    /** Optional description. */
+    description(): string;
+}
+/**
+ * Simple default item implementation.
+ * @public
+ */
+declare class DefaultItem implements Item {
+    private readonly titleText;
+    private readonly descText;
+    constructor(titleText: string, descText?: string);
+    filterValue(): string;
+    title(): string;
+    description(): string;
+}
+
+/**
+ * Style configuration for the list component.
+ * @public
+ */
+interface ListStyles {
+    title: Style;
+    titleBar: Style;
+    spinner: Style;
+    filterPrompt: Style;
+    filterCursor: Style;
+    noItems: Style;
+    statusBar: Style;
+    statusEmpty: Style;
+    pagination: Style;
+    help: Style;
+    normalTitle: Style;
+    normalDesc: Style;
+    selectedTitle: Style;
+    selectedDesc: Style;
+    dimmedTitle: Style;
+    dimmedDesc: Style;
+}
+/** Default styles used by the list component. @public */
+declare function defaultStyles(): ListStyles;
+/**
+ * Merge user provided overrides with defaults.
+ * @public
+ */
+declare function mergeStyles(overrides?: Partial<ListStyles>): ListStyles;
+
+/**
+ * Delegate interface for rendering list items.
+ * @public
+ */
+interface ItemDelegate<T extends Item> {
+    /** Height of each item in lines. */
+    height(): number;
+    /** Spacing between items in lines. */
+    spacing(): number;
+    /** Render an item to a string. */
+    render(item: T, index: number, selected: boolean): string;
+}
+/**
+ * Default delegate renders a title plus optional description.
+ * @public
+ */
+declare class DefaultDelegate implements ItemDelegate<Item> {
+    #private;
+    constructor(styles?: ListStyles);
+    height(): number;
+    spacing(): number;
+    render(item: Item, _index: number, selected: boolean): string;
+    /** Return a copy using different styles. */
+    withStyles(styles: ListStyles): DefaultDelegate;
+}
+
+/**
+ * Keyboard bindings for the list component.
+ * @public
+ */
+interface ListKeyMap extends KeyMap {
+    cursorUp: Binding;
+    cursorDown: Binding;
+    gotoTop: Binding;
+    gotoBottom: Binding;
+    nextPage: Binding;
+    prevPage: Binding;
+    filter: Binding;
+    clearFilter: Binding;
+    acceptFilter: Binding;
+    cancelFilter: Binding;
+    showFullHelp: Binding;
+    closeFullHelp: Binding;
+    quit: Binding;
+    forceQuit: Binding;
+}
+/** Default bindings modeled after the Go bubbles list. @public */
+declare const defaultKeyMap: ListKeyMap;
+
+/** Filtering lifecycle for the list. @public */
+type FilterState = 'unfiltered' | 'filtering' | 'applied';
+/**
+ * Construction options for {@link ListModel}.
+ * @public
+ */
+interface ListOptions<T extends Item> {
+    items: T[];
+    delegate?: ItemDelegate<T>;
+    width?: number;
+    height?: number;
+    title?: string;
+    showTitle?: boolean;
+    showFilter?: boolean;
+    showStatusBar?: boolean;
+    showPagination?: boolean;
+    showHelp?: boolean;
+    filteringEnabled?: boolean;
+    styles?: Partial<ListStyles>;
+    keyMap?: ListKeyMap;
+}
+
+/**
+ * Composite list component with filtering, pagination, spinner, and help.
+ * @public
+ */
+declare class ListModel<T extends Item> {
+    readonly items: T[];
+    readonly filteredItems: T[];
+    readonly cursor: number;
+    readonly filterValue: string;
+    readonly filterState: FilterState;
+    readonly paginator: PaginatorModel;
+    readonly help: HelpModel;
+    readonly spinner: SpinnerModel;
+    readonly delegate: ItemDelegate<T>;
+    readonly styles: ListStyles;
+    readonly keyMap: ListKeyMap;
+    readonly width: number;
+    readonly height: number;
+    readonly title: string;
+    readonly showTitle: boolean;
+    readonly showFilter: boolean;
+    readonly showStatusBar: boolean;
+    readonly showPagination: boolean;
+    readonly showHelp: boolean;
+    readonly filteringEnabled: boolean;
+    readonly loading: boolean;
+    private constructor();
+    /** Create a new list model. */
+    static new<T extends Item>(options: ListOptions<T>): ListModel<T>;
+    /** Currently selected item (after filtering). */
+    selectedItem(): T | undefined;
+    /** Index of the selected item within the filtered collection. */
+    selectedIndex(): number;
+    /** Items visible on the current page. */
+    visibleItems(): T[];
+    /** Move cursor up by one item. */
+    cursorUp(): ListModel<T>;
+    /** Move cursor down by one item. */
+    cursorDown(): ListModel<T>;
+    /** Jump to first item. */
+    gotoTop(): ListModel<T>;
+    /** Jump to last item. */
+    gotoBottom(): ListModel<T>;
+    /** Move to next page. */
+    nextPage(): ListModel<T>;
+    /** Move to previous page. */
+    prevPage(): ListModel<T>;
+    /** Begin filtering. */
+    startFiltering(): ListModel<T>;
+    /** Set the filter query. */
+    setFilter(value: string): ListModel<T>;
+    /** Accept the current filter value. */
+    acceptFilter(): ListModel<T>;
+    /** Cancel filtering and restore the unfiltered list. */
+    cancelFilter(): ListModel<T>;
+    /** Clear the filter text and results. */
+    clearFilter(): ListModel<T>;
+    /** Replace items with a new list. */
+    setItems(items: T[]): ListModel<T>;
+    /** Insert a single item. */
+    insertItem(index: number, item: T): ListModel<T>;
+    /** Remove an item by index. */
+    removeItem(index: number): ListModel<T>;
+    /** Enter loading mode and start the spinner. */
+    startLoading(): [ListModel<T>, Cmd<Msg>];
+    /** Stop loading. */
+    stopLoading(): ListModel<T>;
+    /** Update width. */
+    setWidth(width: number): ListModel<T>;
+    /** Update height and adjust pagination. */
+    setHeight(height: number): ListModel<T>;
+    /** Show detailed help. */
+    showHelpView(): ListModel<T>;
+    /** Hide detailed help. */
+    hideHelpView(): ListModel<T>;
+    /** Tea init - start spinner if already loading. */
+    init(): Cmd<Msg>;
+    /** Handle Tea messages. */
+    update(msg: Msg): [ListModel<T>, Cmd<Msg>];
+    /** Render the list to a string. */
+    view(): string;
+    private with;
+}
+
+export { DefaultDelegate, DefaultItem, type FilterState, type Item, type ItemDelegate, type ListKeyMap, ListModel, type ListOptions, type ListStyles, defaultKeyMap, defaultStyles, mergeStyles };

package/dist/index.d.ts

@@ -0,0 +1,218 @@
+import { Style } from '@boba-cli/chapstick';
+import { KeyMap, HelpModel } from '@boba-cli/help';
+import { Binding } from '@boba-cli/key';
+import { PaginatorModel } from '@boba-cli/paginator';
+import { SpinnerModel } from '@boba-cli/spinner';
+import { Cmd, Msg } from '@boba-cli/tea';
+
+/**
+ * Items displayed in a list must implement this interface.
+ * @public
+ */
+interface Item {
+    /** Text used for filtering. */
+    filterValue(): string;
+    /** Title shown in the list. */
+    title(): string;
+    /** Optional description. */
+    description(): string;
+}
+/**
+ * Simple default item implementation.
+ * @public
+ */
+declare class DefaultItem implements Item {
+    private readonly titleText;
+    private readonly descText;
+    constructor(titleText: string, descText?: string);
+    filterValue(): string;
+    title(): string;
+    description(): string;
+}
+
+/**
+ * Style configuration for the list component.
+ * @public
+ */
+interface ListStyles {
+    title: Style;
+    titleBar: Style;
+    spinner: Style;
+    filterPrompt: Style;
+    filterCursor: Style;
+    noItems: Style;
+    statusBar: Style;
+    statusEmpty: Style;
+    pagination: Style;
+    help: Style;
+    normalTitle: Style;
+    normalDesc: Style;
+    selectedTitle: Style;
+    selectedDesc: Style;
+    dimmedTitle: Style;
+    dimmedDesc: Style;
+}
+/** Default styles used by the list component. @public */
+declare function defaultStyles(): ListStyles;
+/**
+ * Merge user provided overrides with defaults.
+ * @public
+ */
+declare function mergeStyles(overrides?: Partial<ListStyles>): ListStyles;
+
+/**
+ * Delegate interface for rendering list items.
+ * @public
+ */
+interface ItemDelegate<T extends Item> {
+    /** Height of each item in lines. */
+    height(): number;
+    /** Spacing between items in lines. */
+    spacing(): number;
+    /** Render an item to a string. */
+    render(item: T, index: number, selected: boolean): string;
+}
+/**
+ * Default delegate renders a title plus optional description.
+ * @public
+ */
+declare class DefaultDelegate implements ItemDelegate<Item> {
+    #private;
+    constructor(styles?: ListStyles);
+    height(): number;
+    spacing(): number;
+    render(item: Item, _index: number, selected: boolean): string;
+    /** Return a copy using different styles. */
+    withStyles(styles: ListStyles): DefaultDelegate;
+}
+
+/**
+ * Keyboard bindings for the list component.
+ * @public
+ */
+interface ListKeyMap extends KeyMap {
+    cursorUp: Binding;
+    cursorDown: Binding;
+    gotoTop: Binding;
+    gotoBottom: Binding;
+    nextPage: Binding;
+    prevPage: Binding;
+    filter: Binding;
+    clearFilter: Binding;
+    acceptFilter: Binding;
+    cancelFilter: Binding;
+    showFullHelp: Binding;
+    closeFullHelp: Binding;
+    quit: Binding;
+    forceQuit: Binding;
+}
+/** Default bindings modeled after the Go bubbles list. @public */
+declare const defaultKeyMap: ListKeyMap;
+
+/** Filtering lifecycle for the list. @public */
+type FilterState = 'unfiltered' | 'filtering' | 'applied';
+/**
+ * Construction options for {@link ListModel}.
+ * @public
+ */
+interface ListOptions<T extends Item> {
+    items: T[];
+    delegate?: ItemDelegate<T>;
+    width?: number;
+    height?: number;
+    title?: string;
+    showTitle?: boolean;
+    showFilter?: boolean;
+    showStatusBar?: boolean;
+    showPagination?: boolean;
+    showHelp?: boolean;
+    filteringEnabled?: boolean;
+    styles?: Partial<ListStyles>;
+    keyMap?: ListKeyMap;
+}
+
+/**
+ * Composite list component with filtering, pagination, spinner, and help.
+ * @public
+ */
+declare class ListModel<T extends Item> {
+    readonly items: T[];
+    readonly filteredItems: T[];
+    readonly cursor: number;
+    readonly filterValue: string;
+    readonly filterState: FilterState;
+    readonly paginator: PaginatorModel;
+    readonly help: HelpModel;
+    readonly spinner: SpinnerModel;
+    readonly delegate: ItemDelegate<T>;
+    readonly styles: ListStyles;
+    readonly keyMap: ListKeyMap;
+    readonly width: number;
+    readonly height: number;
+    readonly title: string;
+    readonly showTitle: boolean;
+    readonly showFilter: boolean;
+    readonly showStatusBar: boolean;
+    readonly showPagination: boolean;
+    readonly showHelp: boolean;
+    readonly filteringEnabled: boolean;
+    readonly loading: boolean;
+    private constructor();
+    /** Create a new list model. */
+    static new<T extends Item>(options: ListOptions<T>): ListModel<T>;
+    /** Currently selected item (after filtering). */
+    selectedItem(): T | undefined;
+    /** Index of the selected item within the filtered collection. */
+    selectedIndex(): number;
+    /** Items visible on the current page. */
+    visibleItems(): T[];
+    /** Move cursor up by one item. */
+    cursorUp(): ListModel<T>;
+    /** Move cursor down by one item. */
+    cursorDown(): ListModel<T>;
+    /** Jump to first item. */
+    gotoTop(): ListModel<T>;
+    /** Jump to last item. */
+    gotoBottom(): ListModel<T>;
+    /** Move to next page. */
+    nextPage(): ListModel<T>;
+    /** Move to previous page. */
+    prevPage(): ListModel<T>;
+    /** Begin filtering. */
+    startFiltering(): ListModel<T>;
+    /** Set the filter query. */
+    setFilter(value: string): ListModel<T>;
+    /** Accept the current filter value. */
+    acceptFilter(): ListModel<T>;
+    /** Cancel filtering and restore the unfiltered list. */
+    cancelFilter(): ListModel<T>;
+    /** Clear the filter text and results. */
+    clearFilter(): ListModel<T>;
+    /** Replace items with a new list. */
+    setItems(items: T[]): ListModel<T>;
+    /** Insert a single item. */
+    insertItem(index: number, item: T): ListModel<T>;
+    /** Remove an item by index. */
+    removeItem(index: number): ListModel<T>;
+    /** Enter loading mode and start the spinner. */
+    startLoading(): [ListModel<T>, Cmd<Msg>];
+    /** Stop loading. */
+    stopLoading(): ListModel<T>;
+    /** Update width. */
+    setWidth(width: number): ListModel<T>;
+    /** Update height and adjust pagination. */
+    setHeight(height: number): ListModel<T>;
+    /** Show detailed help. */
+    showHelpView(): ListModel<T>;
+    /** Hide detailed help. */
+    hideHelpView(): ListModel<T>;
+    /** Tea init - start spinner if already loading. */
+    init(): Cmd<Msg>;
+    /** Handle Tea messages. */
+    update(msg: Msg): [ListModel<T>, Cmd<Msg>];
+    /** Render the list to a string. */
+    view(): string;
+    private with;
+}
+
+export { DefaultDelegate, DefaultItem, type FilterState, type Item, type ItemDelegate, type ListKeyMap, ListModel, type ListOptions, type ListStyles, defaultKeyMap, defaultStyles, mergeStyles };