lattice-grid-dash 0.1.0__tar.gz

lattice_grid_dash-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python build / cache artifacts
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+develop-eggs/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+
+# Local build outputs (wheels/sdists are built by CI on tag)
+/dist/
+/dist-1.41/
+packages/*/dist/
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Node (the Dash component's build toolchain; its BUILT bundle
+# lattice_grid_dash/lattice_grid_dash.min.js is committed on purpose)
+node_modules/
+packages/*/node_modules/
+
+# Editor / OS
+.DS_Store
+*.swp
+.idea/
+.vscode/

lattice_grid_dash-0.1.0/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.5
+Name: lattice-grid-dash
+Version: 0.1.0
+Summary: Edit a pandas DataFrame as a Lattice Grid inside a Dash app, with edits and selection surfaced back to Python callbacks.
+Project-URL: Homepage, https://latticegrid.dev
+License: Proprietary
+Keywords: component,dash,dataframe,datagrid,lattice-grid,pandas,plotly
+Requires-Python: >=3.9
+Requires-Dist: dash>=2.9
+Requires-Dist: lattice-grid-pandas==0.1.0
+Requires-Dist: pandas>=1.5
+Provides-Extra: dev
+Requires-Dist: playwright>=1.40; extra == 'dev'
+Requires-Dist: pytest>=7; extra == 'dev'
+Requires-Dist: requests; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# lattice-grid-dash
+
+A [Dash](https://dash.plotly.com/) component that renders an editable
+[Lattice Grid](https://latticegrid.dev) over a pandas `DataFrame`, with cell edits
+and selection surfaced back to Python `@callback`s.
+
+Phase **C2** of the Lattice Grid Python integration (card BACKLOG-0000972,
+release 1.41). Built on the same shared serialization layer as the Jupyter widget
+(phase C1): [`lattice-grid-pandas`](../lattice-grid-pandas).
+
+## How it works
+
+The component does **not** re-implement a React binding for the grid. It consumes
+the grid's **shipped React adapter** (`@toclocoinc/lattice-grid/modules/react`,
+grid v1.40.0), which exposes `createLatticeGrid({ React, createGrid })`. We feed
+it Dash's own React (aliased at bundle time to the global the dash-renderer
+serves) so there is a single React instance on the page. This is the lowest-risk
+path identified in the spike: the grid team owns and versions the adapter.
+
+```
+DataFrame ──dataframe_to_data()──▶ data prop (columnar, from lattice-grid-pandas)
+                                        │
+                                   LatticeGrid (React adapter → createGrid)
+                                        │  manual edit
+              cellChanged prop ◀──setProps──  onCellChanged (adapter callback)
+                    │
+             Python @callback(Input("grid", "cellChanged"))
+```
+
+## Install
+
+```bash
+pip install lattice-grid-dash
+```
+
+(Editable/dev: `pip install -e packages/lattice-grid-dash`. The built JS bundle is
+committed under `lattice_grid_dash/`; rebuild it with `npm install && npm run build`.)
+
+## Usage
+
+```python
+import pandas as pd
+from dash import Dash, Input, Output, callback, html
+import lattice_grid_dash
+from lattice_grid_dash import dataframe_to_data, apply_cell_edit
+
+df = pd.DataFrame({"name": ["Ada", "Grace"], "score": [91, 88], "active": [True, False]})
+
+app = Dash(__name__)
+app.layout = html.Div([
+    lattice_grid_dash.LatticeGrid(id="grid", data=dataframe_to_data(df)),
+    html.Pre(id="out"),
+])
+
+@callback(Output("out", "children"), Input("grid", "cellChanged"))
+def on_edit(edit):
+    if not edit:
+        return "no edits yet"
+    apply_cell_edit(df, edit)          # keep the server-side DataFrame in sync, typed
+    return f"{edit['colId']} @ row {edit['key']} = {edit['value']}"
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+See [`examples/app.py`](examples/app.py).
+
+## Props
+
+| Prop | Direction | Description |
+| --- | --- | --- |
+| `data` | in | DataFrame-derived columnar payload from `dataframe_to_data(df)`: `{columns, rowKey, columnar}`. Rows are reconstructed and virtualized in the browser. |
+| `columns` | in | Optional explicit column defs (overrides `data.columns`). |
+| `options` | in | Passthrough to `createGrid` (e.g. `{"edit": True, "rowHeight": 32}`). |
+| `licence` | in | Lattice Grid licence key. Empty on localhost → free/unwatermarked. |
+| `cellChanged` | **out** | Last manual edit `{key, colId, value, old, ts}`. Drives Python callbacks. |
+| `selectedKeys` | in/out | Selected row keys; set by the grid, settable from Python. |
+| `licenceState` | **out** | Grid's resolved licence state (e.g. `"localhost"`). |
+| `style`, `className` | in | Host element styling. |
+
+## Licence plumbing
+
+The `licence` prop is a single opaque string handed straight to
+`createGrid({ licence })`; the grid resolves it **client-side** (localhost origins
+run free, unwatermarked, with no key). The resolved state is surfaced back on the
+`licenceState` prop. This is the same contract as the Jupyter widget — the shared
+rules live in `lattice_grid_pandas._grid`.
+
+## Grid delivery: vendored (default) vs CDN
+
+The grid JavaScript can reach the browser two ways. **This package implements the
+vendored path**; the CDN path is documented here for operators who prefer it.
+
+### Vendored (implemented)
+
+`npm run build` bundles the grid core + React adapter into
+`lattice_grid_dash/lattice_grid_dash.min.js` (~2.7 MB) via `esbuild`, and the grid
+CSS is vendored as `lattice_grid_dash/lattice-grid.min.css`. Both are registered
+as Dash assets (`_js_dist` / `_css_dist`), so the component works **fully offline**
+— no network at render time. This mirrors the C1 widget's `offline=True` default
+and is what the browser smoke test exercises.
+
+Rebuild:
+
+```bash
+cd packages/lattice-grid-dash
+npm install
+npm run build          # build:js (esbuild) + build:py (dash-generate-components)
+```
+
+### CDN (documented alternative)
+
+To ship a thin component bundle that loads the grid from jsDelivr at render time
+(smaller wheel, needs network + a relaxed CSP):
+
+1. In `build.mjs`, mark the grid packages external:
+   `external: ['react-dom', '@toclocoinc/lattice-grid', '@toclocoinc/lattice-grid/modules/react']`.
+2. Before the bundle loads, inject the grid from the CDN, e.g.
+   `https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.40.0/lattice-grid.esm.min.js`
+   and `.../modules/react.esm.min.js` (URLs available from
+   `lattice_grid_pandas.cdn_urls()`), and add the stylesheet
+   `.../lattice-grid.min.css`.
+3. Drop the vendored files from `_js_dist` / `_css_dist`.
+
+The two are mutually exclusive; pick one per build.
+
+## Development / build toolchain
+
+- `npm run build:js` — `esbuild` bundles `src/lib/bundle.js` → `lattice_grid_dash/lattice_grid_dash.min.js`. `react` is aliased to Dash's global React (`src/lib/react-shim.js`); react/react-dom are never bundled.
+- `npm run build:py` — `dash-generate-components` (react-docgen v5) reads `src/lib/components/LatticeGrid.react.js` and generates `LatticeGrid.py`, `_imports_.py`, and `metadata.json`.
+- `pytest tests/` — unit tests for the data bridge, plus a real-browser Playwright smoke test (system Chrome via `channel='chrome'`).

lattice_grid_dash-0.1.0/README.md

@@ -0,0 +1,131 @@
+# lattice-grid-dash
+
+A [Dash](https://dash.plotly.com/) component that renders an editable
+[Lattice Grid](https://latticegrid.dev) over a pandas `DataFrame`, with cell edits
+and selection surfaced back to Python `@callback`s.
+
+Phase **C2** of the Lattice Grid Python integration (card BACKLOG-0000972,
+release 1.41). Built on the same shared serialization layer as the Jupyter widget
+(phase C1): [`lattice-grid-pandas`](../lattice-grid-pandas).
+
+## How it works
+
+The component does **not** re-implement a React binding for the grid. It consumes
+the grid's **shipped React adapter** (`@toclocoinc/lattice-grid/modules/react`,
+grid v1.40.0), which exposes `createLatticeGrid({ React, createGrid })`. We feed
+it Dash's own React (aliased at bundle time to the global the dash-renderer
+serves) so there is a single React instance on the page. This is the lowest-risk
+path identified in the spike: the grid team owns and versions the adapter.
+
+```
+DataFrame ──dataframe_to_data()──▶ data prop (columnar, from lattice-grid-pandas)
+                                        │
+                                   LatticeGrid (React adapter → createGrid)
+                                        │  manual edit
+              cellChanged prop ◀──setProps──  onCellChanged (adapter callback)
+                    │
+             Python @callback(Input("grid", "cellChanged"))
+```
+
+## Install
+
+```bash
+pip install lattice-grid-dash
+```
+
+(Editable/dev: `pip install -e packages/lattice-grid-dash`. The built JS bundle is
+committed under `lattice_grid_dash/`; rebuild it with `npm install && npm run build`.)
+
+## Usage
+
+```python
+import pandas as pd
+from dash import Dash, Input, Output, callback, html
+import lattice_grid_dash
+from lattice_grid_dash import dataframe_to_data, apply_cell_edit
+
+df = pd.DataFrame({"name": ["Ada", "Grace"], "score": [91, 88], "active": [True, False]})
+
+app = Dash(__name__)
+app.layout = html.Div([
+    lattice_grid_dash.LatticeGrid(id="grid", data=dataframe_to_data(df)),
+    html.Pre(id="out"),
+])
+
+@callback(Output("out", "children"), Input("grid", "cellChanged"))
+def on_edit(edit):
+    if not edit:
+        return "no edits yet"
+    apply_cell_edit(df, edit)          # keep the server-side DataFrame in sync, typed
+    return f"{edit['colId']} @ row {edit['key']} = {edit['value']}"
+
+if __name__ == "__main__":
+    app.run(debug=True)
+```
+
+See [`examples/app.py`](examples/app.py).
+
+## Props
+
+| Prop | Direction | Description |
+| --- | --- | --- |
+| `data` | in | DataFrame-derived columnar payload from `dataframe_to_data(df)`: `{columns, rowKey, columnar}`. Rows are reconstructed and virtualized in the browser. |
+| `columns` | in | Optional explicit column defs (overrides `data.columns`). |
+| `options` | in | Passthrough to `createGrid` (e.g. `{"edit": True, "rowHeight": 32}`). |
+| `licence` | in | Lattice Grid licence key. Empty on localhost → free/unwatermarked. |
+| `cellChanged` | **out** | Last manual edit `{key, colId, value, old, ts}`. Drives Python callbacks. |
+| `selectedKeys` | in/out | Selected row keys; set by the grid, settable from Python. |
+| `licenceState` | **out** | Grid's resolved licence state (e.g. `"localhost"`). |
+| `style`, `className` | in | Host element styling. |
+
+## Licence plumbing
+
+The `licence` prop is a single opaque string handed straight to
+`createGrid({ licence })`; the grid resolves it **client-side** (localhost origins
+run free, unwatermarked, with no key). The resolved state is surfaced back on the
+`licenceState` prop. This is the same contract as the Jupyter widget — the shared
+rules live in `lattice_grid_pandas._grid`.
+
+## Grid delivery: vendored (default) vs CDN
+
+The grid JavaScript can reach the browser two ways. **This package implements the
+vendored path**; the CDN path is documented here for operators who prefer it.
+
+### Vendored (implemented)
+
+`npm run build` bundles the grid core + React adapter into
+`lattice_grid_dash/lattice_grid_dash.min.js` (~2.7 MB) via `esbuild`, and the grid
+CSS is vendored as `lattice_grid_dash/lattice-grid.min.css`. Both are registered
+as Dash assets (`_js_dist` / `_css_dist`), so the component works **fully offline**
+— no network at render time. This mirrors the C1 widget's `offline=True` default
+and is what the browser smoke test exercises.
+
+Rebuild:
+
+```bash
+cd packages/lattice-grid-dash
+npm install
+npm run build          # build:js (esbuild) + build:py (dash-generate-components)
+```
+
+### CDN (documented alternative)
+
+To ship a thin component bundle that loads the grid from jsDelivr at render time
+(smaller wheel, needs network + a relaxed CSP):
+
+1. In `build.mjs`, mark the grid packages external:
+   `external: ['react-dom', '@toclocoinc/lattice-grid', '@toclocoinc/lattice-grid/modules/react']`.
+2. Before the bundle loads, inject the grid from the CDN, e.g.
+   `https://cdn.jsdelivr.net/npm/@toclocoinc/lattice-grid@1.40.0/lattice-grid.esm.min.js`
+   and `.../modules/react.esm.min.js` (URLs available from
+   `lattice_grid_pandas.cdn_urls()`), and add the stylesheet
+   `.../lattice-grid.min.css`.
+3. Drop the vendored files from `_js_dist` / `_css_dist`.
+
+The two are mutually exclusive; pick one per build.
+
+## Development / build toolchain
+
+- `npm run build:js` — `esbuild` bundles `src/lib/bundle.js` → `lattice_grid_dash/lattice_grid_dash.min.js`. `react` is aliased to Dash's global React (`src/lib/react-shim.js`); react/react-dom are never bundled.
+- `npm run build:py` — `dash-generate-components` (react-docgen v5) reads `src/lib/components/LatticeGrid.react.js` and generates `LatticeGrid.py`, `_imports_.py`, and `metadata.json`.
+- `pytest tests/` — unit tests for the data bridge, plus a real-browser Playwright smoke test (system Chrome via `channel='chrome'`).

lattice_grid_dash-0.1.0/build.mjs

@@ -0,0 +1,38 @@
+/**
+ * Build the browser bundle for the Dash component.
+ *
+ * Output: lattice_grid_dash/lattice_grid_dash.min.js  (an IIFE that registers
+ * window.lattice_grid_dash.LatticeGrid).
+ *
+ * DELIVERY = "vendor" (implemented): the grid core + its React adapter are
+ * bundled in, so the component works fully offline with no CDN at render time.
+ * See README for the "cdn" delivery variant (mark the grid packages external and
+ * load them from jsDelivr at runtime) -- documented, not built here.
+ *
+ * React/ReactDOM are NOT bundled: the component reads window.React (served by the
+ * dash-renderer), guaranteeing a single React instance.
+ */
+import {build} from 'esbuild';
+import {mkdirSync} from 'node:fs';
+import {fileURLToPath} from 'node:url';
+import {dirname, resolve} from 'node:path';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+mkdirSync('lattice_grid_dash', {recursive: true});
+
+await build({
+    entryPoints: ['src/lib/bundle.js'],
+    bundle: true,
+    format: 'iife',
+    target: ['es2019'],
+    minify: true,
+    sourcemap: false,
+    outfile: 'lattice_grid_dash/lattice_grid_dash.min.js',
+    // `react` -> Dash's global React (see src/lib/react-shim.js); react-dom is
+    // unused by the grid/adapter, so exclude it entirely.
+    alias: {react: resolve(__dirname, 'src/lib/react-shim.js')},
+    external: ['react-dom'],
+    logLevel: 'info',
+});
+
+console.log('built lattice_grid_dash/lattice_grid_dash.min.js');

lattice_grid_dash-0.1.0/examples/app.py

@@ -0,0 +1,53 @@
+"""Minimal Dash app demonstrating the LatticeGrid component round-trip.
+
+Run:  python examples/app.py   then open http://127.0.0.1:8050
+
+Edit a cell in the grid; the panel below updates from a Python @callback that
+observes the component's `cellChanged` prop, and the DataFrame is updated
+server-side (dtype-preserved) via `apply_cell_edit`.
+"""
+
+import pandas as pd
+from dash import Dash, Input, Output, callback, html
+
+import lattice_grid_dash
+from lattice_grid_dash import apply_cell_edit, dataframe_to_data
+
+df = pd.DataFrame(
+    {
+        "name": ["Ada", "Grace", "Linus"],
+        "score": [91, 88, 77],
+        "active": [True, False, True],
+    }
+)
+
+app = Dash(__name__)
+
+app.layout = html.Div(
+    [
+        html.H3("Lattice Grid in Dash"),
+        lattice_grid_dash.LatticeGrid(
+            id="grid",
+            data=dataframe_to_data(df),
+            options={"edit": True},
+        ),
+        html.Pre(id="out", children="Edit a cell..."),
+    ],
+    style={"maxWidth": "720px", "margin": "2rem auto", "fontFamily": "system-ui"},
+)
+
+
+@callback(Output("out", "children"), Input("grid", "cellChanged"))
+def on_edit(edit):
+    if not edit:
+        return "Edit a cell..."
+    apply_cell_edit(df, edit)  # server-side DataFrame stays in sync + typed
+    return (
+        f"cellChanged -> row {edit['key']}, column '{edit['colId']}' = "
+        f"{edit['value']!r} (was {edit.get('old')!r})\n"
+        f"df row now: {df.iloc[int(edit['key'])].to_dict()}"
+    )
+
+
+if __name__ == "__main__":
+    app.run(debug=True)

lattice_grid_dash-0.1.0/lattice_grid_dash/LatticeGrid.py

@@ -0,0 +1,95 @@
+# AUTO GENERATED FILE - DO NOT EDIT
+
+import typing  # noqa: F401
+from typing_extensions import TypedDict, NotRequired, Literal # noqa: F401
+from dash.development.base_component import Component, _explicitize_args
+try:
+    from dash.types import NumberType  # noqa: F401
+except ImportError:
+    # Backwards compatibility for dash<=4.1.0
+    if typing.TYPE_CHECKING:
+        raise
+    NumberType = typing.Union[  # noqa: F401
+        typing.SupportsFloat, typing.SupportsInt, typing.SupportsComplex
+    ]
+
+ComponentSingleType = typing.Union[str, int, float, Component, None]
+ComponentType = typing.Union[
+    ComponentSingleType,
+    typing.Sequence[ComponentSingleType],
+]
+
+
+class LatticeGrid(Component):
+    """A LatticeGrid component.
+LatticeGrid Dash component.
+
+Keyword arguments:
+
+- id (string; optional):
+    Component id, used to target the component in Dash callbacks.
+
+- cellChanged (dict; optional):
+    OUTPUT. The last cell edit made in the grid: `{key, colId, value,
+    old, ts}`. Updated on every manual edit so a Python `@callback`
+    with `Input(id, \"cellChanged\")` fires. Read-only from Python.
+
+- className (string; optional):
+    CSS class for the grid host element.
+
+- columns (list; optional):
+    Optional explicit column definitions; overrides `data.columns`.
+
+- data (dict; default {columns: [], rowKey: ROW_KEY, columnar: {}}):
+    Columnar, DataFrame-derived data produced by
+    `lattice-grid-pandas`: `{columns: [...], rowKey: \"__row_id__\",
+    columnar: {field: [values...]}}`. Rows are reconstructed in the
+    browser (virtualized rendering).
+
+- licence (string; default ''):
+    Lattice Grid licence key. Empty on localhost runs
+    free/unwatermarked.
+
+- licenceState (string; optional):
+    OUTPUT. The grid's resolved licence state (e.g. \"localhost\",
+    \"valid\").
+
+- options (dict; optional):
+    Grid options passed through to `createGrid` (e.g. edit,
+    rowHeight).
+
+- selectedKeys (list of strings; optional):
+    Selected row keys. Set by the grid on selection; may also be set
+    from Python."""
+    _children_props: typing.List[str] = []
+    _base_nodes = ['children']
+    _namespace = 'lattice_grid_dash'
+    _type = 'LatticeGrid'
+
+
+    def __init__(
+        self,
+        id: typing.Optional[typing.Union[str, dict]] = None,
+        data: typing.Optional[dict] = None,
+        columns: typing.Optional[typing.Sequence] = None,
+        options: typing.Optional[dict] = None,
+        licence: typing.Optional[str] = None,
+        cellChanged: typing.Optional[dict] = None,
+        selectedKeys: typing.Optional[typing.Sequence[str]] = None,
+        licenceState: typing.Optional[str] = None,
+        style: typing.Optional[typing.Any] = None,
+        className: typing.Optional[str] = None,
+        **kwargs
+    ):
+        self._prop_names = ['id', 'cellChanged', 'className', 'columns', 'data', 'licence', 'licenceState', 'options', 'selectedKeys', 'style']
+        self._valid_wildcard_attributes =            []
+        self.available_properties = ['id', 'cellChanged', 'className', 'columns', 'data', 'licence', 'licenceState', 'options', 'selectedKeys', 'style']
+        self.available_wildcard_properties =            []
+        _explicit_args = kwargs.pop('_explicit_args')
+        _locals = locals()
+        _locals.update(kwargs)  # For wildcard attrs and excess named props
+        args = {k: _locals[k] for k in _explicit_args}
+
+        super(LatticeGrid, self).__init__(**args)
+
+setattr(LatticeGrid, "__init__", _explicitize_args(LatticeGrid.__init__))

lattice_grid_dash-0.1.0/lattice_grid_dash/__init__.py

@@ -0,0 +1,76 @@
+"""lattice-grid-dash -- a Dash component wrapping Lattice Grid.
+
+Usage::
+
+    import lattice_grid_dash
+    from dash import Dash, callback, Input, Output, html
+    import pandas as pd
+    from lattice_grid_dash import dataframe_to_data
+
+    df = pd.DataFrame({"name": ["Ada", "Grace"], "score": [91, 88]})
+    app = Dash(__name__)
+    app.layout = html.Div([
+        lattice_grid_dash.LatticeGrid(id="grid", data=dataframe_to_data(df)),
+        html.Div(id="out"),
+    ])
+
+    @callback(Output("out", "children"), Input("grid", "cellChanged"))
+    def show(edit):
+        return f"edited {edit}" if edit else "no edits yet"
+
+The grid JS is *vendored* into this package (``lattice_grid_dash.min.js``), so it
+works offline with no CDN at render time. See the README for the CDN variant.
+"""
+
+import json as _json
+import os as _os
+import sys as _sys
+
+import dash as _dash
+
+from ._imports_ import *  # noqa: F401,F403
+from ._imports_ import __all__  # noqa: F401
+from ._serialize_bridge import dataframe_to_data, apply_cell_edit  # noqa: F401
+
+__all__ = list(__all__) + ["dataframe_to_data", "apply_cell_edit"]
+
+if not hasattr(_dash, "development"):
+    print(
+        "Dash was not successfully imported. Make sure you don't have a file "
+        'named \n"dash.py" in your current directory.',
+        file=_sys.stderr,
+    )
+    _sys.exit(1)
+
+_basepath = _os.path.dirname(__file__)
+_filepath = _os.path.abspath(_os.path.join(_basepath, "package-info.json"))
+with open(_filepath) as f:
+    package = _json.load(f)
+
+package_name = package["name"].replace(" ", "_").replace("-", "_")
+__version__ = package["version"]
+
+_current_path = _os.path.dirname(_os.path.abspath(__file__))
+
+_this_module = _sys.modules[__name__]
+
+_js_dist = [
+    {
+        "relative_package_path": "lattice_grid_dash.min.js",
+        "namespace": package_name,
+    }
+]
+
+_css_dist = [
+    {
+        "relative_package_path": "lattice-grid.min.css",
+        "namespace": package_name,
+    }
+]
+
+for _component in __all__:
+    if hasattr(_this_module, _component):
+        _comp = getattr(_this_module, _component)
+        if isinstance(_comp, type):
+            setattr(_comp, "_js_dist", _js_dist)
+            setattr(_comp, "_css_dist", _css_dist)

lattice_grid_dash-0.1.0/lattice_grid_dash/_imports_.py

@@ -0,0 +1,5 @@
+from .LatticeGrid import LatticeGrid
+
+__all__ = [
+    "LatticeGrid"
+]

lattice_grid_dash-0.1.0/lattice_grid_dash/_serialize_bridge.py

@@ -0,0 +1,79 @@
+"""DataFrame <-> ``LatticeGrid`` data-prop bridge for Dash apps.
+
+This is a *thin* adapter over ``lattice-grid-pandas`` -- the same package the
+Jupyter widget (phase C1) uses. It adds ZERO serialization logic of its own: the
+dtype mapping, the columnar payload build and the edit dtype-coercion all come
+from the shared package, so there is one implementation across both wrappers.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Iterable, Optional
+
+import pandas as pd
+from lattice_grid_pandas import (
+    ROW_KEY,
+    build_columnar,
+    build_columns,
+    cast_to_dtype,
+)
+
+
+def positional_keys(n: int) -> list[str]:
+    """Stable per-row keys: the row's integer position, as a string ('0'..'n-1').
+
+    Matches the Jupyter widget's key scheme, so both wrappers behave identically.
+    """
+    return [str(i) for i in range(n)]
+
+
+def dataframe_to_data(
+    df: pd.DataFrame,
+    keys: Optional[Iterable[str]] = None,
+) -> dict:
+    """Build the ``data`` prop for ``LatticeGrid`` from a DataFrame.
+
+    Returns ``{"columns": [...], "rowKey": "__row_id__", "columnar": {...}}`` where
+    the browser reconstructs row objects from the column-major ``columnar`` block.
+    """
+    if not isinstance(df, pd.DataFrame):
+        raise TypeError("dataframe_to_data expects a pandas DataFrame")
+    key_list = list(keys) if keys is not None else positional_keys(len(df))
+    if len(key_list) != len(df):
+        raise ValueError("keys length must match the number of rows")
+    return {
+        "columns": build_columns(df),
+        "rowKey": ROW_KEY,
+        "columnar": build_columnar(df, key_list),
+    }
+
+
+def apply_cell_edit(
+    df: pd.DataFrame,
+    edit: Optional[dict],
+    keys: Optional[Iterable[str]] = None,
+) -> pd.DataFrame:
+    """Apply one ``cellChanged`` payload back into a DataFrame, dtype-preserved.
+
+    ``edit`` is the ``{"key", "colId", "value"}`` payload the component emits.
+    Returns ``df`` mutated in place (and also returned, for convenience). Edits to
+    read-only index columns or unknown rows are ignored, mirroring the widget.
+    """
+    if not edit:
+        return df
+    col = edit.get("colId")
+    key = edit.get("key")
+    value = edit.get("value")
+    if col not in df.columns:
+        return df  # index columns are read-only; ignore
+    key_list = list(keys) if keys is not None else positional_keys(len(df))
+    try:
+        pos = key_list.index(str(key))
+    except ValueError:
+        return df
+    value = cast_to_dtype(df[col].dtype, value)
+    df.iat[pos, df.columns.get_loc(col)] = value
+    return df
+
+
+__all__ = ["dataframe_to_data", "apply_cell_edit", "positional_keys", "ROW_KEY"]