` container. If `None` (the default), a unique
+ ID is auto-generated using `secrets.token_hex(4)`. Providing your own ID is useful when you
+ need to target the table with custom CSS or JavaScript.
+
+ Returns
+ -------
+ TblExplorer
+ A rendered interactive table object. The object has `_repr_html_()` for automatic notebook
+ display.
+
+ Supported Input Data Types
+ --------------------------
+ The `data` parameter accepts any of the following:
+
+ - **Polars DataFrame** — displays a blue *Polars* badge
+ - **Pandas DataFrame** — displays a dark purple *Pandas* badge
+ - **PyArrow Table** — displays an indigo *Arrow* badge
+ - **CSV file** (`.csv`) — loaded automatically; displays a cream *CSV* badge
+ - **TSV file** (`.tsv`) — loaded automatically; displays a green *TSV* badge
+ - **JSONL file** (`.jsonl` or `.ndjson`) — loaded line-by-line; displays a blue *JSONL*
+ badge
+ - **Parquet file** (`.parquet`) — requires `polars`, `pandas`, or `pyarrow`; displays
+ a purple *Parquet* badge
+ - **Feather / Arrow IPC file** (`.feather` or `.arrow`) — requires `polars`, `pandas`,
+ or `pyarrow`; displays an orange *Feather* badge
+ - **Dictionary** (column-oriented, `dict[str, list]`) — displays a gray *Table* badge
+ - **List of dictionaries** (row-oriented, `list[dict]`) — displays a gray *Table* badge
+
+ For file-based inputs, pass a string or `pathlib.Path` object. The file extension is used to
+ determine the format. Polars is preferred for loading when available; Pandas and PyArrow are
+ used as fallbacks.
+
+ Examples
+ --------
+ The simplest way to explore a table is to pass a Python dictionary:
+
+ ```{python}
+ from great_docs import tbl_explorer
+
+ tbl_explorer({
+ "city": ["Tokyo", "Paris", "New York", "London", "Sydney"],
+ "population": [13960000, 2161000, 8336000, 8982000, 5312000],
+ "country": ["Japan", "France", "USA", "UK", "Australia"],
+ })
+ ```
+
+ You can also pass a Polars DataFrame:
+
+ ```{python}
+ import polars as pl
+
+ df = pl.DataFrame({
+ "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
+ "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
+ "price": [29.99, 49.50, 12.00, 8.75, 199.99],
+ "in_stock": [True, False, True, True, False],
+ })
+
+ tbl_explorer(df)
+ ```
+
+ Load a CSV file and show only specific columns:
+
+ ```python
+ tbl_explorer("data/sales.csv", columns=["product", "revenue", "units"])
+ ```
+
+ Disable pagination to show all rows at once:
+
+ ```python
+ tbl_explorer(df, page_size=0)
+ ```
+
+ Create a minimal, sort-only table with no toolbar controls:
+
+ ```python
+ tbl_explorer(
+ df,
+ sortable=True,
+ filterable=False,
+ column_toggle=False,
+ copyable=False,
+ downloadable=False,
+ page_size=0,
+ )
+ ```
+ """
+ import warnings
+
+ # 1. Normalize input data
+ col_names, col_dtypes, all_rows, total_rows, tbl_type = _normalize_data(data)
+ original_n_cols = len(col_names)
+
+ if total_rows > _LARGE_DATASET_THRESHOLD:
+ warnings.warn(
+ f"tbl_explorer() is embedding {total_rows:,} rows as inline JSON. "
+ f"For datasets larger than {_LARGE_DATASET_THRESHOLD:,} rows, consider "
+ f"using tbl_preview() with n_head/n_tail instead.",
+ UserWarning,
+ stacklevel=2,
+ )
+
+ # 2. Apply column subset
+ col_names, col_dtypes, all_rows = _apply_column_subset(col_names, col_dtypes, all_rows, columns)
+
+ # 3. Detect alignments
+ alignments = _detect_alignments(col_dtypes)
+
+ # 4. Build the first page of rows for the static fallback table
+ if page_size > 0 and total_rows > page_size:
+ fallback_rows = all_rows[:page_size]
+ fallback_row_numbers = list(range(page_size))
+ is_full = False
+ n_head_fallback = page_size
+ else:
+ fallback_rows = all_rows
+ fallback_row_numbers = list(range(total_rows))
+ is_full = True
+ n_head_fallback = total_rows
+
+ # 5. Compute column widths (based on fallback rows for initial render)
+ col_widths, rownum_width = _compute_col_widths(
+ col_names,
+ col_dtypes,
+ fallback_rows,
+ max_col_width,
+ min_tbl_width,
+ show_row_numbers,
+ fallback_row_numbers,
+ )
+
+ # 6. Generate unique ID
+ uid = id or secrets.token_hex(4)
+
+ total_cols = len(col_names) + (1 if show_row_numbers else 0)
+
+ # 7. Config dict for the JSON blob
+ config = {
+ "pageSize": page_size,
+ "sortable": sortable,
+ "filterable": filterable,
+ "columnToggle": column_toggle,
+ "copyable": copyable,
+ "downloadable": downloadable,
+ "resizable": resizable,
+ "stickyHeader": sticky_header,
+ "searchHighlight": search_highlight,
+ "showRowNumbers": show_row_numbers,
+ "showDtypes": show_dtypes,
+ "highlightMissing": highlight_missing,
+ }
+
+ # 8. Serialize full data as JSON
+ data_json = _serialize_data_blob(
+ col_names, col_dtypes, alignments, all_rows, total_rows, tbl_type, config
+ )
+
+ # 9. Render static fallback HTML (same structure as tbl_preview)
+ base_css = _render_scoped_css(uid)
+ explorer_css = _render_explorer_css(uid)
+
+ header = _render_header_html(
+ uid, tbl_type, total_rows, original_n_cols, caption, show_dimensions, total_cols
+ )
+ colgroup = _render_colgroup_html(col_widths, rownum_width, show_row_numbers)
+ column_labels = _render_column_labels_html(
+ col_names, col_dtypes, alignments, show_dtypes, show_row_numbers
+ )
+ body = _render_body_html(
+ fallback_rows,
+ fallback_row_numbers,
+ col_names,
+ alignments,
+ col_widths,
+ n_head_fallback,
+ is_full,
+ show_row_numbers,
+ highlight_missing,
+ )
+
+ # 10. Load JS
+ js_source = _get_js_inline()
+
+ # 11. Assemble
+ html = (
+ f'
\n'
+ f"{base_css}\n"
+ f"{explorer_css}\n"
+ f'\n'
+ f'
\n"
+ f"\n"
+ f"
"
+ )
+
+ return TblExplorer(html)
diff --git a/great_docs/assets/_extensions/tbl-explorer/_extension.yml b/great_docs/assets/_extensions/tbl-explorer/_extension.yml
new file mode 100644
index 0000000..a9fb86d
--- /dev/null
+++ b/great_docs/assets/_extensions/tbl-explorer/_extension.yml
@@ -0,0 +1,7 @@
+title: Table Explorer
+author: Great Docs
+version: 1.0.0
+quarto-required: ">=1.3.0"
+contributes:
+ shortcodes:
+ - tbl-explorer.lua
diff --git a/great_docs/assets/_extensions/tbl-explorer/_tbl_explorer_shortcode.py b/great_docs/assets/_extensions/tbl-explorer/_tbl_explorer_shortcode.py
new file mode 100644
index 0000000..9203d61
--- /dev/null
+++ b/great_docs/assets/_extensions/tbl-explorer/_tbl_explorer_shortcode.py
@@ -0,0 +1,88 @@
+#!/usr/bin/env python3
+"""CLI helper for the tbl-explorer Quarto shortcode."""
+
+from __future__ import annotations
+
+import argparse
+import importlib.util
+import sys
+from pathlib import Path
+
+
+def _load_tbl_explorer():
+ """Import tbl_explorer without triggering great_docs.__init__."""
+ try:
+ from great_docs._tbl_explorer import tbl_explorer
+
+ return tbl_explorer
+ except (ImportError, ModuleNotFoundError):
+ here = Path(__file__).resolve().parent
+ p = here
+ while p != p.parent:
+ candidate = p / "great_docs" / "_tbl_explorer.py"
+ if candidate.exists():
+ spec = importlib.util.spec_from_file_location("_tbl_explorer", candidate)
+ mod = importlib.util.module_from_spec(spec)
+ spec.loader.exec_module(mod)
+ return mod.tbl_explorer
+ p = p.parent
+ raise ImportError("Cannot find _tbl_explorer.py")
+
+
+def main() -> None:
+ parser = argparse.ArgumentParser(description="Render an interactive table explorer.")
+ parser.add_argument(
+ "file", help="Path to data file (CSV, TSV, JSONL, Parquet, Feather, Arrow IPC)"
+ )
+ parser.add_argument("--columns", default=None, help="Comma-separated column names")
+ parser.add_argument("--page_size", type=int, default=20)
+ parser.add_argument("--sortable", default="true")
+ parser.add_argument("--filterable", default="true")
+ parser.add_argument("--column_toggle", default="true")
+ parser.add_argument("--copyable", default="true")
+ parser.add_argument("--downloadable", default="true")
+ parser.add_argument("--resizable", default="false")
+ parser.add_argument("--sticky_header", default="true")
+ parser.add_argument("--search_highlight", default="true")
+ parser.add_argument("--show_row_numbers", default="true")
+ parser.add_argument("--show_dtypes", default="true")
+ parser.add_argument("--show_dimensions", default="true")
+ parser.add_argument("--max_col_width", type=int, default=250)
+ parser.add_argument("--min_tbl_width", type=int, default=500)
+ parser.add_argument("--caption", default=None)
+ parser.add_argument("--highlight_missing", default="true")
+ args = parser.parse_args()
+
+ tbl_explorer = _load_tbl_explorer()
+
+ columns = [c.strip() for c in args.columns.split(",")] if args.columns else None
+
+ def _to_bool(s: str) -> bool:
+ return s.lower() in ("true", "1", "yes")
+
+ result = tbl_explorer(
+ data=args.file,
+ columns=columns,
+ page_size=args.page_size,
+ sortable=_to_bool(args.sortable),
+ filterable=_to_bool(args.filterable),
+ column_toggle=_to_bool(args.column_toggle),
+ copyable=_to_bool(args.copyable),
+ downloadable=_to_bool(args.downloadable),
+ resizable=_to_bool(args.resizable),
+ sticky_header=_to_bool(args.sticky_header),
+ search_highlight=_to_bool(args.search_highlight),
+ show_row_numbers=_to_bool(args.show_row_numbers),
+ show_dtypes=_to_bool(args.show_dtypes),
+ show_dimensions=_to_bool(args.show_dimensions),
+ max_col_width=args.max_col_width,
+ min_tbl_width=args.min_tbl_width,
+ caption=args.caption,
+ highlight_missing=_to_bool(args.highlight_missing),
+ )
+
+ sys.stdout.write(result.as_html())
+
+
+if __name__ == "__main__":
+ main()
diff --git a/great_docs/assets/_extensions/tbl-explorer/tbl-explorer.lua b/great_docs/assets/_extensions/tbl-explorer/tbl-explorer.lua
new file mode 100644
index 0000000..89b9dff
--- /dev/null
+++ b/great_docs/assets/_extensions/tbl-explorer/tbl-explorer.lua
@@ -0,0 +1,94 @@
+-- tbl-explorer.lua — Quarto shortcode for interactive table explorer
+--
+-- Usage in .qmd files:
+--
+-- {{< tbl-explorer file="data/example.csv" >}}
+-- {{< tbl-explorer file="data.csv" page_size="25" sortable="true" >}}
+-- {{< tbl-explorer file="data.csv" column_toggle="false" downloadable="false" >}}
+--
+-- Calls the companion _tbl_explorer_shortcode.py script, which imports
+-- tbl_explorer() from great_docs._tbl_explorer and prints the resulting
+-- HTML to stdout.
+
+local function kwarg_str(kwargs, key)
+ local raw = kwargs[key]
+ if raw == nil then return "" end
+ local s = pandoc.utils.stringify(raw)
+ return s or ""
+end
+
+return {
+ ["tbl-explorer"] = function(args, kwargs)
+ -- File path can be a positional arg or named kwarg
+ local file = kwarg_str(kwargs, "file")
+ if file == "" and #args > 0 then
+ file = pandoc.utils.stringify(args[1])
+ end
+
+ if file == "" then
+ return pandoc.RawBlock(
+ "html",
+ ""
+ )
+ end
+
+ -- Locate the helper script (lives alongside this .lua file)
+ local script_dir = debug.getinfo(1, "S").source:match("@?(.*/)") or "./"
+ local helper = script_dir .. "_tbl_explorer_shortcode.py"
+
+ -- Resolve relative file paths against the Quarto project root
+ if file:sub(1, 1) ~= "/" then
+ local project_root = script_dir .. "../../"
+ file = project_root .. file
+ end
+
+ -- Build CLI arguments
+ local cmd_args = { "python3", helper, file }
+
+ -- Forward optional keyword arguments
+ local forwarded = {
+ "columns", "page_size", "sortable", "filterable",
+ "column_toggle", "copyable", "downloadable", "resizable",
+ "sticky_header", "search_highlight",
+ "show_row_numbers", "show_dtypes", "show_dimensions",
+ "max_col_width", "min_tbl_width", "caption",
+ "highlight_missing",
+ }
+ for _, key in ipairs(forwarded) do
+ local val = kwarg_str(kwargs, key)
+ if val ~= "" then
+ table.insert(cmd_args, "--" .. key)
+ table.insert(cmd_args, val)
+ end
+ end
+
+ -- Build shell command (quote each argument)
+ local parts = {}
+ for _, arg in ipairs(cmd_args) do
+ local escaped = arg:gsub("'", "'\\''")
+ table.insert(parts, "'" .. escaped .. "'")
+ end
+ local cmd = table.concat(parts, " ") .. " 2>&1"
+
+ local handle = io.popen(cmd)
+ if not handle then
+ return pandoc.RawBlock(
+ "html",
+ ""
+ )
+ end
+
+ local result = handle:read("*a")
+ local success = handle:close()
+
+ if not success or result == "" then
+ return pandoc.RawBlock(
+ "html",
+ ""
+ )
+ end
+
+ return pandoc.RawBlock("html", result)
+ end
+}
diff --git a/great_docs/assets/tbl-explorer.js b/great_docs/assets/tbl-explorer.js
new file mode 100644
index 0000000..fc8fb9a
--- /dev/null
+++ b/great_docs/assets/tbl-explorer.js
@@ -0,0 +1,1139 @@
+/**
+ * Great Docs Table Explorer — Interactive table enhancement
+ *
+ * Progressive enhancement for .gd-tbl-explorer tables.
+ * Zero external dependencies. Works in all modern browsers.
+ *
+ * Features: sorting, filtering, pagination, column toggling,
+ * copy-to-clipboard, CSV download, search highlighting, sticky header.
+ */
+(function () {
+ "use strict";
+
+ var DEBOUNCE_MS = 200;
+ var COPIED_MS = 2000;
+ var PAGE_WINDOW = 2;
+
+ // SVG sort indicator icons (all same viewBox for consistent width)
+ var SORT_W = 10, SORT_H = 14;
+ var SVG_SORT_NONE = '
' +
+ ' ';
+ var SVG_SORT_ASC = '
' +
+ ' ';
+ var SVG_SORT_DESC = '
' +
+ ' ';
+
+ function setSortIcon(iconEl, dir) {
+ if (dir === "asc") iconEl.innerHTML = SVG_SORT_ASC;
+ else if (dir === "desc") iconEl.innerHTML = SVG_SORT_DESC;
+ else iconEl.innerHTML = SVG_SORT_NONE;
+ }
+
+ // SVG toolbar button icons (all 14×14, viewBox 0 0 24 24, stroke style)
+ var ICON_ATTRS = ' width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"';
+ var SVG_COPY = '
$1 ');
+ }
+
+ // ── Pagination ─────────────────────────────────────────────
+
+ function getVisiblePageRows(state) {
+ if (state.pageSize <= 0) return state.filteredRows;
+ var start = (state.currentPage - 1) * state.pageSize;
+ return state.filteredRows.slice(start, start + state.pageSize);
+ }
+
+ function renderPagination(el, state) {
+ var existing = el.querySelector(".gd-tbl-pagination");
+ if (existing) existing.parentNode.removeChild(existing);
+
+ if (state.pageSize <= 0) return;
+
+ var totalFiltered = state.filteredRows.length;
+ var totalPages = Math.max(1, Math.ceil(totalFiltered / state.pageSize));
+
+ if (totalFiltered <= state.pageSize) return;
+
+ var nav = document.createElement("nav");
+ nav.className = "gd-tbl-pagination";
+ nav.setAttribute("aria-label", "Table pagination");
+
+ // Info
+ var start = (state.currentPage - 1) * state.pageSize + 1;
+ var end = Math.min(state.currentPage * state.pageSize, totalFiltered);
+ var info = document.createElement("span");
+ info.className = "gd-tbl-page-info";
+ info.textContent = "Showing " + fmtNum(start) + "\u2013" +
+ fmtNum(end) + " of " + fmtNum(totalFiltered) + " rows";
+ nav.appendChild(info);
+
+ // Page buttons
+ var btns = document.createElement("span");
+ btns.className = "gd-tbl-page-nav";
+
+ // Prev
+ var prev = makePageBtn("\u25C0", state.currentPage > 1, function () {
+ state.currentPage--;
+ applyState(el, state);
+ });
+ prev.setAttribute("aria-label", "Previous page");
+ btns.appendChild(prev);
+
+ // Page numbers with ellipsis
+ var range = getPageRange(state.currentPage, totalPages);
+ for (var i = 0; i < range.length; i++) {
+ if (range[i] === "...") {
+ var ell = document.createElement("span");
+ ell.className = "gd-tbl-page-ellipsis";
+ ell.textContent = "\u2026";
+ btns.appendChild(ell);
+ } else {
+ var pNum = range[i];
+ (function (p) {
+ var b = makePageBtn(String(p), true, function () {
+ state.currentPage = p;
+ applyState(el, state);
+ });
+ if (p === state.currentPage) b.classList.add("active");
+ b.setAttribute("aria-label", "Page " + p);
+ if (p === state.currentPage) b.setAttribute("aria-current", "page");
+ btns.appendChild(b);
+ })(pNum);
+ }
+ }
+
+ // Next
+ var next = makePageBtn("\u25B6", state.currentPage < totalPages, function () {
+ state.currentPage++;
+ applyState(el, state);
+ });
+ next.setAttribute("aria-label", "Next page");
+ btns.appendChild(next);
+
+ nav.appendChild(btns);
+ el.appendChild(nav);
+ }
+
+ function makePageBtn(text, enabled, onClick) {
+ var btn = document.createElement("button");
+ btn.className = "gd-tbl-page-btn";
+ btn.textContent = text;
+ btn.disabled = !enabled;
+ if (enabled) btn.addEventListener("click", onClick);
+ return btn;
+ }
+
+ function getPageRange(current, total) {
+ if (total <= 7) {
+ var r = [];
+ for (var i = 1; i <= total; i++) r.push(i);
+ return r;
+ }
+ var pages = [1];
+ var lo = Math.max(2, current - PAGE_WINDOW);
+ var hi = Math.min(total - 1, current + PAGE_WINDOW);
+ if (lo > 2) pages.push("...");
+ for (var j = lo; j <= hi; j++) pages.push(j);
+ if (hi < total - 1) pages.push("...");
+ pages.push(total);
+ return pages;
+ }
+
+ // ── Utilities ──────────────────────────────────────────────
+
+ function debounce(fn, ms) {
+ var timer;
+ return function () {
+ var args = arguments, ctx = this;
+ clearTimeout(timer);
+ timer = setTimeout(function () { fn.apply(ctx, args); }, ms);
+ };
+ }
+
+ function fmtNum(n) {
+ return n.toLocaleString();
+ }
+
+ // ── Boot ───────────────────────────────────────────────────
+
+ if (document.readyState === "loading") {
+ document.addEventListener("DOMContentLoaded", init);
+ } else {
+ init();
+ }
+})();
diff --git a/test-packages/synthetic/catalog.py b/test-packages/synthetic/catalog.py
index be50e9a..bbfc9ac 100644
--- a/test-packages/synthetic/catalog.py
+++ b/test-packages/synthetic/catalog.py
@@ -361,6 +361,8 @@
"gdtest_tbl_preview", # 178
# 179: Table preview shortcode showcase
"gdtest_tbl_shortcode", # 179
+ # 180: Interactive table explorer showcase
+ "gdtest_tbl_explorer", # 180
]
@@ -2026,6 +2028,15 @@
"plus multi-table pages and wide-table horizontal scroll. No Python "
"code cells; all rendering is done via the shortcode."
),
+ "gdtest_tbl_explorer": (
+ "Interactive table explorer showcase exercising tbl_explorer() with "
+ "eight user-guide pages: basic sorting/filtering, pagination (custom "
+ "page sizes, no pagination), column toggling (wide tables, subsets, "
+ "toggle disabled), copy/download controls (various combinations), "
+ "missing-value highlighting, minimal chrome (hide row numbers, dtypes, "
+ "dimensions), tbl-explorer Quarto shortcode with CSV/TSV/JSONL files, "
+ "and a side-by-side comparison of tbl_preview() vs tbl_explorer()."
+ ),
}
diff --git a/test-packages/synthetic/specs/gdtest_tbl_explorer.py b/test-packages/synthetic/specs/gdtest_tbl_explorer.py
new file mode 100644
index 0000000..f88ef66
--- /dev/null
+++ b/test-packages/synthetic/specs/gdtest_tbl_explorer.py
@@ -0,0 +1,669 @@
+"""
+gdtest_tbl_explorer — Interactive table explorer showcase.
+
+Dimensions: A1, B1, C1, D1, M4, G1
+Focus: Exercises the ``tbl_explorer()`` function with many different table
+ shapes, data types, display options, and interactive feature toggles.
+ The user guide has eight pages:
+
+ 1. Basic explorer — dict data, default options, sorting & filtering.
+ 2. Large table — 200-row dataset, pagination, page navigation.
+ 3. Column toggling — wide table, hide/show columns, column subsets.
+ 4. Copy & download — copy to clipboard, CSV download.
+ 5. Missing values — None/NaN highlighting, mixed types.
+ 6. Minimal chrome — hide row numbers, dtypes, dimensions.
+ 7. Shortcode explorer — exercise the {{< tbl-explorer >}} shortcode.
+ 8. Side-by-side — tbl_preview() vs tbl_explorer() comparison.
+
+ The API reference documents helper functions that generate sample
+ data for the explorer demos.
+"""
+
+SPEC = {
+ "name": "gdtest_tbl_explorer",
+ "description": "Interactive table explorer showcase with sorting, filtering, pagination.",
+ "dimensions": ["A1", "B1", "C1", "D1", "M2", "G1"],
+ "pyproject_toml": {
+ "project": {
+ "name": "gdtest-tbl-explorer",
+ "version": "0.1.0",
+ "description": "Showcase for the tbl_explorer() interactive table feature",
+ "dependencies": ["great_docs"],
+ },
+ "build-system": {
+ "requires": ["setuptools"],
+ "build-backend": "setuptools.build_meta",
+ },
+ },
+ "config": {},
+ "files": {
+ # ── Project root ──────────────────────────────────────────────────
+ "README.md": (
+ "# gdtest-tbl-explorer\n\n"
+ "A showcase site demonstrating the `tbl_explorer()` function from\n"
+ "Great Docs. Each user-guide page exercises a different combination\n"
+ "of data sources, interactive features, and display options.\n"
+ ),
+ # ── Package source ────────────────────────────────────────────────
+ "gdtest_tbl_explorer/__init__.py": '''\
+ """Sample data generators for table explorer demos."""
+
+ __version__ = "0.1.0"
+ __all__ = [
+ "sample_cities",
+ "sample_products",
+ "sample_wide",
+ "sample_missing",
+ "sample_large",
+ ]
+
+ from .data import (
+ sample_cities,
+ sample_products,
+ sample_wide,
+ sample_missing,
+ sample_large,
+ )
+ ''',
+ "gdtest_tbl_explorer/data.py": '''\
+ """Functions that generate sample data for explorer demos."""
+
+ from __future__ import annotations
+
+
+ def sample_cities(n: int = 12) -> dict[str, list]:
+ """
+ Generate a world cities dataset.
+
+ Parameters
+ ----------
+ n
+ Number of rows.
+
+ Returns
+ -------
+ dict[str, list]
+ Column-oriented dict with city, country, population,
+ latitude, and longitude columns.
+
+ Examples
+ --------
+ >>> data = sample_cities(5)
+ >>> len(data["city"])
+ 5
+ """
+ cities = [
+ ("Tokyo", "Japan", 13960000, 35.6762, 139.6503),
+ ("Paris", "France", 2161000, 48.8566, 2.3522),
+ ("New York", "USA", 8336000, 40.7128, -74.0060),
+ ("London", "UK", 8982000, 51.5074, -0.1278),
+ ("Sydney", "Australia", 5312000, -33.8688, 151.2093),
+ ("Berlin", "Germany", 3645000, 52.5200, 13.4050),
+ ("Mumbai", "India", 20411000, 19.0760, 72.8777),
+ ("São Paulo", "Brazil", 12330000, -23.5505, -46.6333),
+ ("Cairo", "Egypt", 10230000, 30.0444, 31.2357),
+ ("Toronto", "Canada", 2930000, 43.6532, -79.3832),
+ ("Seoul", "South Korea", 9776000, 37.5665, 126.9780),
+ ("Mexico City", "Mexico", 9210000, 19.4326, -99.1332),
+ ("Lagos", "Nigeria", 15400000, 6.5244, 3.3792),
+ ("Bangkok", "Thailand", 10540000, 13.7563, 100.5018),
+ ("Istanbul", "Turkey", 15460000, 41.0082, 28.9784),
+ ]
+ rows = cities[:n]
+ return {
+ "city": [r[0] for r in rows],
+ "country": [r[1] for r in rows],
+ "population": [r[2] for r in rows],
+ "latitude": [r[3] for r in rows],
+ "longitude": [r[4] for r in rows],
+ }
+
+
+ def sample_products(n: int = 15) -> dict[str, list]:
+ """
+ Generate a product catalog dataset.
+
+ Parameters
+ ----------
+ n
+ Number of rows.
+
+ Returns
+ -------
+ dict[str, list]
+ Column-oriented dict with product, category, price,
+ stock, rating, and in_stock columns.
+
+ Examples
+ --------
+ >>> data = sample_products(5)
+ >>> len(data["product"])
+ 5
+ """
+ import random
+ random.seed(42)
+ products = [
+ "Widget", "Gadget", "Doohickey", "Thingamajig",
+ "Gizmo", "Whatchamacallit", "Contraption", "Apparatus",
+ "Device", "Instrument", "Mechanism", "Implement",
+ "Tool", "Utensil", "Component",
+ ]
+ categories = ["Electronics", "Tools", "Kitchen", "Garden", "Office"]
+ rows = []
+ for i in range(n):
+ name = products[i % len(products)]
+ cat = random.choice(categories)
+ price = round(random.uniform(5.0, 250.0), 2)
+ stock = random.randint(0, 500)
+ rating = round(random.uniform(1.0, 5.0), 1)
+ rows.append((name, cat, price, stock, rating, stock > 0))
+ return {
+ "product": [r[0] for r in rows],
+ "category": [r[1] for r in rows],
+ "price": [r[2] for r in rows],
+ "stock": [r[3] for r in rows],
+ "rating": [r[4] for r in rows],
+ "in_stock": [r[5] for r in rows],
+ }
+
+
+ def sample_wide(n_rows: int = 10, n_cols: int = 15) -> dict[str, list]:
+ """
+ Generate a wide dataset with many numeric columns.
+
+ Parameters
+ ----------
+ n_rows
+ Number of rows.
+ n_cols
+ Number of data columns (plus an id column).
+
+ Returns
+ -------
+ dict[str, list]
+ Column-oriented dict with an ``id`` column and
+ ``metric_001`` through ``metric_{n_cols:03d}``.
+
+ Examples
+ --------
+ >>> data = sample_wide(5, 8)
+ >>> len(data)
+ 9
+ """
+ import random
+ random.seed(7)
+ result = {"id": list(range(n_rows))}
+ for i in range(n_cols):
+ result[f"metric_{i+1:03d}"] = [
+ round(random.gauss(0, 1), 3) for _ in range(n_rows)
+ ]
+ return result
+
+
+ def sample_missing(n: int = 12) -> dict[str, list]:
+ """
+ Generate a dataset with scattered missing values.
+
+ Parameters
+ ----------
+ n
+ Number of rows.
+
+ Returns
+ -------
+ dict[str, list]
+ Column-oriented dict with name, value, category, and
+ score columns. Some cells are None.
+
+ Examples
+ --------
+ >>> data = sample_missing(5)
+ >>> None in data["value"]
+ True
+ """
+ import random
+ random.seed(13)
+ names = ["Alpha", "Beta", "Gamma", "Delta", "Epsilon",
+ "Zeta", "Eta", "Theta", "Iota", "Kappa",
+ "Lambda", "Mu"]
+ categories = ["A", "B", "C", None]
+ rows_name = [names[i % len(names)] for i in range(n)]
+ rows_val = [
+ None if random.random() < 0.25
+ else round(random.uniform(10, 100), 1)
+ for _ in range(n)
+ ]
+ rows_cat = [random.choice(categories) for _ in range(n)]
+ rows_score = [
+ None if random.random() < 0.2
+ else random.randint(1, 100)
+ for _ in range(n)
+ ]
+ return {
+ "name": rows_name,
+ "value": rows_val,
+ "category": rows_cat,
+ "score": rows_score,
+ }
+
+
+ def sample_large(n: int = 200) -> dict[str, list]:
+ """
+ Generate a large dataset for pagination testing.
+
+ Parameters
+ ----------
+ n
+ Number of rows.
+
+ Returns
+ -------
+ dict[str, list]
+ Column-oriented dict with id, name, department, salary,
+ years, and active columns.
+
+ Examples
+ --------
+ >>> data = sample_large(50)
+ >>> len(data["id"])
+ 50
+ """
+ import random
+ random.seed(123)
+ first_names = [
+ "Alice", "Bob", "Charlie", "Diana", "Eve", "Frank",
+ "Grace", "Hank", "Iris", "Jack", "Karen", "Leo",
+ "Mona", "Nate", "Olivia", "Paul", "Quinn", "Rosa",
+ ]
+ depts = [
+ "Engineering", "Marketing", "Sales", "Finance",
+ "HR", "Operations", "Legal", "R&D",
+ ]
+ return {
+ "id": list(range(1, n + 1)),
+ "name": [random.choice(first_names) for _ in range(n)],
+ "department": [random.choice(depts) for _ in range(n)],
+ "salary": [random.randint(50000, 200000) for _ in range(n)],
+ "years": [random.randint(1, 30) for _ in range(n)],
+ "active": [random.random() > 0.15 for _ in range(n)],
+ }
+ ''',
+ # ── Data files for shortcode demos ────────────────────────────────
+ "assets/cities.csv": (
+ "city,country,population,latitude,longitude\n"
+ "Tokyo,Japan,13960000,35.6762,139.6503\n"
+ "Paris,France,2161000,48.8566,2.3522\n"
+ "New York,USA,8336000,40.7128,-74.0060\n"
+ "London,UK,8982000,51.5074,-0.1278\n"
+ "Sydney,Australia,5312000,-33.8688,151.2093\n"
+ "Berlin,Germany,3645000,52.5200,13.4050\n"
+ "Mumbai,India,20411000,19.0760,72.8777\n"
+ "São Paulo,Brazil,12330000,-23.5505,-46.6333\n"
+ "Cairo,Egypt,10230000,30.0444,31.2357\n"
+ "Toronto,Canada,2930000,43.6532,-79.3832\n"
+ "Seoul,South Korea,9776000,37.5665,126.9780\n"
+ "Mexico City,Mexico,9210000,19.4326,-99.1332\n"
+ ),
+ "assets/products.tsv": (
+ "product\tcategory\tprice\tstock\trating\n"
+ "Widget\tElectronics\t29.99\t150\t4.5\n"
+ "Gadget\tTools\t49.50\t80\t3.8\n"
+ "Gizmo\tKitchen\t12.00\t300\t4.9\n"
+ "Doohickey\tGarden\t8.75\t0\t4.2\n"
+ "Thingamajig\tOffice\t199.99\t25\t2.1\n"
+ "Contraption\tElectronics\t65.00\t44\t3.5\n"
+ "Apparatus\tTools\t120.00\t12\t4.7\n"
+ ),
+ "assets/logs.jsonl": (
+ '{"ts":"2025-01-15T08:30:00","level":"INFO","module":"auth","msg":"User login OK"}\n'
+ '{"ts":"2025-01-15T08:31:12","level":"WARN","module":"db","msg":"Slow query (3.2s)"}\n'
+ '{"ts":"2025-01-15T08:32:45","level":"ERROR","module":"api","msg":"Timeout /v2/users"}\n'
+ '{"ts":"2025-01-15T08:33:01","level":"INFO","module":"cache","msg":"Cache miss user:42"}\n'
+ '{"ts":"2025-01-15T08:34:20","level":"DEBUG","module":"auth","msg":"Token refresh abc123"}\n'
+ '{"ts":"2025-01-15T08:35:55","level":"ERROR","module":"db","msg":"Pool exhausted"}\n'
+ ),
+ # ── User guide pages ──────────────────────────────────────────────
+ "user_guide/01-basic-explorer.qmd": (
+ "---\n"
+ "title: Basic Explorer\n"
+ "---\n"
+ "\n"
+ "The `tbl_explorer()` function creates interactive tables with\n"
+ "sorting, filtering, pagination, and more.\n"
+ "\n"
+ "## Default Options\n"
+ "\n"
+ "Pass a dictionary and get a fully interactive table:\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_explorer\n"
+ "from gdtest_tbl_explorer import sample_cities\n"
+ "\n"
+ "tbl_explorer(sample_cities())\n"
+ "```\n"
+ "\n"
+ "Try clicking column headers to sort, or type in the filter box.\n"
+ "\n"
+ "## With Caption\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ 'tbl_explorer(sample_cities(), caption="World Cities")\n'
+ "```\n"
+ "\n"
+ "## Product Catalog\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from gdtest_tbl_explorer import sample_products\n"
+ "\n"
+ 'tbl_explorer(sample_products(), caption="Product Catalog")\n'
+ "```\n"
+ ),
+ "user_guide/02-pagination.qmd": (
+ "---\n"
+ "title: Pagination\n"
+ "---\n"
+ "\n"
+ "With larger datasets, `tbl_explorer()` paginates automatically.\n"
+ "\n"
+ "## Default Page Size (20 rows)\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_explorer\n"
+ "from gdtest_tbl_explorer import sample_large\n"
+ "\n"
+ 'tbl_explorer(sample_large(200), caption="200 Employees")\n'
+ "```\n"
+ "\n"
+ "## Custom Page Size (10 rows)\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ 'tbl_explorer(sample_large(200), page_size=10, caption="10 per page")\n'
+ "```\n"
+ "\n"
+ "## Large Page Size (50 rows)\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ 'tbl_explorer(sample_large(200), page_size=50, caption="50 per page")\n'
+ "```\n"
+ "\n"
+ "## No Pagination\n"
+ "\n"
+ "Set `page_size=0` to show all rows at once:\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ 'tbl_explorer(sample_large(30), page_size=0, caption="All 30 rows")\n'
+ "```\n"
+ ),
+ "user_guide/03-column-toggle.qmd": (
+ "---\n"
+ "title: Column Toggling\n"
+ "---\n"
+ "\n"
+ "Use the **Columns** dropdown in the toolbar to show/hide columns.\n"
+ "\n"
+ "## Wide Table\n"
+ "\n"
+ "This table has 16 columns — try hiding some:\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_explorer\n"
+ "from gdtest_tbl_explorer import sample_wide\n"
+ "\n"
+ 'tbl_explorer(sample_wide(10, 15), caption="Wide Metrics Table")\n'
+ "```\n"
+ "\n"
+ "## Column Subset\n"
+ "\n"
+ "Pre-select specific columns with `columns=`:\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from gdtest_tbl_explorer import sample_cities\n"
+ "\n"
+ "tbl_explorer(\n"
+ " sample_cities(),\n"
+ ' columns=["city", "country", "population"],\n'
+ ' caption="Cities — 3 columns only",\n'
+ ")\n"
+ "```\n"
+ "\n"
+ "## Toggle Disabled\n"
+ "\n"
+ "Set `column_toggle=False` to remove the dropdown:\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_cities(),\n"
+ " column_toggle=False,\n"
+ ' caption="No column toggle",\n'
+ ")\n"
+ "```\n"
+ ),
+ "user_guide/04-copy-download.qmd": (
+ "---\n"
+ "title: Copy & Download\n"
+ "---\n"
+ "\n"
+ "The toolbar includes **Copy** (TSV to clipboard) and **Download**\n"
+ "(CSV file) buttons.\n"
+ "\n"
+ "## Full Controls\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_explorer\n"
+ "from gdtest_tbl_explorer import sample_products\n"
+ "\n"
+ 'tbl_explorer(sample_products(), caption="Copy or download this table")\n'
+ "```\n"
+ "\n"
+ "## Copy Only (No Download)\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_products(),\n"
+ " downloadable=False,\n"
+ ' caption="Copy button only",\n'
+ ")\n"
+ "```\n"
+ "\n"
+ "## Download Only (No Copy)\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_products(),\n"
+ " copyable=False,\n"
+ ' caption="Download button only",\n'
+ ")\n"
+ "```\n"
+ "\n"
+ "## No Export Controls\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_products(),\n"
+ " copyable=False,\n"
+ " downloadable=False,\n"
+ ' caption="No export buttons",\n'
+ ")\n"
+ "```\n"
+ ),
+ "user_guide/05-missing-values.qmd": (
+ "---\n"
+ "title: Missing Values\n"
+ "---\n"
+ "\n"
+ "Missing values (`None`, `NaN`) are highlighted in red by default.\n"
+ "\n"
+ "## Default Highlighting\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_explorer\n"
+ "from gdtest_tbl_explorer import sample_missing\n"
+ "\n"
+ 'tbl_explorer(sample_missing(), caption="Missing values highlighted")\n'
+ "```\n"
+ "\n"
+ "## Highlighting Off\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_missing(),\n"
+ " highlight_missing=False,\n"
+ ' caption="Missing values NOT highlighted",\n'
+ ")\n"
+ "```\n"
+ ),
+ "user_guide/06-minimal-chrome.qmd": (
+ "---\n"
+ "title: Minimal Chrome\n"
+ "---\n"
+ "\n"
+ "Strip away table chrome for a clean, data-focused look.\n"
+ "\n"
+ "## No Row Numbers\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_explorer\n"
+ "from gdtest_tbl_explorer import sample_cities\n"
+ "\n"
+ "tbl_explorer(\n"
+ " sample_cities(),\n"
+ " show_row_numbers=False,\n"
+ ' caption="No row numbers",\n'
+ ")\n"
+ "```\n"
+ "\n"
+ "## No Dtype Labels\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_cities(),\n"
+ " show_dtypes=False,\n"
+ ' caption="No dtype labels",\n'
+ ")\n"
+ "```\n"
+ "\n"
+ "## No Header Banner\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_cities(),\n"
+ " show_dimensions=False,\n"
+ ' caption="No header banner",\n'
+ ")\n"
+ "```\n"
+ "\n"
+ "## Fully Minimal\n"
+ "\n"
+ "No row numbers, no dtypes, no dimensions — just the data and controls:\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_cities(),\n"
+ " show_row_numbers=False,\n"
+ " show_dtypes=False,\n"
+ " show_dimensions=False,\n"
+ ' caption="Fully minimal",\n'
+ ")\n"
+ "```\n"
+ "\n"
+ "## Filter Only (No Other Controls)\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "tbl_explorer(\n"
+ " sample_cities(),\n"
+ " sortable=False,\n"
+ " column_toggle=False,\n"
+ " copyable=False,\n"
+ " downloadable=False,\n"
+ ' caption="Filter only",\n'
+ ")\n"
+ "```\n"
+ ),
+ "user_guide/07-shortcode.qmd": (
+ "---\n"
+ "title: Shortcode Explorer\n"
+ "---\n"
+ "\n"
+ "The `{{< tbl-explorer >}}` shortcode embeds interactive tables\n"
+ "from data files — no Python code cells needed.\n"
+ "\n"
+ "## CSV File\n"
+ "\n"
+ '{{< tbl-explorer file="assets/cities.csv" >}}\n'
+ "\n"
+ "## With Caption\n"
+ "\n"
+ '{{< tbl-explorer file="assets/cities.csv" caption="World Cities (shortcode)" >}}\n'
+ "\n"
+ "## TSV File\n"
+ "\n"
+ '{{< tbl-explorer file="assets/products.tsv" caption="Products (TSV)" >}}\n'
+ "\n"
+ "## JSONL File\n"
+ "\n"
+ '{{< tbl-explorer file="assets/logs.jsonl" caption="Server Logs (JSONL)" >}}\n'
+ "\n"
+ "## Custom Options\n"
+ "\n"
+ '{{< tbl-explorer file="assets/cities.csv" page_size="5" '
+ 'caption="5 per page" >}}\n'
+ "\n"
+ "## No Filter\n"
+ "\n"
+ '{{< tbl-explorer file="assets/cities.csv" filterable="false" '
+ 'caption="No filter input" >}}\n'
+ ),
+ "user_guide/08-comparison.qmd": (
+ "---\n"
+ "title: Preview vs Explorer\n"
+ "---\n"
+ "\n"
+ "Compare the static `tbl_preview()` with the interactive\n"
+ "`tbl_explorer()` side by side.\n"
+ "\n"
+ "## Static Preview\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_preview\n"
+ "from gdtest_tbl_explorer import sample_cities\n"
+ "\n"
+ 'tbl_preview(sample_cities(), caption="Static preview")\n'
+ "```\n"
+ "\n"
+ "## Interactive Explorer\n"
+ "\n"
+ "```{python}\n"
+ "#| echo: false\n"
+ "from great_docs import tbl_explorer\n"
+ "\n"
+ 'tbl_explorer(sample_cities(), caption="Interactive explorer")\n'
+ "```\n"
+ "\n"
+ "The explorer adds a toolbar with filter, column toggle, copy,\n"
+ "download, and reset controls. Column headers are sortable.\n"
+ "The static preview is lighter and works without JavaScript.\n"
+ ),
+ },
+}
diff --git a/user_guide/30-table-previews.qmd b/user_guide/30-table-previews.qmd
index dc16ed9..ccb9109 100644
--- a/user_guide/30-table-previews.qmd
+++ b/user_guide/30-table-previews.qmd
@@ -13,73 +13,7 @@ Documentation sites for data-oriented packages often need to show what a dataset
Each preview includes a colored type badge (Polars, Pandas, CSV, Parquet, etc.), compact dtype labels beneath every column header, row-number gutters, head/tail splitting for large tables, and automatic highlighting of missing values. The output renders identically in light mode and dark mode, requires no JavaScript, and is safe to embed in RSS feeds, emails, or static HTML.
-This guide walks through every feature, starting from the simplest Python call and building up to the Quarto shortcode, file format support, and advanced display options.
-
-```{python}
-#| echo: false
-#| output: false
-# Setup: create sample data files used by examples below.
-import pathlib, json
-
-_d = pathlib.Path("assets/tbl-preview-data")
-_d.mkdir(parents=True, exist_ok=True)
-
-(_d / "students.csv").write_text(
- "name,subject,score,grade,passed\n"
- "Alice,Math,95.5,A,true\n"
- "Bob,Science,82.0,B,true\n"
- "Charlie,English,71.3,C,true\n"
- "Diana,History,60.0,D,true\n"
- "Eve,Art,55.8,F,false\n"
- "Frank,Math,88.2,B+,true\n"
- "Grace,Science,79.9,C+,true\n"
- "Hank,English,91.0,A-,true\n"
- "Iris,History,66.4,D+,true\n"
- "Jack,Art,73.7,C,true\n"
-)
-
-(_d / "products.tsv").write_text(
- "product\tcategory\tprice\tstock\trating\n"
- "Widget\tElectronics\t29.99\t150\t4.5\n"
- "Gadget\tTools\t49.50\t80\t3.8\n"
- "Gizmo\tKitchen\t12.00\t300\t4.9\n"
- "Doohickey\tGarden\t8.75\t0\t4.2\n"
- "Thingamajig\tOffice\t199.99\t25\t2.1\n"
- "Contraption\tElectronics\t65.00\t44\t3.5\n"
- "Apparatus\tTools\t120.00\t12\t4.7\n"
-)
-
-_logs = [
- {"timestamp": "2025-01-15T08:30:00", "level": "INFO", "module": "auth", "message": "User login successful"},
- {"timestamp": "2025-01-15T08:31:12", "level": "WARNING", "module": "db", "message": "Slow query detected (3.2s)"},
- {"timestamp": "2025-01-15T08:32:45", "level": "ERROR", "module": "api", "message": "Request timeout on /v2/users"},
- {"timestamp": "2025-01-15T08:33:01", "level": "INFO", "module": "cache", "message": "Cache miss for key user:42"},
- {"timestamp": "2025-01-15T08:34:20", "level": "DEBUG", "module": "auth", "message": "Token refresh for session abc123"},
- {"timestamp": "2025-01-15T08:35:55", "level": "ERROR", "module": "db", "message": "Connection pool exhausted"},
-]
-(_d / "server_logs.jsonl").write_text("\n".join(json.dumps(r) for r in _logs) + "\n")
-
-import polars as pl
-
-_products = pl.DataFrame({
- "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
- "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
- "price": [29.99, 49.50, 12.00, 8.75, 199.99],
- "in_stock": [True, False, True, True, False],
- "rating": [4.5, 3.8, 4.9, 4.2, 2.1],
-})
-_products.write_parquet(str(_d / "products.parquet"))
-
-_employees = pl.DataFrame({
- "name": ["Alice", "Bob", "Charlie", "Diana", "Eve", "Frank"],
- "department": ["Engineering", "Marketing", "Engineering", "Sales", "Marketing", "Sales"],
- "salary": [95000, 72000, 105000, 68000, 88000, 71000],
- "years": [5, 3, 8, 2, 6, 4],
-})
-_employees.write_ipc(str(_d / "employees.feather"))
-
-del _d, _logs, _products, _employees
-```
+This guide walks through every feature, starting from the simplest Python call and building up to the Quarto shortcode, file format support, and advanced display options. For interactive tables with sorting, filtering, and pagination, see the companion [Table Explorer](31-table-explorer.qmd) guide.
## Quick Start
@@ -176,7 +110,7 @@ Both Polars and Pandas DataFrames are detected automatically (no format flag is
Pass a file path (as a string or `pathlib.Path`) to any supported format and `tbl_preview()` reads it directly. CSV files get a warm yellow **CSV** badge:
```{python}
-tbl_preview("assets/tbl-preview-data/students.csv")
+tbl_preview("../assets/data/students.csv")
```
The file is read using Polars if available, falling back to Pandas. Column dtypes are inferred from the file contents.
@@ -186,7 +120,7 @@ The file is read using Polars if available, falling back to Pandas. Column dtype
Tab-separated files (`.tsv` or `.tab`) are auto-detected by extension. The badge shows **TSV** in green:
```{python}
-tbl_preview("assets/tbl-preview-data/products.tsv")
+tbl_preview("../assets/data/products.tsv")
```
TSV support uses the same reader as CSV with the delimiter set to tab, so all the same options (column subsets, head/tail, etc.) apply.
@@ -196,7 +130,7 @@ TSV support uses the same reader as CSV with the delimiter set to tab, so all th
Newline-delimited JSON files (`.jsonl` or `.ndjson`) are read line by line. Each line must be a valid JSON object. The badge shows **JSONL** in light blue:
```{python}
-tbl_preview("assets/tbl-preview-data/server_logs.jsonl", show_all=True)
+tbl_preview("../assets/data/server_logs.jsonl", show_all=True)
```
JSONL is a common format for log data and streaming pipelines, making `tbl_preview()` a convenient way to inspect log files in documentation.
@@ -206,7 +140,7 @@ JSONL is a common format for log data and streaming pipelines, making `tbl_previ
Apache Parquet files (`.parquet` or `.pq`) are read via Polars or PyArrow. The badge shows **Parquet** in purple:
```{python}
-tbl_preview("assets/tbl-preview-data/products.parquet", show_all=True)
+tbl_preview("../assets/data/products.parquet", show_all=True)
```
Parquet preserves the original column types from the file schema, so dtype labels are precise (e.g., `f64` rather than a generic `float`).
@@ -216,7 +150,7 @@ Parquet preserves the original column types from the file schema, so dtype label
Feather files (`.feather`) and Arrow IPC files (`.arrow`, `.ipc`) are both read as Arrow IPC format. Feather files get a **Feather** badge in orange, while `.arrow`/`.ipc` files get an **Arrow** badge in indigo:
```{python}
-tbl_preview("assets/tbl-preview-data/employees.feather", show_all=True)
+tbl_preview("../assets/data/employees.feather", show_all=True)
```
Arrow IPC is the recommended format for fast local reads when you need to preserve exact column types.
@@ -311,7 +245,7 @@ By default, all columns are shown. The `columns` parameter lets you pick a subse
```{python}
tbl_preview(
- "assets/tbl-preview-data/students.csv",
+ "../assets/data/students.csv",
columns=["name", "score", "grade"],
show_all=True,
)
diff --git a/user_guide/31-table-explorer.qmd b/user_guide/31-table-explorer.qmd
new file mode 100644
index 0000000..06a9f57
--- /dev/null
+++ b/user_guide/31-table-explorer.qmd
@@ -0,0 +1,291 @@
+---
+title: "Table Explorer"
+guide-section: "Site Content"
+tags: [Content, Extensions, Data]
+status: experimental
+upcoming: "0.10"
+versions: ">=0.9"
+---
+
+# Table Explorer
+
+The `tbl_explorer()` function generates an interactive table widget from tabular data. Where [`tbl_preview()`](30-table-previews.qmd) produces a static, JavaScript-free snapshot of a dataset, `tbl_explorer()` embeds all rows as inline JSON and progressively enhances a static fallback table with interactive controls: sorting, token-based filtering, pagination, column toggling, copy-to-clipboard, and CSV download.
+
+Like `tbl_preview()`, `tbl_explorer()` accepts any tabular data source—Polars/Pandas DataFrames, PyArrow Tables, CSV/TSV/JSONL/Parquet/Feather files, column-oriented dicts, or row-oriented lists of dicts. The output is a self-contained HTML block that works in Python code cells, Jupyter notebooks, and (via the `{{{< tbl-explorer >}}}` shortcode) directly in Quarto `.qmd` pages.
+
+::: {.callout-note}
+For datasets larger than 10,000 rows, `tbl_explorer()` emits a warning because all data is embedded as JSON, which increases page weight. For very large datasets, consider using `tbl_preview()` with `n_head`/`n_tail` splitting instead.
+:::
+
+```{python}
+#| echo: false
+#| output: false
+from great_docs import tbl_explorer
+```
+
+## Basic Usage
+
+Pass any supported data source to `tbl_explorer()` to get a fully interactive table:
+
+```{python}
+from great_docs import tbl_explorer
+
+tbl_explorer({
+ "city": ["Tokyo", "Paris", "New York", "London", "Sydney"],
+ "population": [13960000, 2161000, 8336000, 8982000, 5312000],
+ "country": ["Japan", "France", "USA", "UK", "Australia"],
+})
+```
+
+The result includes a toolbar with a filter bar, column toggle, copy, download, and reset buttons. Column headers are sortable, and pagination appears at the bottom when the dataset exceeds the page size.
+
+:::{.callout-tip}
+## Hiding the Code Cell
+
+Most of the time you'll want to show just the table itself, not the underlying generation code. Add `#| echo: false` at the top of the code cell to hide the source and display only the rendered explorer:
+
+````markdown
+```{{python}}
+#| echo: false
+tbl_explorer("data/students.csv")
+```
+````
+:::
+
+## Sorting
+
+Click any column header to cycle through three states: **ascending → descending → unsorted**. Sort indicators appear as SVG arrows next to column names.
+
+For multi-column sorting, hold **Shift** while clicking additional columns. Each column sorts within the groups established by prior sort columns. For example, shift-clicking *department* then *salary* will group by department and sort salaries within each department.
+
+```{python}
+#| echo: false
+#| output: false
+# This example is for reference; sorting is demonstrated interactively.
+```
+
+## Token-Based Filtering
+
+The filter system uses structured, token-based filters. Each filter is a discrete token displayed as a blue pill in the filter bar, and all active tokens are ANDed together.
+
+### Adding a Filter
+
+1. Click the **+** button in the filter bar
+2. Select a **column** from the dropdown—each column shows its dtype badge
+3. Choose an **operator**—the available operators depend on the column's data type:
+
+| Column type | Operators |
+|-------------|-----------|
+| String | contains, doesn't contain, starts with, ends with, equals, is empty, is not empty |
+| Numeric | =, ≠, <, ≤, >, ≥, between |
+| Boolean | is true, is false |
+| All types | is null, is not null |
+
+4. For operators that require a value, type it in the input field and press **Enter** or click **Apply**
+
+The *between* operator for numeric columns presents two input fields for the lower and upper bounds of the range.
+
+### Understanding Filter Tokens
+
+Each token shows the column name, operator, and value. Text values appear in single quotes (e.g., `city contains 'york'`). Numeric values are shown unquoted (e.g., `salary > 80000`). Click the **×** on any token to remove that individual filter.
+
+### Case Sensitivity
+
+Text filters are **case-insensitive** by default. When entering a filter value for a text column, an **Aa** toggle button appears next to the input field. Click it to enable case-sensitive matching for that specific filter. Case-sensitive tokens display a small bordered **Aa** badge on the pill.
+
+### Combining Filters
+
+Multiple filters are ANDed together—a row must match *all* active filters to be displayed. You can add multiple filters on the same column (e.g., `salary > 70000` AND `salary < 100000`) or across different columns (e.g., `department contains 'Eng'` AND `rating > 4.0`).
+
+### Search Highlighting
+
+When a "contains" filter is active, matching text in cells is highlighted with a colored background. This makes it easy to spot why each row matched the filter. Disable this with `search_highlight=False`.
+
+## Pagination
+
+Tables are paginated at **20 rows per page** by default. The pagination bar shows:
+
+- The current range (e.g., "Showing 1–20 of 150 rows")
+- **First**, **Previous**, **Next**, and **Last** navigation buttons
+- Page number buttons with ellipsis for large page counts
+
+The row count updates to reflect any active filters (e.g., "Showing 1–5 of 5 rows (filtered from 24)").
+
+To disable pagination and show all rows at once, set `page_size=0`:
+
+```{python}
+tbl_explorer(
+ "../assets/data/students.csv",
+ page_size=0,
+)
+```
+
+Or set a custom page size:
+
+```{python}
+tbl_explorer(
+ "../assets/data/employees.csv",
+ page_size=10,
+)
+```
+
+## Column Toggle
+
+Click the **Columns** button in the toolbar to open a dropdown with checkboxes for each column. Uncheck columns to hide them from the table; check them again to restore them. At least one column must remain visible—the last visible column's checkbox is disabled.
+
+This is useful for wide datasets where you want to focus on specific columns without modifying the underlying data.
+
+## Copy and Download
+
+The toolbar includes two data-export buttons:
+
+- **Copy** (clipboard icon) — copies the currently visible page of data as tab-separated values to the clipboard. On success, the icon briefly turns into a green checkmark. The copied data includes column headers and respects the current sort and filter state.
+- **Download** (download icon) — downloads the full filtered dataset (all pages, not just the current page) as a CSV file. The filename is based on the table's `id` attribute.
+
+## Reset
+
+The **Reset** button (↺ icon) restores the table to its initial state in one click, clearing all:
+
+- Sort states
+- Filter tokens
+- Column visibility changes
+- Pagination (returns to page 1)
+
+## From a File
+
+Like `tbl_preview()`, you can pass a file path directly. The file extension determines the loader:
+
+```{python}
+tbl_explorer("../assets/data/students.csv", page_size=5)
+```
+
+Supported file formats: `.csv`, `.tsv`, `.jsonl` (or `.ndjson`), `.parquet`, `.feather`, `.arrow`.
+
+:::{.callout-tip}
+## Where to Put Data Files
+
+We recommend placing data files in an `assets/data/` directory at the root of your project. This keeps them version-controlled, easy to reference from any `.qmd` page, and separate from images and other static assets:
+
+```
+my-package/
+├── assets/
+│ └── data/
+│ ├── students.csv
+│ └── products.tsv
+├── reference/
+└── user-guide/
+```
+
+Both `tbl_explorer()` and `tbl_preview()` resolve file paths relative to the working directory, which is typically the project root during a Quarto build.
+:::
+
+## From a DataFrame
+
+Pass a Polars or Pandas DataFrame directly:
+
+```{python}
+import polars as pl
+
+df = pl.DataFrame({
+ "product": ["Widget", "Gadget", "Gizmo", "Doohickey", "Thingamajig"],
+ "category": ["Electronics", "Tools", "Kitchen", "Garden", "Office"],
+ "price": [29.99, 49.50, 12.00, 8.75, 199.99],
+ "in_stock": [True, False, True, True, False],
+ "rating": [4.5, 3.8, 4.9, 4.2, 2.1],
+})
+
+tbl_explorer(df)
+```
+
+## Column Subset
+
+Use the `columns=` parameter to show only specific columns:
+
+```{python}
+tbl_explorer(
+ "../assets/data/employees.csv",
+ columns=["name", "department", "salary"],
+)
+```
+
+## Quarto Shortcode
+
+The `{{{< tbl-explorer >}}}` shortcode brings the interactive explorer to `.qmd` pages without writing any Python. The `file=` parameter specifies the data file path relative to the `.qmd` file:
+
+```{markdown}
+{{< tbl-explorer file="data/example.csv" >}}
+```
+
+All parameters can be set as shortcode attributes:
+
+```{markdown}
+{{{< tbl-explorer file="data.csv" page_size="25" sortable="true" >}}}
+{{{< tbl-explorer file="data.csv" column_toggle="false" downloadable="false" >}}}
+{{{< tbl-explorer file="data.csv" columns="name,department,salary" >}}}
+```
+
+Boolean parameters accept `"true"` or `"false"` as strings. The `columns=` parameter accepts a comma-separated list of column names.
+
+## Minimal Chrome
+
+You can selectively disable interactive features for a cleaner, read-only presentation. For example, to show a sortable-only table with no toolbar controls:
+
+```{python}
+tbl_explorer(
+ "../assets/data/products.tsv",
+ sortable=True,
+ filterable=False,
+ column_toggle=False,
+ copyable=False,
+ downloadable=False,
+ page_size=0,
+)
+```
+
+## Progressive Enhancement
+
+The `tbl_explorer()` output is designed with **progressive enhancement** in mind. The initial HTML contains a fully rendered static table (the first page of data) that is readable without JavaScript. When JavaScript is available, the static table is enhanced with interactive controls.
+
+This means:
+
+- **RSS feeds and email** — readers see a usable static table
+- **Search engines** — table content is indexable
+- **Accessibility** — the base table works with screen readers
+- **No-JS environments** — content is still visible
+
+## Choosing Between `tbl_preview()` and `tbl_explorer()`
+
+| | `tbl_preview()` | `tbl_explorer()` |
+|---|---|---|
+| **Interactivity** | None (static HTML) | Sorting, filtering, pagination, column toggle |
+| **JavaScript** | Not required | Required for interactivity; static fallback without it |
+| **Data embedding** | Head/tail rows only | All rows as inline JSON |
+| **Best for** | Quick dataset snapshots, lightweight pages | Exploratory data docs, dashboards, reference tables |
+| **Large datasets** | Efficient (shows only head + tail) | All data embedded (watch page weight) |
+| **Dark mode** | Full support | Full support |
+
+## Parameters Reference
+
+| Parameter | Type | Default | Description |
+|-----------|------|---------|-------------|
+| `data` | various | — | Data source: DataFrame, file path, dict, or list of dicts |
+| `columns` | `list[str]` | `None` | Column subset to display (all if `None`) |
+| `show_row_numbers` | `bool` | `True` | Show row-number gutter column |
+| `show_dtypes` | `bool` | `True` | Show dtype labels under column names |
+| `show_dimensions` | `bool` | `True` | Show header banner with type badge and counts |
+| `max_col_width` | `int` | `250` | Maximum column width in pixels |
+| `min_tbl_width` | `int` | `500` | Minimum total table width in pixels |
+| `caption` | `str` | `None` | Caption text above column headers |
+| `highlight_missing` | `bool` | `True` | Highlight `None`/`NaN`/`NA` in red |
+| `page_size` | `int` | `20` | Rows per page (`0` to disable pagination) |
+| `sortable` | `bool` | `True` | Enable click-to-sort on column headers |
+| `filterable` | `bool` | `True` | Enable the token-based filter bar |
+| `column_toggle` | `bool` | `True` | Enable column visibility dropdown |
+| `copyable` | `bool` | `True` | Enable copy-to-clipboard button |
+| `downloadable` | `bool` | `True` | Enable CSV download button |
+| `resizable` | `bool` | `False` | Enable column drag-resize (reserved for future use) |
+| `sticky_header` | `bool` | `True` | Make column headers sticky on vertical scroll |
+| `search_highlight` | `bool` | `True` | Highlight matching text for "contains" filters |
+| `id` | `str` | auto | Custom HTML `id` for the container |
+
+The return value is a `TblExplorer` object with `_repr_html_()` (for notebook display), `as_html()` (returns the HTML string), and `save(path)` (writes HTML to a file) methods.