@boba-cli/cursor 0.1.0-alpha.2

package/README.md

@@ -0,0 +1,83 @@
+# @boba-cli/cursor
+
+Cursor component for Boba terminal UIs. Handles blinking, focus, and hidden/static modes.
+
+## Install
+
+```bash
+pnpm add @boba-cli/cursor
+```
+
+## Quickstart
+
+```ts
+import {
+  CursorModel,
+  CursorMode,
+  BlinkMsg,
+  InitialBlinkMsg,
+} from '@boba-cli/cursor'
+import type { Cmd, Msg } from '@boba-cli/tea'
+
+// Create a cursor (defaults to blink mode)
+let cursor = new CursorModel()
+
+// In init, start blinking
+function init(): Cmd<Msg> {
+  return cursor.initBlink()
+}
+
+// In update, handle focus/blur and blink messages
+function update(msg: Msg): [MyModel, Cmd<Msg>] {
+  const [nextCursor, cmd] = cursor.update(msg)
+  cursor = nextCursor
+  return [model, cmd]
+}
+
+// In view, render the cursor at your desired position/character
+function view(): string {
+  return cursor.view()
+}
+```
+
+## Modes
+
+| Mode                | Behavior                                        |
+| ------------------- | ----------------------------------------------- |
+| `CursorMode.Blink`  | Toggles between block and text state on a timer |
+| `CursorMode.Static` | Always shows the block                          |
+| `CursorMode.Hidden` | Always shows text (cursor hidden)               |
+
+## API
+
+| Export            | Description                         |
+| ----------------- | ----------------------------------- |
+| `CursorModel`     | Main component model                |
+| `CursorMode`      | Enum of `Blink`, `Static`, `Hidden` |
+| `BlinkMsg`        | Blink toggle message                |
+| `InitialBlinkMsg` | Kickoff message for blinking        |
+
+### CursorModel helpers
+
+| Method               | Description                                    |
+| -------------------- | ---------------------------------------------- |
+| `id()`               | Unique ID for routing                          |
+| `mode()`             | Current mode                                   |
+| `initBlink()`        | Command to send an initial blink message       |
+| `tickBlink()`        | Command to schedule the next blink             |
+| `withMode(mode)`     | Change mode (returns new model + optional cmd) |
+| `withChar(char)`     | Change the underlying character                |
+| `focus()` / `blur()` | Focus management (returns new model)           |
+| `update(msg)`        | Handle messages; returns `[model, cmd]`        |
+| `view()`             | Render the cursor                              |
+
+## Scripts
+
+- `pnpm -C packages/cursor build`
+- `pnpm -C packages/cursor test`
+- `pnpm -C packages/cursor lint`
+- `pnpm -C packages/cursor generate:api-report`
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,184 @@
+'use strict';
+
+var tea = require('@boba-cli/tea');
+var chapstick = require('@boba-cli/chapstick');
+
+// src/model.ts
+
+// src/messages.ts
+var InitialBlinkMsg = class {
+  _tag = "cursor:init-blink";
+};
+var BlinkMsg = class {
+  constructor(id, tag, time) {
+    this.id = id;
+    this.tag = tag;
+    this.time = time;
+  }
+  _tag = "cursor:blink";
+};
+
+// src/model.ts
+var defaultBlinkSpeed = 530;
+var lastId = 0;
+function nextId() {
+  return ++lastId;
+}
+var CursorMode = /* @__PURE__ */ ((CursorMode2) => {
+  CursorMode2["Blink"] = "blink";
+  CursorMode2["Static"] = "static";
+  CursorMode2["Hidden"] = "hidden";
+  return CursorMode2;
+})(CursorMode || {});
+var CursorModel = class _CursorModel {
+  blinkSpeed;
+  style;
+  textStyle;
+  char;
+  #id;
+  #tag;
+  #blink;
+  #focus;
+  #mode;
+  constructor(options = {}, state) {
+    this.blinkSpeed = options.blinkSpeed ?? defaultBlinkSpeed;
+    this.style = options.style ?? new chapstick.Style();
+    this.textStyle = options.textStyle ?? new chapstick.Style();
+    this.char = options.char ?? " ";
+    this.#id = state?.id ?? nextId();
+    this.#tag = state?.tag ?? 0;
+    this.#blink = state?.blink ?? true;
+    this.#focus = state?.focus ?? false;
+    this.#mode = state?.mode ?? options.mode ?? "blink" /* Blink */;
+  }
+  /** Unique ID for this cursor (for message routing). */
+  id() {
+    return this.#id;
+  }
+  /** Current cursor mode. */
+  mode() {
+    return this.#mode;
+  }
+  /** Whether the cursor is currently in the "text" state (hidden block). */
+  isBlinkHidden() {
+    return this.#blink;
+  }
+  /** Whether this cursor currently has focus. */
+  isFocused() {
+    return this.#focus;
+  }
+  /** Kick off blinking at init (emits InitialBlinkMsg). */
+  initBlink() {
+    return () => new InitialBlinkMsg();
+  }
+  /** Command to schedule the next blink toggle. */
+  tickBlink() {
+    const nextTag = this.#tag + 1;
+    const id = this.#id;
+    const speed = this.blinkSpeed;
+    const next = this.#withState({ ...this.#state(), tag: nextTag });
+    const cmd = tea.tick(
+      speed,
+      (time) => new BlinkMsg(id, nextTag, time)
+    );
+    return [next, cmd];
+  }
+  /** Set the character under the cursor. */
+  withChar(char) {
+    return this.#withState(this.#state(), { char });
+  }
+  /** Set the cursor mode. Returns a new model and optional blink command. */
+  withMode(mode) {
+    const bounded = mode === "blink" /* Blink */ || mode === "static" /* Static */ || mode === "hidden" /* Hidden */ ? mode : "blink" /* Blink */;
+    const blink = bounded === "hidden" /* Hidden */ || !this.#focus ? true : this.#blink;
+    const next = this.#withState({ ...this.#state(), blink, mode: bounded });
+    if (bounded === "blink" /* Blink */ && this.#focus) {
+      const [scheduled, cmd] = next.tickBlink();
+      return [scheduled, cmd];
+    }
+    return [next, null];
+  }
+  /** Focus the cursor. Returns new model and optional blink command. */
+  focus() {
+    const blink = this.#mode === "hidden" /* Hidden */ ? true : this.#blink;
+    const next = this.#withState({ ...this.#state(), blink, focus: true });
+    if (this.#mode === "blink" /* Blink */) {
+      const [scheduled, cmd] = next.tickBlink();
+      return [scheduled, cmd];
+    }
+    return [next, null];
+  }
+  /** Blur the cursor. */
+  blur() {
+    return this.#withState({ ...this.#state(), blink: true, focus: false });
+  }
+  /**
+   * Update the cursor model with an incoming message.
+   * Returns a new model and an optional command.
+   */
+  update(msg) {
+    if (msg instanceof InitialBlinkMsg) {
+      if (this.#mode !== "blink" /* Blink */ || !this.#focus) {
+        return [this, null];
+      }
+      const [next, cmd] = this.tickBlink();
+      return [next, cmd];
+    }
+    if (msg instanceof tea.FocusMsg) {
+      return this.focus();
+    }
+    if (msg instanceof tea.BlurMsg) {
+      const next = this.blur();
+      return [next, null];
+    }
+    if (msg instanceof BlinkMsg) {
+      if (this.#mode !== "blink" /* Blink */ || !this.#focus) {
+        return [this, null];
+      }
+      if (msg.id !== this.#id || msg.tag !== this.#tag) {
+        return [this, null];
+      }
+      const toggled = this.#withState({ ...this.#state(), blink: !this.#blink });
+      const [next, cmd] = toggled.tickBlink();
+      return [next, cmd];
+    }
+    return [this, null];
+  }
+  /** Render the cursor. */
+  view() {
+    const char = this.char;
+    if (this.#blink) {
+      return this.textStyle.inline(true).render(char);
+    }
+    return this.style.inline(true).render(char);
+  }
+  #state() {
+    return {
+      id: this.#id,
+      tag: this.#tag,
+      blink: this.#blink,
+      focus: this.#focus,
+      mode: this.#mode
+    };
+  }
+  #withState(state, overrides) {
+    return new _CursorModel(
+      {
+        blinkSpeed: this.blinkSpeed,
+        style: this.style,
+        textStyle: this.textStyle,
+        char: overrides?.char ?? this.char,
+        mode: state.mode,
+        focused: state.focus
+      },
+      state
+    );
+  }
+};
+
+exports.BlinkMsg = BlinkMsg;
+exports.CursorMode = CursorMode;
+exports.CursorModel = CursorModel;
+exports.InitialBlinkMsg = InitialBlinkMsg;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/messages.ts","../src/model.ts"],"names":["CursorMode","Style","tick","FocusMsg","BlurMsg"],"mappings":"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","file":"index.cjs","sourcesContent":["/**\n * @public\n */\nexport class InitialBlinkMsg {\n  readonly _tag = 'cursor:init-blink'\n}\n\n/**\n * @public\n */\nexport class BlinkMsg {\n  readonly _tag = 'cursor:blink'\n  constructor(\n    public readonly id: number,\n    public readonly tag: number,\n    public readonly time: Date,\n  ) {}\n}\n","import { tick, type Cmd, type Msg, FocusMsg, BlurMsg } from '@boba-cli/tea'\nimport { Style } from '@boba-cli/chapstick'\nimport { BlinkMsg, InitialBlinkMsg } from './messages.js'\n\nconst defaultBlinkSpeed = 530 // ms\n\n// Module-level ID counter for unique cursor identification\nlet lastId = 0\nfunction nextId(): number {\n  return ++lastId\n}\n\n/** Available cursor behaviors. @public */\nexport enum CursorMode {\n  Blink = 'blink',\n  Static = 'static',\n  Hidden = 'hidden',\n}\n\n/** Options for creating a CursorModel. @public */\nexport interface CursorOptions {\n  blinkSpeed?: number\n  style?: Style\n  textStyle?: Style\n  char?: string\n  mode?: CursorMode\n  focused?: boolean\n}\n\ntype CursorState = {\n  id: number\n  tag: number\n  blink: boolean\n  focus: boolean\n  mode: CursorMode\n}\n\n/**\n * Cursor component model.\n *\n * Use `tickBlink()` to start blinking, or handle `InitialBlinkMsg` from `initBlink()`.\n * Handle `BlinkMsg`, `FocusMsg`, and `BlurMsg` in your update loop.\n *\n * @public\n */\nexport class CursorModel {\n  readonly blinkSpeed: number\n  readonly style: Style\n  readonly textStyle: Style\n  readonly char: string\n  readonly #id: number\n  readonly #tag: number\n  readonly #blink: boolean\n  readonly #focus: boolean\n  readonly #mode: CursorMode\n\n  constructor(options: CursorOptions = {}, state?: CursorState) {\n    this.blinkSpeed = options.blinkSpeed ?? defaultBlinkSpeed\n    this.style = options.style ?? new Style()\n    this.textStyle = options.textStyle ?? new Style()\n    this.char = options.char ?? ' '\n    this.#id = state?.id ?? nextId()\n    this.#tag = state?.tag ?? 0\n    this.#blink = state?.blink ?? true\n    this.#focus = state?.focus ?? false\n    this.#mode = state?.mode ?? options.mode ?? CursorMode.Blink\n  }\n\n  /** Unique ID for this cursor (for message routing). */\n  id(): number {\n    return this.#id\n  }\n\n  /** Current cursor mode. */\n  mode(): CursorMode {\n    return this.#mode\n  }\n\n  /** Whether the cursor is currently in the \"text\" state (hidden block). */\n  isBlinkHidden(): boolean {\n    return this.#blink\n  }\n\n  /** Whether this cursor currently has focus. */\n  isFocused(): boolean {\n    return this.#focus\n  }\n\n  /** Kick off blinking at init (emits InitialBlinkMsg). */\n  initBlink(): Cmd<InitialBlinkMsg> {\n    return () => new InitialBlinkMsg()\n  }\n\n  /** Command to schedule the next blink toggle. */\n  tickBlink(): [CursorModel, Cmd<BlinkMsg>] {\n    const nextTag = this.#tag + 1\n    const id = this.#id\n    const speed = this.blinkSpeed\n    const next = this.#withState({ ...this.#state(), tag: nextTag })\n    const cmd: Cmd<BlinkMsg> = tick(\n      speed,\n      (time: Date) => new BlinkMsg(id, nextTag, time),\n    )\n    return [next, cmd]\n  }\n\n  /** Set the character under the cursor. */\n  withChar(char: string): CursorModel {\n    return this.#withState(this.#state(), { char })\n  }\n\n  /** Set the cursor mode. Returns a new model and optional blink command. */\n  withMode(mode: CursorMode): [CursorModel, Cmd<Msg>] {\n    const bounded =\n      mode === CursorMode.Blink ||\n      mode === CursorMode.Static ||\n      mode === CursorMode.Hidden\n        ? mode\n        : CursorMode.Blink\n\n    const blink =\n      bounded === CursorMode.Hidden || !this.#focus ? true : this.#blink\n    const next = this.#withState({ ...this.#state(), blink, mode: bounded })\n\n    if (bounded === CursorMode.Blink && this.#focus) {\n      const [scheduled, cmd] = next.tickBlink()\n      return [scheduled, cmd]\n    }\n    return [next, null]\n  }\n\n  /** Focus the cursor. Returns new model and optional blink command. */\n  focus(): [CursorModel, Cmd<Msg>] {\n    const blink = this.#mode === CursorMode.Hidden ? true : this.#blink\n    const next = this.#withState({ ...this.#state(), blink, focus: true })\n    if (this.#mode === CursorMode.Blink) {\n      const [scheduled, cmd] = next.tickBlink()\n      return [scheduled, cmd]\n    }\n    return [next, null]\n  }\n\n  /** Blur the cursor. */\n  blur(): CursorModel {\n    return this.#withState({ ...this.#state(), blink: true, focus: false })\n  }\n\n  /**\n   * Update the cursor model with an incoming message.\n   * Returns a new model and an optional command.\n   */\n  update(msg: Msg): [CursorModel, Cmd<Msg>] {\n    if (msg instanceof InitialBlinkMsg) {\n      if (this.#mode !== CursorMode.Blink || !this.#focus) {\n        return [this, null]\n      }\n      const [next, cmd] = this.tickBlink()\n      return [next, cmd as Cmd<Msg>]\n    }\n\n    if (msg instanceof FocusMsg) {\n      return this.focus()\n    }\n\n    if (msg instanceof BlurMsg) {\n      const next = this.blur()\n      return [next, null]\n    }\n\n    if (msg instanceof BlinkMsg) {\n      // Is this model blink-able and expecting this tick?\n      if (this.#mode !== CursorMode.Blink || !this.#focus) {\n        return [this, null]\n      }\n      if (msg.id !== this.#id || msg.tag !== this.#tag) {\n        return [this, null]\n      }\n\n      const toggled = this.#withState({ ...this.#state(), blink: !this.#blink })\n      const [next, cmd] = toggled.tickBlink()\n      return [next, cmd as Cmd<Msg>]\n    }\n\n    return [this, null]\n  }\n\n  /** Render the cursor. */\n  view(): string {\n    const char = this.char\n    if (this.#blink) {\n      return this.textStyle.inline(true).render(char)\n    }\n    return this.style.inline(true).render(char)\n  }\n\n  #state(): CursorState {\n    return {\n      id: this.#id,\n      tag: this.#tag,\n      blink: this.#blink,\n      focus: this.#focus,\n      mode: this.#mode,\n    }\n  }\n\n  #withState(state: CursorState, overrides?: { char?: string }): CursorModel {\n    return new CursorModel(\n      {\n        blinkSpeed: this.blinkSpeed,\n        style: this.style,\n        textStyle: this.textStyle,\n        char: overrides?.char ?? this.char,\n        mode: state.mode,\n        focused: state.focus,\n      },\n      state,\n    )\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,87 @@
+import { Cmd, Msg } from '@boba-cli/tea';
+import { Style } from '@boba-cli/chapstick';
+
+/**
+ * @public
+ */
+declare class InitialBlinkMsg {
+    readonly _tag = "cursor:init-blink";
+}
+/**
+ * @public
+ */
+declare class BlinkMsg {
+    readonly id: number;
+    readonly tag: number;
+    readonly time: Date;
+    readonly _tag = "cursor:blink";
+    constructor(id: number, tag: number, time: Date);
+}
+
+/** Available cursor behaviors. @public */
+declare enum CursorMode {
+    Blink = "blink",
+    Static = "static",
+    Hidden = "hidden"
+}
+/** Options for creating a CursorModel. @public */
+interface CursorOptions {
+    blinkSpeed?: number;
+    style?: Style;
+    textStyle?: Style;
+    char?: string;
+    mode?: CursorMode;
+    focused?: boolean;
+}
+type CursorState = {
+    id: number;
+    tag: number;
+    blink: boolean;
+    focus: boolean;
+    mode: CursorMode;
+};
+/**
+ * Cursor component model.
+ *
+ * Use `tickBlink()` to start blinking, or handle `InitialBlinkMsg` from `initBlink()`.
+ * Handle `BlinkMsg`, `FocusMsg`, and `BlurMsg` in your update loop.
+ *
+ * @public
+ */
+declare class CursorModel {
+    #private;
+    readonly blinkSpeed: number;
+    readonly style: Style;
+    readonly textStyle: Style;
+    readonly char: string;
+    constructor(options?: CursorOptions, state?: CursorState);
+    /** Unique ID for this cursor (for message routing). */
+    id(): number;
+    /** Current cursor mode. */
+    mode(): CursorMode;
+    /** Whether the cursor is currently in the "text" state (hidden block). */
+    isBlinkHidden(): boolean;
+    /** Whether this cursor currently has focus. */
+    isFocused(): boolean;
+    /** Kick off blinking at init (emits InitialBlinkMsg). */
+    initBlink(): Cmd<InitialBlinkMsg>;
+    /** Command to schedule the next blink toggle. */
+    tickBlink(): [CursorModel, Cmd<BlinkMsg>];
+    /** Set the character under the cursor. */
+    withChar(char: string): CursorModel;
+    /** Set the cursor mode. Returns a new model and optional blink command. */
+    withMode(mode: CursorMode): [CursorModel, Cmd<Msg>];
+    /** Focus the cursor. Returns new model and optional blink command. */
+    focus(): [CursorModel, Cmd<Msg>];
+    /** Blur the cursor. */
+    blur(): CursorModel;
+    /**
+     * Update the cursor model with an incoming message.
+     * Returns a new model and an optional command.
+     */
+    update(msg: Msg): [CursorModel, Cmd<Msg>];
+    /** Render the cursor. */
+    view(): string;
+}
+
+export { BlinkMsg, CursorMode, CursorModel, type CursorOptions, InitialBlinkMsg };

package/dist/index.d.ts

@@ -0,0 +1,87 @@
+import { Cmd, Msg } from '@boba-cli/tea';
+import { Style } from '@boba-cli/chapstick';
+
+/**
+ * @public
+ */
+declare class InitialBlinkMsg {
+    readonly _tag = "cursor:init-blink";
+}
+/**
+ * @public
+ */
+declare class BlinkMsg {
+    readonly id: number;
+    readonly tag: number;
+    readonly time: Date;
+    readonly _tag = "cursor:blink";
+    constructor(id: number, tag: number, time: Date);
+}
+
+/** Available cursor behaviors. @public */
+declare enum CursorMode {
+    Blink = "blink",
+    Static = "static",
+    Hidden = "hidden"
+}
+/** Options for creating a CursorModel. @public */
+interface CursorOptions {
+    blinkSpeed?: number;
+    style?: Style;
+    textStyle?: Style;
+    char?: string;
+    mode?: CursorMode;
+    focused?: boolean;
+}
+type CursorState = {
+    id: number;
+    tag: number;
+    blink: boolean;
+    focus: boolean;
+    mode: CursorMode;
+};
+/**
+ * Cursor component model.
+ *
+ * Use `tickBlink()` to start blinking, or handle `InitialBlinkMsg` from `initBlink()`.
+ * Handle `BlinkMsg`, `FocusMsg`, and `BlurMsg` in your update loop.
+ *
+ * @public
+ */
+declare class CursorModel {
+    #private;
+    readonly blinkSpeed: number;
+    readonly style: Style;
+    readonly textStyle: Style;
+    readonly char: string;
+    constructor(options?: CursorOptions, state?: CursorState);
+    /** Unique ID for this cursor (for message routing). */
+    id(): number;
+    /** Current cursor mode. */
+    mode(): CursorMode;
+    /** Whether the cursor is currently in the "text" state (hidden block). */
+    isBlinkHidden(): boolean;
+    /** Whether this cursor currently has focus. */
+    isFocused(): boolean;
+    /** Kick off blinking at init (emits InitialBlinkMsg). */
+    initBlink(): Cmd<InitialBlinkMsg>;
+    /** Command to schedule the next blink toggle. */
+    tickBlink(): [CursorModel, Cmd<BlinkMsg>];
+    /** Set the character under the cursor. */
+    withChar(char: string): CursorModel;
+    /** Set the cursor mode. Returns a new model and optional blink command. */
+    withMode(mode: CursorMode): [CursorModel, Cmd<Msg>];
+    /** Focus the cursor. Returns new model and optional blink command. */
+    focus(): [CursorModel, Cmd<Msg>];
+    /** Blur the cursor. */
+    blur(): CursorModel;
+    /**
+     * Update the cursor model with an incoming message.
+     * Returns a new model and an optional command.
+     */
+    update(msg: Msg): [CursorModel, Cmd<Msg>];
+    /** Render the cursor. */
+    view(): string;
+}
+
+export { BlinkMsg, CursorMode, CursorModel, type CursorOptions, InitialBlinkMsg };

package/dist/index.js

@@ -0,0 +1,179 @@
+import { tick, FocusMsg, BlurMsg } from '@boba-cli/tea';
+import { Style } from '@boba-cli/chapstick';
+
+// src/model.ts
+
+// src/messages.ts
+var InitialBlinkMsg = class {
+  _tag = "cursor:init-blink";
+};
+var BlinkMsg = class {
+  constructor(id, tag, time) {
+    this.id = id;
+    this.tag = tag;
+    this.time = time;
+  }
+  _tag = "cursor:blink";
+};
+
+// src/model.ts
+var defaultBlinkSpeed = 530;
+var lastId = 0;
+function nextId() {
+  return ++lastId;
+}
+var CursorMode = /* @__PURE__ */ ((CursorMode2) => {
+  CursorMode2["Blink"] = "blink";
+  CursorMode2["Static"] = "static";
+  CursorMode2["Hidden"] = "hidden";
+  return CursorMode2;
+})(CursorMode || {});
+var CursorModel = class _CursorModel {
+  blinkSpeed;
+  style;
+  textStyle;
+  char;
+  #id;
+  #tag;
+  #blink;
+  #focus;
+  #mode;
+  constructor(options = {}, state) {
+    this.blinkSpeed = options.blinkSpeed ?? defaultBlinkSpeed;
+    this.style = options.style ?? new Style();
+    this.textStyle = options.textStyle ?? new Style();
+    this.char = options.char ?? " ";
+    this.#id = state?.id ?? nextId();
+    this.#tag = state?.tag ?? 0;
+    this.#blink = state?.blink ?? true;
+    this.#focus = state?.focus ?? false;
+    this.#mode = state?.mode ?? options.mode ?? "blink" /* Blink */;
+  }
+  /** Unique ID for this cursor (for message routing). */
+  id() {
+    return this.#id;
+  }
+  /** Current cursor mode. */
+  mode() {
+    return this.#mode;
+  }
+  /** Whether the cursor is currently in the "text" state (hidden block). */
+  isBlinkHidden() {
+    return this.#blink;
+  }
+  /** Whether this cursor currently has focus. */
+  isFocused() {
+    return this.#focus;
+  }
+  /** Kick off blinking at init (emits InitialBlinkMsg). */
+  initBlink() {
+    return () => new InitialBlinkMsg();
+  }
+  /** Command to schedule the next blink toggle. */
+  tickBlink() {
+    const nextTag = this.#tag + 1;
+    const id = this.#id;
+    const speed = this.blinkSpeed;
+    const next = this.#withState({ ...this.#state(), tag: nextTag });
+    const cmd = tick(
+      speed,
+      (time) => new BlinkMsg(id, nextTag, time)
+    );
+    return [next, cmd];
+  }
+  /** Set the character under the cursor. */
+  withChar(char) {
+    return this.#withState(this.#state(), { char });
+  }
+  /** Set the cursor mode. Returns a new model and optional blink command. */
+  withMode(mode) {
+    const bounded = mode === "blink" /* Blink */ || mode === "static" /* Static */ || mode === "hidden" /* Hidden */ ? mode : "blink" /* Blink */;
+    const blink = bounded === "hidden" /* Hidden */ || !this.#focus ? true : this.#blink;
+    const next = this.#withState({ ...this.#state(), blink, mode: bounded });
+    if (bounded === "blink" /* Blink */ && this.#focus) {
+      const [scheduled, cmd] = next.tickBlink();
+      return [scheduled, cmd];
+    }
+    return [next, null];
+  }
+  /** Focus the cursor. Returns new model and optional blink command. */
+  focus() {
+    const blink = this.#mode === "hidden" /* Hidden */ ? true : this.#blink;
+    const next = this.#withState({ ...this.#state(), blink, focus: true });
+    if (this.#mode === "blink" /* Blink */) {
+      const [scheduled, cmd] = next.tickBlink();
+      return [scheduled, cmd];
+    }
+    return [next, null];
+  }
+  /** Blur the cursor. */
+  blur() {
+    return this.#withState({ ...this.#state(), blink: true, focus: false });
+  }
+  /**
+   * Update the cursor model with an incoming message.
+   * Returns a new model and an optional command.
+   */
+  update(msg) {
+    if (msg instanceof InitialBlinkMsg) {
+      if (this.#mode !== "blink" /* Blink */ || !this.#focus) {
+        return [this, null];
+      }
+      const [next, cmd] = this.tickBlink();
+      return [next, cmd];
+    }
+    if (msg instanceof FocusMsg) {
+      return this.focus();
+    }
+    if (msg instanceof BlurMsg) {
+      const next = this.blur();
+      return [next, null];
+    }
+    if (msg instanceof BlinkMsg) {
+      if (this.#mode !== "blink" /* Blink */ || !this.#focus) {
+        return [this, null];
+      }
+      if (msg.id !== this.#id || msg.tag !== this.#tag) {
+        return [this, null];
+      }
+      const toggled = this.#withState({ ...this.#state(), blink: !this.#blink });
+      const [next, cmd] = toggled.tickBlink();
+      return [next, cmd];
+    }
+    return [this, null];
+  }
+  /** Render the cursor. */
+  view() {
+    const char = this.char;
+    if (this.#blink) {
+      return this.textStyle.inline(true).render(char);
+    }
+    return this.style.inline(true).render(char);
+  }
+  #state() {
+    return {
+      id: this.#id,
+      tag: this.#tag,
+      blink: this.#blink,
+      focus: this.#focus,
+      mode: this.#mode
+    };
+  }
+  #withState(state, overrides) {
+    return new _CursorModel(
+      {
+        blinkSpeed: this.blinkSpeed,
+        style: this.style,
+        textStyle: this.textStyle,
+        char: overrides?.char ?? this.char,
+        mode: state.mode,
+        focused: state.focus
+      },
+      state
+    );
+  }
+};
+
+export { BlinkMsg, CursorMode, CursorModel, InitialBlinkMsg };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/messages.ts","../src/model.ts"],"names":["CursorMode"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * @public\n */\nexport class InitialBlinkMsg {\n  readonly _tag = 'cursor:init-blink'\n}\n\n/**\n * @public\n */\nexport class BlinkMsg {\n  readonly _tag = 'cursor:blink'\n  constructor(\n    public readonly id: number,\n    public readonly tag: number,\n    public readonly time: Date,\n  ) {}\n}\n","import { tick, type Cmd, type Msg, FocusMsg, BlurMsg } from '@boba-cli/tea'\nimport { Style } from '@boba-cli/chapstick'\nimport { BlinkMsg, InitialBlinkMsg } from './messages.js'\n\nconst defaultBlinkSpeed = 530 // ms\n\n// Module-level ID counter for unique cursor identification\nlet lastId = 0\nfunction nextId(): number {\n  return ++lastId\n}\n\n/** Available cursor behaviors. @public */\nexport enum CursorMode {\n  Blink = 'blink',\n  Static = 'static',\n  Hidden = 'hidden',\n}\n\n/** Options for creating a CursorModel. @public */\nexport interface CursorOptions {\n  blinkSpeed?: number\n  style?: Style\n  textStyle?: Style\n  char?: string\n  mode?: CursorMode\n  focused?: boolean\n}\n\ntype CursorState = {\n  id: number\n  tag: number\n  blink: boolean\n  focus: boolean\n  mode: CursorMode\n}\n\n/**\n * Cursor component model.\n *\n * Use `tickBlink()` to start blinking, or handle `InitialBlinkMsg` from `initBlink()`.\n * Handle `BlinkMsg`, `FocusMsg`, and `BlurMsg` in your update loop.\n *\n * @public\n */\nexport class CursorModel {\n  readonly blinkSpeed: number\n  readonly style: Style\n  readonly textStyle: Style\n  readonly char: string\n  readonly #id: number\n  readonly #tag: number\n  readonly #blink: boolean\n  readonly #focus: boolean\n  readonly #mode: CursorMode\n\n  constructor(options: CursorOptions = {}, state?: CursorState) {\n    this.blinkSpeed = options.blinkSpeed ?? defaultBlinkSpeed\n    this.style = options.style ?? new Style()\n    this.textStyle = options.textStyle ?? new Style()\n    this.char = options.char ?? ' '\n    this.#id = state?.id ?? nextId()\n    this.#tag = state?.tag ?? 0\n    this.#blink = state?.blink ?? true\n    this.#focus = state?.focus ?? false\n    this.#mode = state?.mode ?? options.mode ?? CursorMode.Blink\n  }\n\n  /** Unique ID for this cursor (for message routing). */\n  id(): number {\n    return this.#id\n  }\n\n  /** Current cursor mode. */\n  mode(): CursorMode {\n    return this.#mode\n  }\n\n  /** Whether the cursor is currently in the \"text\" state (hidden block). */\n  isBlinkHidden(): boolean {\n    return this.#blink\n  }\n\n  /** Whether this cursor currently has focus. */\n  isFocused(): boolean {\n    return this.#focus\n  }\n\n  /** Kick off blinking at init (emits InitialBlinkMsg). */\n  initBlink(): Cmd<InitialBlinkMsg> {\n    return () => new InitialBlinkMsg()\n  }\n\n  /** Command to schedule the next blink toggle. */\n  tickBlink(): [CursorModel, Cmd<BlinkMsg>] {\n    const nextTag = this.#tag + 1\n    const id = this.#id\n    const speed = this.blinkSpeed\n    const next = this.#withState({ ...this.#state(), tag: nextTag })\n    const cmd: Cmd<BlinkMsg> = tick(\n      speed,\n      (time: Date) => new BlinkMsg(id, nextTag, time),\n    )\n    return [next, cmd]\n  }\n\n  /** Set the character under the cursor. */\n  withChar(char: string): CursorModel {\n    return this.#withState(this.#state(), { char })\n  }\n\n  /** Set the cursor mode. Returns a new model and optional blink command. */\n  withMode(mode: CursorMode): [CursorModel, Cmd<Msg>] {\n    const bounded =\n      mode === CursorMode.Blink ||\n      mode === CursorMode.Static ||\n      mode === CursorMode.Hidden\n        ? mode\n        : CursorMode.Blink\n\n    const blink =\n      bounded === CursorMode.Hidden || !this.#focus ? true : this.#blink\n    const next = this.#withState({ ...this.#state(), blink, mode: bounded })\n\n    if (bounded === CursorMode.Blink && this.#focus) {\n      const [scheduled, cmd] = next.tickBlink()\n      return [scheduled, cmd]\n    }\n    return [next, null]\n  }\n\n  /** Focus the cursor. Returns new model and optional blink command. */\n  focus(): [CursorModel, Cmd<Msg>] {\n    const blink = this.#mode === CursorMode.Hidden ? true : this.#blink\n    const next = this.#withState({ ...this.#state(), blink, focus: true })\n    if (this.#mode === CursorMode.Blink) {\n      const [scheduled, cmd] = next.tickBlink()\n      return [scheduled, cmd]\n    }\n    return [next, null]\n  }\n\n  /** Blur the cursor. */\n  blur(): CursorModel {\n    return this.#withState({ ...this.#state(), blink: true, focus: false })\n  }\n\n  /**\n   * Update the cursor model with an incoming message.\n   * Returns a new model and an optional command.\n   */\n  update(msg: Msg): [CursorModel, Cmd<Msg>] {\n    if (msg instanceof InitialBlinkMsg) {\n      if (this.#mode !== CursorMode.Blink || !this.#focus) {\n        return [this, null]\n      }\n      const [next, cmd] = this.tickBlink()\n      return [next, cmd as Cmd<Msg>]\n    }\n\n    if (msg instanceof FocusMsg) {\n      return this.focus()\n    }\n\n    if (msg instanceof BlurMsg) {\n      const next = this.blur()\n      return [next, null]\n    }\n\n    if (msg instanceof BlinkMsg) {\n      // Is this model blink-able and expecting this tick?\n      if (this.#mode !== CursorMode.Blink || !this.#focus) {\n        return [this, null]\n      }\n      if (msg.id !== this.#id || msg.tag !== this.#tag) {\n        return [this, null]\n      }\n\n      const toggled = this.#withState({ ...this.#state(), blink: !this.#blink })\n      const [next, cmd] = toggled.tickBlink()\n      return [next, cmd as Cmd<Msg>]\n    }\n\n    return [this, null]\n  }\n\n  /** Render the cursor. */\n  view(): string {\n    const char = this.char\n    if (this.#blink) {\n      return this.textStyle.inline(true).render(char)\n    }\n    return this.style.inline(true).render(char)\n  }\n\n  #state(): CursorState {\n    return {\n      id: this.#id,\n      tag: this.#tag,\n      blink: this.#blink,\n      focus: this.#focus,\n      mode: this.#mode,\n    }\n  }\n\n  #withState(state: CursorState, overrides?: { char?: string }): CursorModel {\n    return new CursorModel(\n      {\n        blinkSpeed: this.blinkSpeed,\n        style: this.style,\n        textStyle: this.textStyle,\n        char: overrides?.char ?? this.char,\n        mode: state.mode,\n        focused: state.focus,\n      },\n      state,\n    )\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@boba-cli/cursor",
+  "description": "Cursor component for Boba terminal UIs",
+  "version": "0.1.0-alpha.2",
+  "dependencies": {
+    "@boba-cli/chapstick": "0.1.0-alpha.2",
+    "@boba-cli/tea": "0.1.0-alpha.1"
+  },
+  "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"
+  }
+}