cenitu-table 0.0.0-stage → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Cenitu
+
+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/README.md

@@ -1,3 +1,173 @@
-# Temporary Holding Version
+# CenituTable
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/cenitu/cenitu-table/actions/workflows/ci.yml/badge.svg)](https://github.com/cenitu/cenitu-table/actions/workflows/ci.yml)
+[![npm](https://img.shields.io/npm/v/cenitu-table.svg)](https://www.npmjs.com/package/cenitu-table)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+A spreadsheet-like data grid with a built-in, multi-sheet formula engine. Written in TypeScript with **zero runtime dependencies**; an optional React component is included.
+
+**[Live demo](https://cenitu.github.io/cenitu-table/)** · [Türkçe](README.tr.md) · [Design notes](docs/SPEC.md)
+
+## Features
+
+- **Grid:** virtual scrolling (only visible cells are in the DOM), keyboard navigation (Ctrl+arrows jump to data edges), spreadsheet-compatible copy/cut/paste with styles, undo/redo, column and row resizing, row/column insert and delete, right-click context menu.
+- **Sorting and filtering:** sort by several columns, filter by condition or value from the column menu. Only the view changes; data and formulas stay where they are.
+- **Find and replace:** Ctrl+F / Ctrl+H, also through rows outside the viewport, in displayed values or in formulas.
+- **Formula bar:** the active cell's address and content above the grid, editable.
+- **Autofill:** drag the fill handle to continue number and text series and to copy formulas with relative references; double-click to fill down; Ctrl+D.
+- **Cell types:** numeric (Intl formats: currency, percent), date, checkbox, dropdown; validators, read-only cells, custom renderers.
+- **Formatting:** bold, italic, underline, strike-through, colors, alignment, wrapping (Ctrl+B / I / U), conditional formatting for cells or whole rows.
+- **Layout:** frozen rows and columns, merged cells, hidden columns, column drag-and-drop.
+- **Formula engine:** 100+ functions (SUM, IF, XLOOKUP, SUMIFS, TEXT, date functions…), dynamic arrays that spill (FILTER, SORT, UNIQUE, SEQUENCE), cross-sheet references (`'Other sheet'!A1`), named expressions, incremental recalculation, cycle detection.
+- **Data binding:** rows as arrays or as objects bound to columns by property path; edits are written back to your objects.
+- **Import and export:** read and write XLSX (formulas, formats, styles, frozen panes, merges), export CSV with protection against formula injection, all without any library.
+- **Accessibility:** ARIA grid roles and an announced active cell for screen readers.
+- **React:** `<CenituTable />` from `cenitu-table/react`.
+
+## Install
+
+```bash
+npm install cenitu-table
+```
+
+## Usage
+
+```ts
+import { CenituGrid } from 'cenitu-table';
+
+const grid = new CenituGrid(document.getElementById('grid')!, {
+  data: [
+    ['Product', 'Qty', 'Price', 'Total'],
+    ['Screw', 10, 2.5, '=B2*C2'],
+    ['Nut', 20, 1.25, '=B3*C3'],
+  ],
+  fixedRowsTop: 1,
+  columnSorting: true,
+  filters: true,
+  contextMenu: true,
+  columns: [
+    { type: 'dropdown', source: ['Screw', 'Nut', 'Washer'] },
+    { type: 'numeric', validator: (v) => Number(v) > 0 || 'Must be positive' },
+    { type: 'numeric', numericFormat: { style: 'currency', currency: 'EUR' } },
+    { type: 'numeric', numericFormat: { style: 'currency', currency: 'EUR' }, readOnly: true },
+  ],
+  height: 400,
+});
+
+grid.addHook('afterChange', (changes, source) => console.log(changes, source));
+grid.getDataAtCell(1, 3);       // 25 (computed value)
+grid.getSourceDataAtCell(1, 3); // "=B2*C2"
+```
+
+### Objects instead of arrays
+
+```ts
+const orders = [{ product: 'Screw', qty: 10, customer: { name: 'Acme' } }];
+
+new CenituGrid(el, {
+  data: orders,
+  columns: [{ data: 'product' }, { data: 'qty', type: 'numeric' }, { data: 'customer.name', title: 'Customer' }],
+  dataSchema: () => ({ product: '', qty: 0, customer: { name: '' } }),
+});
+// Edits are written back: orders[0].qty changes when the cell changes.
+```
+
+Formula cells write their computed value into the object and keep it current, so your properties stay plain values. Set `bindFormulas: 'text'` to store the formula text instead.
+
+### Several sheets
+
+Give one engine to several grids — one grid per sheet:
+
+```ts
+import { CenituGrid, FormulaEngine } from 'cenitu-table';
+
+const engine = FormulaEngine.buildEmpty();
+engine.addNamedExpression('VatRate', 0.2);
+new CenituGrid(el1, { formulas: engine, sheetName: 'Orders', data: orders });
+new CenituGrid(el2, { formulas: engine, sheetName: 'Summary', data: [['=SUM(Orders!F2:F100)*(1+VatRate)']] });
+```
+
+### Export
+
+```ts
+grid.downloadCSV('orders.csv');                      // ";" fields and "," decimals for decimal-comma locales
+await grid.downloadXLSX('book.xlsx', [summaryGrid]); // several sheets in one workbook
+```
+
+### Import
+
+```ts
+await grid.importXLSX(file, { sheet: 'Orders' }); // a File, Blob or bytes; default is the first sheet
+```
+
+To load a whole workbook, give all grids one engine, so formulas can reach the other sheets:
+
+```ts
+import { CenituGrid, readXLSX, workbookEngine } from 'cenitu-table';
+
+const book = await readXLSX(file);
+const engine = workbookEngine(book);
+book.sheets.forEach((sheet, i) => {
+  new CenituGrid(hosts[i], { formulas: engine, sheetName: sheet.name }).loadSheet(sheet);
+});
+```
+
+Read: values, formulas, number formats, fonts, fills, alignment, column widths, row heights, hidden columns, frozen panes, merges and defined names. Not read: charts, images, comments, conditional formats, data validation and hidden rows (they are shown). Pass `formulas: 'values'` to take the results stored in the file instead of formulas, for example when a file uses functions the engine does not have.
+
+### Find, formula bar, sorting by several columns
+
+```ts
+new CenituGrid(el, { data, search: true, formulaBar: true, columnSorting: true });
+
+grid.openSearch(true);                             // or Ctrl+F / Ctrl+H with `search: true`
+grid.findNext('screw', { matchCase: false });
+grid.replaceAll('A1', 'B1', { lookIn: 'formulas' }); // one undo step; returns the cells changed
+grid.sortBy([{ col: 2, order: 'desc' }, { col: 0, order: 'asc' }]);
+```
+
+Without `lookIn: 'formulas'`, replacing leaves formula cells alone. `formulaBar` adds a row above the grid, on top of its `height`. The column menu offers "Then sort" once another column is sorted.
+
+### React
+
+```tsx
+import { CenituTable } from 'cenitu-table/react';
+
+<CenituTable ref={gridRef} data={data} fixedRowsTop={1} onChange={(changes) => save(changes)} />;
+```
+
+### Formula engine on its own
+
+```ts
+import { FormulaEngine, registerFunction } from 'cenitu-table';
+
+const engine = FormulaEngine.buildFromArray([[1, 2, '=A1+B1']]);
+engine.setCellContents({ row: 0, col: 0 }, 10); // returns the changed cells
+engine.getCellValue({ row: 0, col: 2 });         // 12
+registerFunction('DOUBLE', { minArgs: 1, maxArgs: 1, impl: ([x]) => (x as number) * 2 });
+```
+
+### Localization
+
+```ts
+import { trTR } from 'cenitu-table';
+
+new CenituGrid(el, { locale: 'tr-TR', language: trTR, data });
+```
+
+`locale` drives number and date formatting; `language` holds the UI texts (English by default, Turkish included).
+
+## Development
+
+```bash
+npm install
+npm run dev        # demo at http://localhost:5180
+npm test           # unit tests (vitest + jsdom)
+npm run test:e2e   # browser tests (Playwright: Chromium, Firefox, WebKit)
+npm run build      # type check, ESM/CJS bundles and .d.ts in dist/
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). Notable changes are listed in [CHANGELOG.md](CHANGELOG.md).
+
+## License
+
+[MIT](LICENSE)

package/README.tr.md

@@ -0,0 +1,171 @@
+# CenituTable
+
+Spreadsheet benzeri bir data grid ve ona bağlı, çok sayfalı bir formül motoru. TypeScript ile yazıldı, **çalışma zamanı bağımlılığı yok**. İsteğe bağlı bir React bileşeni de içeriyor.
+
+**[Canlı demo](https://cenitu.github.io/cenitu-table/)** · [English](README.md) · [Tasarım notları](docs/SPEC.md)
+
+## Özellikler
+
+- **Grid:** sanal kaydırma (yalnızca görünen hücreler DOM'da), klavye gezinmesi (Ctrl+ok ile veri bloğu sonuna atlama), Excel uyumlu, biçimli kopyala/kes/yapıştır, geri al/yinele, sütun ve satır boyutlandırma, satır/sütun ekleme-silme, sağ tık menüsü.
+- **Sıralama ve filtre:** birden fazla sütuna göre sıralama, sütun menüsünden koşula ya da değere göre filtre. Yalnızca görünüm değişir; veri ve formüller yerinde kalır.
+- **Bul ve değiştir:** Ctrl+F / Ctrl+H; ekran dışındaki satırlarda da çalışır, görünen değerlerde ya da formüllerde arar.
+- **Formül çubuğu:** aktif hücrenin adresi ve içeriği grid'in üstünde gösterilir, buradan düzenlenebilir.
+- **Doldurma tutamacı:** sayı ve metin serileri, göreli kayan formüller, çift tıklamayla otomatik doldurma, Ctrl+D.
+- **Hücre tipleri:** sayı (para, yüzde gibi Intl biçimleri), tarih, onay kutusu, açılır liste; doğrulayıcılar, salt-okunur hücreler, özel çiziciler.
+- **Biçimlendirme:** kalın, italik, altı çizili, üstü çizili, renkler, hizalama, metin kaydırma (Ctrl+B / I / U); hücre ya da tüm satır için koşullu biçimlendirme.
+- **Yerleşim:** sabit satır ve sütunlar, birleştirilmiş hücreler, gizli sütunlar, sürükleyerek sütun taşıma.
+- **Formül motoru:** 100'den fazla fonksiyon (SUM, IF, XLOOKUP, SUMIFS, TEXT, tarih fonksiyonları…), taşan dinamik diziler (FILTER, SORT, UNIQUE, SEQUENCE), sayfalar arası referanslar (`'Diğer Sayfa'!A1`), isimli ifadeler, artımlı yeniden hesaplama, döngü tespiti.
+- **Veri bağlama:** satırlar dizi ya da nesne olarak verilebilir. Nesnelerde sütunlar alan yoluna bağlanır ve düzenlemeler nesnelerinize geri yazılır.
+- **İçe ve dışa aktarma:** XLSX okuma ve yazma (formüller, biçimler, stiller, sabit bölmeler, birleştirmeler), formül enjeksiyonuna karşı korumalı CSV; hiçbir kütüphane kullanmadan.
+- **Erişilebilirlik:** ARIA grid rolleri, ekran okuyucuya duyurulan aktif hücre.
+- **React:** `cenitu-table/react` içinden `<CenituTable />`.
+
+## Kurulum
+
+```bash
+npm install cenitu-table
+```
+
+## Kullanım
+
+```ts
+import { CenituGrid, trTR } from 'cenitu-table';
+
+const grid = new CenituGrid(document.getElementById('grid')!, {
+  data: [
+    ['Ürün', 'Adet', 'Fiyat', 'Tutar'],
+    ['Vida', 10, 2.5, '=B2*C2'],
+    ['Somun', 20, 1.25, '=B3*C3'],
+  ],
+  fixedRowsTop: 1,
+  columnSorting: true,
+  filters: true,
+  contextMenu: true,
+  locale: 'tr-TR',
+  language: trTR,
+  columns: [
+    { type: 'dropdown', source: ['Vida', 'Somun', 'Pul'] },
+    { type: 'numeric', validator: (v) => Number(v) > 0 || 'Pozitif olmalı' },
+    { type: 'numeric', numericFormat: { style: 'currency', currency: 'TRY' } },
+    { type: 'numeric', numericFormat: { style: 'currency', currency: 'TRY' }, readOnly: true },
+  ],
+  height: 400,
+});
+
+grid.addHook('afterChange', (changes, source) => console.log(changes, source));
+grid.getDataAtCell(1, 3);       // 25 (hesaplanmış değer)
+grid.getSourceDataAtCell(1, 3); // "=B2*C2"
+```
+
+### Dizi yerine nesneler
+
+```ts
+const siparisler = [{ urun: 'Vida', adet: 10, musteri: { ad: 'Acme' } }];
+
+new CenituGrid(el, {
+  data: siparisler,
+  columns: [{ data: 'urun' }, { data: 'adet', type: 'numeric' }, { data: 'musteri.ad', title: 'Müşteri' }],
+  dataSchema: () => ({ urun: '', adet: 0, musteri: { ad: '' } }),
+});
+// Düzenlemeler geri yazılır: hücre değişince siparisler[0].adet de değişir.
+```
+
+Formül hücreleri nesneye hesaplanmış değeri yazar ve güncel tutar; böylece alanlarınız düz değer olarak kalır. Formül metnini saklamak için `bindFormulas: 'text'` kullanın.
+
+### Birden fazla sayfa
+
+Tek bir motoru birden fazla grid'e verin (her grid bir sayfa):
+
+```ts
+import { CenituGrid, FormulaEngine } from 'cenitu-table';
+
+const engine = FormulaEngine.buildEmpty();
+engine.addNamedExpression('KdvOrani', 0.2);
+new CenituGrid(el1, { formulas: engine, sheetName: 'Siparişler', data: siparisler });
+new CenituGrid(el2, { formulas: engine, sheetName: 'Özet', data: [['=SUM(Siparişler!F2:F100)*(1+KdvOrani)']] });
+```
+
+### Dışa aktarma
+
+```ts
+grid.downloadCSV('siparisler.csv');                   // tr-TR'de ";" ayraç ve "," ondalık
+await grid.downloadXLSX('kitap.xlsx', [ozetGrid]);    // birden fazla sayfa tek dosyada
+```
+
+### İçe aktarma
+
+```ts
+await grid.importXLSX(dosya, { sheet: 'Siparişler' }); // File, Blob ya da bayt dizisi; varsayılan ilk sayfa
+```
+
+Bütün çalışma kitabını yüklemek için tüm grid'lere tek motor verin; böylece formüller diğer sayfalara ulaşır:
+
+```ts
+import { CenituGrid, readXLSX, workbookEngine } from 'cenitu-table';
+
+const kitap = await readXLSX(dosya);
+const engine = workbookEngine(kitap);
+kitap.sheets.forEach((sayfa, i) => {
+  new CenituGrid(alanlar[i], { formulas: engine, sheetName: sayfa.name }).loadSheet(sayfa);
+});
+```
+
+Okunanlar: değerler, formüller, sayı biçimleri, yazı tipleri, dolgular, hizalama, sütun genişlikleri, satır yükseklikleri, gizli sütunlar, sabit bölmeler, birleştirmeler ve tanımlı adlar. Okunmayanlar: grafikler, resimler, yorumlar, koşullu biçimler, veri doğrulama ve gizli satırlar (görünür hale gelir). Dosyada motorun bilmediği fonksiyonlar varsa `formulas: 'values'` ile formüller yerine dosyadaki sonuçları alabilirsiniz.
+
+### Bul, formül çubuğu, çok sütunlu sıralama
+
+```ts
+new CenituGrid(el, { data, search: true, formulaBar: true, columnSorting: true });
+
+grid.openSearch(true);                                // ya da `search: true` ile Ctrl+F / Ctrl+H
+grid.findNext('vida', { matchCase: false });
+grid.replaceAll('A1', 'B1', { lookIn: 'formulas' });  // tek geri alma adımı; değişen hücre sayısını döndürür
+grid.sortBy([{ col: 2, order: 'desc' }, { col: 0, order: 'asc' }]);
+```
+
+`lookIn: 'formulas'` olmadan değiştirme işlemi formül hücrelerine dokunmaz. `formulaBar`, grid'in `height` değerine ek olarak üstte bir satır kaplar. Bir sütun sıralıyken diğer sütunların menüsünde "Sonra sırala" seçenekleri çıkar.
+
+### React
+
+```tsx
+import { CenituTable } from 'cenitu-table/react';
+
+<CenituTable ref={gridRef} data={data} fixedRowsTop={1} onChange={(changes) => kaydet(changes)} />;
+```
+
+### Yalnızca formül motoru
+
+```ts
+import { FormulaEngine, registerFunction } from 'cenitu-table';
+
+const engine = FormulaEngine.buildFromArray([[1, 2, '=A1+B1']]);
+engine.setCellContents({ row: 0, col: 0 }, 10); // değişen hücreleri döndürür
+engine.getCellValue({ row: 0, col: 2 });         // 12
+registerFunction('DOUBLE', { minArgs: 1, maxArgs: 1, impl: ([x]) => (x as number) * 2 });
+```
+
+### Yerelleştirme
+
+```ts
+import { trTR } from 'cenitu-table';
+
+new CenituGrid(el, { locale: 'tr-TR', language: trTR, data });
+```
+
+`locale` sayı ve tarih biçimini belirler; `language` arayüz metinlerini taşır (varsayılan İngilizce, Türkçe dahil).
+
+## Geliştirme
+
+```bash
+npm install
+npm run dev        # demo: http://localhost:5180
+npm test           # birim testleri (vitest + jsdom)
+npm run test:e2e   # tarayıcı testleri (Playwright: Chromium, Firefox, WebKit)
+npm run build      # tip denetimi, ESM/CJS paketleri ve dist/ altında .d.ts
+```
+
+Bkz. [CONTRIBUTING.md](CONTRIBUTING.md). Önemli değişiklikler [CHANGELOG.md](CHANGELOG.md)'de.
+
+## Lisans
+
+[MIT](LICENSE)

package/dist/cenitu-table.cjs

@@ -0,0 +1 @@
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./index-BHarWDHD.cjs");exports.CSV_MIME=e.CSV_MIME;exports.CellError=e.CellError;exports.CenituGrid=e.CenituGrid;exports.FormulaEngine=e.FormulaEngine;exports.FormulaSyntaxError=e.FormulaSyntaxError;exports.MAX_COLS=e.MAX_COLS;exports.MAX_ROWS=e.MAX_ROWS;exports.RangeValue=e.RangeValue;exports.SHEET_SPAN=e.SHEET_SPAN;exports.XLSX_MIME=e.XLSX_MIME;exports.ZipReader=e.ZipReader;exports.cellKey=e.cellKey;exports.columnIndex=e.columnIndex;exports.columnLabel=e.columnLabel;exports.crc32=e.crc32;exports.dateCodeFromPattern=e.dateCodeFromPattern;exports.dateToSerial=e.dateToSerial;exports.downloadBlob=e.downloadBlob;exports.enUS=e.enUS;exports.formatDateCode=e.formatDateCode;exports.formatSerialDate=e.formatSerialDate;exports.getRegisteredFunctionNames=e.getRegisteredFunctionNames;exports.inverseMove=e.inverseMove;exports.isDateFormat=e.isDateFormat;exports.isError=e.isError;exports.isFormula=e.isFormula;exports.keyToAddress=e.keyToAddress;exports.normalizeRange=e.normalizeRange;exports.numberFormatFromMeta=e.numberFormatFromMeta;exports.parseA1=e.parseA1;exports.parseDateString=e.parseDateString;exports.parseFormula=e.parseFormula;exports.pxToColWidth=e.pxToColWidth;exports.quoteSheetName=e.quoteSheetName;exports.rangeContains=e.rangeContains;exports.readXLSX=e.readXLSX;exports.registerFunction=e.registerFunction;exports.sanitizeSheetNames=e.sanitizeSheetNames;exports.serialToDate=e.serialToDate;exports.setClock=e.setClock;exports.setRandom=e.setRandom;exports.toA1=e.toA1;exports.toCSV=e.toCSV;exports.toXLSX=e.toXLSX;exports.toXLSXCompressed=e.toXLSXCompressed;exports.trTR=e.trTR;exports.unparse=e.unparse;exports.unregisterFunction=e.unregisterFunction;exports.workbookEngine=e.workbookEngine;exports.xlsxParts=e.xlsxParts;exports.zipDeflate=e.zipDeflate;exports.zipStore=e.zipStore;

package/dist/cenitu-table.js

@@ -0,0 +1,55 @@
+import { a as e, b as r, C as o, F as t, c as n, M as i, d as l, R as m, S, X as d, Z as u, e as C, f as F, g, h as p, j as X, k as c, l as E, m as M, n as R, o as x, p as A, q as D, r as L, s as T, t as _, u as b, v as f, w as k, x as z, y as N, z as h, A as y, B as I, D as P, E as V, G as v, H as w, I as W, J as q, K as B, L as G, N as H, P as K, Q as O, T as U, U as Z, V as j, W as J, Y as Q, _ as Y, $ } from "./index-BpjIy-X9.js";
+export {
+  e as CSV_MIME,
+  r as CellError,
+  o as CenituGrid,
+  t as FormulaEngine,
+  n as FormulaSyntaxError,
+  i as MAX_COLS,
+  l as MAX_ROWS,
+  m as RangeValue,
+  S as SHEET_SPAN,
+  d as XLSX_MIME,
+  u as ZipReader,
+  C as cellKey,
+  F as columnIndex,
+  g as columnLabel,
+  p as crc32,
+  X as dateCodeFromPattern,
+  c as dateToSerial,
+  E as downloadBlob,
+  M as enUS,
+  R as formatDateCode,
+  x as formatSerialDate,
+  A as getRegisteredFunctionNames,
+  D as inverseMove,
+  L as isDateFormat,
+  T as isError,
+  _ as isFormula,
+  b as keyToAddress,
+  f as normalizeRange,
+  k as numberFormatFromMeta,
+  z as parseA1,
+  N as parseDateString,
+  h as parseFormula,
+  y as pxToColWidth,
+  I as quoteSheetName,
+  P as rangeContains,
+  V as readXLSX,
+  v as registerFunction,
+  w as sanitizeSheetNames,
+  W as serialToDate,
+  q as setClock,
+  B as setRandom,
+  G as toA1,
+  H as toCSV,
+  K as toXLSX,
+  O as toXLSXCompressed,
+  U as trTR,
+  Z as unparse,
+  j as unregisterFunction,
+  J as workbookEngine,
+  Q as xlsxParts,
+  Y as zipDeflate,
+  $ as zipStore
+};