@threestarsoftware/tssgrid 0.1.31-beta.0 → 0.1.32

package/CHANGELOG.md

@@ -3,7 +3,12 @@
 TssGrid の各リリースの変更点。日付は JST。形式は [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) 準拠（ゆるめ）。
 数値は特記なき限り**自社調べ**（headless Chrome / Windows 11・環境差あり）。
 
-## [Unreleased]
+## [0.1.32] - 2026-11-03
+
+### 改善（プラグイン）
+- **`tss-cascade`（多段プルダウン）にセル右端の目印 `▾` を追加** — 他のポップアップ型エディタ（`tss-combo`/`tss-autocomplete` は `▾`、`tss-calendar` は `📅`）は EditorDef の `icon` を既定で返していたが、`tss-cascade` だけ返しておらず**選ぶ列だと見た目で分からなかった**。`icon`（既定 `'▾'`／`''` で消す）を追加（`tss-combo` と同じ形）。印を押しても従来どおり多段メニューが開く（`openOnClick`）。描画はコア共通経路（`ed.icon`→`data-ico`＋`tg-haspicker`）＝**コア無改変**。型 `tss-cascade.d.ts` に `icon?: string`。
+
+## [0.1.31] - 2026-10-29
 
 ### 改善（プラグイン）
 - **`tss-comment` を実機タッチ対応** — これまで吹き出しは**ホバー（`mouseover`）**だけで、スマホ等のタッチ端末では合成 hover 任せ＝不安定だった。**タッチのときはタップで吹き出しをトグル**するよう分岐（同じセル再タップ・コメント外タップで閉じる）。マウスは従来どおりホバー（`pointerdown` の `pointerType` で判定）。desktop の挙動は不変。

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ThreeStarSoftware
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@threestarsoftware/tssgrid",
-  "version": "0.1.31-beta.0",
+  "version": "0.1.32",
   "description": "軽量・ノービルド・日本語IME堅牢な編集グリッド（vanilla JS / 依存なし / MIT）。Excel ライクな入力画面を <script> タグ1本で。",
   "license": "MIT",
   "author": "ThreeStarSoftware (https://www.threestarsoftware.co.jp/)",

package/plugins/tss-autocomplete.d.ts

@@ -0,0 +1,32 @@
+// TssAutocomplete — 候補サジェスト付きテキスト入力（TssGrid カスタムエディタ）。
+import { EditorDef } from '../src/tssgrid';
+
+export = TssAutocomplete;
+export as namespace TssAutocomplete;
+
+declare function TssAutocomplete(opts: TssAutocomplete.Options): EditorDef;
+
+declare namespace TssAutocomplete {
+  interface SourceCtx { row: any; r: number; c: number; grid: any; }
+
+  interface Options {
+    /** 候補。配列 or `(query, ctx) => string[]`（動的候補）。 */
+    source: string[] | ((query: string, ctx: SourceCtx) => string[]);
+    /** 共有 input に乗る型（既定 true）＝打鍵の1文字目・IME 直打ちが効く。false で自前 input ポップアップ。 */
+    inline?: boolean;
+    /** true=候補から選んだ値のみ許可（既定 false=自由入力可）。 */
+    strict?: boolean;
+    /** この文字数以上で候補を出す（既定 0=開いた時点で全件）。 */
+    minChars?: number;
+    /** 候補表示の最大件数（既定 20）。 */
+    max?: number;
+    /** 照合方法（既定 'includes'）。大文字小文字は無視。 */
+    match?: 'includes' | 'startsWith' | ((item: string, query: string) => boolean);
+    /** シングルクリックで開く（既定 true）。 */
+    openOnClick?: boolean;
+    /** セル右端の目印（既定 '▾'）。 */
+    icon?: string;
+    /** ポップアップに付ける任意クラス。 */
+    className?: string;
+  }
+}

package/plugins/tss-cascade.d.ts

@@ -0,0 +1,38 @@
+// TssCascade — 多段（フライアウト）プルダウン（TssGrid カスタムエディタ・ポップアップ型）。
+import { EditorDef } from '../src/tssgrid';
+
+export = TssCascade;
+export as namespace TssCascade;
+
+declare function TssCascade(opts: TssCascade.Options): EditorDef;
+
+declare namespace TssCascade {
+  /** ノード。枝は `children`、葉は `value`（未指定なら `label` を保存）。
+   *  `other:true` の葉は「その他」＝選ぶと入力欄に切替わり、打った文字を値に確定する。
+   *  その時 codeField へ書くコードは、その「その他」ノード自身の `value`（枝ごとに変えられる）。 */
+  interface Node { label: string; value?: string | number; children?: Node[]; other?: boolean; }
+
+  interface Options {
+    /** 入れ子の選択肢。 */
+    options: Node[];
+    /** コードの書き戻し先の列（data キー or 列 index）。
+     *  指定時: 値セル＝普通の葉はパス「大 / 中 / 小」・その他は打った文字／codeField＝葉(その他ノード)の value。
+     *  省略時: 葉の value を値セルに保存（従来・表示は pathFormat）。 */
+    codeField?: string | number;
+    /** 値セルに入れるパスの区切り（既定 ' / '）。pathFormat の separator と揃えると良い。 */
+    separator?: string;
+    /** 「その他」入力欄のプレースホルダ（既定 '自由入力'）。 */
+    otherPlaceholder?: string;
+    /** シングルクリックで開く（既定 true）。 */
+    openOnClick?: boolean;
+    /** セル右の目印（既定 '▾'／'' で消す）。 */
+    icon?: string;
+    /** ポップアップに付ける任意クラス。 */
+    className?: string;
+  }
+
+  /** 列 format 用: 値 → 「大 / 中 / 小」のパス文字列を返す関数。 */
+  function pathFormat(options: Node[], opts?: { separator?: string }): (value: any) => string;
+  /** 値 → パス文字列（単発）。 */
+  function pathOf(options: Node[], value: any, separator?: string): string;
+}

package/plugins/tss-cascade.js

@@ -39,6 +39,7 @@
  *    separator   : 値セルに入れるパスの区切り（既定 ' / '）。pathFormat と合わせると良い。
  *    otherPlaceholder : 「その他」入力欄のプレースホルダ（既定 '自由入力'）。
  *    openOnClick : 既定 true（プルダウン同様シングルクリックで開く）。
+ *    icon        : セル右の目印（既定 '▾'／'' で消す）。
  *    className   : ポップアップに付ける任意クラス。
  *  静的:
  *    TssCascade.pathFormat(options, { separator }) => (value)=>string   // 列 format 用（モード1の表示）
@@ -194,6 +195,7 @@
 
     return {
       openOnClick: opts.openOnClick !== false,
+      icon: opts.icon != null ? opts.icon : '▾',
       open: function (ctx) {
         ctxRef = ctx; done = false;
         openPanel(roots, 0, ctx.td.getBoundingClientRect());

package/plugins/tss-combo.d.ts

@@ -0,0 +1,37 @@
+// TssCombo — コード付きプルダウン＋「その他」で自由入力（TssGrid カスタムエディタ）。
+// UMD: `import TssCombo from '@threestarsoftware/tssgrid/plugins/tss-combo.js'` でも、<script> タグのグローバル `TssCombo` でも使える。
+import { EditorDef } from '../src/tssgrid';
+
+export = TssCombo;
+export as namespace TssCombo;
+
+declare function TssCombo(opts: TssCombo.Options): EditorDef;
+
+declare namespace TssCombo {
+  /** 選択肢1件。`code`（別名 `value`）と表示 `label`。文字列を渡すと code=label。 */
+  interface Option { code?: string | number; value?: string | number; label?: string; }
+
+  interface Options {
+    /** 選択肢。`{code,label}` か文字列（code=label）の配列。 */
+    options: Array<Option | string>;
+    /** 「その他」を有効化。`true` で `{code:'99', label:'その他'}`。選ぶと入力欄に切替。省略で自由入力なし。 */
+    other?: boolean | Option;
+    /** コードの書き戻し先の列（data キー or 列 index）。省略時はコードを書かず値だけ確定。 */
+    codeField?: string | number;
+    /** その他モードの入力欄プレースホルダ（既定 '自由入力'）。 */
+    otherPlaceholder?: string;
+    /** シングルクリックで開く（既定 true）。 */
+    openOnClick?: boolean;
+    /** セル右端の目印（既定 '▾'）。 */
+    icon?: string;
+    /** ポップアップに付ける任意クラス。 */
+    className?: string;
+  }
+
+  /**
+   * 値 → コードを引く関数を返す（同じ options/other から）。undo/redo・貼付でコードを値に追従させたい時、
+   * `onAfterChange` の中で `grid.setValueRaw(r, コード列, codeOf(grid.getValue(r, 値列)))` のように使う。
+   * 値が選択肢に無ければ other の code、空なら ''。
+   */
+  function codeOf(opts: { options: Array<Option | string>; other?: boolean | Option }): (value: any) => string;
+}

package/plugins/tss-datetime.d.ts

@@ -0,0 +1,42 @@
+// TssDatetime — 日付＋時刻ピッカー（TssGrid カスタムエディタ／単体でも）。保存値は 'YYYY-MM-DDTHH:MM'。
+import { EditorDef } from '../src/tssgrid';
+
+export = TssDatetime;
+export as namespace TssDatetime;
+
+declare function TssDatetime(opts?: TssDatetime.Options): TssDatetime.Editor;
+
+declare namespace TssDatetime {
+  type Holidays = Record<string, string | { name: string; type?: string }>;
+
+  interface Options {
+    holidays?: Holidays;
+    weekend?: number[];
+    weekLabels?: string[];
+    /** 選択可能範囲（'YYYY-MM-DD'）。 */
+    min?: string;
+    max?: string;
+    yearMin?: number;
+    yearMax?: number;
+    /** 分刻み（既定 1）。 */
+    step?: number;
+    /** AM/PM 表示（既定 false=24h）。 */
+    hour12?: boolean;
+    /** 共有 input に乗る型（既定 true）＝直打ち可。false でフォーカス奪取型。 */
+    inline?: boolean;
+    /** シングルクリックで開く（既定 true）。 */
+    openOnClick?: boolean;
+    /** セル右端の目印（既定 '📅'）。 */
+    icon?: string;
+    /** ポップアップに付ける任意クラス。 */
+    className?: string;
+  }
+
+  interface Editor extends EditorDef {
+    /** アンカー要素の下に開き、選択で `onPick('YYYY-MM-DDTHH:MM')` を呼ぶ（単体用）。 */
+    openAt(anchorEl: Element, value: string, onPick: (value: string) => void): void;
+  }
+
+  /** 列 format 用: 保存値 'YYYY-MM-DDTHH:MM' を表示整形。 */
+  function format(value: any, opts?: { hour12?: boolean }): string;
+}

package/plugins/tss-hyperlink.d.ts

@@ -0,0 +1,19 @@
+// TssHyperlink — セル内ハイパーリンク（format ヘルパ）。columns[c].html:true ＋ format に渡す。
+export = TssHyperlink;
+export as namespace TssHyperlink;
+
+/** 値 "表示テキスト|URL"（または URL 単体）を安全なリンク HTML に変換する format 関数を返す。 */
+declare function TssHyperlink(opts?: TssHyperlink.Options): (value: any) => string;
+
+declare namespace TssHyperlink {
+  interface Options {
+    /** 表示テキストと URL の区切り（既定 '|'）。 */
+    separator?: string;
+    /** リンクの target（既定 '_blank'）。 */
+    target?: string;
+    /** <a> に付ける任意クラス（既定 'tss-link'）。 */
+    className?: string;
+  }
+  /** URL を安全化（http/https/mailto/tel のみ許可・スキーム無しは https 補完・許可外は null）。 */
+  function safeUrl(u: any): string | null;
+}

package/plugins/tss-time.d.ts

@@ -0,0 +1,29 @@
+// TssTime — 時/分プルダウン方式の時刻エディタ（TssGrid カスタムエディタ／単体でも）。保存値は 24h 'HH:MM'。
+import { EditorDef } from '../src/tssgrid';
+
+export = TssTime;
+export as namespace TssTime;
+
+declare function TssTime(opts?: TssTime.Options): TssTime.Editor;
+
+declare namespace TssTime {
+  interface Options {
+    /** 分刻み（既定 1）。 */
+    step?: number;
+    /** AM/PM 表示（既定 false=24h）。 */
+    hour12?: boolean;
+    /** 共有 input に乗る型（既定 true）＝直打ち可。false でフォーカス奪取型。 */
+    inline?: boolean;
+    /** シングルクリックで開く（既定 true）。 */
+    openOnClick?: boolean;
+    /** セル右端の目印（既定 '🕐'）。 */
+    icon?: string;
+    /** ポップアップに付ける任意クラス。 */
+    className?: string;
+  }
+
+  interface Editor extends EditorDef {
+    /** アンカー要素の下に開き、選択で `onPick('HH:MM')` を呼ぶ（単体用）。 */
+    openAt(anchorEl: Element, value: string, onPick: (value: string) => void): void;
+  }
+}

package/src/tssgrid.d.ts

@@ -0,0 +1,540 @@
+// =============================================================================
+// TssGrid 型定義（公開APIの契約）
+//   - これが「外から呼べるもの」の正本。エディタ補完にはここに宣言したものだけ出る
+//     ＝内部メソッド（setCell / pushCmd / place など）は候補に出ず、自然に守られる。
+//   - 低レベルだが公開しているメソッドは JSDoc に「通常は○○を推奨」と明記（逃げ道は塞がない）。
+//   - v1 ドラフト。実装と差異を見つけたら本ファイルを正として揃える/直す。
+//   - 使い方:
+//       <script src="tssgrid.js"> 読み込み時 … グローバル TssGrid / HistoryManager に型が付く
+//       import { TssGrid } from 'tssgrid' … ESM entry 整備後（§npm化）に有効
+// =============================================================================
+
+export type MoveDir = 'down' | 'up' | 'right' | 'left' | 'none';
+export type CellType = 'text' | 'number' | 'date' | 'time' | 'dropdown' | 'checkbox';
+export type ChangeSource = 'edit' | 'paste' | 'fill' | 'delete' | 'undo' | 'redo';
+
+/** 1つの値変更（onBeforeChange / onAfterChange の配列要素）。newValue を書き換えると整形確定。 */
+export interface ChangeItem {
+  r: number;
+  c: number;
+  oldValue: any;
+  newValue: any;
+  source: ChangeSource;
+}
+
+/** 選択範囲。r0/c0=開始、r1/c1=終了（昇順とは限らない）。 */
+export interface SelectionRange { r0: number; c0: number; r1: number; c1: number; }
+export interface CellCoord { r: number; c: number; }
+/** cellClass/cellStyle（列版）が受け取る第2引数。row=その行の値配列, src=元レコード（object モード時・非表示フィールドも見える／配列モードは null）。
+ *  src は `any`＝利用側が自分の行型（`src: MyRow`）でそのまま受けられる（`Record<string,any>|null` だと二重キャストを強いるため）。 */
+export interface CellClassCtx { r: number; c: number; row: any[]; src: any; }
+/** cellClass/cellStyle の戻り値のクラス。文字列（空白区切り可）／配列／null 等（＝クラス無し）。 */
+export type ClassValue = string | string[] | null | undefined | false;
+/** cellStyle の戻り値。CSS プロパティのオブジェクト（`{'background':'#fde','--pct':'42%'}`）か文字列（`'background:#fde;--pct:42%'`）。 */
+export type StyleValue = string | Partial<CSSStyleDeclaration> | Record<string, string> | null | undefined;
+export interface SelectionInfo { range: SelectionRange; active: CellCoord; extent: CellCoord; }
+
+/** validator が弾いたセル（onInvalid / getInvalidCells）。 */
+export interface Rejection { r: number; c: number; value: any; code?: string; level?: string; message?: string; }
+/** 読み取り専用セルへの変更を弾いた時（onReadOnly）。 */
+export interface ReadOnlyBlock { r: number; c: number; value: any; }
+
+/** 行/列の挿入・削除の情報（onStructureChange / onBeforeStructureChange）。 */
+export interface StructureInfo { type: 'insertRow' | 'insertRows' | 'deleteRows' | 'insertCol' | 'deleteCols'; undo?: boolean; [k: string]: any; }
+
+/** validator の戻り値: true=OK / 文字列=エラー文 / オブジェクト=メッセージカタログ解決用。 */
+export type ValidatorResult = true | string | { code: string; params?: Record<string, any>; level?: string };
+
+/** 列定義（options.columns[c]）。`data` は data オブジェクトのキー（または列 index）。 */
+export interface ColumnDef {
+  /** data オブジェクトのキー。配列データなら省略可（位置で対応）。 */
+  data?: string | number;
+  /** ヘッダ見出し（headers より優先）。 */
+  title?: string;
+  /** セルタイプ。既定 'text'。 */
+  type?: CellType;
+  /** dropdown の選択肢。関数を渡すと**行ごとに異なる依存ドロップダウン**（例: 都道府県→市区町村）。
+   *  `(r, row)=>[…]` の row はその行の値配列（`grid.data[r]`）。静的配列は全行共通（後方互換）。 */
+  options?: Array<string | { value: string; label?: string }>
+    | ((r: number, row: any[]) => Array<string | { value: string; label?: string }>);
+  /** 列ごとの初期幅(px)。列定義に同居＝並べ替え/コピペで幅が追従。 */
+  width?: number;
+  /** false でこの列だけリサイズ禁止。 */
+  resizable?: boolean;
+  /** 列既定の水平/垂直整列。 */
+  align?: 'left' | 'center' | 'right';
+  valign?: 'top' | 'middle' | 'bottom';
+  /** 列単位の読み取り専用。関数でセル単位判定も可。 */
+  readOnly?: boolean | ((value: any, cell: CellCoord) => boolean);
+  /** 入力検証。編集/貼付/フィルの全経路に効く。 */
+  validator?: (value: any, cell: CellCoord) => ValidatorResult;
+  /** カスタム編集UI（薄いオブジェクト契約 or それを返す関数）。 */
+  editor?: EditorDef | (() => EditorDef);
+  /** 入力の正規化（保存値へ変換）。 */
+  parse?: (input: string, cell: CellCoord) => any;
+  /** 表示の整形（保存値→表示）。文字列 or 宣言的 CellFormat or 関数。
+   *  関数は `(value, { r, c }, row)`＝第3引数 `row` はその行の値配列（`grid.data[r]`・options と同形）。
+   *  html:true 併用でセル内にボタン/アイコン等の HTML を描ける（空セルでも実行される）。 */
+  format?: string | object | ((value: any, cell: CellCoord, row: any[]) => string);
+  /** 数値型: 千区切り表示。 */
+  thousands?: boolean;
+  /** 数値型: 接頭辞（例 '¥'）。 */
+  prefix?: string;
+  /** 値/行を見てセルに付与する CSS クラス（条件付き書式）。**引数は `(value, { r, c, row, src })`**（第1引数がそのセルの値）。
+   *  ＊表全体版は `TssGridOptions.cellClass`（引数順が違う: `(r, c, value, row, src)`）。 */
+  cellClass?: (value: any, cell: CellClassCtx) => ClassValue;
+  /** セル単位のインラインスタイル（連続色・データバー等）。**引数は `(value, { r, c, row, src })`**。 */
+  cellStyle?: (value: any, cell: CellClassCtx) => StyleValue;
+  /** true で表示だけ生HTML（値はテキスト保存のまま）。 */
+  html?: boolean;
+  /** 列単位の折り返し。 */
+  wordWrap?: boolean;
+  /** 複数行(改行)入力を有効化。編集は隠し textarea（IME 直打ち対応）、表示は改行保持(pre-wrap)。行高は自動で伸びないので rowHeights 等で確保する。 */
+  multiline?: boolean;
+  /** 空セルの薄いヒント文字。 */
+  placeholder?: string;
+  [k: string]: any;
+}
+
+/** new TssGrid(container, options) のオプション。 */
+export interface TssGridOptions {
+  headers?: string[];
+  /** 初期データ。2次元配列 or オブジェクト配列。 */
+  data?: any[][] | Record<string, any>[];
+  /** 渡すと複数グリッドで Undo を共有。 */
+  history?: HistoryManager;
+  name?: string;
+  showDump?: boolean;
+  /** Enter 確定後の移動方向（既定 'down'）。Shift で逆。実行時に書換可。 */
+  enterMoves?: MoveDir;
+  /** Tab 確定後の移動方向（既定 'right'）。Shift で逆。実行時に書換可。 */
+  tabMoves?: MoveDir;
+  initialCell?: [number, number] | { r: number; c: number | string };
+  /** 入力フロー制御。Enter/Tab の移動先を上書き（null で既定方向）。入力セルだけ巡回できる。 */
+  nextCell?: (a: { r: number; c: number; key: string; shift: boolean }) => { r: number; c: number } | null;
+  columns?: ColumnDef[];
+  /** 表全体の条件付きクラス（全セルで呼ばれる）。**引数は `(r, c, value, row, src)`**（先頭が行/列番号・列版と順序が違う）。
+   *  `row`=その行の値配列, `src`=元レコード（object モード時・非表示フィールドも見える）。行に色を付けたいなら `rowClass` の方が簡単。 */
+  cellClass?: (r: number, c: number, value: any, row: any[], src: any) => ClassValue;
+  /** 表全体のセル単位インラインスタイル。**引数は `(r, c, value, row, src)`**。返り値は CSS オブジェクト or 文字列。 */
+  cellStyle?: (r: number, c: number, value: any, row: any[], src: any) => StyleValue;
+  /** 行ごとに `<tr>` へ付与する CSS クラス（**行に色を付けるならこれ**）。`(r, row, src)` で呼ばれ、文字列/配列を返す。
+   *  編集でセルが再描画されると即追従。CSS は `.tssgrid tr.クラス > td { … }` のように行単位で当てる。 */
+  rowClass?: (r: number, row: any[], src: any) => ClassValue;
+  /** 検証NG時。'revert'=元に戻す / 'keep'=赤く警告して残す。 */
+  invalidMode?: 'revert' | 'keep';
+  invalidTitle?: boolean;
+  /** エラーの共通メッセージカタログ。 */
+  messages?: Record<string, any> | ((info: { code: string; params?: any; level?: string }) => string);
+  pasteOverflow?: 'clip' | 'error';
+  /** 貼付元の行数がグリッド行数を超える時、不足分を insertRows で一括生成してから貼る（既定 false=従来のクランプ）。行生成＋値貼付は1回の undo で戻る。maxRows 上限内・超過分は pasteOverflow に従う。 */
+  pasteAutoGrow?: boolean;
+  colWidths?: number[] | Record<string, number>;
+  rowHeights?: number[] | Record<string, number>;
+  defaultColWidth?: number;
+  defaultRowHeight?: number;
+  minColWidth?: number;
+  minRowHeight?: number;
+  resizeMode?: 'preview' | 'live';
+  /** 左から固定する列数。freezeCols(n) でも変更可。 */
+  frozenCols?: number;
+  /** 上から固定する行数。freezeRows(n) でも変更可。frozenCols 併用で四隅固定。 */
+  frozenRows?: number;
+  /** ヘッダ結合（複数段見出し）。最下段がリーフ＝実列。 */
+  nestedHeaders?: Array<Array<string | { label: string; colspan?: number }>>;
+  width?: number | string;
+  height?: number | string;
+  resizeCols?: boolean;
+  resizeRows?: boolean;
+  /** false で選択カーソルを非表示（表示専用グリッド向け・内部選択は保持）。 */
+  cursor?: boolean;
+  stretchH?: 'none' | 'last' | 'all';
+  rowHeaders?: boolean;
+  /** 行番号列の幅(px)。既定 40。大量行で桁数が増える時に広げる。 */
+  rowHeaderWidth?: number;
+  /** 行ヘッダの表示内容。未指定=行番号(r+1) / false=数字なし(空) / (r)=>文字列=カスタム表示。 */
+  rowHeaderLabel?: false | ((r: number) => string | number);
+  /** 行のドラッグ並べ替え。true=行ヘッダーセルの ⠿ アイコンを掴んで移動 / 'header'=行ヘッダーセル全体が移動ハンドル（クリック=選択／ドラッグ=移動）。 */
+  rowReorder?: boolean | 'header';
+  /** 行ヘッダーの ⠿ マークの位置。'before'=番号の前（既定）/ 'after'=番号の後 / false=マークを出さない。 */
+  rowReorderMark?: 'before' | 'after' | false;
+  /** 右端に非データの「削除列」（🗑）を1列出す。既定 false。クリックで deleteRows（右クリック→行を削除と同一経路・1 undo で復活）。
+   *  最後の1行（0行にはできない）は削除でなく「中身クリア（行は残す）」＝🗑 は無効にならず内容だけ空に（readOnly はスキップ・1 undo で復活）。
+   *  minRows>1 のロック時は下限で🗑 を無効表示（削除もクリアもしない）。allowDeleteRows:false なら列ごと出さない。
+   *  getRows/getData/toCSV・列インデックス・列選択/リサイズ/reorder の対象外。 */
+  rowDelete?: boolean;
+  /** 削除列の幅(px)。既定 36。 */
+  rowDeleteWidth?: number;
+  /** 仮想スクロール（固定行高ウィンドウイング）。大量行を可視窓だけ描画。true か { buffer:窓上下バッファ行数(既定6) }。
+   *  制約(v1): 行高一定／固定行列・折り返し・セル結合は非対応（指定時は自動無効化）。 */
+  virtual?: boolean | { buffer?: number };
+  colHeaders?: boolean;
+  hiddenColumns?: number[];
+  wordWrap?: boolean;
+  /** multiline 列の Enter 挙動。'commit'(既定・Excel風): Enter=確定 / Alt+Enter=改行。'newline'(メモ帳風): Enter=改行 / Ctrl+Enter=確定。 */
+  multilineEnter?: 'commit' | 'newline';
+  /** multiline セル右上の「複数行」ヒント表示（既定 true）。色は CSS 変数 --tg-ml-mark。false で非表示。 */
+  multilineMark?: boolean;
+  /** multiline 編集時に伸びる箱の最大行数（既定 10）。超えた分はボックス内スクロール。ビューポート/wrap を超える時はそちらが優先。 */
+  multilineEditMaxLines?: number;
+  placeholder?: string;
+  className?: string;
+  /** false でフィル完全OFF。詳細指定も可。 */
+  fillHandle?: boolean | { direction?: 'vertical' | 'horizontal' | 'both'; autoInsertRow?: boolean };
+  autoColumnSize?: boolean | number;
+  copyPaste?: boolean;
+  /** 共有エディタへのブラウザ自動入力（Chrome の「ポイントカード/住所/支払い」等）を強めに抑止する。既定 false。
+   *  通常は name + autocomplete='off' で抑止するが、Chrome は loyalty/payment 系で 'off' を無視することがある。
+   *  true にすると autocomplete='new-password' に切り替えて確実に止める（副作用として環境により鍵アイコンや生成PW提案が出る場合あり＝opt-in）。
+   *  周囲に自前のラベル付き `<input>`（フォーム塊）を並べる埋め込み画面で有効。 */
+  suppressAutofill?: boolean;
+  minSpareRows?: number;
+  autoWrapRow?: boolean;
+  autoWrapCol?: boolean;
+  minRows?: number;
+  maxRows?: number;
+  minCols?: number;
+  maxCols?: number;
+  /** グリッド全体を読み取り専用（ビューア用途）。 */
+  readOnly?: boolean;
+  /** 右クリックメニュー。true=既定 / false=無効 / 配列 or {items} =構成（組込キー文字列＋カスタム MenuItem）。 */
+  contextMenu?: boolean | Array<string | MenuItem> | { items: Array<string | MenuItem> };
+  /** Ctrl+ヘッダで行/列を飛び飛び複数選択（既定 true）。false で Ctrl+クリックは単一選択に戻る。 */
+  disjointSelect?: boolean;
+  allowInsertRows?: boolean;
+  allowDeleteRows?: boolean;
+  allowInsertCols?: boolean;
+  allowDeleteCols?: boolean;
+  shortcuts?: any[];
+  /** 組込ショートカット Ctrl+;（今日）/ Ctrl+:（現在時刻）を有効化（既定 true）。 */
+  dateShortcuts?: boolean;
+  /** 組込ショートカット Ctrl+D（上をコピー=fill down）/ Ctrl+R（左をコピー=fill right）を有効化（既定 true）。 */
+  fillShortcuts?: boolean;
+  /** Ctrl+; が「date 型でない列」に入れる日付形式（既定 'YYYY-MM-DD'）。トークン YYYY/MM/DD、または (d:Date)=>string。date 列は列の仕組み（ISO 保存＋列 format 表示）に従う。 */
+  todayFormat?: string | ((d: Date) => string);
+  /** Ctrl+: が「time 型でない列」に入れる時刻形式（既定 'HH:MM'）。トークン HH/mm、または (d:Date)=>string。time 列は 'HH:MM' 保存。 */
+  nowFormat?: string | ((d: Date) => string);
+  /** プラグイン（関数 or 登録名）。init(grid) で初期化。 */
+  plugins?: any[];
+
+  // ---- イベント / コールバック -------------------------------------------
+  /** 確定の直前。検証・自動整形。false で全取消、change.newValue 書換で整形。 */
+  onBeforeChange?: (changes: ChangeItem[], source: ChangeSource) => boolean | void;
+  /** 確定の直後（undo/redo 含む）。保存・再計算に。 */
+  onAfterChange?: (changes: ChangeItem[], source: ChangeSource) => void;
+  onEditStart?: (info: { r: number; c: number; value: any }) => void;
+  onEditEnd?: (info: { r: number; c: number; oldValue: any; newValue: any; canceled: boolean }) => void;
+  onSelectionChange?: (info: SelectionInfo) => void;
+  onBeforeSelectionChange?: (info: SelectionInfo) => boolean | void;
+  onBeforePaste?: (data: string[][]) => boolean | string[][] | void;
+  onAfterPaste?: (data: string[][], info: { range: SelectionRange }) => void;
+  onBeforeCopy?: (data: string[][], info: { range: SelectionRange }) => boolean | string[][] | void;
+  onBeforeCut?: (data: string[][], info: { range: SelectionRange }) => boolean | string[][] | void;
+  onAfterCopy?: (data: string[][], info: { range: SelectionRange; cut: boolean }) => void;
+  onBeforeStructureChange?: (info: StructureInfo) => boolean | void;
+  onStructureChange?: (info: StructureInfo) => void;
+  /** 遅延ロード(push): 描画窓が変わった時に呼ぶ (start,end)。未取得(PENDING)行を fillRows で埋めるトリガ。 */
+  onViewportChange?: (start: number, end: number) => void;
+  /** 遅延ロード(push): dataComplete=false で sort/filter 要求が来た時に呼ぶ。エンジンはローカル計算せず、これで通知＋パージ＝プラグインがサーバ側で並替/絞込して setRowCount+fillRows し直す。 */
+  onSortFilterChange?: (state: { type: 'sort' | 'filter'; sort?: any; filter?: any }) => void;
+  onBeforeAutofill?: (src: SelectionRange, target: SelectionRange) => boolean | void;
+  onAfterAutofill?: (src: SelectionRange, target: SelectionRange) => void;
+  onBeforeKeyDown?: (e: KeyboardEvent) => boolean | void;
+  onHeaderClick?: (c: number, e: MouseEvent) => boolean | void;
+  /** 各列ヘッダ th の生成後に呼ぶ（再描画毎に自動で再実行）。ソートアイコン等の要素差し込み用。 */
+  onHeaderRender?: (th: HTMLTableCellElement, c: number) => void;
+  onInvalid?: (rejections: Rejection[], source: ChangeSource) => void;
+  onReadOnly?: (blocked: ReadOnlyBlock[], source: ChangeSource) => void;
+  onChange?: (grid: TssGrid) => void;
+  onPasteOverflow?: (info: { anchor: CellCoord; height: number; width: number; rows: number; cols: number; overRows: number; overCols: number }) => void;
+
+  [k: string]: any;
+}
+
+export interface CsvOptions {
+  headers?: boolean; formatted?: boolean; skipEmpty?: boolean; eol?: string;
+  /** CSV数式インジェクション無害化（既定 true）。=@+- 始まりの非数値セルを ' で保護。生値が要る用途は false。 */
+  sanitizeFormula?: boolean;
+  delimiter?: string; [k: string]: any;
+}
+
+/** カスタム編集UIが `open` で受け取る ctx。確定は commit＝本体の関所（検証/整形/readOnly/履歴）を通る。 */
+export interface EditorContext {
+  grid: TssGrid; r: number; c: number; value: any; td: HTMLTableCellElement | null;
+  commit(value?: any): void; cancel(): void;
+  /** inline エディタのみ: true。 */
+  inline?: boolean;
+  /** inline エディタのみ: 打鍵/IME が入る本体の共有 input（読み取り・listen 用）。 */
+  input?: HTMLInputElement | HTMLTextAreaElement;
+  /** inline エディタのみ: 共有 input の値を差し替える（候補で置換する用・確定はしない）。 */
+  setValue?(value: any): void;
+  /**
+   * inline エディタのみ: 打たれた文字を**この列の保存値**に解釈する（＝セルの確定と同じ読み方。
+   * `columns[c].parse` があればそれ、無ければ型ごとの組込＝date/time/number）。解釈できなければ `null`。
+   * **エディタが独自パーサを持つと本体と食い違う**ので、打った内容に追従する実装は必ずこれを使うこと。
+   */
+  parseCell?(value: any): any;
+  [k: string]: any;
+}
+/** カスタム編集UIの契約（`columns[c].editor`）。 */
+export interface EditorDef {
+  open(ctx: EditorContext): void;
+  close?(): void;
+  /** セル右端に出すアイコン。 */
+  icon?: string;
+  /** シングルクリックで開く（ドロップダウン同様）。 */
+  openOnClick?: boolean;
+  /**
+   * `true` で「本体の共有 input に乗るエディタ」＝**打鍵の1文字目・IME 直打ちが素のテキスト列と同じに効く**。
+   * 入力は本体（IME 堅牢な共有 input）に任せ、エディタは候補表示等だけを担当する型。text/number 系の列で有効
+   * （dropdown/checkbox/ネイティブ日付は従来どおり対象外）。未指定なら従来のフォーカスを奪うエディタ（挙動不変）。
+   */
+  inline?: boolean;
+  /** inline のみ: 本体より先にキーを受ける（**IME 変換中も呼ばれる**＝変換中の↑↓を奪わない実装が書ける）。`false` で本体既定を止める。 */
+  onKeyDown?(e: KeyboardEvent, ctx: EditorContext): boolean | void;
+  /** inline のみ: 共有 input の入力通知（候補の絞り込み用）。 */
+  onInput?(value: string, ctx: EditorContext): void;
+  [k: string]: any;
+}
+
+/** 右クリックの対象種別。カスタムメニュー項目の name/disabled/hidden の第2引数、callback の {ctx} で受け取る。 */
+export interface MenuContext { on: 'col' | 'row' | 'cell' | 'corner'; r: number; c: number; }
+
+/** 右クリックメニューのカスタム項目。name/disabled/hidden は関数なら (range, ctx) で呼ばれる。 */
+export interface MenuItem {
+  name?: string | ((range: SelectionRange, ctx: MenuContext) => string);
+  callback?: (arg: { range: SelectionRange; key?: string; ctx: MenuContext }) => void;
+  disabled?: boolean | ((range: SelectionRange, ctx: MenuContext) => boolean);
+  hidden?: boolean | ((range: SelectionRange, ctx: MenuContext) => boolean);
+  danger?: boolean; separator?: boolean; key?: string; submenu?: Array<string | MenuItem>;
+}
+
+/** Undo/Redo 履歴。複数グリッドで共有すると Undo タイムラインが繋がる。 */
+export declare class HistoryManager {
+  constructor(max?: number);
+  onChange: ((h: HistoryManager) => void) | null;
+  push(cmd: { apply: () => void; revert: () => void }): void;
+  undo(): void;
+  redo(): void;
+  clear(): void;
+  canUndo(): boolean;
+  canRedo(): boolean;
+}
+
+/**
+ * 軽量・ノービルド・日本語IME堅牢な編集グリッド。
+ * @example
+ * const grid = new TssGrid(document.getElementById('app'), {
+ *   columns: [{ data: 'name', title: '品名' }, { data: 'qty', title: '数量', type: 'number' }],
+ *   data: [{ name: 'りんご', qty: 12 }],
+ * });
+ */
+export declare class TssGrid {
+  constructor(container: HTMLElement, options?: TssGridOptions);
+
+  /** 行数 / 列数（読み取り）。 */
+  readonly ROWS: number;
+  readonly COLS: number;
+  /** 列定義（実行時参照）。 */
+  columns: ColumnDef[];
+  /** 履歴マネージャ。 */
+  history: HistoryManager;
+  /** Enter/Tab 確定後の移動方向（代入で即反映）。 */
+  enterMoves: MoveDir;
+  tabMoves: MoveDir;
+  /** グリッド名（読み取り）。 */
+  readonly name: string;
+  /** アクティブセル（読み取り。移動は setActive）。 */
+  readonly active: { r: number; c: number };
+  /** 選択の伸長端（読み取り。setExtent で移動）。 */
+  readonly extent: { r: number; c: number };
+  /** 仮想スクロール有効か（読み取り）。 */
+  readonly virtual: boolean;
+  /** グリッド全体の読み取り専用（読み取り。実行時変更は setReadOnly）。 */
+  readonly readOnly: boolean;
+
+  // ---- データ -------------------------------------------------------------
+  /** 全データを2次元配列で取得（コピー）。 */
+  getData(): any[][];
+  /** 全行をオブジェクト配列で取得（columns[c].data キー基準）。 */
+  getRows(): Record<string, any>[];
+  /** r 行目をオブジェクトで取得。 */
+  getRow(r: number): Record<string, any>;
+  /** 列を縦に取得（index か data キー）。 */
+  getColumn(cOrKey: number | string): any[] | undefined;
+  /** 全列を配列の配列で取得。 */
+  getColumns(): any[][];
+  /** 1セルの値を取得（c は index か data キー）。 */
+  getValue(r: number, cOrKey: number | string): any;
+  /** データを差し替え（履歴・フィルタ・整列状態はリセット）。 */
+  setData(rows: any[][] | Record<string, any>[]): void;
+  /** 実行時に列定義を差し替える（Vue の `:columns` 変更等）。`headers` 省略時は columns から再導出。
+   *  object モードは元レコード(`_src`)から新 columns で再展開、配列モードは各行を新 COLS に詰める。
+   *  列構造が変わるので整列/セル単位 readOnly はクリア、frozen/選択は範囲内へクランプ。 */
+  setColumns(columns: ColumnDef[], headers?: (string | { label?: string })[]): void;
+  /** グリッド全体の読み取り専用を実行時に切替（Vue の `:readonly` 等）。 */
+  setReadOnly(flag: boolean): void;
+  /**
+   * 背景で"育てる"追記（progressive）。data 末尾へ rows を足し、可視窓＋スペーサだけ再描画する。
+   * buildTable 全再描画をせず、スクロール位置・アクティブセル・フォーカス・選択・編集中のエディタと値を保ち、履歴にも積まない。
+   * 「先頭ページを描く→残りを idle で appendRows」して first-paint を早める土台（既存の setData/insertRows 経路は不変）。
+   * rows は現在のデータと同形（オブジェクトモードはオブジェクト配列／配列モードは行配列）。
+   */
+  appendRows(rows: any[][] | Record<string, any>[], opts?: { keepScroll?: boolean; noHistory?: boolean }): void;
+  /**
+   * 遅延ロード(push・on-demand)。総行数を total に確保し、未取得ぶんを PENDING 行で埋める（virtual 前提）。
+   * dataComplete=false になり、この間 minSpareRows は自動無効。onViewportChange で「今要る範囲」を受け fillRows で埋める流れ。
+   * setData で解除。AG Grid の Infinite Row Model 相当を push プリミティブで。
+   */
+  setRowCount(total: number): void;
+  /**
+   * 遅延ロード(push): PENDING 行 [start, start+rows.length) を実データに差し替える（onViewportChange への応答）。
+   * 塗り替え範囲が可視窓に重なる時だけ窓を再描画＝スクロール/選択/アクティブは不変。全 PENDING が埋まると dataComplete=true。
+   */
+  fillRows(start: number, rows: any[][] | Record<string, any>[]): void;
+  /** 遅延ロード: 全行がロード済みなら true。setRowCount で false、全 fillRows 完了で true に戻る。 */
+  readonly dataComplete: boolean;
+  /** 1セルに書き込み（履歴あり・検証/onBeforeChange 経由）。force=true で readOnly 貫通。 */
+  setValue(r: number, cOrKey: number | string, val: any, force?: boolean): void;
+  /** 履歴に積まず・検証も通さず直接書き込み（計算列など派生値用。readOnly 貫通）。 */
+  setValueRaw(r: number, cOrKey: number | string, val: any): void;
+  /** 複数セルをまとめて書き込み、1 undo にする。`c` は列 index か data キー。値コピー→再計算等の batch 書き込みに。 */
+  setCells(cells: { r: number; c: number | string; value: any }[]): void;
+  /** アクティブセルを編集モードにする（低レベル）。`value` 指定でその値から開始、`caretEnd` でキャレット末尾。読取専用は無視。 */
+  toEdit(value?: any, caretEnd?: boolean): void;
+  /** アクティブセルを左上に、2次元配列を貼り付け（はみ出しは pasteOverflow ポリシー・1 undo）。 */
+  pasteGrid(grid: any[][]): void;
+
+  // ---- 並べ替え / フィルタ -------------------------------------------------
+  /** 列で並べ替え（c は index か data キー）。 */
+  sortBy(cOrKey: number | string, dir?: 'asc' | 'desc'): void;
+  /** 多段（複数列）で並べ替え。specs は優先順（先頭=第1キー）。各段は sortBy と同じ比較規則。 */
+  sortByCols(specs: Array<{ col: number | string; dir?: 'asc' | 'desc' }>): void;
+  /** 比較関数で並べ替え。 */
+  sortRows(cmp: (a: any[], b: any[]) => number): void;
+  /** 並べ替え解除（入力順に戻す）。 */
+  clearSort(): void;
+  isSorted(): boolean;
+  /** 非破壊フィルタ。pred(row, masterIndex, src)=>boolean、または { col: 値|fn }。 */
+  filter(pred: ((row: any[], masterIndex: number, src: any) => boolean) | Record<string, any>): void;
+  /** フィルタ解除（フィルタ中に編集/追加した行も含め全部戻る）。 */
+  clearFilter(): void;
+  isFiltered(): boolean;
+  /** フィルタ中でも全行（マスタ）を取得。 */
+  getAllRows(): Record<string, any>[];
+
+  // ---- 選択 / カーソル ----------------------------------------------------
+  setActive(r: number, c: number): void;
+  setExtent(r: number, c: number): void;
+  selectRect(r0: number, c0: number, r1: number, c1: number): void;
+  selectRow(r: number): void;
+  selectCol(c: number): void;
+  selectAll(): void;
+  /**
+   * 指定行までスクロール（HTML の `#` アンカー相当・選択は変えない）。
+   * `align` は `'start'`（既定＝その行を先頭＝sticky ヘッダ直下へ）/ `'center'` / `'end'` / `'nearest'`（可視ならそのまま）。
+   * 仮想（均一行高）でも非仮想（可変行高・実DOM測定）でも動く。範囲外の `r` は自動でクランプ。
+   */
+  scrollToRow(r: number, align?: 'start' | 'center' | 'end' | 'nearest'): void;
+  /** 選択中の列インデックス（Ctrl+ヘッダクリックの飛び飛び選択に対応・昇順）。列選択モードでなければ `[]`。 */
+  getSelectedColumns(): number[];
+  /** 選択中の行インデックス（Ctrl+行ヘッダクリックの飛び飛び選択に対応・昇順）。行選択モードでなければ `[]`。 */
+  getSelectedRows(): number[];
+  /** 現在の選択範囲（矩形＋active/extent）を取得。 */
+  getSelection(): { r0: number; c0: number; r1: number; c1: number; active: { r: number; c: number }; extent: { r: number; c: number } };
+  /** 現在の選択矩形 `{r0,c0,r1,c1}`（active↔extent の正規化）。 */
+  rectRange(): { r0: number; c0: number; r1: number; c1: number };
+  /** 飛び飛びの複数列をまとめて削除（高index側から。右クリック「N 列を削除」の実体）。 */
+  deleteColsSet(cols: number[]): void;
+  /** 飛び飛びの複数行をまとめて削除（高index側から。右クリック「N 行を削除」の実体）。 */
+  deleteRowsSet(rows: number[]): void;
+
+  // ---- 行 / 列 構造 -------------------------------------------------------
+  insertRow(ri: number, where?: 'above' | 'below'): void;
+  /** count 行を1回の再描画・1つの undo コマンドで挿入（大量挿入を O(N) に）。maxRows 上限でクランプ。既定 count=1 は insertRow と等価。 */
+  insertRows(ri: number, count?: number, where?: 'above' | 'below'): void;
+  deleteRows(r0: number, r1?: number): void;
+  /** 行 r の中身を空にする（行自体は残す・readOnly はスキップ・1 undo）。rowDelete の🗑を最後の1行で押した時の実体。 */
+  clearRow(r: number): void;
+  insertCol(ci: number, where?: 'left' | 'right'): void;
+  deleteCols(c0: number, c1?: number): void;
+  /** 1行を移動（Undo 対応）。 */
+  moveRow(from: number, to: number): void;
+  /** 複数行をまとめて移動（Undo 対応）。 */
+  moveRows(r0: number, r1: number, to: number): void;
+
+  // ---- 列の表示 / 幅 / 固定 / 行高 ---------------------------------------
+  hideColumn(c: number): void;
+  showColumn(c: number): void;
+  toggleColumn(c: number): void;
+  isColumnHidden(c: number): boolean;
+  getHiddenColumns(): number[];
+  /** 列 c の定義（columns[c]）を取得（列の introspection 用）。 */
+  colCfg(c: number): ColumnDef;
+  /** 列 c の型（'text'|'dropdown'|'checkbox'|'date'|'time'|'number'）。 */
+  colType(c: number): string;
+  /** checkbox 列を全 ON/OFF（readOnly 行はスキップ・1 undo）。 */
+  setColumnChecked(c: number, flag: boolean): void;
+  setColWidth(c: number, px: number): void;
+  autoSizeColumn(c: number): void;
+  autoSizeAllColumns(): void;
+  freezeCols(n: number): void;
+  freezeRows(n: number): void;
+  setRowHeight(r: number, px: number): void;
+
+  // ---- セル状態 / 検証 ----------------------------------------------------
+  setAlignment(align: string, range?: SelectionRange): void;
+  getAlignment(r: number, c: number): string;
+  setCellReadOnly(flag: boolean, range?: SelectionRange): void;
+  /** 今の全セルを検証し、NG を一覧で返す（保存前チェック等）。 */
+  getInvalidCells(): Rejection[];
+
+  // ---- 出力 / 再描画 / 破棄 ----------------------------------------------
+  toCSV(opts?: CsvOptions): string;
+  downloadCSV(filename: string, opts?: CsvOptions): void;
+  /** 列定義変更後などの再描画（データ・選択は保持）。 */
+  redraw(): void;
+  /** セル1つだけ表示を描き直す（テキスト/HTML・条件付き書式・無効表示を最新データで）。全体 redraw より軽い。
+   *  format が外部状態に依存する／セル内ボタンの状態を更新した等に。`c` は列 index か data キー。窓外/非表示は no-op。 */
+  renderCell(r: number, cOrKey: number | string): void;
+  /** 画像/フォント等の遅延レイアウト後に幾何キャッシュを再構築する保険。 */
+  refreshGeometry(): void;
+  /** グリッドを破棄（リスナ除去・DOM 撤去・idempotent）。フレームワークの teardown で呼ぶ。 */
+  destroy(): void;
+
+  // ---- 拡張 ---------------------------------------------------------------
+  addShortcut(s: { name: string; keys: string; handler: (grid: TssGrid, e: KeyboardEvent) => void }): void;
+  removeShortcut(name: string): void;
+  usePlugin(plugin: ((grid: TssGrid, opts?: any) => any) | string, opts?: any): any;
+  getPlugin(name: string): any;
+
+  // ---- 低レベル（公開はするが通常は上位APIを推奨） -----------------------
+  /** 選択範囲（または range）をクリア。※通常は値消去なら setValue('') を推奨。一括の低レベル手段。 */
+  clearRange(): void;
+  /** 選択範囲をクリップボードへ。cut=true で切り取り。 */
+  copy(cut?: boolean): void;
+  /** テーブルDOMを再構築（低レベル）。※通常は redraw() を推奨。主にプラグイン拡張者向け。 */
+  buildTable(): void;
+  /** セルの DOM 要素を返す（低レベル・内部DOM構造に依存）。結合セルはアンカーに解決。 */
+  cellEl(r: number, c: number): HTMLTableCellElement | null;
+
+  /** 遅延ロード: 未取得行を表す sentinel。setRowCount が未取得ぶんを data[r] に入れ、fillRows で実データへ差し替える。 */
+  static readonly PENDING: unique symbol;
+
+  /** 全角→半角（数字・符号・小数点・カンマ・%・¥・空白＋日付/時刻の区切り ／：）。IME 誤入力対策のユーティリティ。
+   *  number/date/time の組込 parse で使うほか、カスタム `parse`/`format` から `TssGrid.zen2han(v)` として呼べる。 */
+  static zen2han(s: string): string;
+
+  /** HTML エスケープ（`&` `<` `>` `"` `'`）。`format` で HTML/属性を組む時などに（属性値も安全）。 */
+  static esc(s: any): string;
+
+  [k: string]: any;
+}
+
+// グローバル（<script> 読み込み時の window.TssGrid / window.HistoryManager）にも型を付ける。
+declare global {
+  interface Window {
+    TssGrid: typeof TssGrid;
+    HistoryManager: typeof HistoryManager;
+  }
+}