## pagination (`poetry_pagination`)

Navigation for moving between pages of content.

Class: Poetry::Ui::Pagination::Component - BEM block `poetry-ui-pagination`.
- `current:` (integer) - required - The current page number (1-based).
- `current_variant:` (symbol) - one of outline|filled, default "outline" - How the current page link renders: :outline, or :filled for the primary Button treatment (an unambiguous active state).
- `edges:` (symbol) - one of labeled|icons|none, default "labeled" - The Previous/Next treatment: :labeled (chevron + responsive text), :icons (chevron only - table footers), :none (no edge links).
- `label:` (string) - default "pagination" - The nav landmark's accessible name.
- `next_label:` (string) - default "Next" - The Next link's visible text (hidden on narrow viewports).
- `pages:` (boolean) - default true - Set false to drop the numbered links - the compact two-button pager (pair with edges: :icons).
- `previous_label:` (string) - default "Previous" - The Previous link's visible text (hidden on narrow viewports).
- `siblings:` (integer) - default 1 - How many page links flank the current page before gaps elide to ellipses.
- `total:` (integer) - required - The total page count.
- PART `pagination` - The <nav> landmark (role=navigation, aria-label) around the page list
- PART `pagination-content` - The <ul> holding every entry as one horizontal row
- PART `pagination-item` - One <li> per entry - previous/next, a page link, or a gap
- PART `pagination-ellipsis` - The elided-pages marker between windows - aria-hidden with an sr-only 'More pages'
In blocks: `data-index` - for a screen, start from the block (MCP compose/describe_block, or `bin/rails g poetry:block`), not from scratch.
- RULE: poetry_pagination(current:, total:, path:) - never hand-build the <nav>/<ul>/<li> list.
- RULE: path: is a callable ->(page) { url } (e.g. ->(p) { products_path(page: p) }).
- RULE: The current page is aria-current=page; current_variant: :outline (the default) or :filled (the primary treatment - unambiguous active state); the rest are ghost links.
- RULE: edges: :icons renders chevron-only Previous/Next (the table-footer posture); :none drops them for a bare page list; pages: false drops the numbers (pair with edges: :icons for the compact pager).
- RULE: Host paginates with kaminari, pagy (v43+), or will_paginate? Run bin/rails g poetry:pagination (no argument = detect and install an adapter for each loaded gem) and keep calling paginate / poetry_pagy_nav / will_paginate(renderer: PoetryLinkRenderer) - never hand-wire poetry_pagination around a paginator gem.