@boba-cli/paginator 0.1.0-alpha.1

package/README.md

@@ -0,0 +1,20 @@
+# @boba-cli/paginator
+
+Pagination state management and rendering for Boba terminal UIs. Ported from the Charm `bubbles/paginator` component.
+
+<img src="../../examples/paginator-demo.gif" width="950" alt="Paginator component demo" />
+
+## Usage
+
+```ts
+import { PaginatorModel, PaginatorType } from '@boba-cli/paginator'
+
+const paginator = PaginatorModel.new({
+  type: PaginatorType.Dots,
+  perPage: 10,
+})
+
+const next = paginator.setTotalPages(items.length)
+const [start, end] = next.getSliceBounds(items.length)
+const visibleItems = items.slice(start, end)
+```

package/dist/index.cjs

@@ -0,0 +1,138 @@
+'use strict';
+
+var key = require('@boba-cli/key');
+var tea = require('@boba-cli/tea');
+
+// src/model.ts
+var PaginatorType = /* @__PURE__ */ ((PaginatorType2) => {
+  PaginatorType2["Arabic"] = "arabic";
+  PaginatorType2["Dots"] = "dots";
+  return PaginatorType2;
+})(PaginatorType || {});
+var defaultKeyMap = {
+  prevPage: key.newBinding({ keys: ["pgup", "left", "h"] }),
+  nextPage: key.newBinding({ keys: ["pgdown", "right", "l"] })
+};
+
+// src/model.ts
+var PaginatorModel = class _PaginatorModel {
+  type;
+  page;
+  perPage;
+  totalPages;
+  activeDot;
+  inactiveDot;
+  arabicFormat;
+  keyMap;
+  constructor(options = {}) {
+    this.type = options.type ?? "arabic" /* Arabic */;
+    this.page = Math.max(0, options.page ?? 0);
+    this.perPage = Math.max(1, options.perPage ?? 1);
+    this.totalPages = Math.max(1, options.totalPages ?? 1);
+    this.activeDot = options.activeDot ?? "\u2022";
+    this.inactiveDot = options.inactiveDot ?? "\u25CB";
+    this.arabicFormat = options.arabicFormat ?? "%d/%d";
+    this.keyMap = options.keyMap ?? defaultKeyMap;
+  }
+  /** Create a new paginator with defaults. */
+  static new(options = {}) {
+    return new _PaginatorModel(options);
+  }
+  /** Set total pages based on item count (rounded up). */
+  setTotalPages(items) {
+    if (items < 1) {
+      return this;
+    }
+    const totalPages = Math.max(1, Math.ceil(items / this.perPage));
+    return this.with({ totalPages });
+  }
+  /** Number of items on the current page for a given total. */
+  itemsOnPage(totalItems) {
+    if (totalItems < 1) {
+      return 0;
+    }
+    const [start, end] = this.getSliceBounds(totalItems);
+    return end - start;
+  }
+  /** Slice bounds for the current page, clamped to length. */
+  getSliceBounds(length) {
+    const start = this.page * this.perPage;
+    const end = Math.min(start + this.perPage, length);
+    return [start, end];
+  }
+  /** Move to previous page (no-op on first page). */
+  prevPage() {
+    if (this.page <= 0) {
+      return this;
+    }
+    return this.with({ page: this.page - 1 });
+  }
+  /** Move to next page (no-op on last page). */
+  nextPage() {
+    if (this.onLastPage()) {
+      return this;
+    }
+    return this.with({ page: this.page + 1 });
+  }
+  /** Whether the current page is the first page. */
+  onFirstPage() {
+    return this.page === 0;
+  }
+  /** Whether the current page is the last page. */
+  onLastPage() {
+    return this.page >= this.totalPages - 1;
+  }
+  /** Handle Tea messages (responds to KeyMsg). */
+  update(msg) {
+    if (!(msg instanceof tea.KeyMsg)) {
+      return [this, null];
+    }
+    if (key.matches(msg, this.keyMap.nextPage)) {
+      return [this.nextPage(), null];
+    }
+    if (key.matches(msg, this.keyMap.prevPage)) {
+      return [this.prevPage(), null];
+    }
+    return [this, null];
+  }
+  /** Render pagination. */
+  view() {
+    switch (this.type) {
+      case "dots" /* Dots */:
+        return this.dotsView();
+      case "arabic" /* Arabic */:
+      default:
+        return this.arabicView();
+    }
+  }
+  dotsView() {
+    let s = "";
+    for (let i = 0; i < this.totalPages; i++) {
+      s += i === this.page ? this.activeDot : this.inactiveDot;
+    }
+    return s;
+  }
+  arabicView() {
+    const current = this.page + 1;
+    return this.arabicFormat.replace("%d", String(current)).replace("%d", String(this.totalPages));
+  }
+  with(patch) {
+    return new _PaginatorModel({
+      type: this.type,
+      page: this.page,
+      perPage: this.perPage,
+      totalPages: this.totalPages,
+      activeDot: this.activeDot,
+      inactiveDot: this.inactiveDot,
+      arabicFormat: this.arabicFormat,
+      keyMap: this.keyMap,
+      ...patch
+    });
+  }
+};
+
+exports.PaginatorModel = PaginatorModel;
+exports.PaginatorType = PaginatorType;
+exports.defaultKeyMap = defaultKeyMap;
+//# sourceMappingURL=index.cjs.map
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/model.ts"],"names":["PaginatorType","newBinding","KeyMsg","matches"],"mappings":"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","file":"index.cjs","sourcesContent":["import { Binding, newBinding } from '@boba-cli/key'\n\n/**\n * Pagination display style.\n * @public\n */\nexport enum PaginatorType {\n  Arabic = 'arabic',\n  Dots = 'dots',\n}\n\n/**\n * Key bindings for paginator navigation.\n * @public\n */\nexport interface KeyMap {\n  prevPage: Binding\n  nextPage: Binding\n}\n\n/**\n * Default paginator key bindings.\n * @public\n */\nexport const defaultKeyMap: KeyMap = {\n  prevPage: newBinding({ keys: ['pgup', 'left', 'h'] }),\n  nextPage: newBinding({ keys: ['pgdown', 'right', 'l'] }),\n}\n","import { matches } from '@boba-cli/key'\nimport { KeyMsg, type Cmd, type Msg } from '@boba-cli/tea'\nimport { defaultKeyMap, PaginatorType, type KeyMap } from './types.js'\n\n/**\n * Options for creating a paginator.\n * @public\n */\nexport interface PaginatorOptions {\n  type?: PaginatorType\n  page?: number\n  perPage?: number\n  totalPages?: number\n  activeDot?: string\n  inactiveDot?: string\n  arabicFormat?: string\n  keyMap?: KeyMap\n}\n\n/**\n * Pagination state and rendering.\n * @public\n */\nexport class PaginatorModel {\n  readonly type: PaginatorType\n  readonly page: number\n  readonly perPage: number\n  readonly totalPages: number\n  readonly activeDot: string\n  readonly inactiveDot: string\n  readonly arabicFormat: string\n  readonly keyMap: KeyMap\n\n  private constructor(options: PaginatorOptions = {}) {\n    this.type = options.type ?? PaginatorType.Arabic\n    this.page = Math.max(0, options.page ?? 0)\n    this.perPage = Math.max(1, options.perPage ?? 1)\n    this.totalPages = Math.max(1, options.totalPages ?? 1)\n    this.activeDot = options.activeDot ?? '•'\n    this.inactiveDot = options.inactiveDot ?? '○'\n    this.arabicFormat = options.arabicFormat ?? '%d/%d'\n    this.keyMap = options.keyMap ?? defaultKeyMap\n  }\n\n  /** Create a new paginator with defaults. */\n  static new(options: PaginatorOptions = {}): PaginatorModel {\n    return new PaginatorModel(options)\n  }\n\n  /** Set total pages based on item count (rounded up). */\n  setTotalPages(items: number): PaginatorModel {\n    if (items < 1) {\n      return this\n    }\n    const totalPages = Math.max(1, Math.ceil(items / this.perPage))\n    return this.with({ totalPages })\n  }\n\n  /** Number of items on the current page for a given total. */\n  itemsOnPage(totalItems: number): number {\n    if (totalItems < 1) {\n      return 0\n    }\n    const [start, end] = this.getSliceBounds(totalItems)\n    return end - start\n  }\n\n  /** Slice bounds for the current page, clamped to length. */\n  getSliceBounds(length: number): [number, number] {\n    const start = this.page * this.perPage\n    const end = Math.min(start + this.perPage, length)\n    return [start, end]\n  }\n\n  /** Move to previous page (no-op on first page). */\n  prevPage(): PaginatorModel {\n    if (this.page <= 0) {\n      return this\n    }\n    return this.with({ page: this.page - 1 })\n  }\n\n  /** Move to next page (no-op on last page). */\n  nextPage(): PaginatorModel {\n    if (this.onLastPage()) {\n      return this\n    }\n    return this.with({ page: this.page + 1 })\n  }\n\n  /** Whether the current page is the first page. */\n  onFirstPage(): boolean {\n    return this.page === 0\n  }\n\n  /** Whether the current page is the last page. */\n  onLastPage(): boolean {\n    return this.page >= this.totalPages - 1\n  }\n\n  /** Handle Tea messages (responds to KeyMsg). */\n  update(msg: Msg): [PaginatorModel, Cmd<Msg>] {\n    if (!(msg instanceof KeyMsg)) {\n      return [this, null]\n    }\n\n    if (matches(msg, this.keyMap.nextPage)) {\n      return [this.nextPage(), null]\n    }\n    if (matches(msg, this.keyMap.prevPage)) {\n      return [this.prevPage(), null]\n    }\n\n    return [this, null]\n  }\n\n  /** Render pagination. */\n  view(): string {\n    switch (this.type) {\n      case PaginatorType.Dots:\n        return this.dotsView()\n      case PaginatorType.Arabic:\n      default:\n        return this.arabicView()\n    }\n  }\n\n  private dotsView(): string {\n    let s = ''\n    for (let i = 0; i < this.totalPages; i++) {\n      s += i === this.page ? this.activeDot : this.inactiveDot\n    }\n    return s\n  }\n\n  private arabicView(): string {\n    const current = this.page + 1\n    return this.arabicFormat\n      .replace('%d', String(current))\n      .replace('%d', String(this.totalPages))\n  }\n\n  private with(patch: Partial<PaginatorOptions>): PaginatorModel {\n    return new PaginatorModel({\n      type: this.type,\n      page: this.page,\n      perPage: this.perPage,\n      totalPages: this.totalPages,\n      activeDot: this.activeDot,\n      inactiveDot: this.inactiveDot,\n      arabicFormat: this.arabicFormat,\n      keyMap: this.keyMap,\n      ...patch,\n    })\n  }\n}\n"]}

package/dist/index.d.cts

@@ -0,0 +1,79 @@
+import { Msg, Cmd } from '@boba-cli/tea';
+import { Binding } from '@boba-cli/key';
+
+/**
+ * Pagination display style.
+ * @public
+ */
+declare enum PaginatorType {
+    Arabic = "arabic",
+    Dots = "dots"
+}
+/**
+ * Key bindings for paginator navigation.
+ * @public
+ */
+interface KeyMap {
+    prevPage: Binding;
+    nextPage: Binding;
+}
+/**
+ * Default paginator key bindings.
+ * @public
+ */
+declare const defaultKeyMap: KeyMap;
+
+/**
+ * Options for creating a paginator.
+ * @public
+ */
+interface PaginatorOptions {
+    type?: PaginatorType;
+    page?: number;
+    perPage?: number;
+    totalPages?: number;
+    activeDot?: string;
+    inactiveDot?: string;
+    arabicFormat?: string;
+    keyMap?: KeyMap;
+}
+/**
+ * Pagination state and rendering.
+ * @public
+ */
+declare class PaginatorModel {
+    readonly type: PaginatorType;
+    readonly page: number;
+    readonly perPage: number;
+    readonly totalPages: number;
+    readonly activeDot: string;
+    readonly inactiveDot: string;
+    readonly arabicFormat: string;
+    readonly keyMap: KeyMap;
+    private constructor();
+    /** Create a new paginator with defaults. */
+    static new(options?: PaginatorOptions): PaginatorModel;
+    /** Set total pages based on item count (rounded up). */
+    setTotalPages(items: number): PaginatorModel;
+    /** Number of items on the current page for a given total. */
+    itemsOnPage(totalItems: number): number;
+    /** Slice bounds for the current page, clamped to length. */
+    getSliceBounds(length: number): [number, number];
+    /** Move to previous page (no-op on first page). */
+    prevPage(): PaginatorModel;
+    /** Move to next page (no-op on last page). */
+    nextPage(): PaginatorModel;
+    /** Whether the current page is the first page. */
+    onFirstPage(): boolean;
+    /** Whether the current page is the last page. */
+    onLastPage(): boolean;
+    /** Handle Tea messages (responds to KeyMsg). */
+    update(msg: Msg): [PaginatorModel, Cmd<Msg>];
+    /** Render pagination. */
+    view(): string;
+    private dotsView;
+    private arabicView;
+    private with;
+}
+
+export { type KeyMap, PaginatorModel, type PaginatorOptions, PaginatorType, defaultKeyMap };

package/dist/index.d.ts

@@ -0,0 +1,79 @@
+import { Msg, Cmd } from '@boba-cli/tea';
+import { Binding } from '@boba-cli/key';
+
+/**
+ * Pagination display style.
+ * @public
+ */
+declare enum PaginatorType {
+    Arabic = "arabic",
+    Dots = "dots"
+}
+/**
+ * Key bindings for paginator navigation.
+ * @public
+ */
+interface KeyMap {
+    prevPage: Binding;
+    nextPage: Binding;
+}
+/**
+ * Default paginator key bindings.
+ * @public
+ */
+declare const defaultKeyMap: KeyMap;
+
+/**
+ * Options for creating a paginator.
+ * @public
+ */
+interface PaginatorOptions {
+    type?: PaginatorType;
+    page?: number;
+    perPage?: number;
+    totalPages?: number;
+    activeDot?: string;
+    inactiveDot?: string;
+    arabicFormat?: string;
+    keyMap?: KeyMap;
+}
+/**
+ * Pagination state and rendering.
+ * @public
+ */
+declare class PaginatorModel {
+    readonly type: PaginatorType;
+    readonly page: number;
+    readonly perPage: number;
+    readonly totalPages: number;
+    readonly activeDot: string;
+    readonly inactiveDot: string;
+    readonly arabicFormat: string;
+    readonly keyMap: KeyMap;
+    private constructor();
+    /** Create a new paginator with defaults. */
+    static new(options?: PaginatorOptions): PaginatorModel;
+    /** Set total pages based on item count (rounded up). */
+    setTotalPages(items: number): PaginatorModel;
+    /** Number of items on the current page for a given total. */
+    itemsOnPage(totalItems: number): number;
+    /** Slice bounds for the current page, clamped to length. */
+    getSliceBounds(length: number): [number, number];
+    /** Move to previous page (no-op on first page). */
+    prevPage(): PaginatorModel;
+    /** Move to next page (no-op on last page). */
+    nextPage(): PaginatorModel;
+    /** Whether the current page is the first page. */
+    onFirstPage(): boolean;
+    /** Whether the current page is the last page. */
+    onLastPage(): boolean;
+    /** Handle Tea messages (responds to KeyMsg). */
+    update(msg: Msg): [PaginatorModel, Cmd<Msg>];
+    /** Render pagination. */
+    view(): string;
+    private dotsView;
+    private arabicView;
+    private with;
+}
+
+export { type KeyMap, PaginatorModel, type PaginatorOptions, PaginatorType, defaultKeyMap };

package/dist/index.js

@@ -0,0 +1,134 @@
+import { newBinding, matches } from '@boba-cli/key';
+import { KeyMsg } from '@boba-cli/tea';
+
+// src/model.ts
+var PaginatorType = /* @__PURE__ */ ((PaginatorType2) => {
+  PaginatorType2["Arabic"] = "arabic";
+  PaginatorType2["Dots"] = "dots";
+  return PaginatorType2;
+})(PaginatorType || {});
+var defaultKeyMap = {
+  prevPage: newBinding({ keys: ["pgup", "left", "h"] }),
+  nextPage: newBinding({ keys: ["pgdown", "right", "l"] })
+};
+
+// src/model.ts
+var PaginatorModel = class _PaginatorModel {
+  type;
+  page;
+  perPage;
+  totalPages;
+  activeDot;
+  inactiveDot;
+  arabicFormat;
+  keyMap;
+  constructor(options = {}) {
+    this.type = options.type ?? "arabic" /* Arabic */;
+    this.page = Math.max(0, options.page ?? 0);
+    this.perPage = Math.max(1, options.perPage ?? 1);
+    this.totalPages = Math.max(1, options.totalPages ?? 1);
+    this.activeDot = options.activeDot ?? "\u2022";
+    this.inactiveDot = options.inactiveDot ?? "\u25CB";
+    this.arabicFormat = options.arabicFormat ?? "%d/%d";
+    this.keyMap = options.keyMap ?? defaultKeyMap;
+  }
+  /** Create a new paginator with defaults. */
+  static new(options = {}) {
+    return new _PaginatorModel(options);
+  }
+  /** Set total pages based on item count (rounded up). */
+  setTotalPages(items) {
+    if (items < 1) {
+      return this;
+    }
+    const totalPages = Math.max(1, Math.ceil(items / this.perPage));
+    return this.with({ totalPages });
+  }
+  /** Number of items on the current page for a given total. */
+  itemsOnPage(totalItems) {
+    if (totalItems < 1) {
+      return 0;
+    }
+    const [start, end] = this.getSliceBounds(totalItems);
+    return end - start;
+  }
+  /** Slice bounds for the current page, clamped to length. */
+  getSliceBounds(length) {
+    const start = this.page * this.perPage;
+    const end = Math.min(start + this.perPage, length);
+    return [start, end];
+  }
+  /** Move to previous page (no-op on first page). */
+  prevPage() {
+    if (this.page <= 0) {
+      return this;
+    }
+    return this.with({ page: this.page - 1 });
+  }
+  /** Move to next page (no-op on last page). */
+  nextPage() {
+    if (this.onLastPage()) {
+      return this;
+    }
+    return this.with({ page: this.page + 1 });
+  }
+  /** Whether the current page is the first page. */
+  onFirstPage() {
+    return this.page === 0;
+  }
+  /** Whether the current page is the last page. */
+  onLastPage() {
+    return this.page >= this.totalPages - 1;
+  }
+  /** Handle Tea messages (responds to KeyMsg). */
+  update(msg) {
+    if (!(msg instanceof KeyMsg)) {
+      return [this, null];
+    }
+    if (matches(msg, this.keyMap.nextPage)) {
+      return [this.nextPage(), null];
+    }
+    if (matches(msg, this.keyMap.prevPage)) {
+      return [this.prevPage(), null];
+    }
+    return [this, null];
+  }
+  /** Render pagination. */
+  view() {
+    switch (this.type) {
+      case "dots" /* Dots */:
+        return this.dotsView();
+      case "arabic" /* Arabic */:
+      default:
+        return this.arabicView();
+    }
+  }
+  dotsView() {
+    let s = "";
+    for (let i = 0; i < this.totalPages; i++) {
+      s += i === this.page ? this.activeDot : this.inactiveDot;
+    }
+    return s;
+  }
+  arabicView() {
+    const current = this.page + 1;
+    return this.arabicFormat.replace("%d", String(current)).replace("%d", String(this.totalPages));
+  }
+  with(patch) {
+    return new _PaginatorModel({
+      type: this.type,
+      page: this.page,
+      perPage: this.perPage,
+      totalPages: this.totalPages,
+      activeDot: this.activeDot,
+      inactiveDot: this.inactiveDot,
+      arabicFormat: this.arabicFormat,
+      keyMap: this.keyMap,
+      ...patch
+    });
+  }
+};
+
+export { PaginatorModel, PaginatorType, defaultKeyMap };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/types.ts","../src/model.ts"],"names":["PaginatorType"],"mappings":"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","file":"index.js","sourcesContent":["import { Binding, newBinding } from '@boba-cli/key'\n\n/**\n * Pagination display style.\n * @public\n */\nexport enum PaginatorType {\n  Arabic = 'arabic',\n  Dots = 'dots',\n}\n\n/**\n * Key bindings for paginator navigation.\n * @public\n */\nexport interface KeyMap {\n  prevPage: Binding\n  nextPage: Binding\n}\n\n/**\n * Default paginator key bindings.\n * @public\n */\nexport const defaultKeyMap: KeyMap = {\n  prevPage: newBinding({ keys: ['pgup', 'left', 'h'] }),\n  nextPage: newBinding({ keys: ['pgdown', 'right', 'l'] }),\n}\n","import { matches } from '@boba-cli/key'\nimport { KeyMsg, type Cmd, type Msg } from '@boba-cli/tea'\nimport { defaultKeyMap, PaginatorType, type KeyMap } from './types.js'\n\n/**\n * Options for creating a paginator.\n * @public\n */\nexport interface PaginatorOptions {\n  type?: PaginatorType\n  page?: number\n  perPage?: number\n  totalPages?: number\n  activeDot?: string\n  inactiveDot?: string\n  arabicFormat?: string\n  keyMap?: KeyMap\n}\n\n/**\n * Pagination state and rendering.\n * @public\n */\nexport class PaginatorModel {\n  readonly type: PaginatorType\n  readonly page: number\n  readonly perPage: number\n  readonly totalPages: number\n  readonly activeDot: string\n  readonly inactiveDot: string\n  readonly arabicFormat: string\n  readonly keyMap: KeyMap\n\n  private constructor(options: PaginatorOptions = {}) {\n    this.type = options.type ?? PaginatorType.Arabic\n    this.page = Math.max(0, options.page ?? 0)\n    this.perPage = Math.max(1, options.perPage ?? 1)\n    this.totalPages = Math.max(1, options.totalPages ?? 1)\n    this.activeDot = options.activeDot ?? '•'\n    this.inactiveDot = options.inactiveDot ?? '○'\n    this.arabicFormat = options.arabicFormat ?? '%d/%d'\n    this.keyMap = options.keyMap ?? defaultKeyMap\n  }\n\n  /** Create a new paginator with defaults. */\n  static new(options: PaginatorOptions = {}): PaginatorModel {\n    return new PaginatorModel(options)\n  }\n\n  /** Set total pages based on item count (rounded up). */\n  setTotalPages(items: number): PaginatorModel {\n    if (items < 1) {\n      return this\n    }\n    const totalPages = Math.max(1, Math.ceil(items / this.perPage))\n    return this.with({ totalPages })\n  }\n\n  /** Number of items on the current page for a given total. */\n  itemsOnPage(totalItems: number): number {\n    if (totalItems < 1) {\n      return 0\n    }\n    const [start, end] = this.getSliceBounds(totalItems)\n    return end - start\n  }\n\n  /** Slice bounds for the current page, clamped to length. */\n  getSliceBounds(length: number): [number, number] {\n    const start = this.page * this.perPage\n    const end = Math.min(start + this.perPage, length)\n    return [start, end]\n  }\n\n  /** Move to previous page (no-op on first page). */\n  prevPage(): PaginatorModel {\n    if (this.page <= 0) {\n      return this\n    }\n    return this.with({ page: this.page - 1 })\n  }\n\n  /** Move to next page (no-op on last page). */\n  nextPage(): PaginatorModel {\n    if (this.onLastPage()) {\n      return this\n    }\n    return this.with({ page: this.page + 1 })\n  }\n\n  /** Whether the current page is the first page. */\n  onFirstPage(): boolean {\n    return this.page === 0\n  }\n\n  /** Whether the current page is the last page. */\n  onLastPage(): boolean {\n    return this.page >= this.totalPages - 1\n  }\n\n  /** Handle Tea messages (responds to KeyMsg). */\n  update(msg: Msg): [PaginatorModel, Cmd<Msg>] {\n    if (!(msg instanceof KeyMsg)) {\n      return [this, null]\n    }\n\n    if (matches(msg, this.keyMap.nextPage)) {\n      return [this.nextPage(), null]\n    }\n    if (matches(msg, this.keyMap.prevPage)) {\n      return [this.prevPage(), null]\n    }\n\n    return [this, null]\n  }\n\n  /** Render pagination. */\n  view(): string {\n    switch (this.type) {\n      case PaginatorType.Dots:\n        return this.dotsView()\n      case PaginatorType.Arabic:\n      default:\n        return this.arabicView()\n    }\n  }\n\n  private dotsView(): string {\n    let s = ''\n    for (let i = 0; i < this.totalPages; i++) {\n      s += i === this.page ? this.activeDot : this.inactiveDot\n    }\n    return s\n  }\n\n  private arabicView(): string {\n    const current = this.page + 1\n    return this.arabicFormat\n      .replace('%d', String(current))\n      .replace('%d', String(this.totalPages))\n  }\n\n  private with(patch: Partial<PaginatorOptions>): PaginatorModel {\n    return new PaginatorModel({\n      type: this.type,\n      page: this.page,\n      perPage: this.perPage,\n      totalPages: this.totalPages,\n      activeDot: this.activeDot,\n      inactiveDot: this.inactiveDot,\n      arabicFormat: this.arabicFormat,\n      keyMap: this.keyMap,\n      ...patch,\n    })\n  }\n}\n"]}

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@boba-cli/paginator",
+  "description": "Pagination state + rendering for Boba terminal UIs",
+  "version": "0.1.0-alpha.1",
+  "dependencies": {
+    "@boba-cli/key": "0.1.0-alpha.1",
+    "@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"
+  }
+}