----------------------------------------------------------------------
This is the API documentation for the gdtest_tbl_explorer library.
----------------------------------------------------------------------


## Functions

Public functions


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

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

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

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

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


----------------------------------------------------------------------
This is the User Guide documentation for the package.
----------------------------------------------------------------------

### Basic Explorer

The `tbl_explorer()` function creates interactive tables with
sorting, filtering, pagination, and more.

## Default Options

Pass a dictionary and get a fully interactive table:

```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_cities

tbl_explorer(sample_cities())
```

Try clicking column headers to sort, or type in the filter box.

## With Caption

```{python}
#| echo: false
tbl_explorer(sample_cities(), caption="World Cities")
```

## Product Catalog

```{python}
#| echo: false
from gdtest_tbl_explorer import sample_products

tbl_explorer(sample_products(), caption="Product Catalog")
```


### Pagination

With larger datasets, `tbl_explorer()` paginates automatically.

## Default Page Size (20 rows)

```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_large

tbl_explorer(sample_large(200), caption="200 Employees")
```

## Custom Page Size (10 rows)

```{python}
#| echo: false
tbl_explorer(sample_large(200), page_size=10, caption="10 per page")
```

## Large Page Size (50 rows)

```{python}
#| echo: false
tbl_explorer(sample_large(200), page_size=50, caption="50 per page")
```

## No Pagination

Set `page_size=0` to show all rows at once:

```{python}
#| echo: false
tbl_explorer(sample_large(30), page_size=0, caption="All 30 rows")
```


### Column Toggling

Use the **Columns** dropdown in the toolbar to show/hide columns.

## Wide Table

This table has 16 columns — try hiding some:

```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_wide

tbl_explorer(sample_wide(10, 15), caption="Wide Metrics Table")
```

## Column Subset

Pre-select specific columns with `columns=`:

```{python}
#| echo: false
from gdtest_tbl_explorer import sample_cities

tbl_explorer(
    sample_cities(),
    columns=["city", "country", "population"],
    caption="Cities — 3 columns only",
)
```

## Toggle Disabled

Set `column_toggle=False` to remove the dropdown:

```{python}
#| echo: false
tbl_explorer(
    sample_cities(),
    column_toggle=False,
    caption="No column toggle",
)
```


### Copy & Download

The toolbar includes **Copy** (TSV to clipboard) and **Download**
(CSV file) buttons.

## Full Controls

```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_products

tbl_explorer(sample_products(), caption="Copy or download this table")
```

## Copy Only (No Download)

```{python}
#| echo: false
tbl_explorer(
    sample_products(),
    downloadable=False,
    caption="Copy button only",
)
```

## Download Only (No Copy)

```{python}
#| echo: false
tbl_explorer(
    sample_products(),
    copyable=False,
    caption="Download button only",
)
```

## No Export Controls

```{python}
#| echo: false
tbl_explorer(
    sample_products(),
    copyable=False,
    downloadable=False,
    caption="No export buttons",
)
```


### Missing Values

Missing values (`None`, `NaN`) are highlighted in red by default.

## Default Highlighting

```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_missing

tbl_explorer(sample_missing(), caption="Missing values highlighted")
```

## Highlighting Off

```{python}
#| echo: false
tbl_explorer(
    sample_missing(),
    highlight_missing=False,
    caption="Missing values NOT highlighted",
)
```


### Minimal Chrome

Strip away table chrome for a clean, data-focused look.

## No Row Numbers

```{python}
#| echo: false
from great_docs import tbl_explorer
from gdtest_tbl_explorer import sample_cities

tbl_explorer(
    sample_cities(),
    show_row_numbers=False,
    caption="No row numbers",
)
```

## No Dtype Labels

```{python}
#| echo: false
tbl_explorer(
    sample_cities(),
    show_dtypes=False,
    caption="No dtype labels",
)
```

## No Header Banner

```{python}
#| echo: false
tbl_explorer(
    sample_cities(),
    show_dimensions=False,
    caption="No header banner",
)
```

## Fully Minimal

No row numbers, no dtypes, no dimensions — just the data and controls:

```{python}
#| echo: false
tbl_explorer(
    sample_cities(),
    show_row_numbers=False,
    show_dtypes=False,
    show_dimensions=False,
    caption="Fully minimal",
)
```

## Filter Only (No Other Controls)

```{python}
#| echo: false
tbl_explorer(
    sample_cities(),
    sortable=False,
    column_toggle=False,
    copyable=False,
    downloadable=False,
    caption="Filter only",
)
```


### Shortcode Explorer

The `{{< tbl-explorer >}}` shortcode embeds interactive tables
from data files — no Python code cells needed.

## CSV File

{{< tbl-explorer file="assets/cities.csv" >}}

## With Caption

{{< tbl-explorer file="assets/cities.csv" caption="World Cities (shortcode)" >}}

## TSV File

{{< tbl-explorer file="assets/products.tsv" caption="Products (TSV)" >}}

## JSONL File

{{< tbl-explorer file="assets/logs.jsonl" caption="Server Logs (JSONL)" >}}

## Custom Options

{{< tbl-explorer file="assets/cities.csv" page_size="5" caption="5 per page" >}}

## No Filter

{{< tbl-explorer file="assets/cities.csv" filterable="false" caption="No filter input" >}}


### Preview vs Explorer

Compare the static `tbl_preview()` with the interactive
`tbl_explorer()` side by side.

## Static Preview

```{python}
#| echo: false
from great_docs import tbl_preview
from gdtest_tbl_explorer import sample_cities

tbl_preview(sample_cities(), caption="Static preview")
```

## Interactive Explorer

```{python}
#| echo: false
from great_docs import tbl_explorer

tbl_explorer(sample_cities(), caption="Interactive explorer")
```

The explorer adds a toolbar with filter, column toggle, copy,
download, and reset controls. Column headers are sortable.
The static preview is lighter and works without JavaScript.