Widget Snippet Catalogue

This page is the working reference for the three widget factories exposed by factor_wiki_widgets: grid, chart, and dashboard. Every snippet below is a runnable {pyodide} cell, so you can compare expected output against what your page actually renders.

The Python module ships as a wheel served from this site under /wheels/ and registered in the site’s Pyodide lockfile, so pages reference it by name (factor-wiki-widgets). The front matter of this page — the pyodide: map — is the literal template to paste into any page that needs the widgets: listing factor-wiki-widgets in pyodide.packages: is the only declaration required. The site-wide loader injects the client libraries, and the factories activate the Panel extensions themselves on first import — no setup cell, no script includes.

Section 1 — Grid from an inline DataFrame

grid(df) wraps a pandas.DataFrame in a Panel Tabulator widget with sensible defaults: sizing_mode="stretch_width", no pagination, the checkbox column for selection, header-filter widgets on every column, and configuration={"clipboard": True} so a reader can copy rows. Pass any keyword argument Tabulator accepts to override a default:

Section 2 — Chart from a plotly Figure

chart(fig) wraps a plotly.graph_objects.Figure in a Panel Plotly pane with sizing_mode="stretch_width". The factory does NOT mutate the figure: no fig.update_layout, no fig.add_*. If you want a title, set it on the figure before passing it to chart:

Section 3 — Static dashboard

dashboard(grid_widget, charts, layout="static") arranges one grid and any number of charts in a pn.Column with the grid on top and the charts in a pn.Row underneath. Use this layout for read-only walk-through pages where the spatial arrangement is part of the story:

Section 4 — GridStack dashboard

dashboard(grid_widget, charts, layout="gridstack") returns a Panel GridStack template whose panels are draggable and resizable in the browser. Use this layout for exploratory pages where readers should rearrange the panels themselves:

Section 5 — `load_dataset → grid` cross-spec composition

The data-access spec ships a factor_wiki_data wheel that exposes load_dataset(path) -> DataFrame. The grid factory accepts the returned DataFrame directly — there is no glue code between the two specs. The composition pattern is:

from factor_wiki_data import load_dataset
from factor_wiki_widgets import grid

df = await load_dataset("smoke/tiny.parquet")
grid(df)

Note

This snippet is shown as a static code block until the data-access spec (.kiro/specs/data-access/) ships the factor_wiki_data wheel. Once that wheel is published to /wheels/factor_wiki_data-latest-py3-none-any.whl, add its URL to the pyodide.packages: block above and convert this block into a {pyodide} cell. The widget factories themselves require no change — grid accepts any pandas.DataFrame regardless of how it was produced.

Error surface

Each factory validates its inputs and raises a subclass of WidgetError:

grid(not_a_df) raises WidgetTypeError naming the type it received.
chart(not_a_figure) raises WidgetTypeError naming the type it received.
dashboard(..., layout="kanban") raises WidgetLayoutError listing the accepted layouts ("static", "gridstack").

Catch the base class to handle any widget error, or catch a subclass for a specific failure mode:

from factor_wiki_widgets import WidgetError, WidgetTypeError

try:
    grid(some_value)
except WidgetTypeError as e:
    # input was the wrong shape; show a hint
    raise
except WidgetError:
    # any other widget error
    raise