@shiguri/solid-grid 0.0.1 → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 shiguri
+
+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,42 +1,59 @@
 # solid-grid
 
-Headless spreadsheet-like grid for SolidJS. Works with a 2D array (`T[][]`) and gives you full control over rendering and styling.
+A headless, plugin-driven grid component for [SolidJS](https://www.solidjs.com/).
+Designed for **T[][]** data and custom rendering.
 
-## Install
+> **Work in progress**: The API is still evolving and may include breaking changes.
+
+## Installation
 
 ```bash
 npm install @shiguri/solid-grid
 ```
 
-## Quick Start
+## Usage
 
 ```tsx
-import { Gridsheet } from "@shiguri/solid-grid";
 import { createSignal } from "solid-js";
+import {
+  Gridsheet,
+  createPluginHost,
+  selectionPlugin,
+  editingPlugin,
+} from "@shiguri/solid-grid";
 
 const [data, setData] = createSignal([
   ["A1", "B1"],
   ["A2", "B2"],
 ]);
 
+const plugins = createPluginHost([
+  selectionPlugin(),
+  editingPlugin({ triggerKeys: ["Enter"] }),
+]);
+
 <Gridsheet
   data={data()}
-  onDataChange={setData}
-  renderCell={(ctx) =>
-    ctx.isEditing ? (
-      <input
-        value={ctx.value}
-        onKeyDown={(e) =>
-          e.key === "Enter" && ctx.commitEdit(e.currentTarget.value)
-        }
-      />
-    ) : (
-      <span>{ctx.value}</span>
-    )
+  onCellsChange={(patches) =>
+    setData((prev) => {
+      const next = prev.map((row) => row.slice());
+      for (const { pos, value } of patches) {
+        next[pos.row][pos.col] = value;
+      }
+      return next;
+    })
   }
+  renderCell={(ctx) => <span>{ctx.value}</span>}
+  onEvent={plugins.onEvent}
 />;
 ```
 
-## More Info
+## Documentation
+
+- `docs/guide.md`
+- `docs/recipes.md`
+- `docs/styling.md`
+
+---
 
-See full docs in the root repository `docs/`.
+© 2025 shiguri | [MIT License](./LICENSE)

package/dist/gridsheet-D9A0kuhj.d.ts

@@ -0,0 +1,138 @@
+import { JSX } from "solid-js/jsx-runtime";
+
+//#region src/gridsheet.d.ts
+/** Zero-based cell position. */
+type CellPosition = {
+  row: number;
+  col: number;
+};
+/** Inclusive range of cells. */
+type CellRange = {
+  min: CellPosition;
+  max: CellPosition;
+};
+/** Normalize two positions into an inclusive range. */
+declare function normalizeRange(pos1: CellPosition, pos2: CellPosition): CellRange;
+/** Render-time context for a single cell. */
+interface CellRenderContext<T> {
+  row: number;
+  col: number;
+  value: T;
+  isActive: boolean;
+  isSelected: boolean;
+  isEditing: boolean;
+  cellRef: HTMLTableCellElement | undefined;
+  beginEdit: () => void;
+  commitEdit: (value: T) => void;
+  cancelEditing: () => void;
+}
+/** Events emitted from Gridsheet to plugins/handlers. */
+type GridEvent = {
+  type: "cell:pointerdown";
+  pos: CellPosition;
+  e: MouseEvent;
+} | {
+  type: "cell:pointerover";
+  pos: CellPosition;
+  e: MouseEvent;
+} | {
+  type: "cell:dblclick";
+  pos: CellPosition;
+  e: MouseEvent;
+} | {
+  type: "key:down";
+  e: KeyboardEvent;
+} | {
+  type: "corner:click";
+  e: MouseEvent;
+} | {
+  type: "rowheader:pointerdown";
+  row: number;
+  e: MouseEvent;
+} | {
+  type: "rowheader:pointerover";
+  row: number;
+  e: MouseEvent;
+} | {
+  type: "colheader:pointerdown";
+  col: number;
+  e: MouseEvent;
+} | {
+  type: "colheader:pointerover";
+  col: number;
+  e: MouseEvent;
+} | {
+  type: "pointer:up";
+  e: PointerEvent | MouseEvent;
+};
+/** Return true to stop further handling. */
+type GridEventHandler<T> = (ev: GridEvent, api: GridApi<T>) => boolean | undefined;
+/** Props for the Gridsheet component. */
+interface GridsheetProps<T> {
+  data: T[][];
+  /** Apply patches to external data store. */
+  onCellsChange?: (patches: CellPatch<T>[]) => void;
+  renderCell: (ctx: CellRenderContext<T>) => JSX.Element;
+  renderRowHeader?: (ctx: {
+    index: number;
+    isSelected: boolean;
+  }) => JSX.Element;
+  renderColHeader?: (ctx: {
+    index: number;
+    isSelected: boolean;
+  }) => JSX.Element;
+  activeCell?: CellPosition | null;
+  onActiveCellChange?: (pos: CellPosition | null) => void;
+  selection?: CellRange | null;
+  onSelectionChange?: (range: CellRange | null) => void;
+  isEditing?: boolean;
+  onIsEditingChange?: (isEditing: boolean) => void;
+  /**
+   * 本体は仕様を持たず “イベントを投げる” のが仕事。
+   * 既定の挙動は plugin 側で組み立てる
+   */
+  onEvent?: GridEventHandler<T>;
+  ref?: HTMLTableElement | ((el: HTMLTableElement) => void) | undefined;
+  class?: string;
+  style?: JSX.CSSProperties | string;
+  classes?: {
+    cell?: string | ((ctx: CellRenderContext<T>) => string);
+    row?: string | ((ctx: {
+      rowIndex: number;
+    }) => string);
+    rowHeader?: string | ((ctx: {
+      rowIndex: number;
+      isSelected: boolean;
+    }) => string);
+    colHeader?: string | ((ctx: {
+      colIndex: number;
+      isSelected: boolean;
+    }) => string);
+    corner?: string;
+    header?: string;
+    body?: string;
+  };
+}
+/** Patch for a single cell update. */
+type CellPatch<T> = {
+  pos: CellPosition;
+  value: T;
+};
+/** API exposed to plugins and external handlers. */
+type GridApi<T> = {
+  numRows: () => number;
+  numCols: () => number;
+  activeCell: () => CellPosition | null;
+  selection: () => CellRange | null;
+  isEditing: () => boolean;
+  setActiveCell: (pos: CellPosition | null) => void;
+  setSelection: (range: CellRange | null) => void;
+  beginEdit: (pos: CellPosition) => void;
+  cancelEdit: () => void;
+  commitEdit: (pos: CellPosition, value: T) => void;
+  updateCells: (patches: CellPatch<T>[]) => void;
+};
+declare function Gridsheet<T>(props: GridsheetProps<T>): JSX.Element;
+//#endregion
+export { GridApi as a, Gridsheet as c, CellRenderContext as i, GridsheetProps as l, CellPosition as n, GridEvent as o, CellRange as r, GridEventHandler as s, CellPatch as t, normalizeRange as u };
+//# sourceMappingURL=gridsheet-D9A0kuhj.d.ts.map

package/dist/index.d.ts

@@ -1,73 +1,77 @@
-import { JSX } from "solid-js/jsx-runtime";
+import { a as GridApi, c as Gridsheet, i as CellRenderContext, l as GridsheetProps, n as CellPosition, o as GridEvent, r as CellRange, s as GridEventHandler, t as CellPatch, u as normalizeRange } from "./gridsheet-D9A0kuhj.js";
 
-//#region src/index.d.ts
-interface CellPosition {
-  row: number;
-  col: number;
-}
-interface CellRange {
-  min: CellPosition;
-  max: CellPosition;
-}
-interface CellRenderContext<T> {
-  /** Row index */
-  row: number;
-  /** Column index */
-  col: number;
-  /** Cell value */
-  value: T;
-  /** Is this the active cell (focused) */
-  isActive: boolean;
-  /** Is this cell currently selected */
-  isSelected: boolean;
-  /** Is this cell currently being edited */
-  isEditing: boolean;
-  /** Solid ref for scrolling, focusing, measuring, etc. */
-  cellRef: HTMLTableCellElement | undefined;
-  /** Enter editing mode for this cell */
-  beginEdit: () => void;
-  /** Commit edit with new value */
-  commitEdit: (value: T) => void;
-  /** Exit editing mode for this cell */
-  cancelEditing: () => void;
-}
-interface GridsheetProps<T> {
-  /** 2D matrix of values */
+//#region src/plugin.d.ts
+/** Plugin interface for extending grid behavior. */
+type GridPlugin<T> = {
+  name: string;
+  onEvent?: GridEventHandler<T>;
+};
+/** Compose multiple plugins into a single event handler. */
+declare function createPluginHost<T>(plugins: GridPlugin<T>[]): {
+  onEvent: GridEventHandler<T>;
+};
+//#endregion
+//#region src/plugins/clipboard-memory.d.ts
+type ClipboardData<T> = {
   data: T[][];
-  onDataChange?: (next: T[][]) => void;
-  /** Renderer for each cell */
-  renderCell: (ctx: CellRenderContext<T>) => JSX.Element;
-  /** Currently focused cell */
-  activeCell?: CellPosition | null;
-  onActiveCellChange?: (pos: CellPosition | null) => void;
-  /** Current selection range */
-  selection?: CellRange | null;
-  onSelectionChange?: (range: CellRange | null) => void;
-  /** Is the active cell in editing mode */
-  isEditing?: boolean;
-  onIsEditingChange?: (isEditing: boolean) => void;
-  ref?: HTMLTableElement | ((el: HTMLTableElement) => void) | undefined;
-  class?: string;
-  style?: JSX.CSSProperties | string;
-  classes?: {
-    cell?: string | ((ctx: CellRenderContext<T>) => string);
-    row?: string | ((ctx: {
-      rowIndex: number;
-    }) => string);
-    rowHeader?: string | ((ctx: {
-      rowIndex: number;
-      isSelected: boolean;
-    }) => string);
-    colHeader?: string | ((ctx: {
-      colIndex: number;
-      isSelected: boolean;
-    }) => string);
-    corner?: string;
-    header?: string;
-    body?: string;
-  };
-}
-declare function Gridsheet<T>(props: GridsheetProps<T>): JSX.Element;
+  range: CellRange;
+};
+/** Options for in-memory clipboard behavior. */
+type ClipboardPluginOptions<T> = {
+  getData: () => T[][];
+  onCopy?: (data: T[][], range: CellRange) => boolean | undefined | Promise<boolean | undefined>;
+  onCut?: (data: T[][], range: CellRange) => boolean | undefined | Promise<boolean | undefined>;
+  onPaste?: (clipboardData: T[][], targetPosition: CellPosition) => CellPatch<T>[] | false | undefined | Promise<CellPatch<T>[] | false | undefined>;
+  onClipboardChange?: (clipboard: ClipboardData<T> | null) => void;
+  emptyValue?: T;
+  getEmptyValue?: (pos: CellPosition) => T;
+  copyKeys?: string[];
+  cutKeys?: string[];
+  pasteKeys?: string[];
+};
+/** In-memory clipboard with optional cut clearing. */
+declare function clipboardMemoryPlugin<T>(options: ClipboardPluginOptions<T>): GridPlugin<T>;
+//#endregion
+//#region src/plugins/clipboard-text.d.ts
+/** Options for system clipboard text/TSV behavior. */
+type ClipboardTextPluginOptions<T> = {
+  getData: () => T[][];
+  toText?: (data: T[][]) => string;
+  fromText?: (text: string, target: CellPosition) => CellPatch<T>[] | false;
+  parseCell?: (raw: string) => T;
+  formatCell?: (value: T) => string;
+  readText?: () => Promise<string>;
+  writeText?: (text: string) => Promise<void>;
+  emptyValue?: T;
+  getEmptyValue?: (pos: CellPosition) => T;
+  copyKeys?: string[];
+  cutKeys?: string[];
+  pasteKeys?: string[];
+};
+/** System clipboard integration with TSV defaults. */
+declare function clipboardTextPlugin<T>(options: ClipboardTextPluginOptions<T>): GridPlugin<T>;
+//#endregion
+//#region src/plugins/delete.d.ts
+/** Options for delete behavior. */
+type DeletePluginOptions<T> = {
+  keys?: string[];
+  emptyValue?: T;
+  getEmptyValue?: (pos: CellPosition) => T;
+  onDelete?: (range: CellRange) => CellPatch<T>[] | false | undefined;
+};
+/** Clears selected range with provided empty values. */
+declare function deletePlugin<T>(options: DeletePluginOptions<T>): GridPlugin<T>;
+//#endregion
+//#region src/plugins/editing.d.ts
+type EditingPluginOptions = {
+  triggerKeys?: string[];
+};
+/** Starts editing via double click or configured keys. */
+declare function editingPlugin<T>(options?: EditingPluginOptions): GridPlugin<T>;
+//#endregion
+//#region src/plugins/selection.d.ts
+/** Selection, drag, and arrow-key navigation. */
+declare function selectionPlugin<T>(): GridPlugin<T>;
 //#endregion
-export { CellPosition, CellRange, CellRenderContext, Gridsheet, GridsheetProps };
+export { type CellPatch, type CellPosition, type CellRange, type CellRenderContext, type GridApi, type GridEvent, type GridEventHandler, type GridPlugin, Gridsheet, type GridsheetProps, clipboardMemoryPlugin, clipboardTextPlugin, createPluginHost, deletePlugin, editingPlugin, normalizeRange, selectionPlugin };
 //# sourceMappingURL=index.d.ts.map