@lofid/web 1.1.0 → 1.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -1,141 +1,141 @@
1
- # lof-pagination
2
-
3
- Page navigation implementing the Figma "Pagination" component in its three **Type** layouts: `extended` (prev/next ghost buttons around numbered page chips, with a windowed ellipsis for long ranges), `compact` (prev/next around a "Page X of Y" readout) and `count-text` (a "1–10 of 50" item range with the nav on the right). Use it under tables, lists and search results that load one page at a time. It never fetches data or reads the URL: listen for `lof-change` and load the requested page yourself.
4
-
5
- ## Usage
6
-
7
- ```html
8
- <!-- Extended (default): numbered pages, uncontrolled -->
9
- <lof-pagination total-pages="12" default-page="3"></lof-pagination>
10
-
11
- <!-- Extended with the "Viewing page X of Y" caption -->
12
- <lof-pagination total-pages="20" show-label></lof-pagination>
13
-
14
- <!-- Compact: prev / "Page X of Y" / next -->
15
- <lof-pagination type="compact" total-pages="8"></lof-pagination>
16
-
17
- <!-- Count-text: item range computed from total-items and per-page -->
18
- <lof-pagination type="count-text" total-items="137" per-page="25"></lof-pagination>
19
-
20
- <!-- Controlled: the parent owns the page -->
21
- <lof-pagination id="results" page="1" total-pages="40" ariaLabel="Search results pagination"></lof-pagination>
22
- <script>
23
- const pager = document.getElementById('results');
24
- pager.addEventListener('lof-change', (e) => {
25
- loadResults(e.detail.page).then(() => {
26
- pager.page = e.detail.page; // commit once the data is in
27
- });
28
- });
29
- </script>
30
-
31
- <!-- Disabled while loading -->
32
- <lof-pagination total-pages="12" disabled></lof-pagination>
33
-
34
- <!-- New in 1.5.0. Page select: prev / "Page [dropdown] of Y" / next; the dropdown jumps to any page -->
35
- <lof-pagination type="page-select" total-pages="40"></lof-pagination>
36
-
37
- <!-- New in 1.5.0. A rows-per-page selector after the navigation (Figma "Extended with Rows").
38
- Works with every type; choosing a value updates per-page and returns to page 1. -->
39
- <lof-pagination total-items="137" per-page="20" show-rows-per-page></lof-pagination>
40
- <lof-pagination type="count-text" total-items="137" per-page="25"
41
- show-rows-per-page rows-per-page-options="[25, 50, 100]"></lof-pagination>
42
- <script>
43
- document.querySelector('lof-pagination[show-rows-per-page]')
44
- .addEventListener('lof-per-page-change', (e) => reload({ perPage: e.detail.perPage, page: 1 }));
45
- </script>
46
- ```
47
-
48
- Without `show-rows-per-page` there is no rows-per-page selector, and every type except `page-select` has no jump-to-page control: those are the defaults, so existing markup renders exactly as before.
49
-
50
- ### Deprecated aliases
51
-
52
- ```html
53
- <!-- Lowercase-joined attribute spellings → kebab-case (since 1.5.0; still work, log a one-time
54
- console notice, removed in 3.0). camelCase markup (totalPages="12") lands on these too. -->
55
- <lof-pagination totalpages="12" defaultpage="3" showlabel></lof-pagination>
56
- <lof-pagination type="count-text" totalitems="137" perpage="25" hreftemplate="?page={page}"></lof-pagination>
57
- <!-- canonical -->
58
- <lof-pagination total-pages="12" default-page="3" show-label></lof-pagination>
59
- <lof-pagination type="count-text" total-items="137" per-page="25" href-template="?page={page}"></lof-pagination>
60
- ```
61
-
62
- <!-- readme-gen:start -->
63
-
64
- <!-- Generated from lof-pagination.ts — do not edit; run readme-generate.mjs -->
65
-
66
- ## API
67
-
68
- ### Attributes / Properties
69
-
70
- | Property | Attribute | Type | Default | Description |
71
- | --- | --- | --- | --- | --- |
72
- | `type` | `type` | `"extended" \| "compact" \| "count-text" \| "page-select"` | `"extended"` | Figma "Type": `extended` = prev/next + numbered page buttons (auto-collapses to compact under 480px container width), `compact` = prev/next + "Page X of Y", `count-text` = "start–end of total" item range + prev/next around the current page number, `page-select` = prev/next around "Page [select] of Y", a dropdown that jumps to any page (new in 1.5.0). Every type except `page-select` has no jump-to-page control. Reflected. |
73
- | `page` | `page` | `number` | `undefined` | Controlled current page (1-based). When set, the element only emits `lof-change` and waits for the parent to update `page`; leave unset for uncontrolled behaviour. |
74
- | `defaultPage` | `default-page` | `number` | `1` | Starting page for uncontrolled use (ignored when `page` is set). The `defaultpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
75
- | `totalPages` | `total-pages` | `number` | `0` | Total number of pages. `0` (the default) lets `totalItems` / `perPage` compute the page count instead. The `totalpages` attribute spelling is deprecated (still works; removal targeted for 3.0). |
76
- | `totalItems` | `total-items` | `number` | `0` | Total item count; with `perPage` it computes the page count when `totalPages` is `0` and is the "of N" figure in the count-text readout. The `totalitems` attribute spelling is deprecated (still works; removal targeted for 3.0). |
77
- | `perPage` | `per-page` | `number` | `10` | Items per page, used to compute the page count from `totalItems` and the "start–end" range in the count-text readout. The `perpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
78
- | `showLabel` | `show-label` | `boolean` | `false` | Shows a "Viewing page X of Y" caption under the extended layout (ignored by the other types). Off by default. The `showlabel` attribute spelling is deprecated (still works; removal targeted for 3.0). |
79
- | `disabled` | `disabled` | `boolean` | `false` | Dims the whole control to 40% opacity, shows a `not-allowed` cursor and ignores every page change. Reflected. |
80
- | `hrefTemplate` | `href-template` | `string` | `""` | Reserved for link-mode pagination. Currently accepted but not rendered: every page control is a `<button>`, so navigate in your `lof-change` handler instead. The `hreftemplate` attribute spelling is deprecated (still works; removal targeted for 3.0). |
81
- | `ariaLabel` | `arialabel` | `string` | `"Pagination"` | Accessible name of the `role="navigation"` landmark (attribute `ariaLabel`). Set it when a page contains more than one pagination control. |
82
- | `showRowsPerPage` | `show-rows-per-page` | `boolean` | `false` | New in 1.5.0. Adds a rows-per-page selector after the navigation, with any `type` (Figma "Extended with Rows" is `type="extended"` with this set). Choosing a value sets `perPage`, fires `lof-per-page-change` and returns to page 1. Off by default: no rows-per-page selector. |
83
- | `rowsPerPageOptions` | `rows-per-page-options` | `number[]` | `[10, 20, 50, 100]` | New in 1.5.0. The values the rows-per-page selector offers (a number array, or a JSON array in the attribute). The current `perPage` is added to the list when it is not in it. |
84
- | `rowsPerPageLabel` | `rows-per-page-label` | `string` | `"Results per Page"` | New in 1.5.0. Text before the rows-per-page selector, also its accessible name. |
85
-
86
- ## Events
87
-
88
- | Event | Detail | Bubbles / composed | Description |
89
- | --- | --- | --- | --- |
90
- | `lof-change` | `{ page: newPage }` | bubbles / composed | Fired when the user picks another page (prev/next or a page number). Detail: `{ page: number }` (1-based). In controlled mode the parent must then set `page`. |
91
- | `lof-per-page-change` | `{ perPage }` | bubbles / composed | New in 1.5.0. Fired when the user picks a value in the rows-per-page selector (`show-rows-per-page`). Detail: `{ perPage: number }`. `perPage` is already updated; the element then returns to page 1 (in controlled mode it fires `lof-change` with `{ page: 1 }` for the parent to commit). |
92
-
93
- ## Slots
94
-
95
- | Slot | Description |
96
- | --- | --- |
97
- | — | This element has no slots. |
98
-
99
- ## CSS Parts
100
-
101
- | Part | Description |
102
- | --- | --- |
103
- | `base` | The `role="navigation"` root of the extended layout (page buttons plus the optional "Viewing page" label). |
104
- | `label` | The `role="navigation"` root row of the count-text layout (item-range text plus prev/next nav). |
105
- | `page-select` | The `lof-select` of the `page-select` layout (the jump-to-page dropdown). New in 1.5.0. |
106
- | `rows-per-page` | The rows-per-page block (its text plus the `lof-select`), rendered with `show-rows-per-page`. New in 1.5.0. |
107
-
108
- <!-- readme-gen:end -->
109
-
110
- ## Accessibility
111
-
112
- - The control is a `role="navigation"` landmark named by `ariaLabel` (default "Pagination"); give each pager on a page a distinct name.
113
- - Prev/next are native buttons labelled "Previous page" / "Next page"; they are disabled (not hidden) on the first / last page.
114
- - Each page chip is a native button labelled "Page N" with `aria-current="page"` on the current one. Abbreviated first/last chips (e.g. "368k") keep the exact number in their `title`.
115
- - Every page change is announced to screen readers as "Page N of M" via the shared live region.
116
- - If a prev/next button becomes disabled while it has focus (you reached the first/last page), focus moves to the other nav button instead of being lost.
117
- - `type="page-select"` (new in 1.5.0): the dropdown is a `lof-select` combobox named "Page (of N)", so it is read as, for example, "Page (of 40), 3". The visible "Page" and "of N" texts are hidden from assistive technology because the name already carries them. It sits inside the navigation landmark, and picking a page is announced like any other page change.
118
- - `show-rows-per-page` (new in 1.5.0): the rows-per-page dropdown is a `lof-select` combobox named by `rows-per-page-label` (default "Results per Page"), placed after the navigation landmark rather than inside it. Its visible text is hidden from assistive technology for the same reason.
119
- - `disabled` also disables both dropdowns.
120
-
121
- | Key | Action |
122
- | --- | --- |
123
- | `Tab` / `Shift+Tab` | Move between the prev button, page chips (or the page dropdown) and next button, then the rows-per-page dropdown |
124
- | `Enter` / `Space` | Activate the focused button (native behaviour); on a dropdown, open it |
125
- | `ArrowDown` / `ArrowUp`, `Enter`, `Escape` (dropdown open) | Move the highlight, pick the highlighted value, close without picking (lof-select's keyboard model) |
126
- | Typing (page dropdown open) | Moves the highlight to the next page that starts with the digits typed within half a second (2 then 5 for page 25); Enter picks it |
127
-
128
- The page chips and nav buttons have no arrow-key navigation; they are regular tab stops.
129
-
130
- ## Notes / Edge Cases
131
-
132
- - **Attribute names.** Multi-word attributes are kebab-case: `total-pages`, `default-page`, `total-items`, `per-page`, `show-label`, `href-template`. They are observed like any other attribute, so later changes apply. The older lowercase spellings (which camelCase markup also produces, since HTML attribute names are case-insensitive) still work since 1.5.0 but log a one-time console notice and are removed in 3.0; see Deprecated aliases. `ariaLabel` keeps its `arialabel` attribute.
133
- - **Page count.** `totalPages` wins when greater than `0`; otherwise the count is `ceil(totalItems / perPage)`. With neither set the element renders no page chips and both nav buttons disabled.
134
- - **Controlled vs uncontrolled.** With `page` unset the element tracks the current page itself starting at `defaultPage`. Once `page` is set it stays on that page until the parent changes it — clicking only emits `lof-change`.
135
- - **Ellipsis window.** Up to 7 pages render in full. Beyond that: the first 5 + last near the start, first + last 5 near the end, otherwise first, current ±1 and last, with `…` between. Far first/last chips abbreviate large numbers (`10000` → `10k`, `2500000` → `2.5M`); chips inside the window are never abbreviated.
136
- - **Responsive.** `extended` uses a container query on the host: between 480px and 768px only first, last and current ±1 stay visible, with `…` wherever that hides two or more pages (a single hidden page stays visible instead); under 480px the whole control swaps to the compact layout (media-query fallback for browsers without container queries). The `label` part belongs to the `count-text` layout, not to the "Viewing page" caption.
137
- - **`hrefTemplate`** is accepted but currently unused — chips are always buttons, not links. Perform navigation in the `lof-change` handler.
138
- - **`lof-change` is not fired** for the current page, out-of-range pages, or while `disabled`.
139
- - **Page select.** The dropdown lists every page. Above 1,000 pages it lists a window of 1,000 around the current page plus the first and last, so the list stays fast. In controlled mode the dropdown snaps back to `page` until the parent commits the new one.
140
- - **Rows per page.** `rows-per-page-options` defaults to `[10, 20, 50, 100]`; the current `per-page` is added when it is not in the list. A pick sets `perPage`, fires `lof-per-page-change` (`{ perPage }`), then returns to page 1: uncontrolled, the element moves and fires `lof-change` with `{ page: 1 }`; controlled, it only fires `lof-change` with `{ page: 1 }`. When it is already on page 1, no `lof-change` fires. The inner dropdowns' own `changed` / `lof-change` events stop at the dropdown, so a listener on the pagination only ever sees `{ page }`.
141
- - **Narrow containers.** With `show-rows-per-page` the navigation and the rows-per-page block share one row, 16px apart, and wrap onto two rows when they do not fit.
1
+ # lof-pagination
2
+
3
+ Page navigation implementing the Figma "Pagination" component in its three **Type** layouts: `extended` (prev/next ghost buttons around numbered page chips, with a windowed ellipsis for long ranges), `compact` (prev/next around a "Page X of Y" readout) and `count-text` (a "1–10 of 50" item range with the nav on the right). Use it under tables, lists and search results that load one page at a time. It never fetches data or reads the URL: listen for `lof-change` and load the requested page yourself.
4
+
5
+ ## Usage
6
+
7
+ ```html
8
+ <!-- Extended (default): numbered pages, uncontrolled -->
9
+ <lof-pagination total-pages="12" default-page="3"></lof-pagination>
10
+
11
+ <!-- Extended with the "Viewing page X of Y" caption -->
12
+ <lof-pagination total-pages="20" show-label></lof-pagination>
13
+
14
+ <!-- Compact: prev / "Page X of Y" / next -->
15
+ <lof-pagination type="compact" total-pages="8"></lof-pagination>
16
+
17
+ <!-- Count-text: item range computed from total-items and per-page -->
18
+ <lof-pagination type="count-text" total-items="137" per-page="25"></lof-pagination>
19
+
20
+ <!-- Controlled: the parent owns the page -->
21
+ <lof-pagination id="results" page="1" total-pages="40" ariaLabel="Search results pagination"></lof-pagination>
22
+ <script>
23
+ const pager = document.getElementById('results');
24
+ pager.addEventListener('lof-change', (e) => {
25
+ loadResults(e.detail.page).then(() => {
26
+ pager.page = e.detail.page; // commit once the data is in
27
+ });
28
+ });
29
+ </script>
30
+
31
+ <!-- Disabled while loading -->
32
+ <lof-pagination total-pages="12" disabled></lof-pagination>
33
+
34
+ <!-- New in 1.5.0. Page select: prev / "Page [dropdown] of Y" / next; the dropdown jumps to any page -->
35
+ <lof-pagination type="page-select" total-pages="40"></lof-pagination>
36
+
37
+ <!-- New in 1.5.0. A rows-per-page selector after the navigation (Figma "Extended with Rows").
38
+ Works with every type; choosing a value updates per-page and returns to page 1. -->
39
+ <lof-pagination total-items="137" per-page="20" show-rows-per-page></lof-pagination>
40
+ <lof-pagination type="count-text" total-items="137" per-page="25"
41
+ show-rows-per-page rows-per-page-options="[25, 50, 100]"></lof-pagination>
42
+ <script>
43
+ document.querySelector('lof-pagination[show-rows-per-page]')
44
+ .addEventListener('lof-per-page-change', (e) => reload({ perPage: e.detail.perPage, page: 1 }));
45
+ </script>
46
+ ```
47
+
48
+ Without `show-rows-per-page` there is no rows-per-page selector, and every type except `page-select` has no jump-to-page control: those are the defaults, so existing markup renders exactly as before.
49
+
50
+ ### Deprecated aliases
51
+
52
+ ```html
53
+ <!-- Lowercase-joined attribute spellings → kebab-case (since 1.5.0; still work, log a one-time
54
+ console notice, removed in 3.0). camelCase markup (totalPages="12") lands on these too. -->
55
+ <lof-pagination totalpages="12" defaultpage="3" showlabel></lof-pagination>
56
+ <lof-pagination type="count-text" totalitems="137" perpage="25" hreftemplate="?page={page}"></lof-pagination>
57
+ <!-- canonical -->
58
+ <lof-pagination total-pages="12" default-page="3" show-label></lof-pagination>
59
+ <lof-pagination type="count-text" total-items="137" per-page="25" href-template="?page={page}"></lof-pagination>
60
+ ```
61
+
62
+ <!-- readme-gen:start -->
63
+
64
+ <!-- Generated from lof-pagination.ts — do not edit; run readme-generate.mjs -->
65
+
66
+ ## API
67
+
68
+ ### Attributes / Properties
69
+
70
+ | Property | Attribute | Type | Default | Description |
71
+ | --- | --- | --- | --- | --- |
72
+ | `type` | `type` | `"extended" \| "compact" \| "count-text" \| "page-select"` | `"extended"` | Figma "Type": `extended` = prev/next + numbered page buttons (auto-collapses to compact under 480px container width), `compact` = prev/next + "Page X of Y", `count-text` = "start–end of total" item range + prev/next around the current page number, `page-select` = prev/next around "Page [select] of Y", a dropdown that jumps to any page (new in 1.5.0). Every type except `page-select` has no jump-to-page control. Reflected. |
73
+ | `page` | `page` | `number` | `undefined` | Controlled current page (1-based). When set, the element only emits `lof-change` and waits for the parent to update `page`; leave unset for uncontrolled behaviour. |
74
+ | `defaultPage` | `default-page` | `number` | `1` | Starting page for uncontrolled use (ignored when `page` is set). The `defaultpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
75
+ | `totalPages` | `total-pages` | `number` | `0` | Total number of pages. `0` (the default) lets `totalItems` / `perPage` compute the page count instead. The `totalpages` attribute spelling is deprecated (still works; removal targeted for 3.0). |
76
+ | `totalItems` | `total-items` | `number` | `0` | Total item count; with `perPage` it computes the page count when `totalPages` is `0` and is the "of N" figure in the count-text readout. The `totalitems` attribute spelling is deprecated (still works; removal targeted for 3.0). |
77
+ | `perPage` | `per-page` | `number` | `10` | Items per page, used to compute the page count from `totalItems` and the "start–end" range in the count-text readout. The `perpage` attribute spelling is deprecated (still works; removal targeted for 3.0). |
78
+ | `showLabel` | `show-label` | `boolean` | `false` | Shows a "Viewing page X of Y" caption under the extended layout (ignored by the other types). Off by default. The `showlabel` attribute spelling is deprecated (still works; removal targeted for 3.0). |
79
+ | `disabled` | `disabled` | `boolean` | `false` | Dims the whole control to 40% opacity, shows a `not-allowed` cursor and ignores every page change. Reflected. |
80
+ | `hrefTemplate` | `href-template` | `string` | `""` | Reserved for link-mode pagination. Currently accepted but not rendered: every page control is a `<button>`, so navigate in your `lof-change` handler instead. The `hreftemplate` attribute spelling is deprecated (still works; removal targeted for 3.0). |
81
+ | `ariaLabel` | `arialabel` | `string` | `"Pagination"` | Accessible name of the `role="navigation"` landmark (attribute `ariaLabel`). Set it when a page contains more than one pagination control. |
82
+ | `showRowsPerPage` | `show-rows-per-page` | `boolean` | `false` | New in 1.5.0. Adds a rows-per-page selector after the navigation, with any `type` (Figma "Extended with Rows" is `type="extended"` with this set). Choosing a value sets `perPage`, fires `lof-per-page-change` and returns to page 1. Off by default: no rows-per-page selector. |
83
+ | `rowsPerPageOptions` | `rows-per-page-options` | `number[]` | `[10, 20, 50, 100]` | New in 1.5.0. The values the rows-per-page selector offers (a number array, or a JSON array in the attribute). The current `perPage` is added to the list when it is not in it. |
84
+ | `rowsPerPageLabel` | `rows-per-page-label` | `string` | `"Results per Page"` | New in 1.5.0. Text before the rows-per-page selector, also its accessible name. |
85
+
86
+ ## Events
87
+
88
+ | Event | Detail | Bubbles / composed | Description |
89
+ | --- | --- | --- | --- |
90
+ | `lof-change` | `{ page: newPage }` | bubbles / composed | Fired when the user picks another page (prev/next or a page number). Detail: `{ page: number }` (1-based). In controlled mode the parent must then set `page`. |
91
+ | `lof-per-page-change` | `{ perPage }` | bubbles / composed | New in 1.5.0. Fired when the user picks a value in the rows-per-page selector (`show-rows-per-page`). Detail: `{ perPage: number }`. `perPage` is already updated; the element then returns to page 1 (in controlled mode it fires `lof-change` with `{ page: 1 }` for the parent to commit). |
92
+
93
+ ## Slots
94
+
95
+ | Slot | Description |
96
+ | --- | --- |
97
+ | — | This element has no slots. |
98
+
99
+ ## CSS Parts
100
+
101
+ | Part | Description |
102
+ | --- | --- |
103
+ | `base` | The `role="navigation"` root of the extended layout (page buttons plus the optional "Viewing page" label). |
104
+ | `label` | The `role="navigation"` root row of the count-text layout (item-range text plus prev/next nav). |
105
+ | `page-select` | The `lof-select` of the `page-select` layout (the jump-to-page dropdown). New in 1.5.0. |
106
+ | `rows-per-page` | The rows-per-page block (its text plus the `lof-select`), rendered with `show-rows-per-page`. New in 1.5.0. |
107
+
108
+ <!-- readme-gen:end -->
109
+
110
+ ## Accessibility
111
+
112
+ - The control is a `role="navigation"` landmark named by `ariaLabel` (default "Pagination"); give each pager on a page a distinct name.
113
+ - Prev/next are native buttons labelled "Previous page" / "Next page"; they are disabled (not hidden) on the first / last page.
114
+ - Each page chip is a native button labelled "Page N" with `aria-current="page"` on the current one. Abbreviated first/last chips (e.g. "368k") keep the exact number in their `title`.
115
+ - Every page change is announced to screen readers as "Page N of M" via the shared live region.
116
+ - If a prev/next button becomes disabled while it has focus (you reached the first/last page), focus moves to the other nav button instead of being lost.
117
+ - `type="page-select"` (new in 1.5.0): the dropdown is a `lof-select` combobox named "Page (of N)", so it is read as, for example, "Page (of 40), 3". The visible "Page" and "of N" texts are hidden from assistive technology because the name already carries them. It sits inside the navigation landmark, and picking a page is announced like any other page change.
118
+ - `show-rows-per-page` (new in 1.5.0): the rows-per-page dropdown is a `lof-select` combobox named by `rows-per-page-label` (default "Results per Page"), placed after the navigation landmark rather than inside it. Its visible text is hidden from assistive technology for the same reason.
119
+ - `disabled` also disables both dropdowns.
120
+
121
+ | Key | Action |
122
+ | --- | --- |
123
+ | `Tab` / `Shift+Tab` | Move between the prev button, page chips (or the page dropdown) and next button, then the rows-per-page dropdown |
124
+ | `Enter` / `Space` | Activate the focused button (native behaviour); on a dropdown, open it |
125
+ | `ArrowDown` / `ArrowUp`, `Enter`, `Escape` (dropdown open) | Move the highlight, pick the highlighted value, close without picking (lof-select's keyboard model) |
126
+ | Typing (page dropdown open) | Moves the highlight to the next page that starts with the digits typed within half a second (2 then 5 for page 25); Enter picks it |
127
+
128
+ The page chips and nav buttons have no arrow-key navigation; they are regular tab stops.
129
+
130
+ ## Notes / Edge Cases
131
+
132
+ - **Attribute names.** Multi-word attributes are kebab-case: `total-pages`, `default-page`, `total-items`, `per-page`, `show-label`, `href-template`. They are observed like any other attribute, so later changes apply. The older lowercase spellings (which camelCase markup also produces, since HTML attribute names are case-insensitive) still work since 1.5.0 but log a one-time console notice and are removed in 3.0; see Deprecated aliases. `ariaLabel` keeps its `arialabel` attribute.
133
+ - **Page count.** `totalPages` wins when greater than `0`; otherwise the count is `ceil(totalItems / perPage)`. With neither set the element renders no page chips and both nav buttons disabled.
134
+ - **Controlled vs uncontrolled.** With `page` unset the element tracks the current page itself starting at `defaultPage`. Once `page` is set it stays on that page until the parent changes it — clicking only emits `lof-change`.
135
+ - **Ellipsis window.** Up to 7 pages render in full. Beyond that: the first 5 + last near the start, first + last 5 near the end, otherwise first, current ±1 and last, with `…` between. Far first/last chips abbreviate large numbers (`10000` → `10k`, `2500000` → `2.5M`); chips inside the window are never abbreviated.
136
+ - **Responsive.** `extended` uses a container query on the host: between 480px and 768px only first, last and current ±1 stay visible, with `…` wherever that hides two or more pages (a single hidden page stays visible instead); under 480px the whole control swaps to the compact layout (media-query fallback for browsers without container queries). Because the host is a size container it takes its width from its container, not its content: in a flex row give it a basis (`flex: 1 1 18rem`) or it shrinks to zero width and its buttons spill out. The `label` part belongs to the `count-text` layout, not to the "Viewing page" caption.
137
+ - **`hrefTemplate`** is accepted but currently unused — chips are always buttons, not links. Perform navigation in the `lof-change` handler.
138
+ - **`lof-change` is not fired** for the current page, out-of-range pages, or while `disabled`.
139
+ - **Page select.** The dropdown lists every page. Above 1,000 pages it lists a window of 1,000 around the current page plus the first and last, so the list stays fast. In controlled mode the dropdown snaps back to `page` until the parent commits the new one.
140
+ - **Rows per page.** `rows-per-page-options` defaults to `[10, 20, 50, 100]`; the current `per-page` is added when it is not in the list. A pick sets `perPage`, fires `lof-per-page-change` (`{ perPage }`), then returns to page 1: uncontrolled, the element moves and fires `lof-change` with `{ page: 1 }`; controlled, it only fires `lof-change` with `{ page: 1 }`. When it is already on page 1, no `lof-change` fires. The inner dropdowns' own `changed` / `lof-change` events stop at the dropdown, so a listener on the pagination only ever sees `{ page }`.
141
+ - **Narrow containers.** With `show-rows-per-page` the navigation and the rows-per-page block share one row, 16px apart, and wrap onto two rows when they do not fit.
@@ -163,7 +163,7 @@
163
163
 
164
164
  | Name | Type | Description |
165
165
  | --- | --- | --- |
166
- | `currentSize` | `number` | Current size as a percentage of the group (also written to the host's `flex-basis`); read-only — the parent group updates it on every resize. |
166
+ | `currentSize` | `number` | Current size as a percentage of the group (also written to the host's `flex-grow`); read-only — the parent group updates it on every resize. |
167
167
  | `scrollable` | `boolean` | True while the content overflows the panel in either axis; read-only, kept current by a ResizeObserver. |
168
168
 
169
169
  ### Events
@@ -211,7 +211,7 @@
211
211
 
212
212
  - Panels and handles must be **direct children** of the group (`:scope > lof-resizable-panel`), alternating panel / handle / panel. A handle at the start or end, or two handles in a row, has no valid pair and does nothing.
213
213
  - Layout is computed once in `firstUpdated`: panels without `default-size` share whatever remains of 100%, then all sizes are normalised to sum to exactly 100 (so `default-size="50"` + `default-size="70"` ends up as 41.7 / 58.3). Panels or handles added or removed later are **not** observed; re-attach the group to re-initialise.
214
- - Sizes are always percentages of the group, applied as `flex-basis` with `flex-grow: 0; flex-shrink: 0`. The group itself is `display: flex; width: 100%; height: 100%`, so a `vertical` group needs an ancestor with a definite height or it has nothing to divide.
214
+ - Sizes are always percentages of the space the handles leave, applied as `flex: <size> 1 0px` with `min-width: 0` / `min-height: 0`, so panels always fit the group (wide content scrolls inside its panel instead of pushing the group wider). The group itself is `display: flex; width: 100%; height: 100%`, so a `vertical` group needs an ancestor with a definite height or it has nothing to divide.
215
215
  - Only the two panels adjacent to the dragged handle change; each is clamped to its own `min-size` / `max-size`, then the pair is rescaled so their combined share stays constant. A panel therefore cannot go below its `min-size` (default 10) and never collapses to 0 unless you set `min-size="0"`.
216
216
  - Attribute names are kebab-case: `default-size`, `min-size`, `max-size` (properties `defaultSize`, `minSize`, `maxSize`). The older lowercase spellings still work since 1.5.0 but log a one-time console notice and are removed in 3.0; see Deprecated aliases.
217
217
  - While a drag is in progress the active handle carries a `data-dragging` attribute (the group sets and removes it) — the only hook for drag-specific styling from outside.
@@ -123,7 +123,7 @@ Set these on the host (or an ancestor) to customise the element without touching
123
123
 
124
124
  | Custom property | Default | Description |
125
125
  | --- | --- | --- |
126
- | `--lof-field-label-reserve` | `calc(var(--lof-body-field-label-line-height) + var(--lof-spacing-2xs))` | Height held for the label row whenever no label renders above the trigger — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the trigger — so the trigger still lines up with labelled siblings in a form row. Defaults to that size's label line-height plus the wrapper gap (24px at `small`, 26px at `medium` and `large`). Set to `0` to collapse the row entirely (toolbars, table cells). |
126
+ | `--lof-field-label-reserve` | `0px` | Height held for the label row whenever no label renders above the trigger — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the trigger. Nothing is held by default, so an unlabelled field (a search bar) lines up with the buttons beside it. In a form row that mixes labelled and unlabelled fields, set it to the label row's height — `calc(var(--lof-body-field-label-line-height) + var(--lof-spacing-2xs))` (24px at `small`, 26px at `medium` and `large`) — so the triggers share a bottom edge. |
127
127
  | `--lof-overlay-fallback-z` | `1001` | z-index of the panel on the **no-Popover-API fallback path only**. Wherever the browser top layer is available the panel is promoted into it and this value is inert, because top-layer elements are not in the page stacking order at all. Shared with the other overlays (select, autocomplete, the three pickers) so the whole family can be moved from one place. |
128
128
  | `--lof-select-bg` | `var(--lof-bg-neutral)` | Background of the trigger, the panel and its sticky header. No longer paints behind the floating label — see `--lof-select-surface`. |
129
129
  | `--lof-select-bg-disabled` | `var(--lof-bg-neutral-elevated-2)` | Trigger background when `state="disabled"` |
@@ -189,5 +189,5 @@ Set these on the host (or an ancestor) to customise the element without touching
189
189
  - The search field uses the small field sizing for both `small` and `medium` selects; only `large` bumps it to medium. Empty results show "No matches found" (or "No options available" when `options` is empty).
190
190
  - The `helper` part exists only while `supporting-text` is non-empty.
191
191
  - The open listbox is promoted to the browser top layer (native Popover API, `popover="manual"`) so it renders correctly inside transformed or `overflow: hidden` containers such as a centered `lof-modal` or a `lof-drawer`; engines without the Popover API fall back to `position: fixed` with a measure-and-cancel correction. The panel matches the trigger width, flips above the trigger when there is not enough room below, is capped at 360px with internal scrolling, and closes on any outside pointerdown. On an outside scroll (since 1.5.0) it **stays open and moves with the field while the field is still visible**, and closes once the field scrolls out of the viewport or its scroll container, or under a sticky header — so the top-layer panel never paints over page furniture (the reason 1.4.9 closed it on every scroll). Only the window and the field's own scroll containers count, including ones inside shadow roots such as `lof-modal`'s body; scrolls of unrelated elements and of the panel itself are ignored, and a wheel or swipe over the panel never scrolls the page (`overscroll-behavior: contain`).
192
- - `--lof-field-label-reserve` (see Component hooks) keeps a `label-style="none"` select bottom-aligned with labelled siblings; set it to `0` in toolbars or table cells.
192
+ - No label row is held when no label renders above the trigger, so `label-style="none"` sits flush with buttons in toolbars and page headers. To bottom-align it with labelled siblings in a form row, set `--lof-field-label-reserve` (see Component hooks) on the row.
193
193
  - The trigger heights (28 / 34 / 40px) match `lof-textfield` and the date / time / range picker triggers so mixed form rows line up.
@@ -29,7 +29,7 @@
29
29
  | `value` | `value` | `string` | `""` | The figure, already formatted ("9.3k", "$295.7k"). |
30
30
  | `label` | `label` | `string` | `""` | What the figure counts ("Amazing mates"). |
31
31
  | `change` | `change` | `string` | `""` | Trend text ("+2.7%"); renders the trend chip. |
32
- | `trend` | `trend` | `"up" \| "down" \| "neutral"` | `—` | Direction of the change. Default: from the sign of `change` (`+` up, `-` down, otherwise neutral). |
32
+ | `trend` | `trend` | `"up" \| "down" \| "neutral"` | `—` | Whether the change is good (`up`, green), bad (`down`, red) or `neutral`. Default: from the sign of `change`. It sets the colour only: the arrow follows `change` itself (its sign, or the words lower / higher), so `change="−0.4 pts" trend="up"` is a green chip with a down arrow — right for a refund rate that fell. |
33
33
  | `changeLabel` | `change-label` | `string` | `""` | Spoken direction words, e.g. "up 2.7% from last month". Default: "increase" / "decrease". |
34
34
  | `size` | `size` | `"medium" \| "large"` | `"medium"` | |
35
35
  | `appearance` | `appearance` | `"card" \| "plain"` | `"card"` | |
@@ -170,7 +170,7 @@ Set these on the host (or an ancestor) to customise the element without touching
170
170
 
171
171
  | Custom property | Default | Description |
172
172
  | --- | --- | --- |
173
- | `--lof-field-label-reserve` | `calc(var(--lof-body-field-label-line-height) + var(--lof-spacing-2xs))` | Height held for the label row whenever no label renders above the control — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the control — so the control still lines up with labelled siblings in a form row. Defaults to that size's label line-height plus the wrapper gap (24px at `small`, 26px at `medium` and `large`). Set to `0` to collapse the row entirely (toolbars, table cells). |
173
+ | `--lof-field-label-reserve` | `0px` | Height held for the label row whenever no label renders above the control — `labelStyle="none"`, and `labelStyle="floating"` where the label sits inside the control. Nothing is held by default, so an unlabelled field (a search bar) lines up with the buttons beside it. In a form row that mixes labelled and unlabelled fields, set it to the label row's height — `calc(var(--lof-body-field-label-line-height) + var(--lof-spacing-2xs))` (24px at `small`, 26px at `medium` and `large`) — so the controls share a bottom edge. |
174
174
  | `--lof-textfield-surface` | `var(--lof-bg-neutral)` | Colour of the strip the floating label lays over the control's top border and focus ring so the label appears to sit in a notch. It overshoots the band by 2px on the page side, so it must match the surface the field sits on; defaults to the control's own fill (`--lof-bg-neutral`). Set it on a tinted or elevated surface, otherwise the strip shows as a light dash across the border. |
175
175
 
176
176
  <!-- readme-gen:end -->
@@ -200,7 +200,7 @@ Focus behaviour: `focus()` on the host focuses the inner input / textarea (the h
200
200
  - `fullWidth` defaults to `true`; without it the host becomes `inline-block` at its content width. Turn it off with `full-width="false"` (since 1.5.0) or the property (`.fullWidth=${false}`). In 1.x it still reflects as the `fullwidth` attribute, so `lof-textfield[fullwidth]` selectors keep matching.
201
201
  - `label-style="floating"`: the placeholder is hidden until the field is focused; the label floats onto the border when focused or filled. Internally the deprecated `floatingLabel` boolean is kept in sync with `labelStyle` and its reflected `floatinglabel` attribute is the styling hook, so both spellings render identically. With a `prefix-style="clear"` prefix the floated label slides back over the control's left edge (Figma "Floating Label"); `divider` / `fill` prefixes keep it after the block.
202
202
  - `variant="legend"` + `label-style="none"` drops the `<legend>` entirely so the top border runs continuous; a `fill` prefix is squared off in this variant because it cannot reach the notched top border.
203
- - `--lof-field-label-reserve` (see Component hooks) keeps a `label-style="none"` field bottom-aligned with labelled siblings; set it to `0` in toolbars or table cells.
203
+ - No label row is held when no label renders above the control, so `label-style="none"` sits flush with buttons in toolbars and page headers. To bottom-align it with labelled siblings in a form row, set `--lof-field-label-reserve` (see Component hooks) on the row.
204
204
  - Inside the prefix block the order is slotted content → icon → text (nearest the input); in the suffix block it is text → icon → slotted content. Clicking a non-interactive part of either block focuses the input.
205
205
  - The control height (28 / 34 / 40px) is explicit so the field lines up with `lof-select` and the date / time / range picker triggers; the textarea keeps the padding model and grows with `rows`.
206
206
  - In Figma, the `error` state's border has no focus ring; that matches the code (`box-shadow: none` in error).