lhngrid 0.0.1__tar.gz

lhngrid-0.0.1/LICENSE

@@ -0,0 +1 @@
+YOUR LICENSE HERE

lhngrid-0.0.1/MANIFEST.in

@@ -0,0 +1,2 @@
+recursive-include lhngrid/frontend/build *
+include pyproject.toml

lhngrid-0.0.1/PKG-INFO

@@ -0,0 +1,196 @@
+Metadata-Version: 2.4
+Name: lhngrid
+Version: 0.0.1
+Summary: A custom grid to handle tabular data
+Author-email: Anu <anu@abc.com>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: streamlit>=1.51
+Provides-Extra: snowpark
+Requires-Dist: snowflake-snowpark-python>=1.5.0; extra == "snowpark"
+Provides-Extra: devel
+Requires-Dist: wheel; extra == "devel"
+Requires-Dist: pytest==7.4.0; extra == "devel"
+Requires-Dist: playwright==1.48.0; extra == "devel"
+Requires-Dist: requests==2.31.0; extra == "devel"
+Requires-Dist: pytest-playwright-snapshot==1.0; extra == "devel"
+Requires-Dist: pytest-rerunfailures==12.0; extra == "devel"
+Dynamic: license-file
+
+# lhngrid
+
+A custom grid to handle tabular data
+
+## Installation instructions
+
+```sh
+uv pip install lhngrid
+```
+
+### Development install (editable)
+
+When developing this component locally, install it in editable mode so Streamlit picks up code changes without rebuilding a wheel. Run this from the directory that contains `pyproject.toml`:
+
+```sh
+uv pip install -e . --force-reinstall
+```
+
+## Usage instructions
+
+```python
+import streamlit as st
+
+from lhngrid import lhngrid
+
+TABLE_KEY = "tasks"
+PAGE_INDEX_KEY = f"{TABLE_KEY}_page_index"
+PAGE_SIZE_KEY = f"{TABLE_KEY}_page_size"
+
+st.session_state.setdefault(PAGE_INDEX_KEY, 0)
+st.session_state.setdefault(PAGE_SIZE_KEY, 10)
+
+
+def sync_grid_state(key: str) -> None:
+    component = st.session_state.get(key)
+
+    if component is None:
+        return
+
+    st.session_state[PAGE_INDEX_KEY] = component.pageIndex
+    st.session_state[PAGE_SIZE_KEY] = component.pageSize
+
+
+value = lhngrid(
+    rows=rows,
+    columns=columns,
+    row_key="id",
+    page_index=st.session_state[PAGE_INDEX_KEY],
+    page_size=st.session_state[PAGE_SIZE_KEY],
+    theme="streamlit-dataframe",
+    show_row_selection=False,
+    pagination_position="top-left",
+    key=TABLE_KEY,
+    on_pageIndex_change=sync_grid_state,
+    on_pageSize_change=sync_grid_state,
+)
+
+st.write(value)
+```
+
+### Snowpark DataFrames
+
+LHNGrid can also accept a Snowpark DataFrame through the same `rows`
+parameter. Install the optional Snowpark extra when using this path:
+
+```sh
+uv pip install "lhngrid[snowpark]"
+```
+
+When `rows` is a Snowpark DataFrame, LHNGrid queries only the current page,
+applies supported sorting/filtering in Snowpark, and sends page-sized JSON rows
+to the frontend.
+
+```python
+value = lhngrid(
+    rows=session.table("TASKS"),
+    columns=None,  # infer columns from the Snowpark schema
+    row_key="ID",
+    page_index=st.session_state[PAGE_INDEX_KEY],
+    page_size=st.session_state[PAGE_SIZE_KEY],
+    sorting=st.session_state.get(SORTING_KEY, []),
+    key=TABLE_KEY,
+    on_pageIndex_change=sync_grid_state,
+    on_pageSize_change=sync_grid_state,
+    on_sorting_change=sync_grid_state,
+)
+```
+
+Explicit columns remain the source of truth when provided. Use `sourceKey` when
+the Snowpark column name differs from the frontend row key.
+
+```python
+columns = [
+    {
+        "id": "task",
+        "header": "Task",
+        "accessorKey": "task",
+        "sourceKey": "TASK",
+        "type": "text",
+        "sortable": True,
+    },
+    {
+        "id": "created_at",
+        "header": "Created At",
+        "accessorKey": "createdAt",
+        "sourceKey": "CREATED_AT",
+        "type": "date",
+        "sortable": True,
+    },
+]
+
+value = lhngrid(
+    rows=session.table("TASKS"),
+    columns=columns,
+    row_key="ID",
+    page_index=st.session_state[PAGE_INDEX_KEY],
+    page_size=st.session_state[PAGE_SIZE_KEY],
+    sorting=st.session_state.get(SORTING_KEY, []),
+    key=TABLE_KEY,
+)
+```
+
+Callbacks receive the component key so the handler can read the current
+component value from `st.session_state[key]`. Exposed callbacks are
+`on_pageIndex_change`, `on_pageSize_change`, `on_sorting_change`,
+`on_columnFilters_change`, `on_selectedRowId_change`,
+`on_selectedRowIds_change`, `on_rowOffset_change`, `on_rowLimit_change`, and
+`on_rowAction_change`. The legacy `onIndexChange` parameter still aliases
+`on_pageIndex_change`.
+
+### Styling hooks
+
+Available themes are `default` and `streamlit-dataframe`. The
+`streamlit-dataframe` theme only changes styling so the grid visually matches
+Streamlit's default DataFrame component; it does not add DataFrame features.
+Set `show_row_selection=False` to hide the checkbox selection column.
+Use `pagination_position` to place the pagination controls. Supported values are
+`top-left`, `top-middle`, `top-right`, `bottom-left`, `bottom-middle`, and
+`bottom-right`. The default is `bottom-right`.
+
+The component uses readable, scoped class names so app-level CSS can target the
+grid safely. Common hooks include `lhn-grid`, `lhn-grid-table-container`,
+`lhn-grid-table`, `lhn-grid-header-cell`, `lhn-grid-cell`,
+`lhn-grid-table-row`, `lhn-grid-table-row-selected`,
+`lhn-grid-row-selection-checkbox`, `lhn-grid-badge`,
+`lhn-grid-pagination`, `lhn-grid-page-size-select`, and
+`lhn-grid-pagination-button`.
+
+## Build a wheel
+
+To package this component for distribution:
+
+1. Build the frontend assets (from `lhngrid/frontend`):
+
+   ```sh
+   npm i
+   npm run build
+   ```
+
+2. Build the Python wheel using UV (from the project root):
+   ```sh
+   uv build
+   ```
+
+This will create a `dist/` directory containing your wheel. The wheel includes the compiled frontend from `lhngrid/frontend/build`.
+
+### Requirements
+
+- Python >= 3.10
+- Node.js >= 24 (LTS)
+
+### Expected output
+
+- `dist/lhngrid-0.0.1-py3-none-any.whl`
+- If you run `uv run --with build python -m build` (without `--wheel`), you’ll also get an sdist: `dist/lhngrid-0.0.1.tar.gz`

lhngrid-0.0.1/README.md

@@ -0,0 +1,175 @@
+# lhngrid
+
+A custom grid to handle tabular data
+
+## Installation instructions
+
+```sh
+uv pip install lhngrid
+```
+
+### Development install (editable)
+
+When developing this component locally, install it in editable mode so Streamlit picks up code changes without rebuilding a wheel. Run this from the directory that contains `pyproject.toml`:
+
+```sh
+uv pip install -e . --force-reinstall
+```
+
+## Usage instructions
+
+```python
+import streamlit as st
+
+from lhngrid import lhngrid
+
+TABLE_KEY = "tasks"
+PAGE_INDEX_KEY = f"{TABLE_KEY}_page_index"
+PAGE_SIZE_KEY = f"{TABLE_KEY}_page_size"
+
+st.session_state.setdefault(PAGE_INDEX_KEY, 0)
+st.session_state.setdefault(PAGE_SIZE_KEY, 10)
+
+
+def sync_grid_state(key: str) -> None:
+    component = st.session_state.get(key)
+
+    if component is None:
+        return
+
+    st.session_state[PAGE_INDEX_KEY] = component.pageIndex
+    st.session_state[PAGE_SIZE_KEY] = component.pageSize
+
+
+value = lhngrid(
+    rows=rows,
+    columns=columns,
+    row_key="id",
+    page_index=st.session_state[PAGE_INDEX_KEY],
+    page_size=st.session_state[PAGE_SIZE_KEY],
+    theme="streamlit-dataframe",
+    show_row_selection=False,
+    pagination_position="top-left",
+    key=TABLE_KEY,
+    on_pageIndex_change=sync_grid_state,
+    on_pageSize_change=sync_grid_state,
+)
+
+st.write(value)
+```
+
+### Snowpark DataFrames
+
+LHNGrid can also accept a Snowpark DataFrame through the same `rows`
+parameter. Install the optional Snowpark extra when using this path:
+
+```sh
+uv pip install "lhngrid[snowpark]"
+```
+
+When `rows` is a Snowpark DataFrame, LHNGrid queries only the current page,
+applies supported sorting/filtering in Snowpark, and sends page-sized JSON rows
+to the frontend.
+
+```python
+value = lhngrid(
+    rows=session.table("TASKS"),
+    columns=None,  # infer columns from the Snowpark schema
+    row_key="ID",
+    page_index=st.session_state[PAGE_INDEX_KEY],
+    page_size=st.session_state[PAGE_SIZE_KEY],
+    sorting=st.session_state.get(SORTING_KEY, []),
+    key=TABLE_KEY,
+    on_pageIndex_change=sync_grid_state,
+    on_pageSize_change=sync_grid_state,
+    on_sorting_change=sync_grid_state,
+)
+```
+
+Explicit columns remain the source of truth when provided. Use `sourceKey` when
+the Snowpark column name differs from the frontend row key.
+
+```python
+columns = [
+    {
+        "id": "task",
+        "header": "Task",
+        "accessorKey": "task",
+        "sourceKey": "TASK",
+        "type": "text",
+        "sortable": True,
+    },
+    {
+        "id": "created_at",
+        "header": "Created At",
+        "accessorKey": "createdAt",
+        "sourceKey": "CREATED_AT",
+        "type": "date",
+        "sortable": True,
+    },
+]
+
+value = lhngrid(
+    rows=session.table("TASKS"),
+    columns=columns,
+    row_key="ID",
+    page_index=st.session_state[PAGE_INDEX_KEY],
+    page_size=st.session_state[PAGE_SIZE_KEY],
+    sorting=st.session_state.get(SORTING_KEY, []),
+    key=TABLE_KEY,
+)
+```
+
+Callbacks receive the component key so the handler can read the current
+component value from `st.session_state[key]`. Exposed callbacks are
+`on_pageIndex_change`, `on_pageSize_change`, `on_sorting_change`,
+`on_columnFilters_change`, `on_selectedRowId_change`,
+`on_selectedRowIds_change`, `on_rowOffset_change`, `on_rowLimit_change`, and
+`on_rowAction_change`. The legacy `onIndexChange` parameter still aliases
+`on_pageIndex_change`.
+
+### Styling hooks
+
+Available themes are `default` and `streamlit-dataframe`. The
+`streamlit-dataframe` theme only changes styling so the grid visually matches
+Streamlit's default DataFrame component; it does not add DataFrame features.
+Set `show_row_selection=False` to hide the checkbox selection column.
+Use `pagination_position` to place the pagination controls. Supported values are
+`top-left`, `top-middle`, `top-right`, `bottom-left`, `bottom-middle`, and
+`bottom-right`. The default is `bottom-right`.
+
+The component uses readable, scoped class names so app-level CSS can target the
+grid safely. Common hooks include `lhn-grid`, `lhn-grid-table-container`,
+`lhn-grid-table`, `lhn-grid-header-cell`, `lhn-grid-cell`,
+`lhn-grid-table-row`, `lhn-grid-table-row-selected`,
+`lhn-grid-row-selection-checkbox`, `lhn-grid-badge`,
+`lhn-grid-pagination`, `lhn-grid-page-size-select`, and
+`lhn-grid-pagination-button`.
+
+## Build a wheel
+
+To package this component for distribution:
+
+1. Build the frontend assets (from `lhngrid/frontend`):
+
+   ```sh
+   npm i
+   npm run build
+   ```
+
+2. Build the Python wheel using UV (from the project root):
+   ```sh
+   uv build
+   ```
+
+This will create a `dist/` directory containing your wheel. The wheel includes the compiled frontend from `lhngrid/frontend/build`.
+
+### Requirements
+
+- Python >= 3.10
+- Node.js >= 24 (LTS)
+
+### Expected output
+
+- `dist/lhngrid-0.0.1-py3-none-any.whl`
+- If you run `uv run --with build python -m build` (without `--wheel`), you’ll also get an sdist: `dist/lhngrid-0.0.1.tar.gz`

lhngrid-0.0.1/lhngrid/__init__.py

@@ -0,0 +1,270 @@
+from __future__ import annotations
+
+from collections.abc import Sequence
+from functools import partial
+from typing import Any, Callable, Literal, cast
+
+import streamlit as st
+
+from ._pagination import normalize_pagination
+from ._snowpark import is_snowpark_dataframe, prepare_snowpark_data
+
+_component = st.components.v2.component(
+    "lhngrid.lhngrid",
+    js="index-*.js",
+    css="index-*.css",
+    html='<div class="react-root"></div>',
+)
+
+
+def _noop() -> None:
+    return None
+
+
+GridCallback = Callable[[str], None]
+GridTheme = Literal["default", "streamlit-dataframe"]
+GridPaginationPosition = Literal[
+    "top-left",
+    "top-middle",
+    "top-right",
+    "bottom-left",
+    "bottom-middle",
+    "bottom-right",
+]
+_GRID_THEMES: set[str] = {"default", "streamlit-dataframe"}
+_GRID_PAGINATION_POSITIONS: set[str] = {
+    "top-left",
+    "top-middle",
+    "top-right",
+    "bottom-left",
+    "bottom-middle",
+    "bottom-right",
+}
+
+
+def _bind_callback(callback: GridCallback | None, key: str) -> Callable[[], None]:
+    if callback is None:
+        return _noop
+
+    return partial(callback, key)
+
+
+def _normalize_size(value: int | float | str | None) -> str | None:
+    if value is None:
+        return None
+
+    if isinstance(value, bool):
+        raise TypeError("width and height must be a number, string, or None.")
+
+    if isinstance(value, (int, float)):
+        if value < 0:
+            raise ValueError("width and height must be non-negative.")
+
+        return f"{value}px"
+
+    if isinstance(value, str):
+        return value
+
+    raise TypeError("width and height must be a number, string, or None.")
+
+
+def _normalize_theme(value: str) -> GridTheme:
+    if value not in _GRID_THEMES:
+        themes = ", ".join(sorted(_GRID_THEMES))
+        raise ValueError(f"theme must be one of: {themes}.")
+
+    return cast(GridTheme, value)
+
+
+def _normalize_pagination_position(value: str) -> GridPaginationPosition:
+    if value not in _GRID_PAGINATION_POSITIONS:
+        positions = ", ".join(sorted(_GRID_PAGINATION_POSITIONS))
+        raise ValueError(f"pagination_position must be one of: {positions}.")
+
+    return cast(GridPaginationPosition, value)
+
+
+def _paginate_rows(
+    rows: Sequence[dict[str, Any]],
+    page_index: int,
+    page_size: int,
+    total_rows: int | None,
+) -> tuple[list[dict[str, Any]], int, int, int, int, int]:
+    total_rows_value = len(rows) if total_rows is None else max(0, int(total_rows))
+    page_index_value, page_size_value, row_offset, row_limit = normalize_pagination(
+        page_index,
+        page_size,
+        total_rows_value,
+    )
+
+    if total_rows is not None and total_rows_value > len(rows):
+        return (
+            list(rows),
+            page_index_value,
+            page_size_value,
+            total_rows_value,
+            row_offset,
+            row_limit,
+        )
+
+    page_start = row_offset
+    page_end = page_start + row_limit
+
+    return (
+        list(rows[page_start:page_end]),
+        page_index_value,
+        page_size_value,
+        total_rows_value,
+        row_offset,
+        row_limit,
+    )
+
+
+def _normalize_sequence_rows(rows: Any) -> Sequence[dict[str, Any]]:
+    if isinstance(rows, (str, bytes)) or not isinstance(rows, Sequence):
+        raise TypeError(
+            "rows must be a sequence of dictionaries or a Snowpark DataFrame."
+        )
+
+    return cast(Sequence[dict[str, Any]], rows)
+
+
+def lhngrid(
+    *,
+    rows: Any,
+    columns: list[dict[str, Any]] | None = None,
+    row_key: str,
+    page_index: int = 0,
+    page_size: int = 10,
+    total_rows: int | None = None,
+    sorting: list[dict[str, Any]] | None = None,
+    column_filters: list[dict[str, Any]] | None = None,
+    loading: bool = False,
+    width: int | float | str | None = None,
+    height: int | float | str | None = None,
+    page_size_options: Sequence[int] = (5, 10, 25, 50, 100),
+    pagination_position: GridPaginationPosition = "bottom-right",
+    show_row_selection: bool = True,
+    show_actions: bool = False,
+    theme: GridTheme = "default",
+    key: str | None = None,
+    on_pageIndex_change: GridCallback | None = None,
+    on_pageSize_change: GridCallback | None = None,
+    on_sorting_change: GridCallback | None = None,
+    on_columnFilters_change: GridCallback | None = None,
+    on_selectedRowId_change: GridCallback | None = None,
+    on_selectedRowIds_change: GridCallback | None = None,
+    on_rowOffset_change: GridCallback | None = None,
+    on_rowLimit_change: GridCallback | None = None,
+    on_rowAction_change: GridCallback | None = None,
+    onIndexChange: GridCallback | None = None,
+) -> Any:
+    """Render an LHNGrid Streamlit component."""
+    if key is None:
+        raise ValueError("lhngrid requires a stable key.")
+
+    page_index_callback = on_pageIndex_change or onIndexChange
+    sorting_value = sorting or []
+    column_filters_value = column_filters or []
+    theme_value = _normalize_theme(theme)
+    pagination_position_value = _normalize_pagination_position(pagination_position)
+
+    if is_snowpark_dataframe(rows):
+        prepared_grid_data = prepare_snowpark_data(
+            dataframe=rows,
+            columns=columns,
+            row_key=row_key,
+            page_index=page_index,
+            page_size=page_size,
+            total_rows=total_rows,
+            sorting=sorting_value,
+            column_filters=column_filters_value,
+        )
+        paged_rows = prepared_grid_data.rows
+        component_columns = prepared_grid_data.columns
+        page_index_value = prepared_grid_data.page_index
+        page_size_value = prepared_grid_data.page_size
+        total_rows_value = prepared_grid_data.total_rows
+        row_offset = prepared_grid_data.row_offset
+        row_limit = prepared_grid_data.row_limit
+    else:
+        if columns is None:
+            raise ValueError(
+                "columns is required when rows is not a Snowpark DataFrame."
+            )
+
+        sequence_rows = _normalize_sequence_rows(rows)
+        component_columns = columns
+        (
+            paged_rows,
+            page_index_value,
+            page_size_value,
+            total_rows_value,
+            row_offset,
+            row_limit,
+        ) = _paginate_rows(sequence_rows, page_index, page_size, total_rows)
+
+    page_size_options_value = list(
+        dict.fromkeys(
+            max(1, int(option))
+            for option in (*page_size_options, page_size_value)
+        )
+    )
+
+    return _component(
+        key=key,
+        data={
+            "rows": paged_rows,
+            "columns": component_columns,
+            "rowKey": row_key,
+            "pageIndex": page_index_value,
+            "pageSize": page_size_value,
+            "totalRows": total_rows_value,
+            "sorting": sorting_value,
+            "columnFilters": column_filters_value,
+            "loading": loading,
+            "width": _normalize_size(width),
+            "height": _normalize_size(height),
+            "rowOffset": row_offset,
+            "rowLimit": row_limit,
+            "pageSizeOptions": page_size_options_value,
+            "paginationPosition": pagination_position_value,
+            "showRowSelection": show_row_selection,
+            "showActions": show_actions,
+            "theme": theme_value,
+            "enabledCallbacks": {
+                "pageIndex": page_index_callback is not None,
+                "pageSize": on_pageSize_change is not None,
+                "sorting": on_sorting_change is not None,
+                "columnFilters": on_columnFilters_change is not None,
+                "selectedRowId": on_selectedRowId_change is not None,
+                "selectedRowIds": on_selectedRowIds_change is not None,
+                "rowOffset": on_rowOffset_change is not None,
+                "rowLimit": on_rowLimit_change is not None,
+                "rowAction": show_actions or on_rowAction_change is not None,
+            },
+        },
+        default={
+            "pageIndex": page_index_value,
+            "pageSize": page_size_value,
+            "sorting": sorting_value,
+            "columnFilters": column_filters_value,
+            "selectedRowId": None,
+            "selectedRowIds": [],
+            "rowOffset": row_offset,
+            "rowLimit": row_limit,
+            "rowAction": None,
+        },
+        on_pageIndex_change=_bind_callback(page_index_callback, key),
+        on_pageSize_change=_bind_callback(on_pageSize_change, key),
+        on_sorting_change=_bind_callback(on_sorting_change, key),
+        on_columnFilters_change=_bind_callback(on_columnFilters_change, key),
+        on_selectedRowId_change=_bind_callback(on_selectedRowId_change, key),
+        on_selectedRowIds_change=_bind_callback(on_selectedRowIds_change, key),
+        on_rowOffset_change=_bind_callback(on_rowOffset_change, key),
+        on_rowLimit_change=_bind_callback(on_rowLimit_change, key),
+        on_rowAction_change=_bind_callback(on_rowAction_change, key),
+    )
+
+
+__all__ = ["lhngrid"]

lhngrid-0.0.1/lhngrid/_pagination.py

@@ -0,0 +1,17 @@
+from __future__ import annotations
+
+
+def normalize_pagination(
+    page_index: int,
+    page_size: int,
+    total_rows: int,
+) -> tuple[int, int, int, int]:
+    page_index_value = max(0, int(page_index))
+    page_size_value = max(1, int(page_size))
+    total_rows_value = max(0, int(total_rows))
+    max_page_index = max((total_rows_value - 1) // page_size_value, 0)
+    page_index_value = min(page_index_value, max_page_index)
+    row_offset = page_index_value * page_size_value
+    row_limit = page_size_value
+
+    return page_index_value, page_size_value, row_offset, row_limit