@threestarsoftware/tssgrid 0.1.9 → 0.1.11

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 TssGrid の各リリースの変更点。日付は JST。形式は [Keep a Changelog](https://keepachangelog.com/ja/1.1.0/) 準拠（ゆるめ）。
 数値は特記なき限り**自社調べ**（headless Chrome / Windows 11・環境差あり）。
 
+## [0.1.11] - 2026-09-16
+
+### 修正
+- **表全体版 `cellClass` / `cellStyle` / `rowClass` と `CellClassCtx` の `src`（元レコード）を `any` に**（型定義のみ・実行時は不変）— `src` は関数の**引数（反変位置）**なので `Record<string, any> | null` で固定すると、**自分で行の型を書いている利用者が関数を渡せず** `as unknown as MyRow` の二重キャストを強いられていた（0.1.9〜0.1.10 で該当）。`any` にすると利用側が `src: MyRow` と**そのまま注釈でき、関数内はその型で検査される**（今より安全側・既に `row: any[]` なので揃う）。d.ts 4か所（`CellClassCtx.src` / 表全体 `cellClass`・`cellStyle`・`rowClass`）＋ api.html を更新。※将来の `TssGrid<Row>` ジェネリック化は 0.2 系で検討。
+
+## [0.1.10] - 2026-09-16
+
+### 追加
+- **`scrollToRow(r, align?)`（指定行までスクロール＝HTML の `#` アンカー相当）**（コア）— 任意の行を画面の**先頭へ**持ってくる公開メソッド。`align` は `'start'`（既定＝先頭・sticky ヘッダ直下）/ `'center'` / `'end'` / `'nearest'`（可視ならそのまま）。**仮想（均一行高）でも非仮想（実DOM測定・可変行高）でも動く**。範囲外の `r` は自動クランプ。**選択は変えない**（目印が欲しい時は `rowClass` 等を併用）。動く例 `examples/scroll-to-row.html`（1000行・行番号ジャンプ＋align 切替＋rowClass ハイライト）。
+
 ## [0.1.9] - 2026-09-15
 
 ### 追加

package/README.md

@@ -918,7 +918,7 @@ new TssGrid(el, {
 });
 ```
 
-メソッド: `getData()` / `getRows()` / `getRow(r)` / `getColumn(cOrKey)` / `getColumns()` / `setData(rows)` / `appendRows(rows,opts?)`（**背景で"育てる"追記**＝data末尾に足し可視窓だけ再描画。buildTable全再描画せずスクロール位置・選択・編集中エディタを保ち履歴にも積まない。「先頭ページを描く→残りをidleでappendRows」でfirst-paintを早める土台。既存経路は不変のopt-in） / `setRowCount(total)` ＋ `fillRows(start,rows)`（**遅延ロード=on-demand**＝virtual前提。総件数を確保し未取得ぶんは「読込中」行、`onViewportChange(start,end)` で要る範囲を受け `fillRows` で実データを流し込む。sort/filterは遅延中ローカル計算せず `onSortFilterChange` でサーバ委譲、未取得セルは編集不可、export（getData/toCSV）はロード済みのみ＝AG Grid の Infinite Row Model 相当を push で） / `getValue(r,cOrKey)` / `setValue(r,cOrKey,val,force?)` / `setValueRaw(r,cOrKey,val)`（履歴に積まない派生値書き込み・計算列用） / `hideColumn(c)` / `showColumn(c)` / `toggleColumn(c)` / `isColumnHidden(c)` / `getHiddenColumns()` / `setAlignment(align,range?)` / `getAlignment(r,c)` / `setCellReadOnly(flag,range?)` / `autoSizeColumn(c)` / `autoSizeAllColumns()` / `sortBy(cOrKey, dir)` / `sortRows(cmp)` / `addShortcut(s)` / `removeShortcut(name)` / `usePlugin(fn)` / `getPlugin(name)` / `destroy()` / `setActive(r,c)` / `selectRow(r)` / `selectCol(c)` / `selectAll()` / `setColWidth(c,px)` / `setRowHeight(r,px)` / `freezeCols(n)` / `freezeRows(n)` / `moveRow(from,to)` / `moveRows(r0,r1,to)` / `clearSort()` / `toCSV(opts)` / `downloadCSV(name,opts)` / `insertRow(ri,'above'|'below')` / `insertRows(ri,count?,'above'|'below')`（count 行を1回の再描画・1 undo で一括挿入＝大量挿入が O(N)） / `deleteRows(r0,r1?)` / `insertCol(ci,'left'|'right')` / `deleteCols(c0,c1?)` / `redraw()`（列定義変更後の再描画, データ・選択は保持）ほか。
+メソッド: `getData()` / `getRows()` / `getRow(r)` / `getColumn(cOrKey)` / `getColumns()` / `setData(rows)` / `appendRows(rows,opts?)`（**背景で"育てる"追記**＝data末尾に足し可視窓だけ再描画。buildTable全再描画せずスクロール位置・選択・編集中エディタを保ち履歴にも積まない。「先頭ページを描く→残りをidleでappendRows」でfirst-paintを早める土台。既存経路は不変のopt-in） / `setRowCount(total)` ＋ `fillRows(start,rows)`（**遅延ロード=on-demand**＝virtual前提。総件数を確保し未取得ぶんは「読込中」行、`onViewportChange(start,end)` で要る範囲を受け `fillRows` で実データを流し込む。sort/filterは遅延中ローカル計算せず `onSortFilterChange` でサーバ委譲、未取得セルは編集不可、export（getData/toCSV）はロード済みのみ＝AG Grid の Infinite Row Model 相当を push で） / `getValue(r,cOrKey)` / `setValue(r,cOrKey,val,force?)` / `setValueRaw(r,cOrKey,val)`（履歴に積まない派生値書き込み・計算列用） / `hideColumn(c)` / `showColumn(c)` / `toggleColumn(c)` / `isColumnHidden(c)` / `getHiddenColumns()` / `setAlignment(align,range?)` / `getAlignment(r,c)` / `setCellReadOnly(flag,range?)` / `autoSizeColumn(c)` / `autoSizeAllColumns()` / `sortBy(cOrKey, dir)` / `sortRows(cmp)` / `addShortcut(s)` / `removeShortcut(name)` / `usePlugin(fn)` / `getPlugin(name)` / `destroy()` / `setActive(r,c)` / `scrollToRow(r, align?)`（**指定行までスクロール＝HTML の `#` アンカー相当**。`align` は `'start'`〔既定＝先頭・sticky ヘッダ直下〕/`'center'`/`'end'`/`'nearest'`〔可視ならそのまま〕。仮想・非仮想どちらでも動き、範囲外 `r` は自動クランプ。**選択は変えない**ので目印は `rowClass` 等を併用。例 `examples/scroll-to-row.html`） / `selectRow(r)` / `selectCol(c)` / `selectAll()` / `setColWidth(c,px)` / `setRowHeight(r,px)` / `freezeCols(n)` / `freezeRows(n)` / `moveRow(from,to)` / `moveRows(r0,r1,to)` / `clearSort()` / `toCSV(opts)` / `downloadCSV(name,opts)` / `insertRow(ri,'above'|'below')` / `insertRows(ri,count?,'above'|'below')`（count 行を1回の再描画・1 undo で一括挿入＝大量挿入が O(N)） / `deleteRows(r0,r1?)` / `insertCol(ci,'left'|'right')` / `deleteCols(c0,c1?)` / `redraw()`（列定義変更後の再描画, データ・選択は保持）ほか。
 
 ## イベント
 

package/package.json

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

package/src/tssgrid.d.ts

@@ -25,8 +25,9 @@ export interface ChangeItem {
 /** 選択範囲。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）。 */
-export interface CellClassCtx { r: number; c: number; row: any[]; src: Record<string, any> | null; }
+/** 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%'`）。 */
@@ -114,12 +115,12 @@ export interface TssGridOptions {
   columns?: ColumnDef[];
   /** 表全体の条件付きクラス（全セルで呼ばれる）。**引数は `(r, c, value, row, src)`**（先頭が行/列番号・列版と順序が違う）。
    *  `row`=その行の値配列, `src`=元レコード（object モード時・非表示フィールドも見える）。行に色を付けたいなら `rowClass` の方が簡単。 */
-  cellClass?: (r: number, c: number, value: any, row: any[], src: Record<string, any> | null) => ClassValue;
+  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: Record<string, any> | null) => StyleValue;
+  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: Record<string, any> | null) => ClassValue;
+  rowClass?: (r: number, row: any[], src: any) => ClassValue;
   /** 検証NG時。'revert'=元に戻す / 'keep'=赤く警告して残す。 */
   invalidMode?: 'revert' | 'keep';
   invalidTitle?: boolean;
@@ -399,6 +400,12 @@ export declare class TssGrid {
   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+行ヘッダクリックの飛び飛び選択に対応・昇順）。行選択モードでなければ `[]`。 */

package/src/tssgrid.js

@@ -1486,6 +1486,35 @@
       if (st !== cur) this.wrap.scrollTop = st;
       this._renderWindow(this._vWindow(), false);   // 窓を即同期（place 前に DOM を確定）
     }
+    // 指定行までスクロール（HTML の # アンカー相当）。align: 'start'(既定=先頭へ)/'center'/'end'/'nearest'。
+    // 仮想（均一行高）でも非仮想（実DOM・可変行高）でも動く。sticky ヘッダの下にちゃんと収める。
+    scrollToRow(r, align = 'start') {
+      if (!this.wrap || !this.ROWS) return;
+      r = Math.max(0, Math.min(this.ROWS - 1, Math.trunc(r || 0)));
+      if (align === 'nearest' && this.virtual) { this._vEnsureVisible(r); return; }   // 最小移動は既存ロジックに委譲
+      const head = this.colHeaders ? (this._theadH || 0) : 0;
+      const viewH = this.wrap.clientHeight || 400;
+      let top, rowH;
+      if (this.virtual) {
+        rowH = this.defRowH; top = r * rowH;   // 均一行高: content-top（sticky thead 直下が基準）
+      } else {
+        const tr = this.table && this.table.querySelector('tbody tr[data-r="' + r + '"]');
+        if (!tr) return;
+        const t = tr.getBoundingClientRect(), w = this.wrap.getBoundingClientRect();
+        rowH = t.height; top = t.top - w.top + this.wrap.scrollTop - head;   // 実DOMから測る（可変行高対応）
+      }
+      let st = top;   // start: 行を先頭（sticky thead 直下）へ
+      if (align === 'center') st = top - Math.max(0, (viewH - head - rowH) / 2);
+      else if (align === 'end') st = top - Math.max(0, viewH - head - rowH);
+      else if (align === 'nearest') {   // 非仮想の nearest: 既に可視なら動かさない
+        const vt = top - this.wrap.scrollTop;
+        if (vt >= 0 && vt + rowH <= viewH - head) return;
+        if (vt > 0) st = top - (viewH - head - rowH);   // 下にはみ出し→下端、上は top のまま
+      }
+      const max = this.wrap.scrollHeight - this.wrap.clientHeight;
+      this.wrap.scrollTop = Math.max(0, Math.min(st, max));
+      if (this.virtual) this._renderWindow(this._vWindow(), false);   // 窓を即同期
+    }
     buildTable() {
       if (this._renderPaused) { this._renderDirty = true; return; }   // バッチ描画中は最後にまとめて1回（_withBatchedRender）
       if (this._customEditor && this._customCancel) this._customCancel();   // 開いているカスタムエディタを閉じる（body直下ポップアップの取り残し防止・_commitActive と同じ扱い）