tabler-react-2 0.1.153 → 0.1.154

package/docs/src/docs/changelog.mdx

@@ -2,6 +2,10 @@
 title: Changelog
 ---
 
+# 0.1.153
+
+- Support className and arbitrary props on the `Checkbox` component.
+
 # 0.1.152
 
 - Fix rendering of `invalid` prop on `Input` components with `prependedText` or `appendedText`.

package/docs/src/docs/components/table-v2.mdx

@@ -0,0 +1,367 @@
+---
+title: Tables v2
+---
+
+import { Excerpt } from "../../components/Excerpt.jsx";
+import { TableV2 } from "../../components/LoadableTabler.jsx";
+import congressPeople from "../../data/congressPeople.json";
+
+Tables v2 is a new data table built on TanStack Table v8 with Tabler styling. It is fully controlled: you pass the current page of `data`, the total row count, and the active `sorting`. This design fits server-side pagination and ordering out of the box.
+
+> Note: live previews on this page may require a package version that exports `TableV2`. If you don’t see live examples, the code snippets still illustrate usage.
+
+## Signature
+
+```jsx
+import { TableV2 } from "tabler-react-2";
+
+<TableV2 {...props} />;
+```
+
+### Core props
+
+| Prop                   | Required | Type                                                                 | Description                                                                      |
+| ---------------------- | -------- | -------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| `columns`              | Yes      | TanStack `ColumnDef[]`                                               | Column definitions using `accessorKey`, `header`, and optional `cell` renderers. |
+| `data`                 | Yes      | `any[]`                                                              | Current page rows only.                                                          |
+| `totalRows`            | Yes      | `number`                                                             | Total available row count (for page count and range text).                       |
+| `page`                 | Yes      | `number`                                                             | Current page (1-based).                                                          |
+| `size`                 | Yes      | `number`                                                             | Current page size.                                                               |
+| `onPageChange`         | Yes      | `(page:number) => void`                                              | Called with next 1-based page.                                                   |
+| `onSizeChange`         | Yes      | `(size:number) => void`                                              | Called with next page size. Typically also reset page to 1.                      |
+| `sorting`              | Yes      | `{ id:string, desc?:boolean }[]`                                     | Active ordering (TanStack format). Empty array for “no sort”.                    |
+| `onSortingChange`      | Yes      | `(next) => void`                                                     | Called when the user clicks a sortable header.                                   |
+| `loading`              | No       | `boolean`                                                            | Shows a small spinner and disables pager while loading.                          |
+| `headerSticky`         | No       | `boolean`                                                            | Makes the header stick to the top of the card.                                   |
+| `emptyState`           | No       | `string                                          \| () => ReactNode` | What to render when there are no rows.                                           |
+| `getRowId`             | No       | `(row) => string`                                                    | Supply when your rows need a stable custom ID.                                   |
+| `rowSelection`         | No       | `Record<string, boolean>`                                            | Controlled selection map.                                                        |
+| `onRowSelectionChange` | No       | `(updater) => void`                                                  | Controlled selection callback.                                                   |
+| `renderToolbarLeft`    | No       | `({ page,size,totalRows,sorting }) => ReactNode`                     | Custom left content in the card header.                                          |
+| `renderToolbarRight`   | No       | same                                                                 | Custom right content in the card header.                                         |
+
+## Basic usage (client or server data)
+
+The table is controlled; keep `page`, `size`, and `sorting` in your component state. The example below uses in-memory data, but the same shape works with server APIs.
+
+```jsx
+import { useMemo, useState } from "react";
+import { TableV2 } from "tabler-react-2";
+
+const allRows = congressPeople; // e.g., from your API
+
+export default function Demo() {
+  const [page, setPage] = useState(1);
+  const [size, setSize] = useState(5);
+  const [sorting, setSorting] = useState([]); // [{ id:'name', desc:false }]
+
+  const columns = useMemo(
+    () => [
+      { accessorKey: "name", header: "Name" },
+      { accessorKey: "party", header: "Party" },
+      { accessorKey: "region.state", header: "State" },
+      {
+        accessorKey: "email",
+        header: "Email",
+        cell: ({ getValue }) => (
+          <a className="text-reset" href={`mailto:${getValue()}`}>
+            {getValue()}
+          </a>
+        ),
+      },
+    ],
+    []
+  );
+
+  // client-side slice just for the demo
+  const ordered = useMemo(() => {
+    if (!sorting.length) return allRows;
+    const { id, desc } = sorting[0];
+    const val = (row) => id.split(".").reduce((a, k) => a?.[k], row);
+    const cmp = (a, b) => (a === b ? 0 : a > b ? 1 : -1);
+    const sorted = [...allRows].sort((a, b) => cmp(val(a), val(b)));
+    return desc ? sorted.reverse() : sorted;
+  }, [sorting]);
+
+  const start = (page - 1) * size;
+  const pageData = ordered.slice(start, start + size);
+
+  return (
+    <TableV2
+      columns={columns}
+      data={pageData}
+      totalRows={allRows.length}
+      page={page}
+      size={size}
+      onPageChange={setPage}
+      onSizeChange={(n) => {
+        setPage(1);
+        setSize(n);
+      }}
+      sorting={sorting}
+      onSortingChange={(next) => {
+        setPage(1);
+        setSorting(next);
+      }}
+    />
+  );
+}
+```
+
+<Excerpt>
+{(() => {
+  const React = require("react");
+  const { useMemo, useState } = React;
+
+  // Local, fully functional demo state (client-side slice)
+  const allRows = congressPeople;
+  const [page, setPage] = useState(1);
+  const [size, setSize] = useState(10);
+  const [sorting, setSorting] = useState([]); // [{ id:'name', desc:false }]
+
+  const ordered = useMemo(() => {
+    if (!sorting.length) return allRows;
+    const { id, desc } = sorting[0];
+    const val = (row) => id.split(".").reduce((a, k) => a?.[k], row);
+    const cmp = (a, b) => (a === b ? 0 : a > b ? 1 : -1);
+    const sorted = [...allRows].sort((a, b) => cmp(val(a), val(b)));
+    return desc ? sorted.reverse() : sorted;
+  }, [sorting]);
+
+  const start = (page - 1) * size;
+  const pageData = ordered.slice(start, start + size);
+
+  return (
+    <TableV2
+      columns={[
+        { accessorKey: "name", header: "Name" },
+        { accessorKey: "party", header: "Party" },
+        { accessorKey: "region.state", header: "State" },
+        {
+          accessorKey: "email",
+          header: "Email",
+          cell: ({ getValue }) => (
+            <a className="text-reset" href={`mailto:${getValue()}`}>
+              {getValue()}
+            </a>
+          ),
+        },
+      ]}
+      data={pageData}
+      totalRows={allRows.length}
+      page={page}
+      size={size}
+      onPageChange={setPage}
+      onSizeChange={(n) => {
+        setPage(1);
+        setSize(n);
+      }}
+      sorting={sorting}
+      onSortingChange={(next) => {
+        setPage(1);
+        setSorting(next);
+      }}
+      loading={false}
+    />
+  );
+})()}
+
+</Excerpt>
+
+## Server-side workflow
+
+When fetching from an API, keep the same controlled state, but fetch rows for the current `page`, `size`, and `sorting`.
+
+```jsx
+const [page, setPage] = useState(1);
+const [size, setSize] = useState(25);
+const [sorting, setSorting] = useState([]);
+const [rows, setRows] = useState([]);
+const [total, setTotal] = useState(0);
+const [loading, setLoading] = useState(false);
+
+useEffect(() => {
+  let isMounted = true;
+  (async () => {
+    setLoading(true);
+    try {
+      const res = await fetchPeople({ page, size, sorting });
+      if (!isMounted) return;
+      setRows(res.items);
+      setTotal(res.total);
+    } finally {
+      setLoading(false);
+    }
+  })();
+  return () => {
+    isMounted = false;
+  };
+}, [page, size, sorting]);
+
+<TableV2
+  columns={columns}
+  data={rows}
+  totalRows={total}
+  page={page}
+  size={size}
+  onPageChange={setPage}
+  onSizeChange={(n) => {
+    setPage(1);
+    setSize(n);
+  }}
+  sorting={sorting}
+  onSortingChange={(next) => {
+    setPage(1);
+    setSorting(next);
+  }}
+  loading={loading}
+/>;
+```
+
+### Live async demo (simulated API)
+
+The preview below simulates a server by sorting and slicing in a faux `fetch` with a 1s delay.
+
+<Excerpt>
+{(() => {
+  const React = require("react");
+  const { useEffect, useMemo, useState } = React;
+
+  // Simulated API that delays 1s and then returns sorted, paged rows
+  const fetchPeople = ({ page, size, sorting }) =>
+    new Promise((resolve) => {
+      setTimeout(() => {
+        const all = congressPeople;
+        const total = all.length;
+
+        // server-side order
+        let ordered = all;
+        if (sorting?.length) {
+          const { id, desc } = sorting[0];
+          const val = (row) => id.split(".").reduce((a, k) => a?.[k], row);
+          const cmp = (a, b) => (a === b ? 0 : a > b ? 1 : -1);
+          const sorted = [...all].sort((a, b) => cmp(val(a), val(b)));
+          ordered = desc ? sorted.reverse() : sorted;
+        }
+
+        // server-side page
+        const start = (page - 1) * size;
+        const items = ordered.slice(start, start + size);
+        resolve({ items, total });
+      }, 1000);
+    });
+
+  const columns = useMemo(
+    () => [
+      { accessorKey: "name", header: "Name" },
+      { accessorKey: "party", header: "Party" },
+      { accessorKey: "region.state", header: "State" },
+      {
+        accessorKey: "email",
+        header: "Email",
+        cell: ({ getValue }) => (
+          <a className="text-reset" href={`mailto:${getValue()}`}>
+            {getValue()}
+          </a>
+        ),
+      },
+    ],
+    []
+  );
+
+  const [page, setPage] = useState(1);
+  const [size, setSize] = useState(10);
+  const [sorting, setSorting] = useState([]);
+  const [rows, setRows] = useState([]);
+  const [total, setTotal] = useState(0);
+  const [loading, setLoading] = useState(false);
+
+  useEffect(() => {
+    let isMounted = true;
+    setLoading(true);
+    fetchPeople({ page, size, sorting }).then((res) => {
+      if (!isMounted) return;
+      setRows(res.items);
+      setTotal(res.total);
+      setLoading(false);
+    });
+    return () => {
+      isMounted = false;
+    };
+  }, [page, size, sorting]);
+
+  return (
+    <TableV2
+      columns={columns}
+      data={rows}
+      totalRows={total}
+      page={page}
+      size={size}
+      onPageChange={setPage}
+      onSizeChange={(n) => {
+        setPage(1);
+        setSize(n);
+      }}
+      sorting={sorting}
+      onSortingChange={(next) => {
+        setPage(1);
+        setSorting(next);
+      }}
+      loading={loading}
+    />
+  );
+})()}
+
+</Excerpt>
+
+## Extras
+
+- Sticky header: pass `headerSticky` to keep headers visible while scrolling.
+- Toolbars: use `renderToolbarLeft`/`renderToolbarRight` to add filters or actions.
+- Row selection: control with `rowSelection` and `onRowSelectionChange`.
+
+### Sticky header example
+
+```jsx
+<TableV2 {...commonProps} headerSticky />
+```
+
+### Toolbar example
+
+```jsx
+<TableV2
+  {...commonProps}
+  renderToolbarLeft={() => (
+    <input className="form-control form-control-sm" placeholder="Search" />
+  )}
+  renderToolbarRight={() => (
+    <button className="btn btn-sm btn-primary">Add</button>
+  )}
+/>
+```
+
+### Row selection (minimal)
+
+```jsx
+const [rowSelection, setRowSelection] = useState({});
+
+<TableV2
+  {...commonProps}
+  rowSelection={rowSelection}
+  onRowSelectionChange={setRowSelection}
+  columns={[
+    {
+      id: "select",
+      header: () => null,
+      cell: ({ row }) => (
+        <input
+          type="checkbox"
+          checked={row.getIsSelected()}
+          onChange={row.getToggleSelectedHandler()}
+        />
+      ),
+    },
+    ...columns,
+  ]}
+/>;
+```

package/docs/src/docs/components/tables.mdx

@@ -454,3 +454,231 @@ const customSortFn = (a, b) => {
 ```
 
 > **Note**: Sorting only works for the data in the table. If, for example, you have thousands of rows and are only rendering a few, you will need to handle the sorting yourself, outside of the table. Incorporating internal pagination that supports sorting is a planned feature but not yet implemented.
+
+### External ordering
+
+You can control ordering from the parent (e.g., server-side sort) and still use the table’s sortable headers. Provide the props below. When controlled, the table will not sort your `data`; it assumes you already passed rows in the desired order.
+
+- orderBy: accessor of the active column
+- order: either `"asc"` or `"desc"`
+- onSetOrder: called with `(orderBy, order)` when the user clicks a header
+
+<Excerpt>
+  {(() => {
+    const React = require("react");
+    const [page, setPage] = React.useState(1);
+    const [size, setSize] = React.useState(5);
+    const [orderBy, setOrderBy] = React.useState("name");
+    const [order, setOrder] = React.useState("asc");
+    const total = congressPeople.length;
+
+    const sorted = [...congressPeople].sort((a, b) => {
+      const av = orderBy.split('.').reduce((acc, k) => acc?.[k], a);
+      const bv = orderBy.split('.').reduce((acc, k) => acc?.[k], b);
+      if (av === bv) return 0;
+      const cmp = av > bv ? 1 : -1;
+      return order === 'asc' ? cmp : -cmp;
+    });
+    const start = (page - 1) * size;
+    const pageData = sorted.slice(start, start + size);
+
+    return (
+      <Table
+        columns={[
+          { label: "Name", accessor: "name", sortable: true },
+          { label: "Party", accessor: "party", sortable: true },
+          { label: "State", accessor: "region.state", sortable: true },
+        ]}
+        data={pageData}
+        showPagination
+        page={page}
+        size={size}
+        totalRows={total}
+        orderBy={orderBy}
+        order={order}
+        onSetOrder={(by, dir) => { setOrderBy(by); setOrder(dir); }}
+        onSetPage={setPage}
+        onSetSize={(n) => { setPage(1); setSize(n); }}
+      />
+    );
+  })()}
+</Excerpt>
+
+```jsx
+// Parent controls ordering and pagination
+const [orderBy, setOrderBy] = useState('name');
+const [order, setOrder] = useState('asc');
+const [page, setPage] = useState(1);
+const [size, setSize] = useState(10);
+
+const ordered = [...allRows].sort((a, b) => {
+  const av = orderBy.split('.').reduce((acc, k) => acc?.[k], a);
+  const bv = orderBy.split('.').reduce((acc, k) => acc?.[k], b);
+  if (av === bv) return 0;
+  const cmp = av > bv ? 1 : -1;
+  return order === 'asc' ? cmp : -cmp;
+});
+
+const start = (page - 1) * size;
+const currentData = ordered.slice(start, start + size);
+
+<Table
+  columns={columns}
+  data={currentData}
+  showPagination
+  page={page}
+  size={size}
+  totalRows={allRows.length}
+  orderBy={orderBy}
+  order={order}
+  onSetOrder={(by, dir) => { setOrderBy(by); setOrder(dir); }}
+  onSetPage={setPage}
+  onSetSize={(n) => { setPage(1); setSize(n); }}
+/>;
+```
+
+## Pagination
+
+The `Table` supports built-in pagination UI. Enable it with `showPagination`.
+
+- showPagination: toggles the pagination controls
+- defaultRowsPerPage: initial rows per page for internal mode
+- pageSizeOptions: selectable page sizes (default `[10, 25, 50, 100]`)
+
+<Excerpt>
+  <Table
+    columns={[
+      { label: "Name", accessor: "name" },
+      { label: "Party", accessor: "party" },
+      { label: "State", accessor: "region.state" },
+    ]}
+    data={congressPeople}
+    showPagination
+    defaultRowsPerPage={10}
+  />
+</Excerpt>
+
+```jsx
+<Table
+  columns={columns}
+  data={rows}
+  showPagination
+  defaultRowsPerPage={10}
+  pageSizeOptions={[10, 25, 50, 100]}
+/>
+```
+
+### External pagination
+
+You can also fully control pagination from the parent (e.g., server-side paging) while keeping the same UI. Provide the controlled props and callbacks below. When any controlled pagination prop is provided, the table does not slice your `data` and instead assumes `data` already contains the current page.
+
+- page: current page (1-based)
+- size: current page size
+- totalRows: total available row count used for page count and the “Showing … of …” text
+- onSetPage: called with next page (1-based)
+- onSetSize: called with next page size
+
+Aliases are supported for compatibility: `rowsPerPage`, `onPageChange`, `onRowsPerPageChange`.
+
+<Excerpt>
+  {(() => {
+    // Simulated external pagination
+    const React = require("react");
+    const [page, setPage] = React.useState(1);
+    const [rpp, setRpp] = React.useState(4);
+    const total = congressPeople.length;
+    const start = (page - 1) * rpp;
+    const pageData = congressPeople.slice(start, start + rpp);
+    return (
+      <Table
+        columns={[
+          { label: "Name", accessor: "name" },
+          { label: "Party", accessor: "party" },
+          { label: "State", accessor: "region.state" },
+        ]}
+        data={pageData}
+        showPagination
+        page={page}
+        size={rpp}
+        totalRows={total}
+        onSetPage={setPage}
+        onSetSize={(n) => {
+          setPage(1);
+          setRpp(n);
+        }}
+      />
+    );
+  })()}
+</Excerpt>
+
+```jsx
+// Parent controls the table
+const [page, setPage] = useState(1);
+const [rowsPerPage, setRowsPerPage] = useState(10);
+const totalRows = allRows.length; // from your API
+
+// Only pass the current slice to the table
+const start = (page - 1) * rowsPerPage;
+const currentData = allRows.slice(start, start + rowsPerPage);
+
+<Table
+  columns={columns}
+  data={currentData}
+  showPagination
+  page={page}
+  size={rowsPerPage}
+  totalRows={totalRows}
+  onSetPage={setPage}
+  onSetSize={(n) => { setPage(1); setRowsPerPage(n); }}
+/>;
+```
+
+If you don’t supply these controlled props, the table falls back to its internal pagination state, preserving backwards compatibility.
+
+## useTable hook
+
+For async workflows, use the helper hook to centralize loading, pagination, count, and ordering while preserving the Table’s controlled API.
+
+```jsx
+import { useEffect, useState } from 'react';
+import { Table, useTable } from 'tabler-react-2';
+
+function PeopleTable() {
+  const [rows, setRows] = useState([]);
+  const { tableProps, setLoading, setPage, setCount, setOrder } = useTable({
+    autoLoading: false,
+    onPageChange: async (page, size, sort) => {
+      setLoading(true);
+      try {
+        // fetch your data here using page, size, and sort
+        const res = await fetchPeople({ page, size, sort });
+        setRows(res.items);
+        setCount(res.total);
+      } finally {
+        setLoading(false);
+      }
+    },
+    onSortChange: async (by, dir) => {
+      // optionally kick off a fetch based on new sort
+      // setOrder(by, dir) is already called for you
+    },
+  });
+
+  useEffect(() => {
+    // initial load
+    setPage(1);
+  }, [setPage]);
+
+  return <Table {...tableProps} columns={[
+      { label: 'Name', accessor: 'name', sortable: true },
+      { label: 'Party', accessor: 'party', sortable: true },
+      { label: 'State', accessor: 'region.state', sortable: true },
+    ]} data={rows} />;
+}
+```
+
+The hook returns:
+
+- tableProps: spread onto `<Table />` to enable controlled pagination, ordering, and loading
+- setLoading, setPage, setCount: imperative helpers for async flows
+- Also available: page, size, count, orderBy, order, setSize, setOrder

package/package.json

@@ -1,12 +1,14 @@
 {
   "name": "tabler-react-2",
-  "version": "0.1.153",
+  "version": "0.1.154",
   "description": "A react implementation of Tabler ui",
   "main": "dist/index.js",
   "scripts": {
     "test": "cd demo && yarn start",
     "build:css": "postcss src/**/*.css --dir dist",
-    "build": "babel src --out-dir dist && npm run build:css"
+    "build": "babel src --out-dir dist && npm run build:css",
+    "docs:vanilla": "yarn --cwd docs start",
+    "docs": "cpulimit -l 20 -- yarn --cwd docs start"
   },
   "author": "Jack Crane",
   "license": "MIT",
@@ -15,6 +17,8 @@
     "@babel/core": "^7.24.8",
     "@babel/preset-env": "^7.24.8",
     "@babel/preset-react": "^7.24.7",
+    "@emotion/react": "^11.14.0",
+    "@tanstack/react-table": "^8.21.3",
     "classnames": "^2.5.1",
     "prop-types": "^15.8.1",
     "react": "^18.3.1",