@boba-cli/help 0.1.0-alpha.2

package/README.md

@@ -0,0 +1,33 @@
+# @boba-cli/help
+
+Render short or full help text from your key bindings. Ported from the Charm `bubbles/help` component.
+
+<img src="../../examples/help-demo.gif" width="950" alt="Help component demo" />
+
+```ts
+import { HelpModel } from '@boba-cli/help'
+
+const help = HelpModel.new({ width: 80 })
+const text = help.view(keyMap)
+```
+
+## HelpBubble
+
+A self-contained help bubble component with a scrollable viewport for displaying keyboard shortcuts.
+
+<img src="../../examples/help-bubble-demo.gif" width="950" alt="HelpBubble component demo" />
+
+```ts
+import { HelpBubble } from '@boba-cli/help'
+
+const bubble = HelpBubble.new(
+  true,
+  'Keyboard Shortcuts',
+  { foreground: '#f8f8f2', background: '#6272a4' },
+  [
+    { key: '↑/↓', description: 'Navigate' },
+    { key: 'enter', description: 'Select' },
+    { key: 'q', description: 'Quit' },
+  ],
+)
+```

package/dist/index.cjs

@@ -0,0 +1,315 @@
+'use strict';
+
+var chapstick = require('@boba-cli/chapstick');
+var viewport = require('@boba-cli/viewport');
+
+// src/model.ts
+function defaultStyles() {
+  const keyStyle = new chapstick.Style().foreground("#626262");
+  const descStyle = new chapstick.Style().foreground("#4A4A4A");
+  const sepStyle = new chapstick.Style().foreground("#3C3C3C");
+  return {
+    shortKey: keyStyle,
+    shortDesc: descStyle,
+    shortSeparator: sepStyle,
+    ellipsis: sepStyle,
+    fullKey: keyStyle,
+    fullDesc: descStyle,
+    fullSeparator: sepStyle
+  };
+}
+
+// src/model.ts
+var HelpModel = class _HelpModel {
+  width;
+  showAll;
+  shortSeparator;
+  fullSeparator;
+  ellipsis;
+  styles;
+  constructor(options = {}) {
+    this.width = options.width ?? 0;
+    this.showAll = options.showAll ?? false;
+    this.shortSeparator = options.shortSeparator ?? " \u2022 ";
+    this.fullSeparator = options.fullSeparator ?? "    ";
+    this.ellipsis = options.ellipsis ?? "\u2026";
+    const defaults = defaultStyles();
+    this.styles = { ...defaults, ...options.styles };
+  }
+  /** Create a new help model with defaults applied. */
+  static new(options = {}) {
+    return new _HelpModel(options);
+  }
+  /** Return a new model with updated width. */
+  withWidth(width) {
+    return this.with({ width });
+  }
+  /** Return a new model with showAll toggled. */
+  withShowAll(showAll) {
+    return this.with({ showAll });
+  }
+  /** Tea update: no-op (view-only component). */
+  update(_msg) {
+    return [this, null];
+  }
+  /** Render help text from the provided key map. */
+  view(keyMap) {
+    if (this.showAll) {
+      return this.fullHelpView(keyMap.fullHelp());
+    }
+    return this.shortHelpView(keyMap.shortHelp());
+  }
+  /** Render single-line help. */
+  shortHelpView(bindings) {
+    if (!bindings || bindings.length === 0) {
+      return "";
+    }
+    let result = "";
+    let totalWidth = 0;
+    const separator = this.styles.shortSeparator.inline(true).render(this.shortSeparator);
+    for (const [i, kb] of bindings.entries()) {
+      if (!kb.enabled()) continue;
+      const sep = totalWidth > 0 && i < bindings.length ? separator : "";
+      const help = kb.help();
+      const item = sep + this.styles.shortKey.inline(true).render(help.key) + " " + this.styles.shortDesc.inline(true).render(help.desc);
+      const itemWidth = chapstick.width(item);
+      const [tail, ok] = this.shouldAddItem(totalWidth, itemWidth);
+      if (!ok) {
+        if (tail) {
+          result += tail;
+        }
+        break;
+      }
+      totalWidth += itemWidth;
+      result += item;
+    }
+    return result;
+  }
+  /** Render multi-column help. */
+  fullHelpView(groups) {
+    if (!groups || groups.length === 0) {
+      return "";
+    }
+    const out = [];
+    let totalWidth = 0;
+    const separator = this.styles.fullSeparator.inline(true).render(this.fullSeparator);
+    for (const [i, group] of groups.entries()) {
+      if (!group || !shouldRenderColumn(group)) {
+        continue;
+      }
+      const keys = [];
+      const descriptions = [];
+      for (const kb of group) {
+        if (!kb.enabled()) continue;
+        const help = kb.help();
+        keys.push(this.styles.fullKey.render(help.key));
+        descriptions.push(this.styles.fullDesc.render(help.desc));
+      }
+      const sep = totalWidth > 0 && i < groups.length ? separator : "";
+      const parts = sep ? [sep, keys.join("\n"), " ", descriptions.join("\n")] : [keys.join("\n"), " ", descriptions.join("\n")];
+      const column = chapstick.joinHorizontal(...parts);
+      const columnWidth = chapstick.width(column);
+      const [tail, ok] = this.shouldAddItem(totalWidth, columnWidth);
+      if (!ok) {
+        if (tail) {
+          out.push(tail);
+        }
+        break;
+      }
+      totalWidth += columnWidth;
+      out.push(column);
+    }
+    return chapstick.joinHorizontal(...out);
+  }
+  shouldAddItem(totalWidth, width) {
+    if (this.width > 0 && totalWidth + width > this.width) {
+      const tail = " " + this.styles.ellipsis.inline(true).render(this.ellipsis);
+      if (totalWidth + chapstick.width(tail) < this.width) {
+        return [tail, false];
+      }
+    }
+    return ["", true];
+  }
+  with(patch) {
+    return new _HelpModel({
+      width: this.width,
+      showAll: this.showAll,
+      shortSeparator: this.shortSeparator,
+      fullSeparator: this.fullSeparator,
+      ellipsis: this.ellipsis,
+      styles: this.styles,
+      ...patch
+    });
+  }
+};
+function shouldRenderColumn(bindings) {
+  return bindings.some((b) => b.enabled());
+}
+var KEY_WIDTH = 12;
+function generateHelpScreen(title, titleColor, entries, width, height) {
+  let helpScreen = "";
+  for (const content of entries) {
+    const paddedKey = content.key.padEnd(KEY_WIDTH);
+    const keyText = new chapstick.Style().bold(true).foreground({ dark: "#ffffff", light: "#000000" }).render(paddedKey);
+    const descriptionText = new chapstick.Style().foreground({ dark: "#ffffff", light: "#000000" }).render(content.description);
+    const row = chapstick.joinHorizontal(2, keyText, descriptionText);
+    helpScreen += `${row}
+`;
+  }
+  const titleText = new chapstick.Style().bold(true).background(titleColor.background).foreground(titleColor.foreground).padding(0, 1).italic(true).render(title);
+  return new chapstick.Style().width(width).height(height).render(chapstick.joinVertical(titleText, helpScreen));
+}
+var HelpBubble = class _HelpBubble {
+  /**
+   * The viewport model that handles scrolling and content display.
+   */
+  viewport;
+  /**
+   * The array of help entries displayed in the bubble.
+   */
+  entries;
+  /**
+   * The title text shown at the top of the help screen.
+   */
+  title;
+  /**
+   * The color configuration for the title bar.
+   */
+  titleColor;
+  /**
+   * Whether the help bubble is active and receiving input.
+   */
+  active;
+  constructor(viewport, entries, title, titleColor, active) {
+    this.viewport = viewport;
+    this.entries = entries;
+    this.title = title;
+    this.titleColor = titleColor;
+    this.active = active;
+  }
+  /**
+   * Create a new help bubble.
+   * @param active - Whether the component receives input
+   * @param title - Title text for the help screen
+   * @param titleColor - Color configuration for the title
+   * @param entries - Array of help entries to display
+   */
+  static new(active, title, titleColor, entries) {
+    const viewport$1 = viewport.ViewportModel.new({ width: 0, height: 0 });
+    const content = generateHelpScreen(title, titleColor, entries, 0, 0);
+    const initializedViewport = viewport$1.setContent(content);
+    return new _HelpBubble(
+      initializedViewport,
+      entries,
+      title,
+      titleColor,
+      active
+    );
+  }
+  /**
+   * Set the size of the help bubble and regenerate content.
+   * @param width - Width in characters
+   * @param height - Height in lines
+   */
+  setSize(width, height) {
+    const content = generateHelpScreen(
+      this.title,
+      this.titleColor,
+      this.entries,
+      width,
+      height
+    );
+    const updatedViewport = this.viewport.setWidth(width).setHeight(height).setContent(content);
+    return new _HelpBubble(
+      updatedViewport,
+      this.entries,
+      this.title,
+      this.titleColor,
+      this.active
+    );
+  }
+  /**
+   * Set whether the component is active (receives input).
+   * @param active - Active state
+   */
+  setIsActive(active) {
+    if (this.active === active) return this;
+    return new _HelpBubble(
+      this.viewport,
+      this.entries,
+      this.title,
+      this.titleColor,
+      active
+    );
+  }
+  /**
+   * Set the title color and regenerate content.
+   * @param color - New title color configuration
+   */
+  setTitleColor(color) {
+    const content = generateHelpScreen(
+      this.title,
+      color,
+      this.entries,
+      this.viewport.width,
+      this.viewport.height
+    );
+    const updatedViewport = this.viewport.setContent(content);
+    return new _HelpBubble(
+      updatedViewport,
+      this.entries,
+      this.title,
+      color,
+      this.active
+    );
+  }
+  /**
+   * Scroll to the top of the viewport.
+   */
+  gotoTop() {
+    const updatedViewport = this.viewport.scrollToTop();
+    if (updatedViewport === this.viewport) return this;
+    return new _HelpBubble(
+      updatedViewport,
+      this.entries,
+      this.title,
+      this.titleColor,
+      this.active
+    );
+  }
+  /**
+   * Handle Tea update messages (viewport scrolling when active).
+   * @param msg - Tea message
+   */
+  update(msg) {
+    if (!this.active) {
+      return [this, null];
+    }
+    const [updatedViewport, cmd] = this.viewport.update(msg);
+    if (updatedViewport === this.viewport) {
+      return [this, cmd];
+    }
+    return [
+      new _HelpBubble(
+        updatedViewport,
+        this.entries,
+        this.title,
+        this.titleColor,
+        this.active
+      ),
+      cmd
+    ];
+  }
+  /**
+   * Render the help screen.
+   */
+  view() {
+    return this.viewport.view();
+  }
+};
+
+exports.HelpBubble = HelpBubble;
+exports.HelpModel = HelpModel;
+exports.defaultStyles = defaultStyles;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/styles.ts","../src/model.ts","../src/bubble.ts"],"names":["Style","stringWidth","joinHorizontal","joinVertical","viewport","ViewportModel"],"mappings":"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","file":"index.cjs","sourcesContent":["import { Style } from '@boba-cli/chapstick'\nimport type { HelpStyles } from './types.js'\n\n/**\n * Default styling for help output.\n * @public\n */\nexport function defaultStyles(): HelpStyles {\n  const keyStyle = new Style().foreground('#626262')\n  const descStyle = new Style().foreground('#4A4A4A')\n  const sepStyle = new Style().foreground('#3C3C3C')\n\n  return {\n    shortKey: keyStyle,\n    shortDesc: descStyle,\n    shortSeparator: sepStyle,\n    ellipsis: sepStyle,\n    fullKey: keyStyle,\n    fullDesc: descStyle,\n    fullSeparator: sepStyle,\n  }\n}\n","import { joinHorizontal, width as stringWidth } from '@boba-cli/chapstick'\nimport { type Cmd, type Msg } from '@boba-cli/tea'\nimport type { Binding } from '@boba-cli/key'\nimport { defaultStyles } from './styles.js'\nimport type { HelpStyles, KeyMap } from './types.js'\n\n/**\n * Options for configuring the help component.\n * @public\n */\nexport interface HelpOptions {\n  width?: number\n  showAll?: boolean\n  shortSeparator?: string\n  fullSeparator?: string\n  ellipsis?: string\n  styles?: Partial<HelpStyles>\n}\n\n/**\n * Help view renderer.\n * @public\n */\nexport class HelpModel {\n  readonly width: number\n  readonly showAll: boolean\n  readonly shortSeparator: string\n  readonly fullSeparator: string\n  readonly ellipsis: string\n  readonly styles: HelpStyles\n\n  private constructor(options: HelpOptions = {}) {\n    this.width = options.width ?? 0\n    this.showAll = options.showAll ?? false\n    this.shortSeparator = options.shortSeparator ?? ' • '\n    this.fullSeparator = options.fullSeparator ?? '    '\n    this.ellipsis = options.ellipsis ?? '…'\n    const defaults = defaultStyles()\n    this.styles = { ...defaults, ...options.styles }\n  }\n\n  /** Create a new help model with defaults applied. */\n  static new(options: HelpOptions = {}): HelpModel {\n    return new HelpModel(options)\n  }\n\n  /** Return a new model with updated width. */\n  withWidth(width: number): HelpModel {\n    return this.with({ width })\n  }\n\n  /** Return a new model with showAll toggled. */\n  withShowAll(showAll: boolean): HelpModel {\n    return this.with({ showAll })\n  }\n\n  /** Tea update: no-op (view-only component). */\n  update(_msg: Msg): [HelpModel, Cmd<Msg>] {\n    return [this, null]\n  }\n\n  /** Render help text from the provided key map. */\n  view(keyMap: KeyMap): string {\n    if (this.showAll) {\n      return this.fullHelpView(keyMap.fullHelp())\n    }\n    return this.shortHelpView(keyMap.shortHelp())\n  }\n\n  /** Render single-line help. */\n  shortHelpView(bindings: Binding[]): string {\n    if (!bindings || bindings.length === 0) {\n      return ''\n    }\n\n    let result = ''\n    let totalWidth = 0\n    const separator = this.styles.shortSeparator\n      .inline(true)\n      .render(this.shortSeparator)\n\n    for (const [i, kb] of bindings.entries()) {\n      if (!kb.enabled()) continue\n\n      const sep = totalWidth > 0 && i < bindings.length ? separator : ''\n      const help = kb.help()\n      const item =\n        sep +\n        this.styles.shortKey.inline(true).render(help.key) +\n        ' ' +\n        this.styles.shortDesc.inline(true).render(help.desc)\n      const itemWidth = stringWidth(item)\n\n      const [tail, ok] = this.shouldAddItem(totalWidth, itemWidth)\n      if (!ok) {\n        if (tail) {\n          result += tail\n        }\n        break\n      }\n\n      totalWidth += itemWidth\n      result += item\n    }\n\n    return result\n  }\n\n  /** Render multi-column help. */\n  fullHelpView(groups: Binding[][]): string {\n    if (!groups || groups.length === 0) {\n      return ''\n    }\n\n    const out: string[] = []\n    let totalWidth = 0\n    const separator = this.styles.fullSeparator\n      .inline(true)\n      .render(this.fullSeparator)\n\n    for (const [i, group] of groups.entries()) {\n      if (!group || !shouldRenderColumn(group)) {\n        continue\n      }\n\n      const keys: string[] = []\n      const descriptions: string[] = []\n      for (const kb of group) {\n        if (!kb.enabled()) continue\n        const help = kb.help()\n        keys.push(this.styles.fullKey.render(help.key))\n        descriptions.push(this.styles.fullDesc.render(help.desc))\n      }\n\n      const sep = totalWidth > 0 && i < groups.length ? separator : ''\n      const parts = sep\n        ? [sep, keys.join('\\n'), ' ', descriptions.join('\\n')]\n        : [keys.join('\\n'), ' ', descriptions.join('\\n')]\n      const column = joinHorizontal(...parts)\n      const columnWidth = stringWidth(column)\n\n      const [tail, ok] = this.shouldAddItem(totalWidth, columnWidth)\n      if (!ok) {\n        if (tail) {\n          out.push(tail)\n        }\n        break\n      }\n\n      totalWidth += columnWidth\n      out.push(column)\n    }\n\n    return joinHorizontal(...out)\n  }\n\n  private shouldAddItem(totalWidth: number, width: number): [string, boolean] {\n    if (this.width > 0 && totalWidth + width > this.width) {\n      const tail = ' ' + this.styles.ellipsis.inline(true).render(this.ellipsis)\n      if (totalWidth + stringWidth(tail) < this.width) {\n        return [tail, false]\n      }\n    }\n    return ['', true]\n  }\n\n  private with(patch: Partial<HelpOptions>): HelpModel {\n    return new HelpModel({\n      width: this.width,\n      showAll: this.showAll,\n      shortSeparator: this.shortSeparator,\n      fullSeparator: this.fullSeparator,\n      ellipsis: this.ellipsis,\n      styles: this.styles,\n      ...patch,\n    })\n  }\n}\n\nfunction shouldRenderColumn(bindings: Binding[]): boolean {\n  return bindings.some((b) => b.enabled())\n}\n","import { Style, joinVertical, joinHorizontal } from '@boba-cli/chapstick'\nimport { ViewportModel } from '@boba-cli/viewport'\nimport { type Cmd, type Msg } from '@boba-cli/tea'\nimport type { Entry, TitleColor } from './bubble-types.js'\n\nconst KEY_WIDTH = 12\n\n/**\n * Generates the help screen content with styled title and entries.\n * @internal\n */\nfunction generateHelpScreen(\n  title: string,\n  titleColor: TitleColor,\n  entries: Entry[],\n  width: number,\n  height: number,\n): string {\n  let helpScreen = ''\n\n  // Build each entry row with two-column layout\n  for (const content of entries) {\n    const paddedKey = content.key.padEnd(KEY_WIDTH)\n    const keyText = new Style()\n      .bold(true)\n      .foreground({ dark: '#ffffff', light: '#000000' })\n      .render(paddedKey)\n\n    const descriptionText = new Style()\n      .foreground({ dark: '#ffffff', light: '#000000' })\n      .render(content.description)\n\n    const row = joinHorizontal(2, keyText, descriptionText)\n    helpScreen += `${row}\\n`\n  }\n\n  // Create styled title\n  const titleText = new Style()\n    .bold(true)\n    .background(titleColor.background)\n    .foreground(titleColor.foreground)\n    .padding(0, 1)\n    .italic(true)\n    .render(title)\n\n  // Combine title and entries, apply width/height constraints\n  return new Style()\n    .width(width)\n    .height(height)\n    .render(joinVertical(titleText, helpScreen))\n}\n\n/**\n * Model representing a scrollable help bubble.\n * Displays a styled title and a list of key binding entries in a scrollable viewport.\n * @public\n */\nexport class HelpBubble {\n  /**\n   * The viewport model that handles scrolling and content display.\n   */\n  readonly viewport: ViewportModel\n  /**\n   * The array of help entries displayed in the bubble.\n   */\n  readonly entries: Entry[]\n  /**\n   * The title text shown at the top of the help screen.\n   */\n  readonly title: string\n  /**\n   * The color configuration for the title bar.\n   */\n  readonly titleColor: TitleColor\n  /**\n   * Whether the help bubble is active and receiving input.\n   */\n  readonly active: boolean\n\n  private constructor(\n    viewport: ViewportModel,\n    entries: Entry[],\n    title: string,\n    titleColor: TitleColor,\n    active: boolean,\n  ) {\n    this.viewport = viewport\n    this.entries = entries\n    this.title = title\n    this.titleColor = titleColor\n    this.active = active\n  }\n\n  /**\n   * Create a new help bubble.\n   * @param active - Whether the component receives input\n   * @param title - Title text for the help screen\n   * @param titleColor - Color configuration for the title\n   * @param entries - Array of help entries to display\n   */\n  static new(\n    active: boolean,\n    title: string,\n    titleColor: TitleColor,\n    entries: Entry[],\n  ): HelpBubble {\n    const viewport = ViewportModel.new({ width: 0, height: 0 })\n    const content = generateHelpScreen(title, titleColor, entries, 0, 0)\n    const initializedViewport = viewport.setContent(content)\n\n    return new HelpBubble(\n      initializedViewport,\n      entries,\n      title,\n      titleColor,\n      active,\n    )\n  }\n\n  /**\n   * Set the size of the help bubble and regenerate content.\n   * @param width - Width in characters\n   * @param height - Height in lines\n   */\n  setSize(width: number, height: number): HelpBubble {\n    const content = generateHelpScreen(\n      this.title,\n      this.titleColor,\n      this.entries,\n      width,\n      height,\n    )\n    const updatedViewport = this.viewport\n      .setWidth(width)\n      .setHeight(height)\n      .setContent(content)\n\n    return new HelpBubble(\n      updatedViewport,\n      this.entries,\n      this.title,\n      this.titleColor,\n      this.active,\n    )\n  }\n\n  /**\n   * Set whether the component is active (receives input).\n   * @param active - Active state\n   */\n  setIsActive(active: boolean): HelpBubble {\n    if (this.active === active) return this\n    return new HelpBubble(\n      this.viewport,\n      this.entries,\n      this.title,\n      this.titleColor,\n      active,\n    )\n  }\n\n  /**\n   * Set the title color and regenerate content.\n   * @param color - New title color configuration\n   */\n  setTitleColor(color: TitleColor): HelpBubble {\n    const content = generateHelpScreen(\n      this.title,\n      color,\n      this.entries,\n      this.viewport.width,\n      this.viewport.height,\n    )\n    const updatedViewport = this.viewport.setContent(content)\n\n    return new HelpBubble(\n      updatedViewport,\n      this.entries,\n      this.title,\n      color,\n      this.active,\n    )\n  }\n\n  /**\n   * Scroll to the top of the viewport.\n   */\n  gotoTop(): HelpBubble {\n    const updatedViewport = this.viewport.scrollToTop()\n    if (updatedViewport === this.viewport) return this\n\n    return new HelpBubble(\n      updatedViewport,\n      this.entries,\n      this.title,\n      this.titleColor,\n      this.active,\n    )\n  }\n\n  /**\n   * Handle Tea update messages (viewport scrolling when active).\n   * @param msg - Tea message\n   */\n  update(msg: Msg): [HelpBubble, Cmd<Msg>] {\n    if (!this.active) {\n      return [this, null]\n    }\n\n    const [updatedViewport, cmd] = this.viewport.update(msg)\n\n    if (updatedViewport === this.viewport) {\n      return [this, cmd]\n    }\n\n    return [\n      new HelpBubble(\n        updatedViewport,\n        this.entries,\n        this.title,\n        this.titleColor,\n        this.active,\n      ),\n      cmd,\n    ]\n  }\n\n  /**\n   * Render the help screen.\n   */\n  view(): string {\n    return this.viewport.view()\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,165 @@
+import { Msg, Cmd } from '@boba-cli/tea';
+import { Binding } from '@boba-cli/key';
+import { Style, ColorInput } from '@boba-cli/chapstick';
+import { ViewportModel } from '@boba-cli/viewport';
+
+/**
+ * Interface for components that provide help bindings.
+ * @public
+ */
+interface KeyMap {
+    /** Bindings for short (single-line) help. */
+    shortHelp(): Binding[];
+    /** Bindings grouped into columns for full help. */
+    fullHelp(): Binding[][];
+}
+/**
+ * Style configuration for help rendering.
+ * @public
+ */
+interface HelpStyles {
+    ellipsis: Style;
+    shortKey: Style;
+    shortDesc: Style;
+    shortSeparator: Style;
+    fullKey: Style;
+    fullDesc: Style;
+    fullSeparator: Style;
+}
+
+/**
+ * Options for configuring the help component.
+ * @public
+ */
+interface HelpOptions {
+    width?: number;
+    showAll?: boolean;
+    shortSeparator?: string;
+    fullSeparator?: string;
+    ellipsis?: string;
+    styles?: Partial<HelpStyles>;
+}
+/**
+ * Help view renderer.
+ * @public
+ */
+declare class HelpModel {
+    readonly width: number;
+    readonly showAll: boolean;
+    readonly shortSeparator: string;
+    readonly fullSeparator: string;
+    readonly ellipsis: string;
+    readonly styles: HelpStyles;
+    private constructor();
+    /** Create a new help model with defaults applied. */
+    static new(options?: HelpOptions): HelpModel;
+    /** Return a new model with updated width. */
+    withWidth(width: number): HelpModel;
+    /** Return a new model with showAll toggled. */
+    withShowAll(showAll: boolean): HelpModel;
+    /** Tea update: no-op (view-only component). */
+    update(_msg: Msg): [HelpModel, Cmd<Msg>];
+    /** Render help text from the provided key map. */
+    view(keyMap: KeyMap): string;
+    /** Render single-line help. */
+    shortHelpView(bindings: Binding[]): string;
+    /** Render multi-column help. */
+    fullHelpView(groups: Binding[][]): string;
+    private shouldAddItem;
+    private with;
+}
+
+/**
+ * Default styling for help output.
+ * @public
+ */
+declare function defaultStyles(): HelpStyles;
+
+/**
+ * Color configuration for the help bubble title (adaptive for light/dark terminals).
+ * @public
+ */
+interface TitleColor {
+    /** Background color (adaptive) */
+    background: ColorInput;
+    /** Foreground color (adaptive) */
+    foreground: ColorInput;
+}
+/**
+ * A single entry in the help bubble screen.
+ * @public
+ */
+interface Entry {
+    /** Key binding (e.g., "ctrl+c", "j/up") */
+    key: string;
+    /** Description of what the key does */
+    description: string;
+}
+
+/**
+ * Model representing a scrollable help bubble.
+ * Displays a styled title and a list of key binding entries in a scrollable viewport.
+ * @public
+ */
+declare class HelpBubble {
+    /**
+     * The viewport model that handles scrolling and content display.
+     */
+    readonly viewport: ViewportModel;
+    /**
+     * The array of help entries displayed in the bubble.
+     */
+    readonly entries: Entry[];
+    /**
+     * The title text shown at the top of the help screen.
+     */
+    readonly title: string;
+    /**
+     * The color configuration for the title bar.
+     */
+    readonly titleColor: TitleColor;
+    /**
+     * Whether the help bubble is active and receiving input.
+     */
+    readonly active: boolean;
+    private constructor();
+    /**
+     * Create a new help bubble.
+     * @param active - Whether the component receives input
+     * @param title - Title text for the help screen
+     * @param titleColor - Color configuration for the title
+     * @param entries - Array of help entries to display
+     */
+    static new(active: boolean, title: string, titleColor: TitleColor, entries: Entry[]): HelpBubble;
+    /**
+     * Set the size of the help bubble and regenerate content.
+     * @param width - Width in characters
+     * @param height - Height in lines
+     */
+    setSize(width: number, height: number): HelpBubble;
+    /**
+     * Set whether the component is active (receives input).
+     * @param active - Active state
+     */
+    setIsActive(active: boolean): HelpBubble;
+    /**
+     * Set the title color and regenerate content.
+     * @param color - New title color configuration
+     */
+    setTitleColor(color: TitleColor): HelpBubble;
+    /**
+     * Scroll to the top of the viewport.
+     */
+    gotoTop(): HelpBubble;
+    /**
+     * Handle Tea update messages (viewport scrolling when active).
+     * @param msg - Tea message
+     */
+    update(msg: Msg): [HelpBubble, Cmd<Msg>];
+    /**
+     * Render the help screen.
+     */
+    view(): string;
+}
+
+export { type Entry, HelpBubble, HelpModel, type HelpOptions, type HelpStyles, type KeyMap, type TitleColor, defaultStyles };

package/dist/index.d.ts

@@ -0,0 +1,165 @@
+import { Msg, Cmd } from '@boba-cli/tea';
+import { Binding } from '@boba-cli/key';
+import { Style, ColorInput } from '@boba-cli/chapstick';
+import { ViewportModel } from '@boba-cli/viewport';
+
+/**
+ * Interface for components that provide help bindings.
+ * @public
+ */
+interface KeyMap {
+    /** Bindings for short (single-line) help. */
+    shortHelp(): Binding[];
+    /** Bindings grouped into columns for full help. */
+    fullHelp(): Binding[][];
+}
+/**
+ * Style configuration for help rendering.
+ * @public
+ */
+interface HelpStyles {
+    ellipsis: Style;
+    shortKey: Style;
+    shortDesc: Style;
+    shortSeparator: Style;
+    fullKey: Style;
+    fullDesc: Style;
+    fullSeparator: Style;
+}
+
+/**
+ * Options for configuring the help component.
+ * @public
+ */
+interface HelpOptions {
+    width?: number;
+    showAll?: boolean;
+    shortSeparator?: string;
+    fullSeparator?: string;
+    ellipsis?: string;
+    styles?: Partial<HelpStyles>;
+}
+/**
+ * Help view renderer.
+ * @public
+ */
+declare class HelpModel {
+    readonly width: number;
+    readonly showAll: boolean;
+    readonly shortSeparator: string;
+    readonly fullSeparator: string;
+    readonly ellipsis: string;
+    readonly styles: HelpStyles;
+    private constructor();
+    /** Create a new help model with defaults applied. */
+    static new(options?: HelpOptions): HelpModel;
+    /** Return a new model with updated width. */
+    withWidth(width: number): HelpModel;
+    /** Return a new model with showAll toggled. */
+    withShowAll(showAll: boolean): HelpModel;
+    /** Tea update: no-op (view-only component). */
+    update(_msg: Msg): [HelpModel, Cmd<Msg>];
+    /** Render help text from the provided key map. */
+    view(keyMap: KeyMap): string;
+    /** Render single-line help. */
+    shortHelpView(bindings: Binding[]): string;
+    /** Render multi-column help. */
+    fullHelpView(groups: Binding[][]): string;
+    private shouldAddItem;
+    private with;
+}
+
+/**
+ * Default styling for help output.
+ * @public
+ */
+declare function defaultStyles(): HelpStyles;
+
+/**
+ * Color configuration for the help bubble title (adaptive for light/dark terminals).
+ * @public
+ */
+interface TitleColor {
+    /** Background color (adaptive) */
+    background: ColorInput;
+    /** Foreground color (adaptive) */
+    foreground: ColorInput;
+}
+/**
+ * A single entry in the help bubble screen.
+ * @public
+ */
+interface Entry {
+    /** Key binding (e.g., "ctrl+c", "j/up") */
+    key: string;
+    /** Description of what the key does */
+    description: string;
+}
+
+/**
+ * Model representing a scrollable help bubble.
+ * Displays a styled title and a list of key binding entries in a scrollable viewport.
+ * @public
+ */
+declare class HelpBubble {
+    /**
+     * The viewport model that handles scrolling and content display.
+     */
+    readonly viewport: ViewportModel;
+    /**
+     * The array of help entries displayed in the bubble.
+     */
+    readonly entries: Entry[];
+    /**
+     * The title text shown at the top of the help screen.
+     */
+    readonly title: string;
+    /**
+     * The color configuration for the title bar.
+     */
+    readonly titleColor: TitleColor;
+    /**
+     * Whether the help bubble is active and receiving input.
+     */
+    readonly active: boolean;
+    private constructor();
+    /**
+     * Create a new help bubble.
+     * @param active - Whether the component receives input
+     * @param title - Title text for the help screen
+     * @param titleColor - Color configuration for the title
+     * @param entries - Array of help entries to display
+     */
+    static new(active: boolean, title: string, titleColor: TitleColor, entries: Entry[]): HelpBubble;
+    /**
+     * Set the size of the help bubble and regenerate content.
+     * @param width - Width in characters
+     * @param height - Height in lines
+     */
+    setSize(width: number, height: number): HelpBubble;
+    /**
+     * Set whether the component is active (receives input).
+     * @param active - Active state
+     */
+    setIsActive(active: boolean): HelpBubble;
+    /**
+     * Set the title color and regenerate content.
+     * @param color - New title color configuration
+     */
+    setTitleColor(color: TitleColor): HelpBubble;
+    /**
+     * Scroll to the top of the viewport.
+     */
+    gotoTop(): HelpBubble;
+    /**
+     * Handle Tea update messages (viewport scrolling when active).
+     * @param msg - Tea message
+     */
+    update(msg: Msg): [HelpBubble, Cmd<Msg>];
+    /**
+     * Render the help screen.
+     */
+    view(): string;
+}
+
+export { type Entry, HelpBubble, HelpModel, type HelpOptions, type HelpStyles, type KeyMap, type TitleColor, defaultStyles };

package/dist/index.js

@@ -0,0 +1,311 @@
+import { Style, width, joinHorizontal, joinVertical } from '@boba-cli/chapstick';
+import { ViewportModel } from '@boba-cli/viewport';
+
+// src/model.ts
+function defaultStyles() {
+  const keyStyle = new Style().foreground("#626262");
+  const descStyle = new Style().foreground("#4A4A4A");
+  const sepStyle = new Style().foreground("#3C3C3C");
+  return {
+    shortKey: keyStyle,
+    shortDesc: descStyle,
+    shortSeparator: sepStyle,
+    ellipsis: sepStyle,
+    fullKey: keyStyle,
+    fullDesc: descStyle,
+    fullSeparator: sepStyle
+  };
+}
+
+// src/model.ts
+var HelpModel = class _HelpModel {
+  width;
+  showAll;
+  shortSeparator;
+  fullSeparator;
+  ellipsis;
+  styles;
+  constructor(options = {}) {
+    this.width = options.width ?? 0;
+    this.showAll = options.showAll ?? false;
+    this.shortSeparator = options.shortSeparator ?? " \u2022 ";
+    this.fullSeparator = options.fullSeparator ?? "    ";
+    this.ellipsis = options.ellipsis ?? "\u2026";
+    const defaults = defaultStyles();
+    this.styles = { ...defaults, ...options.styles };
+  }
+  /** Create a new help model with defaults applied. */
+  static new(options = {}) {
+    return new _HelpModel(options);
+  }
+  /** Return a new model with updated width. */
+  withWidth(width) {
+    return this.with({ width });
+  }
+  /** Return a new model with showAll toggled. */
+  withShowAll(showAll) {
+    return this.with({ showAll });
+  }
+  /** Tea update: no-op (view-only component). */
+  update(_msg) {
+    return [this, null];
+  }
+  /** Render help text from the provided key map. */
+  view(keyMap) {
+    if (this.showAll) {
+      return this.fullHelpView(keyMap.fullHelp());
+    }
+    return this.shortHelpView(keyMap.shortHelp());
+  }
+  /** Render single-line help. */
+  shortHelpView(bindings) {
+    if (!bindings || bindings.length === 0) {
+      return "";
+    }
+    let result = "";
+    let totalWidth = 0;
+    const separator = this.styles.shortSeparator.inline(true).render(this.shortSeparator);
+    for (const [i, kb] of bindings.entries()) {
+      if (!kb.enabled()) continue;
+      const sep = totalWidth > 0 && i < bindings.length ? separator : "";
+      const help = kb.help();
+      const item = sep + this.styles.shortKey.inline(true).render(help.key) + " " + this.styles.shortDesc.inline(true).render(help.desc);
+      const itemWidth = width(item);
+      const [tail, ok] = this.shouldAddItem(totalWidth, itemWidth);
+      if (!ok) {
+        if (tail) {
+          result += tail;
+        }
+        break;
+      }
+      totalWidth += itemWidth;
+      result += item;
+    }
+    return result;
+  }
+  /** Render multi-column help. */
+  fullHelpView(groups) {
+    if (!groups || groups.length === 0) {
+      return "";
+    }
+    const out = [];
+    let totalWidth = 0;
+    const separator = this.styles.fullSeparator.inline(true).render(this.fullSeparator);
+    for (const [i, group] of groups.entries()) {
+      if (!group || !shouldRenderColumn(group)) {
+        continue;
+      }
+      const keys = [];
+      const descriptions = [];
+      for (const kb of group) {
+        if (!kb.enabled()) continue;
+        const help = kb.help();
+        keys.push(this.styles.fullKey.render(help.key));
+        descriptions.push(this.styles.fullDesc.render(help.desc));
+      }
+      const sep = totalWidth > 0 && i < groups.length ? separator : "";
+      const parts = sep ? [sep, keys.join("\n"), " ", descriptions.join("\n")] : [keys.join("\n"), " ", descriptions.join("\n")];
+      const column = joinHorizontal(...parts);
+      const columnWidth = width(column);
+      const [tail, ok] = this.shouldAddItem(totalWidth, columnWidth);
+      if (!ok) {
+        if (tail) {
+          out.push(tail);
+        }
+        break;
+      }
+      totalWidth += columnWidth;
+      out.push(column);
+    }
+    return joinHorizontal(...out);
+  }
+  shouldAddItem(totalWidth, width$1) {
+    if (this.width > 0 && totalWidth + width$1 > this.width) {
+      const tail = " " + this.styles.ellipsis.inline(true).render(this.ellipsis);
+      if (totalWidth + width(tail) < this.width) {
+        return [tail, false];
+      }
+    }
+    return ["", true];
+  }
+  with(patch) {
+    return new _HelpModel({
+      width: this.width,
+      showAll: this.showAll,
+      shortSeparator: this.shortSeparator,
+      fullSeparator: this.fullSeparator,
+      ellipsis: this.ellipsis,
+      styles: this.styles,
+      ...patch
+    });
+  }
+};
+function shouldRenderColumn(bindings) {
+  return bindings.some((b) => b.enabled());
+}
+var KEY_WIDTH = 12;
+function generateHelpScreen(title, titleColor, entries, width, height) {
+  let helpScreen = "";
+  for (const content of entries) {
+    const paddedKey = content.key.padEnd(KEY_WIDTH);
+    const keyText = new Style().bold(true).foreground({ dark: "#ffffff", light: "#000000" }).render(paddedKey);
+    const descriptionText = new Style().foreground({ dark: "#ffffff", light: "#000000" }).render(content.description);
+    const row = joinHorizontal(2, keyText, descriptionText);
+    helpScreen += `${row}
+`;
+  }
+  const titleText = new Style().bold(true).background(titleColor.background).foreground(titleColor.foreground).padding(0, 1).italic(true).render(title);
+  return new Style().width(width).height(height).render(joinVertical(titleText, helpScreen));
+}
+var HelpBubble = class _HelpBubble {
+  /**
+   * The viewport model that handles scrolling and content display.
+   */
+  viewport;
+  /**
+   * The array of help entries displayed in the bubble.
+   */
+  entries;
+  /**
+   * The title text shown at the top of the help screen.
+   */
+  title;
+  /**
+   * The color configuration for the title bar.
+   */
+  titleColor;
+  /**
+   * Whether the help bubble is active and receiving input.
+   */
+  active;
+  constructor(viewport, entries, title, titleColor, active) {
+    this.viewport = viewport;
+    this.entries = entries;
+    this.title = title;
+    this.titleColor = titleColor;
+    this.active = active;
+  }
+  /**
+   * Create a new help bubble.
+   * @param active - Whether the component receives input
+   * @param title - Title text for the help screen
+   * @param titleColor - Color configuration for the title
+   * @param entries - Array of help entries to display
+   */
+  static new(active, title, titleColor, entries) {
+    const viewport = ViewportModel.new({ width: 0, height: 0 });
+    const content = generateHelpScreen(title, titleColor, entries, 0, 0);
+    const initializedViewport = viewport.setContent(content);
+    return new _HelpBubble(
+      initializedViewport,
+      entries,
+      title,
+      titleColor,
+      active
+    );
+  }
+  /**
+   * Set the size of the help bubble and regenerate content.
+   * @param width - Width in characters
+   * @param height - Height in lines
+   */
+  setSize(width, height) {
+    const content = generateHelpScreen(
+      this.title,
+      this.titleColor,
+      this.entries,
+      width,
+      height
+    );
+    const updatedViewport = this.viewport.setWidth(width).setHeight(height).setContent(content);
+    return new _HelpBubble(
+      updatedViewport,
+      this.entries,
+      this.title,
+      this.titleColor,
+      this.active
+    );
+  }
+  /**
+   * Set whether the component is active (receives input).
+   * @param active - Active state
+   */
+  setIsActive(active) {
+    if (this.active === active) return this;
+    return new _HelpBubble(
+      this.viewport,
+      this.entries,
+      this.title,
+      this.titleColor,
+      active
+    );
+  }
+  /**
+   * Set the title color and regenerate content.
+   * @param color - New title color configuration
+   */
+  setTitleColor(color) {
+    const content = generateHelpScreen(
+      this.title,
+      color,
+      this.entries,
+      this.viewport.width,
+      this.viewport.height
+    );
+    const updatedViewport = this.viewport.setContent(content);
+    return new _HelpBubble(
+      updatedViewport,
+      this.entries,
+      this.title,
+      color,
+      this.active
+    );
+  }
+  /**
+   * Scroll to the top of the viewport.
+   */
+  gotoTop() {
+    const updatedViewport = this.viewport.scrollToTop();
+    if (updatedViewport === this.viewport) return this;
+    return new _HelpBubble(
+      updatedViewport,
+      this.entries,
+      this.title,
+      this.titleColor,
+      this.active
+    );
+  }
+  /**
+   * Handle Tea update messages (viewport scrolling when active).
+   * @param msg - Tea message
+   */
+  update(msg) {
+    if (!this.active) {
+      return [this, null];
+    }
+    const [updatedViewport, cmd] = this.viewport.update(msg);
+    if (updatedViewport === this.viewport) {
+      return [this, cmd];
+    }
+    return [
+      new _HelpBubble(
+        updatedViewport,
+        this.entries,
+        this.title,
+        this.titleColor,
+        this.active
+      ),
+      cmd
+    ];
+  }
+  /**
+   * Render the help screen.
+   */
+  view() {
+    return this.viewport.view();
+  }
+};
+
+export { HelpBubble, HelpModel, defaultStyles };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/styles.ts","../src/model.ts","../src/bubble.ts"],"names":["stringWidth","width","Style","joinHorizontal"],"mappings":";;;;AAOO,SAAS,aAAA,GAA4B;AAC1C,EAAA,MAAM,QAAA,GAAW,IAAI,KAAA,EAAM,CAAE,WAAW,SAAS,CAAA;AACjD,EAAA,MAAM,SAAA,GAAY,IAAI,KAAA,EAAM,CAAE,WAAW,SAAS,CAAA;AAClD,EAAA,MAAM,QAAA,GAAW,IAAI,KAAA,EAAM,CAAE,WAAW,SAAS,CAAA;AAEjD,EAAA,OAAO;AAAA,IACL,QAAA,EAAU,QAAA;AAAA,IACV,SAAA,EAAW,SAAA;AAAA,IACX,cAAA,EAAgB,QAAA;AAAA,IAChB,QAAA,EAAU,QAAA;AAAA,IACV,OAAA,EAAS,QAAA;AAAA,IACT,QAAA,EAAU,SAAA;AAAA,IACV,aAAA,EAAe;AAAA,GACjB;AACF;;;ACEO,IAAM,SAAA,GAAN,MAAM,UAAA,CAAU;AAAA,EACZ,KAAA;AAAA,EACA,OAAA;AAAA,EACA,cAAA;AAAA,EACA,aAAA;AAAA,EACA,QAAA;AAAA,EACA,MAAA;AAAA,EAED,WAAA,CAAY,OAAA,GAAuB,EAAC,EAAG;AAC7C,IAAA,IAAA,CAAK,KAAA,GAAQ,QAAQ,KAAA,IAAS,CAAA;AAC9B,IAAA,IAAA,CAAK,OAAA,GAAU,QAAQ,OAAA,IAAW,KAAA;AAClC,IAAA,IAAA,CAAK,cAAA,GAAiB,QAAQ,cAAA,IAAkB,UAAA;AAChD,IAAA,IAAA,CAAK,aAAA,GAAgB,QAAQ,aAAA,IAAiB,MAAA;AAC9C,IAAA,IAAA,CAAK,QAAA,GAAW,QAAQ,QAAA,IAAY,QAAA;AACpC,IAAA,MAAM,WAAW,aAAA,EAAc;AAC/B,IAAA,IAAA,CAAK,SAAS,EAAE,GAAG,QAAA,EAAU,GAAG,QAAQ,MAAA,EAAO;AAAA,EACjD;AAAA;AAAA,EAGA,OAAO,GAAA,CAAI,OAAA,GAAuB,EAAC,EAAc;AAC/C,IAAA,OAAO,IAAI,WAAU,OAAO,CAAA;AAAA,EAC9B;AAAA;AAAA,EAGA,UAAU,KAAA,EAA0B;AAClC,IAAA,OAAO,IAAA,CAAK,IAAA,CAAK,EAAE,KAAA,EAAO,CAAA;AAAA,EAC5B;AAAA;AAAA,EAGA,YAAY,OAAA,EAA6B;AACvC,IAAA,OAAO,IAAA,CAAK,IAAA,CAAK,EAAE,OAAA,EAAS,CAAA;AAAA,EAC9B;AAAA;AAAA,EAGA,OAAO,IAAA,EAAkC;AACvC,IAAA,OAAO,CAAC,MAAM,IAAI,CAAA;AAAA,EACpB;AAAA;AAAA,EAGA,KAAK,MAAA,EAAwB;AAC3B,IAAA,IAAI,KAAK,OAAA,EAAS;AAChB,MAAA,OAAO,IAAA,CAAK,YAAA,CAAa,MAAA,CAAO,QAAA,EAAU,CAAA;AAAA,IAC5C;AACA,IAAA,OAAO,IAAA,CAAK,aAAA,CAAc,MAAA,CAAO,SAAA,EAAW,CAAA;AAAA,EAC9C;AAAA;AAAA,EAGA,cAAc,QAAA,EAA6B;AACzC,IAAA,IAAI,CAAC,QAAA,IAAY,QAAA,CAAS,MAAA,KAAW,CAAA,EAAG;AACtC,MAAA,OAAO,EAAA;AAAA,IACT;AAEA,IAAA,IAAI,MAAA,GAAS,EAAA;AACb,IAAA,IAAI,UAAA,GAAa,CAAA;AACjB,IAAA,MAAM,SAAA,GAAY,KAAK,MAAA,CAAO,cAAA,CAC3B,OAAO,IAAI,CAAA,CACX,MAAA,CAAO,IAAA,CAAK,cAAc,CAAA;AAE7B,IAAA,KAAA,MAAW,CAAC,CAAA,EAAG,EAAE,CAAA,IAAK,QAAA,CAAS,SAAQ,EAAG;AACxC,MAAA,IAAI,CAAC,EAAA,CAAG,OAAA,EAAQ,EAAG;AAEnB,MAAA,MAAM,MAAM,UAAA,GAAa,CAAA,IAAK,CAAA,GAAI,QAAA,CAAS,SAAS,SAAA,GAAY,EAAA;AAChE,MAAA,MAAM,IAAA,GAAO,GAAG,IAAA,EAAK;AACrB,MAAA,MAAM,IAAA,GACJ,MACA,IAAA,CAAK,MAAA,CAAO,SAAS,MAAA,CAAO,IAAI,EAAE,MAAA,CAAO,IAAA,CAAK,GAAG,CAAA,GACjD,GAAA,GACA,KAAK,MAAA,CAAO,SAAA,CAAU,OAAO,IAAI,CAAA,CAAE,MAAA,CAAO,IAAA,CAAK,IAAI,CAAA;AACrD,MAAA,MAAM,SAAA,GAAYA,MAAY,IAAI,CAAA;AAElC,MAAA,MAAM,CAAC,IAAA,EAAM,EAAE,IAAI,IAAA,CAAK,aAAA,CAAc,YAAY,SAAS,CAAA;AAC3D,MAAA,IAAI,CAAC,EAAA,EAAI;AACP,QAAA,IAAI,IAAA,EAAM;AACR,UAAA,MAAA,IAAU,IAAA;AAAA,QACZ;AACA,QAAA;AAAA,MACF;AAEA,MAAA,UAAA,IAAc,SAAA;AACd,MAAA,MAAA,IAAU,IAAA;AAAA,IACZ;AAEA,IAAA,OAAO,MAAA;AAAA,EACT;AAAA;AAAA,EAGA,aAAa,MAAA,EAA6B;AACxC,IAAA,IAAI,CAAC,MAAA,IAAU,MAAA,CAAO,MAAA,KAAW,CAAA,EAAG;AAClC,MAAA,OAAO,EAAA;AAAA,IACT;AAEA,IAAA,MAAM,MAAgB,EAAC;AACvB,IAAA,IAAI,UAAA,GAAa,CAAA;AACjB,IAAA,MAAM,SAAA,GAAY,KAAK,MAAA,CAAO,aAAA,CAC3B,OAAO,IAAI,CAAA,CACX,MAAA,CAAO,IAAA,CAAK,aAAa,CAAA;AAE5B,IAAA,KAAA,MAAW,CAAC,CAAA,EAAG,KAAK,CAAA,IAAK,MAAA,CAAO,SAAQ,EAAG;AACzC,MAAA,IAAI,CAAC,KAAA,IAAS,CAAC,kBAAA,CAAmB,KAAK,CAAA,EAAG;AACxC,QAAA;AAAA,MACF;AAEA,MAAA,MAAM,OAAiB,EAAC;AACxB,MAAA,MAAM,eAAyB,EAAC;AAChC,MAAA,KAAA,MAAW,MAAM,KAAA,EAAO;AACtB,QAAA,IAAI,CAAC,EAAA,CAAG,OAAA,EAAQ,EAAG;AACnB,QAAA,MAAM,IAAA,GAAO,GAAG,IAAA,EAAK;AACrB,QAAA,IAAA,CAAK,KAAK,IAAA,CAAK,MAAA,CAAO,QAAQ,MAAA,CAAO,IAAA,CAAK,GAAG,CAAC,CAAA;AAC9C,QAAA,YAAA,CAAa,KAAK,IAAA,CAAK,MAAA,CAAO,SAAS,MAAA,CAAO,IAAA,CAAK,IAAI,CAAC,CAAA;AAAA,MAC1D;AAEA,MAAA,MAAM,MAAM,UAAA,GAAa,CAAA,IAAK,CAAA,GAAI,MAAA,CAAO,SAAS,SAAA,GAAY,EAAA;AAC9D,MAAA,MAAM,KAAA,GAAQ,MACV,CAAC,GAAA,EAAK,KAAK,IAAA,CAAK,IAAI,CAAA,EAAG,GAAA,EAAK,YAAA,CAAa,IAAA,CAAK,IAAI,CAAC,CAAA,GACnD,CAAC,IAAA,CAAK,IAAA,CAAK,IAAI,GAAG,GAAA,EAAK,YAAA,CAAa,IAAA,CAAK,IAAI,CAAC,CAAA;AAClD,MAAA,MAAM,MAAA,GAAS,cAAA,CAAe,GAAG,KAAK,CAAA;AACtC,MAAA,MAAM,WAAA,GAAcA,MAAY,MAAM,CAAA;AAEtC,MAAA,MAAM,CAAC,IAAA,EAAM,EAAE,IAAI,IAAA,CAAK,aAAA,CAAc,YAAY,WAAW,CAAA;AAC7D,MAAA,IAAI,CAAC,EAAA,EAAI;AACP,QAAA,IAAI,IAAA,EAAM;AACR,UAAA,GAAA,CAAI,KAAK,IAAI,CAAA;AAAA,QACf;AACA,QAAA;AAAA,MACF;AAEA,MAAA,UAAA,IAAc,WAAA;AACd,MAAA,GAAA,CAAI,KAAK,MAAM,CAAA;AAAA,IACjB;AAEA,IAAA,OAAO,cAAA,CAAe,GAAG,GAAG,CAAA;AAAA,EAC9B;AAAA,EAEQ,aAAA,CAAc,YAAoBC,OAAA,EAAkC;AAC1E,IAAA,IAAI,KAAK,KAAA,GAAQ,CAAA,IAAK,UAAA,GAAaA,OAAA,GAAQ,KAAK,KAAA,EAAO;AACrD,MAAA,MAAM,IAAA,GAAO,GAAA,GAAM,IAAA,CAAK,MAAA,CAAO,QAAA,CAAS,OAAO,IAAI,CAAA,CAAE,MAAA,CAAO,IAAA,CAAK,QAAQ,CAAA;AACzE,MAAA,IAAI,UAAA,GAAaD,KAAA,CAAY,IAAI,CAAA,GAAI,KAAK,KAAA,EAAO;AAC/C,QAAA,OAAO,CAAC,MAAM,KAAK,CAAA;AAAA,MACrB;AAAA,IACF;AACA,IAAA,OAAO,CAAC,IAAI,IAAI,CAAA;AAAA,EAClB;AAAA,EAEQ,KAAK,KAAA,EAAwC;AACnD,IAAA,OAAO,IAAI,UAAA,CAAU;AAAA,MACnB,OAAO,IAAA,CAAK,KAAA;AAAA,MACZ,SAAS,IAAA,CAAK,OAAA;AAAA,MACd,gBAAgB,IAAA,CAAK,cAAA;AAAA,MACrB,eAAe,IAAA,CAAK,aAAA;AAAA,MACpB,UAAU,IAAA,CAAK,QAAA;AAAA,MACf,QAAQ,IAAA,CAAK,MAAA;AAAA,MACb,GAAG;AAAA,KACJ,CAAA;AAAA,EACH;AACF;AAEA,SAAS,mBAAmB,QAAA,EAA8B;AACxD,EAAA,OAAO,SAAS,IAAA,CAAK,CAAC,CAAA,KAAM,CAAA,CAAE,SAAS,CAAA;AACzC;AChLA,IAAM,SAAA,GAAY,EAAA;AAMlB,SAAS,kBAAA,CACP,KAAA,EACA,UAAA,EACA,OAAA,EACA,OACA,MAAA,EACQ;AACR,EAAA,IAAI,UAAA,GAAa,EAAA;AAGjB,EAAA,KAAA,MAAW,WAAW,OAAA,EAAS;AAC7B,IAAA,MAAM,SAAA,GAAY,OAAA,CAAQ,GAAA,CAAI,MAAA,CAAO,SAAS,CAAA;AAC9C,IAAA,MAAM,UAAU,IAAIE,KAAAA,EAAM,CACvB,IAAA,CAAK,IAAI,CAAA,CACT,UAAA,CAAW,EAAE,IAAA,EAAM,WAAW,KAAA,EAAO,SAAA,EAAW,CAAA,CAChD,OAAO,SAAS,CAAA;AAEnB,IAAA,MAAM,eAAA,GAAkB,IAAIA,KAAAA,EAAM,CAC/B,WAAW,EAAE,IAAA,EAAM,SAAA,EAAW,KAAA,EAAO,SAAA,EAAW,CAAA,CAChD,MAAA,CAAO,QAAQ,WAAW,CAAA;AAE7B,IAAA,MAAM,GAAA,GAAMC,cAAAA,CAAe,CAAA,EAAG,OAAA,EAAS,eAAe,CAAA;AACtD,IAAA,UAAA,IAAc,GAAG,GAAG;AAAA,CAAA;AAAA,EACtB;AAGA,EAAA,MAAM,SAAA,GAAY,IAAID,KAAAA,EAAM,CACzB,KAAK,IAAI,CAAA,CACT,UAAA,CAAW,UAAA,CAAW,UAAU,CAAA,CAChC,WAAW,UAAA,CAAW,UAAU,CAAA,CAChC,OAAA,CAAQ,CAAA,EAAG,CAAC,EACZ,MAAA,CAAO,IAAI,CAAA,CACX,MAAA,CAAO,KAAK,CAAA;AAGf,EAAA,OAAO,IAAIA,KAAAA,EAAM,CACd,KAAA,CAAM,KAAK,CAAA,CACX,MAAA,CAAO,MAAM,CAAA,CACb,MAAA,CAAO,YAAA,CAAa,SAAA,EAAW,UAAU,CAAC,CAAA;AAC/C;AAOO,IAAM,UAAA,GAAN,MAAM,WAAA,CAAW;AAAA;AAAA;AAAA;AAAA,EAIb,QAAA;AAAA;AAAA;AAAA;AAAA,EAIA,OAAA;AAAA;AAAA;AAAA;AAAA,EAIA,KAAA;AAAA;AAAA;AAAA;AAAA,EAIA,UAAA;AAAA;AAAA;AAAA;AAAA,EAIA,MAAA;AAAA,EAED,WAAA,CACN,QAAA,EACA,OAAA,EACA,KAAA,EACA,YACA,MAAA,EACA;AACA,IAAA,IAAA,CAAK,QAAA,GAAW,QAAA;AAChB,IAAA,IAAA,CAAK,OAAA,GAAU,OAAA;AACf,IAAA,IAAA,CAAK,KAAA,GAAQ,KAAA;AACb,IAAA,IAAA,CAAK,UAAA,GAAa,UAAA;AAClB,IAAA,IAAA,CAAK,MAAA,GAAS,MAAA;AAAA,EAChB;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EASA,OAAO,GAAA,CACL,MAAA,EACA,KAAA,EACA,YACA,OAAA,EACY;AACZ,IAAA,MAAM,QAAA,GAAW,cAAc,GAAA,CAAI,EAAE,OAAO,CAAA,EAAG,MAAA,EAAQ,GAAG,CAAA;AAC1D,IAAA,MAAM,UAAU,kBAAA,CAAmB,KAAA,EAAO,UAAA,EAAY,OAAA,EAAS,GAAG,CAAC,CAAA;AACnE,IAAA,MAAM,mBAAA,GAAsB,QAAA,CAAS,UAAA,CAAW,OAAO,CAAA;AAEvD,IAAA,OAAO,IAAI,WAAA;AAAA,MACT,mBAAA;AAAA,MACA,OAAA;AAAA,MACA,KAAA;AAAA,MACA,UAAA;AAAA,MACA;AAAA,KACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,EAOA,OAAA,CAAQ,OAAe,MAAA,EAA4B;AACjD,IAAA,MAAM,OAAA,GAAU,kBAAA;AAAA,MACd,IAAA,CAAK,KAAA;AAAA,MACL,IAAA,CAAK,UAAA;AAAA,MACL,IAAA,CAAK,OAAA;AAAA,MACL,KAAA;AAAA,MACA;AAAA,KACF;AACA,IAAA,MAAM,eAAA,GAAkB,IAAA,CAAK,QAAA,CAC1B,QAAA,CAAS,KAAK,EACd,SAAA,CAAU,MAAM,CAAA,CAChB,UAAA,CAAW,OAAO,CAAA;AAErB,IAAA,OAAO,IAAI,WAAA;AAAA,MACT,eAAA;AAAA,MACA,IAAA,CAAK,OAAA;AAAA,MACL,IAAA,CAAK,KAAA;AAAA,MACL,IAAA,CAAK,UAAA;AAAA,MACL,IAAA,CAAK;AAAA,KACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,YAAY,MAAA,EAA6B;AACvC,IAAA,IAAI,IAAA,CAAK,MAAA,KAAW,MAAA,EAAQ,OAAO,IAAA;AACnC,IAAA,OAAO,IAAI,WAAA;AAAA,MACT,IAAA,CAAK,QAAA;AAAA,MACL,IAAA,CAAK,OAAA;AAAA,MACL,IAAA,CAAK,KAAA;AAAA,MACL,IAAA,CAAK,UAAA;AAAA,MACL;AAAA,KACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,cAAc,KAAA,EAA+B;AAC3C,IAAA,MAAM,OAAA,GAAU,kBAAA;AAAA,MACd,IAAA,CAAK,KAAA;AAAA,MACL,KAAA;AAAA,MACA,IAAA,CAAK,OAAA;AAAA,MACL,KAAK,QAAA,CAAS,KAAA;AAAA,MACd,KAAK,QAAA,CAAS;AAAA,KAChB;AACA,IAAA,MAAM,eAAA,GAAkB,IAAA,CAAK,QAAA,CAAS,UAAA,CAAW,OAAO,CAAA;AAExD,IAAA,OAAO,IAAI,WAAA;AAAA,MACT,eAAA;AAAA,MACA,IAAA,CAAK,OAAA;AAAA,MACL,IAAA,CAAK,KAAA;AAAA,MACL,KAAA;AAAA,MACA,IAAA,CAAK;AAAA,KACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,OAAA,GAAsB;AACpB,IAAA,MAAM,eAAA,GAAkB,IAAA,CAAK,QAAA,CAAS,WAAA,EAAY;AAClD,IAAA,IAAI,eAAA,KAAoB,IAAA,CAAK,QAAA,EAAU,OAAO,IAAA;AAE9C,IAAA,OAAO,IAAI,WAAA;AAAA,MACT,eAAA;AAAA,MACA,IAAA,CAAK,OAAA;AAAA,MACL,IAAA,CAAK,KAAA;AAAA,MACL,IAAA,CAAK,UAAA;AAAA,MACL,IAAA,CAAK;AAAA,KACP;AAAA,EACF;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,OAAO,GAAA,EAAkC;AACvC,IAAA,IAAI,CAAC,KAAK,MAAA,EAAQ;AAChB,MAAA,OAAO,CAAC,MAAM,IAAI,CAAA;AAAA,IACpB;AAEA,IAAA,MAAM,CAAC,eAAA,EAAiB,GAAG,IAAI,IAAA,CAAK,QAAA,CAAS,OAAO,GAAG,CAAA;AAEvD,IAAA,IAAI,eAAA,KAAoB,KAAK,QAAA,EAAU;AACrC,MAAA,OAAO,CAAC,MAAM,GAAG,CAAA;AAAA,IACnB;AAEA,IAAA,OAAO;AAAA,MACL,IAAI,WAAA;AAAA,QACF,eAAA;AAAA,QACA,IAAA,CAAK,OAAA;AAAA,QACL,IAAA,CAAK,KAAA;AAAA,QACL,IAAA,CAAK,UAAA;AAAA,QACL,IAAA,CAAK;AAAA,OACP;AAAA,MACA;AAAA,KACF;AAAA,EACF;AAAA;AAAA;AAAA;AAAA,EAKA,IAAA,GAAe;AACb,IAAA,OAAO,IAAA,CAAK,SAAS,IAAA,EAAK;AAAA,EAC5B;AACF","file":"index.js","sourcesContent":["import { Style } from '@boba-cli/chapstick'\nimport type { HelpStyles } from './types.js'\n\n/**\n * Default styling for help output.\n * @public\n */\nexport function defaultStyles(): HelpStyles {\n  const keyStyle = new Style().foreground('#626262')\n  const descStyle = new Style().foreground('#4A4A4A')\n  const sepStyle = new Style().foreground('#3C3C3C')\n\n  return {\n    shortKey: keyStyle,\n    shortDesc: descStyle,\n    shortSeparator: sepStyle,\n    ellipsis: sepStyle,\n    fullKey: keyStyle,\n    fullDesc: descStyle,\n    fullSeparator: sepStyle,\n  }\n}\n","import { joinHorizontal, width as stringWidth } from '@boba-cli/chapstick'\nimport { type Cmd, type Msg } from '@boba-cli/tea'\nimport type { Binding } from '@boba-cli/key'\nimport { defaultStyles } from './styles.js'\nimport type { HelpStyles, KeyMap } from './types.js'\n\n/**\n * Options for configuring the help component.\n * @public\n */\nexport interface HelpOptions {\n  width?: number\n  showAll?: boolean\n  shortSeparator?: string\n  fullSeparator?: string\n  ellipsis?: string\n  styles?: Partial<HelpStyles>\n}\n\n/**\n * Help view renderer.\n * @public\n */\nexport class HelpModel {\n  readonly width: number\n  readonly showAll: boolean\n  readonly shortSeparator: string\n  readonly fullSeparator: string\n  readonly ellipsis: string\n  readonly styles: HelpStyles\n\n  private constructor(options: HelpOptions = {}) {\n    this.width = options.width ?? 0\n    this.showAll = options.showAll ?? false\n    this.shortSeparator = options.shortSeparator ?? ' • '\n    this.fullSeparator = options.fullSeparator ?? '    '\n    this.ellipsis = options.ellipsis ?? '…'\n    const defaults = defaultStyles()\n    this.styles = { ...defaults, ...options.styles }\n  }\n\n  /** Create a new help model with defaults applied. */\n  static new(options: HelpOptions = {}): HelpModel {\n    return new HelpModel(options)\n  }\n\n  /** Return a new model with updated width. */\n  withWidth(width: number): HelpModel {\n    return this.with({ width })\n  }\n\n  /** Return a new model with showAll toggled. */\n  withShowAll(showAll: boolean): HelpModel {\n    return this.with({ showAll })\n  }\n\n  /** Tea update: no-op (view-only component). */\n  update(_msg: Msg): [HelpModel, Cmd<Msg>] {\n    return [this, null]\n  }\n\n  /** Render help text from the provided key map. */\n  view(keyMap: KeyMap): string {\n    if (this.showAll) {\n      return this.fullHelpView(keyMap.fullHelp())\n    }\n    return this.shortHelpView(keyMap.shortHelp())\n  }\n\n  /** Render single-line help. */\n  shortHelpView(bindings: Binding[]): string {\n    if (!bindings || bindings.length === 0) {\n      return ''\n    }\n\n    let result = ''\n    let totalWidth = 0\n    const separator = this.styles.shortSeparator\n      .inline(true)\n      .render(this.shortSeparator)\n\n    for (const [i, kb] of bindings.entries()) {\n      if (!kb.enabled()) continue\n\n      const sep = totalWidth > 0 && i < bindings.length ? separator : ''\n      const help = kb.help()\n      const item =\n        sep +\n        this.styles.shortKey.inline(true).render(help.key) +\n        ' ' +\n        this.styles.shortDesc.inline(true).render(help.desc)\n      const itemWidth = stringWidth(item)\n\n      const [tail, ok] = this.shouldAddItem(totalWidth, itemWidth)\n      if (!ok) {\n        if (tail) {\n          result += tail\n        }\n        break\n      }\n\n      totalWidth += itemWidth\n      result += item\n    }\n\n    return result\n  }\n\n  /** Render multi-column help. */\n  fullHelpView(groups: Binding[][]): string {\n    if (!groups || groups.length === 0) {\n      return ''\n    }\n\n    const out: string[] = []\n    let totalWidth = 0\n    const separator = this.styles.fullSeparator\n      .inline(true)\n      .render(this.fullSeparator)\n\n    for (const [i, group] of groups.entries()) {\n      if (!group || !shouldRenderColumn(group)) {\n        continue\n      }\n\n      const keys: string[] = []\n      const descriptions: string[] = []\n      for (const kb of group) {\n        if (!kb.enabled()) continue\n        const help = kb.help()\n        keys.push(this.styles.fullKey.render(help.key))\n        descriptions.push(this.styles.fullDesc.render(help.desc))\n      }\n\n      const sep = totalWidth > 0 && i < groups.length ? separator : ''\n      const parts = sep\n        ? [sep, keys.join('\\n'), ' ', descriptions.join('\\n')]\n        : [keys.join('\\n'), ' ', descriptions.join('\\n')]\n      const column = joinHorizontal(...parts)\n      const columnWidth = stringWidth(column)\n\n      const [tail, ok] = this.shouldAddItem(totalWidth, columnWidth)\n      if (!ok) {\n        if (tail) {\n          out.push(tail)\n        }\n        break\n      }\n\n      totalWidth += columnWidth\n      out.push(column)\n    }\n\n    return joinHorizontal(...out)\n  }\n\n  private shouldAddItem(totalWidth: number, width: number): [string, boolean] {\n    if (this.width > 0 && totalWidth + width > this.width) {\n      const tail = ' ' + this.styles.ellipsis.inline(true).render(this.ellipsis)\n      if (totalWidth + stringWidth(tail) < this.width) {\n        return [tail, false]\n      }\n    }\n    return ['', true]\n  }\n\n  private with(patch: Partial<HelpOptions>): HelpModel {\n    return new HelpModel({\n      width: this.width,\n      showAll: this.showAll,\n      shortSeparator: this.shortSeparator,\n      fullSeparator: this.fullSeparator,\n      ellipsis: this.ellipsis,\n      styles: this.styles,\n      ...patch,\n    })\n  }\n}\n\nfunction shouldRenderColumn(bindings: Binding[]): boolean {\n  return bindings.some((b) => b.enabled())\n}\n","import { Style, joinVertical, joinHorizontal } from '@boba-cli/chapstick'\nimport { ViewportModel } from '@boba-cli/viewport'\nimport { type Cmd, type Msg } from '@boba-cli/tea'\nimport type { Entry, TitleColor } from './bubble-types.js'\n\nconst KEY_WIDTH = 12\n\n/**\n * Generates the help screen content with styled title and entries.\n * @internal\n */\nfunction generateHelpScreen(\n  title: string,\n  titleColor: TitleColor,\n  entries: Entry[],\n  width: number,\n  height: number,\n): string {\n  let helpScreen = ''\n\n  // Build each entry row with two-column layout\n  for (const content of entries) {\n    const paddedKey = content.key.padEnd(KEY_WIDTH)\n    const keyText = new Style()\n      .bold(true)\n      .foreground({ dark: '#ffffff', light: '#000000' })\n      .render(paddedKey)\n\n    const descriptionText = new Style()\n      .foreground({ dark: '#ffffff', light: '#000000' })\n      .render(content.description)\n\n    const row = joinHorizontal(2, keyText, descriptionText)\n    helpScreen += `${row}\\n`\n  }\n\n  // Create styled title\n  const titleText = new Style()\n    .bold(true)\n    .background(titleColor.background)\n    .foreground(titleColor.foreground)\n    .padding(0, 1)\n    .italic(true)\n    .render(title)\n\n  // Combine title and entries, apply width/height constraints\n  return new Style()\n    .width(width)\n    .height(height)\n    .render(joinVertical(titleText, helpScreen))\n}\n\n/**\n * Model representing a scrollable help bubble.\n * Displays a styled title and a list of key binding entries in a scrollable viewport.\n * @public\n */\nexport class HelpBubble {\n  /**\n   * The viewport model that handles scrolling and content display.\n   */\n  readonly viewport: ViewportModel\n  /**\n   * The array of help entries displayed in the bubble.\n   */\n  readonly entries: Entry[]\n  /**\n   * The title text shown at the top of the help screen.\n   */\n  readonly title: string\n  /**\n   * The color configuration for the title bar.\n   */\n  readonly titleColor: TitleColor\n  /**\n   * Whether the help bubble is active and receiving input.\n   */\n  readonly active: boolean\n\n  private constructor(\n    viewport: ViewportModel,\n    entries: Entry[],\n    title: string,\n    titleColor: TitleColor,\n    active: boolean,\n  ) {\n    this.viewport = viewport\n    this.entries = entries\n    this.title = title\n    this.titleColor = titleColor\n    this.active = active\n  }\n\n  /**\n   * Create a new help bubble.\n   * @param active - Whether the component receives input\n   * @param title - Title text for the help screen\n   * @param titleColor - Color configuration for the title\n   * @param entries - Array of help entries to display\n   */\n  static new(\n    active: boolean,\n    title: string,\n    titleColor: TitleColor,\n    entries: Entry[],\n  ): HelpBubble {\n    const viewport = ViewportModel.new({ width: 0, height: 0 })\n    const content = generateHelpScreen(title, titleColor, entries, 0, 0)\n    const initializedViewport = viewport.setContent(content)\n\n    return new HelpBubble(\n      initializedViewport,\n      entries,\n      title,\n      titleColor,\n      active,\n    )\n  }\n\n  /**\n   * Set the size of the help bubble and regenerate content.\n   * @param width - Width in characters\n   * @param height - Height in lines\n   */\n  setSize(width: number, height: number): HelpBubble {\n    const content = generateHelpScreen(\n      this.title,\n      this.titleColor,\n      this.entries,\n      width,\n      height,\n    )\n    const updatedViewport = this.viewport\n      .setWidth(width)\n      .setHeight(height)\n      .setContent(content)\n\n    return new HelpBubble(\n      updatedViewport,\n      this.entries,\n      this.title,\n      this.titleColor,\n      this.active,\n    )\n  }\n\n  /**\n   * Set whether the component is active (receives input).\n   * @param active - Active state\n   */\n  setIsActive(active: boolean): HelpBubble {\n    if (this.active === active) return this\n    return new HelpBubble(\n      this.viewport,\n      this.entries,\n      this.title,\n      this.titleColor,\n      active,\n    )\n  }\n\n  /**\n   * Set the title color and regenerate content.\n   * @param color - New title color configuration\n   */\n  setTitleColor(color: TitleColor): HelpBubble {\n    const content = generateHelpScreen(\n      this.title,\n      color,\n      this.entries,\n      this.viewport.width,\n      this.viewport.height,\n    )\n    const updatedViewport = this.viewport.setContent(content)\n\n    return new HelpBubble(\n      updatedViewport,\n      this.entries,\n      this.title,\n      color,\n      this.active,\n    )\n  }\n\n  /**\n   * Scroll to the top of the viewport.\n   */\n  gotoTop(): HelpBubble {\n    const updatedViewport = this.viewport.scrollToTop()\n    if (updatedViewport === this.viewport) return this\n\n    return new HelpBubble(\n      updatedViewport,\n      this.entries,\n      this.title,\n      this.titleColor,\n      this.active,\n    )\n  }\n\n  /**\n   * Handle Tea update messages (viewport scrolling when active).\n   * @param msg - Tea message\n   */\n  update(msg: Msg): [HelpBubble, Cmd<Msg>] {\n    if (!this.active) {\n      return [this, null]\n    }\n\n    const [updatedViewport, cmd] = this.viewport.update(msg)\n\n    if (updatedViewport === this.viewport) {\n      return [this, cmd]\n    }\n\n    return [\n      new HelpBubble(\n        updatedViewport,\n        this.entries,\n        this.title,\n        this.titleColor,\n        this.active,\n      ),\n      cmd,\n    ]\n  }\n\n  /**\n   * Render the help screen.\n   */\n  view(): string {\n    return this.viewport.view()\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@boba-cli/help",
+  "description": "Help components for Boba terminal UIs: key binding renderer and scrollable help bubble",
+  "version": "0.1.0-alpha.2",
+  "dependencies": {
+    "@boba-cli/chapstick": "0.1.0-alpha.2",
+    "@boba-cli/key": "0.1.0-alpha.1",
+    "@boba-cli/tea": "0.1.0-alpha.1",
+    "@boba-cli/viewport": "0.1.0-alpha.2"
+  },
+  "devDependencies": {
+    "typescript": "5.8.2",
+    "vitest": "^4.0.16"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "scripts": {
+    "build": "tsup",
+    "check:api-report": "pnpm run generate:api-report",
+    "check:eslint": "pnpm run lint",
+    "generate:api-report": "api-extractor run --local",
+    "lint": "eslint \"{src,test}/**/*.{ts,tsx}\"",
+    "test": "vitest run"
+  }
+}