ng-hub-ui-paginable 22.1.3 → 22.4.0

package/README.md

@@ -119,6 +119,31 @@ import { TableComponent } from 'ng-hub-ui-paginable';
 
 ---
 
+## Form-controls synergy (optional, agnostic)
+
+The table renders its primitive controls (global **search** input and the
+**rows-per-page** selector) as native `<input>` / `<select>` by default — `ng-hub-ui-paginable`
+has **no hard dependency** on a forms library. Provide the adapter shipped by
+`ng-hub-ui-forms` once and those controls upgrade to `hub-input` / `hub-select`
+automatically (dynamic component creation under the hood), with no template
+changes:
+
+```ts
+import { provideHubPaginableFormControls } from 'ng-hub-ui-paginable';
+import { hubFormControlAdapter } from 'ng-hub-ui-forms';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideHubPaginableFormControls(hubFormControlAdapter)]
+};
+```
+
+To limit it to one table, provide the `HUB_PAGINABLE_FORM_CONTROLS` token in that
+component's `providers` instead. Remove it and the table falls back to native
+controls. See the ecosystem-wide
+[Synergies & agnosticism](../../README.md#synergies--agnosticism) section.
+
+---
+
 ## ✨ Inspiration
 
 This library arises from the need to offer highly configurable, accessible, and modern data visualization components for Angular applications, enabling integrated lists, tables, and pagination with full support for signals, reactive forms, and complete render customization.
@@ -150,7 +175,7 @@ All components are built as standalone Angular components with full Angular Sign
 - **📋 Smart Sorting**: Ascending/descending column sorting with visual indicators
 - **☑️ Row Selection**: Single or multiple row selection with batch operations and ControlValueAccessor support
 - **📈 Expandable Content**: Collapsible row content for detailed views with custom templates
-- **📄 Dual Pagination**: Support for both local and remote pagination strategies
+- **📄 Dual Pagination**: Automatic **client-side** pagination for plain arrays (in-memory search, filter, sort & slice) or **server-side** via `PaginationState` / `totalItems`
 - **🎨 Template Customization**: Extensive custom templates for headers, cells, filters, states (empty, loading, error)
 - **📱 Responsive Design**: Configurable responsive breakpoints for optimal mobile experience
 - **♿ Accessibility Ready**: Built-in ARIA support and keyboard navigation
@@ -1012,11 +1037,11 @@ filters = signal({
 | Name                 | Type                                          | Default         | Description                                                                                              |
 | -------------------- | --------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------- |
 | `headers`            | `PaginableTableHeader[]`                      | `[]`            | Column definitions with titles, sorting, filtering, and actions.                                         |
-| `data` / `rows`      | `T[]` or `PaginationState<T>`                 | `[]`            | Table data - can be flat array or paginated object with metadata.                                        |
-| `page`               | `number`                                      | `null`          | Current page number (1-based, model signal).                                                             |
-| `perPage`            | `number`                                      | `null`          | Number of items per page.                                                                                |
-| `perPageOptions`     | `number[]`                                    | `[20, 50, 100]` | Available options for items per page.                                                                    |
-| `totalItems`         | `number`                                      | `null`          | Total number of items across all pages.                                                                  |
+| `data` / `rows`      | `T[]` or `PaginationState<T>`                 | `[]`            | Table data. A plain array → client-side mode (in-memory pagination); a `PaginationState` → server mode.   |
+| `page`               | `number`                                      | `null`          | Current page number (1-based, model signal). Defaulted to `1` automatically in client-side mode.          |
+| `perPage`            | `number`                                      | `10`            | Number of items per page (model signal).                                                                 |
+| `perPageOptions`     | `number[]`                                    | `[10, 20, 50, 100]` | Available options for items per page.                                                                |
+| `totalItems`         | `number`                                      | `null`          | Total items across all pages. Setting it selects **server mode** (the table renders `data` as-is).        |
 | `searchable`         | `boolean`                                     | `true`          | Whether to show the global search input.                                                                 |
 | `searchTerm`         | `string`                                      | `''`            | Current search term (model signal).                                                                      |
 | `searchFn`           | `(a: T, b: T) => boolean`                     | `null`          | Custom search function for filtering.                                                                    |
@@ -1027,7 +1052,7 @@ filters = signal({
 | `filters`            | `Record<string, any>`                         | `{}`            | Active column filters (model signal).                                                                    |
 | `debounce`           | `number`                                      | `0`             | Debounce time in ms for search and filter inputs.                                                        |
 | `loading`            | `boolean`                                     | `false`         | Loading state indicator (model signal).                                                                  |
-| `paginate`           | `boolean`                                     | `true`          | Whether to enable pagination.                                                                            |
+| `paginate`           | `boolean`                                     | `true`          | Enables pagination. With a plain array and no `totalItems`, this turns on automatic client-side mode. `false` renders the whole array unpaginated. |
 | `paginationPosition` | `'top' \| 'bottom' \| 'both'`                 | `'bottom'`      | Where to display pagination controls.                                                                    |
 | `paginationInfo`     | `boolean`                                     | `true`          | Whether to show pagination info (e.g., "Showing 1 to 10 of 100").                                        |
 | `stickyActions`      | `boolean`                                     | `false`         | Whether action buttons should stick during scrolling.                                                    |
@@ -1078,6 +1103,7 @@ interface TableRowEvent<T> {
 | `batchActions` | `Array<PaginableTableDropdown \| PaginableActionButton>` | `[]`         | Actions for selected items.                                                                                    |
 | `clickFn`      | `(event: ListClickEvent<T>) => void`          | `null`       | Handler for item click events.                                                                                 |
 | `rowClass`     | `string \| ((item: T) => string)`             | `null`       | Custom CSS class for a list item. Can be a fixed string or a function that returns a class based on item data. |
+| `connected`    | `boolean`                                     | `false`      | Draws a vertical connector between consecutive items for a timeline / pipeline look (list display only, skipped in cards). Themed via `--hub-list-connector-color` / `-width` / `-style` / `-offset`. |
 
 **List Click Event (`ListClickEvent<T>`):**
 
@@ -1207,7 +1233,7 @@ You can also use `tableRowTpt` with expandable components.
 The `ng-hub-ui-paginable` library is fully style-configurable through **CSS custom properties (CSS variables)** for **Table**, **List**, and **Paginator**.
 
 For a complete and up-to-date token catalog, see [CSS Variables Reference](./docs/css-variables-reference.md).
-Table and List also expose context pagination tokens (`--hub-table-pagination-*`, `--hub-list-pagination-*`) so embedded paginators follow component themes by default.
+The paginator embedded in Table and List is themed through the shared `--hub-paginator-*` tokens — override them on the host component to re-theme it in context.
 
 ### 🔗 Import styles
 
@@ -1236,6 +1262,45 @@ Table and List also expose context pagination tokens (`--hub-table-pagination-*`
 }
 ```
 
+### 🧩 SCSS mixins — one-call theming
+
+Instead of setting the `--hub-*` tokens by hand, you can theme the table or the list in a single `@include`. Every parameter is optional and defaults to `null`, so only the ones you pass are emitted (the rest keep the component defaults). Import the mixin you need from the distributed styles:
+
+```scss
+@use 'ng-hub-ui-paginable/styles/mixins/table-theme' as *;
+@use 'ng-hub-ui-paginable/styles/mixins/list-theme' as *;
+```
+
+#### `hub-table-theme(…)` — theme `<hub-table>`
+
+Colour (`$accent`, `$bg`, `$color`, `$border-color`, `$hover-bg`, `$hover-color`, `$selected-bg`, `$selected-color`, `$striped-bg`, `$striped-color`), border (`$border-width`, `$border-radius`), density (`$cell-padding-x`, `$cell-padding-y`) and footer / bottom-bar (`$footer-gap`, `$footer-justify`, `$footer-align`, `$footer-wrap`).
+
+```scss
+.invoices-table {
+	@include hub-table-theme(
+		$accent: var(--hub-sys-color-success),
+		$border-radius: 0.5rem,
+		$cell-padding-y: 0.375rem,
+		$footer-justify: end
+	);
+}
+```
+
+#### `hub-list-theme(…)` — theme `<hub-list>` (list & cards)
+
+Colour (`$accent`, `$bg`, `$item-bg`, `$item-color`, `$item-border-color`, `$hover-bg`, `$selected-bg`, `$selected-color`), border/radius (`$border-radius`, `$item-border-radius`), density (`$item-padding-x`, `$item-padding-y`, `$gap`), the cards layout (`$cards-bg`, `$cards-border-color`, `$cards-border-radius`, `$cards-padding-x`, `$cards-padding-y`, `$cards-min-column-width`, `$cards-gap`) and footer (`$footer-gap`, `$footer-justify`, `$footer-align`, `$footer-wrap`).
+
+```scss
+.team-list {
+	@include hub-list-theme(
+		$accent: var(--hub-sys-color-success),
+		$item-border-radius: 0.75rem,
+		$gap: 0.5rem,
+		$cards-min-column-width: 16rem
+	);
+}
+```
+
 ### Dynamic Row Styling (`rowClass`)
 
 The `rowClass` input allows you to dynamically assign custom CSS classes to each row in both the table and list components. This is useful for visually highlighting rows based on their data. It accepts either a static `string` (to apply the same class to all rows) or a `function` that receives the item data and returns a class string.
@@ -1949,9 +2014,9 @@ headers = [
 
 ```scss
 .hub-table {
-	--hub-body-bg: #f8f9fa;
-	--hub-body-color: #212529;
-	--hub-border-color: #dee2e6;
+	--hub-table-bg: #f8f9fa;
+	--hub-table-color: #212529;
+	--hub-table-border-color: #dee2e6;
 }
 ```
 
@@ -2069,11 +2134,21 @@ This allows you to adapt any type of visual filter (date-range, boolean, dropdow
 
 ## 🧠 Pagination and Data Handling
 
-The `hub-ui-table` component can receive data in two different ways:
+The `hub-ui-table` component supports **three** data / pagination modes:
+
+#### 1. Client-side (automatic) — pass a plain array
+
+Hand the table the **full array** and let it paginate, search, sort and filter **entirely in memory** — no parent wiring required. This is the default whenever `[data]` is a plain array, `paginate` is `true` (its default) and you do **not** provide `totalItems`; the table computes the total itself. It mirrors the client-side behaviour of `<hub-ui-list>`.
+
+```html
+<hub-ui-table [data]="allRows()" [headers]="headers" [(page)]="page" [perPage]="20" [searchable]="true"></hub-ui-table>
+```
+
+> The global search box, sortable headers and every per-column filter (inline "row" filters and the advanced "menu" rule engine) all resolve client-side, and the current page resets/clamps automatically as the result set changes. Set `[paginate]="false"` to render the whole array without any pagination.
 
-#### 1. Grouped form (`PaginationState<T>`)
+#### 2. Grouped form (`PaginationState<T>`) — server-side
 
-Ideal if you manage pagination outside the component. The `data` input can directly accept an object with the full pagination structure:
+Ideal if you manage pagination outside the component (a service, store or `computed()`). Passing a `PaginationState` keeps the table in **server mode**: it renders `data` as-is and reads `page` / `perPage` / `totalItems` from the object. The `data` input accepts it directly:
 
 ```html
 <hub-ui-table
@@ -2088,17 +2163,17 @@ Ideal if you manage pagination outside the component. The `data` input can direc
 
 > This form is useful when you manage `PaginationState` in a single place (for example, from a service, `computed()`, or store).
 
-#### 2. Split form (individual inputs)
+#### 3. Split form (individual inputs) — server-side
 
-You can also pass each value separately:
+You can also pass each value separately, holding only the current page's rows in `data`:
 
 ```html
-<hub-ui-table [data]="data()" [page]="page()" [perPage]="perPage()" [totalItems]="totalItems()"></hub-ui-table>
+<hub-ui-table [data]="pageRows()" [page]="page()" [perPage]="perPage()" [totalItems]="totalItems()"></hub-ui-table>
 ```
 
-> It is important that if you choose this form, **all inputs are present**. If `page`, `perPage`, or `totalItems` are missing, the component will show an error in the console.
+> Set **`totalItems`** to opt into server mode — it tells the table you are managing the total yourself, so it renders `data` as-is instead of paginating it in memory. (If you pass a plain array **without** `totalItems`, the table assumes client-side mode #1 and paginates it for you.)
 
-Both forms are compatible with Signals and can be easily integrated with `model()` and `computed()`.
+All three modes are compatible with Signals and integrate cleanly with `model()` and `computed()`.
 
 ### Advanced Pagination Example