@masmarino/gabarit 1.4.0 → 2.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@masmarino/gabarit",
-  "version": "1.4.0",
+  "version": "2.1.0",
   "description": "Angular design system — UI components and dataviz for self-hosted applications.",
   "license": "MIT",
   "homepage": "https://github.com/Masmarino/Gabarit",
@@ -39,6 +39,12 @@
       "style": "./src/lib/tokens/index.scss",
       "default": "./src/lib/tokens/index.scss"
     },
+    "./fonts": {
+      "sass": "./fonts/index.scss",
+      "style": "./fonts/index.scss",
+      "default": "./fonts/index.scss"
+    },
+    "./fonts/*": "./fonts/*",
     "./package.json": {
       "default": "./package.json"
     },
@@ -46,9 +52,337 @@
       "types": "./types/masmarino-gabarit.d.ts",
       "default": "./fesm2022/masmarino-gabarit.mjs"
     },
+    "./accordion": {
+      "types": "./types/masmarino-gabarit-accordion.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-accordion.mjs"
+    },
+    "./alert": {
+      "types": "./types/masmarino-gabarit-alert.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-alert.mjs"
+    },
+    "./app-shell": {
+      "types": "./types/masmarino-gabarit-app-shell.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-app-shell.mjs"
+    },
+    "./auth": {
+      "types": "./types/masmarino-gabarit-auth.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-auth.mjs"
+    },
+    "./auth-activate": {
+      "types": "./types/masmarino-gabarit-auth-activate.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-auth-activate.mjs"
+    },
+    "./auth-login": {
+      "types": "./types/masmarino-gabarit-auth-login.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-auth-login.mjs"
+    },
+    "./auth-register": {
+      "types": "./types/masmarino-gabarit-auth-register.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-auth-register.mjs"
+    },
+    "./auth-reset-password": {
+      "types": "./types/masmarino-gabarit-auth-reset-password.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-auth-reset-password.mjs"
+    },
+    "./autocomplete": {
+      "types": "./types/masmarino-gabarit-autocomplete.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-autocomplete.mjs"
+    },
+    "./avatar": {
+      "types": "./types/masmarino-gabarit-avatar.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-avatar.mjs"
+    },
+    "./avatar-group": {
+      "types": "./types/masmarino-gabarit-avatar-group.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-avatar-group.mjs"
+    },
+    "./badge": {
+      "types": "./types/masmarino-gabarit-badge.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-badge.mjs"
+    },
+    "./bar-chart": {
+      "types": "./types/masmarino-gabarit-bar-chart.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-bar-chart.mjs"
+    },
+    "./breadcrumb": {
+      "types": "./types/masmarino-gabarit-breadcrumb.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-breadcrumb.mjs"
+    },
+    "./button": {
+      "types": "./types/masmarino-gabarit-button.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-button.mjs"
+    },
+    "./card": {
+      "types": "./types/masmarino-gabarit-card.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-card.mjs"
+    },
+    "./chart": {
+      "types": "./types/masmarino-gabarit-chart.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-chart.mjs"
+    },
+    "./checkbox": {
+      "types": "./types/masmarino-gabarit-checkbox.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-checkbox.mjs"
+    },
+    "./checkbox-group": {
+      "types": "./types/masmarino-gabarit-checkbox-group.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-checkbox-group.mjs"
+    },
+    "./confirm-danger-modal": {
+      "types": "./types/masmarino-gabarit-confirm-danger-modal.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-confirm-danger-modal.mjs"
+    },
+    "./copy-button": {
+      "types": "./types/masmarino-gabarit-copy-button.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-copy-button.mjs"
+    },
+    "./copy-field": {
+      "types": "./types/masmarino-gabarit-copy-field.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-copy-field.mjs"
+    },
+    "./date-picker": {
+      "types": "./types/masmarino-gabarit-date-picker.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-date-picker.mjs"
+    },
+    "./description-list": {
+      "types": "./types/masmarino-gabarit-description-list.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-description-list.mjs"
+    },
+    "./dimension-card": {
+      "types": "./types/masmarino-gabarit-dimension-card.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-dimension-card.mjs"
+    },
+    "./disclosure": {
+      "types": "./types/masmarino-gabarit-disclosure.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-disclosure.mjs"
+    },
+    "./divider": {
+      "types": "./types/masmarino-gabarit-divider.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-divider.mjs"
+    },
     "./docs": {
       "types": "./types/masmarino-gabarit-docs.d.ts",
       "default": "./fesm2022/masmarino-gabarit-docs.mjs"
+    },
+    "./drawer": {
+      "types": "./types/masmarino-gabarit-drawer.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-drawer.mjs"
+    },
+    "./empty-state": {
+      "types": "./types/masmarino-gabarit-empty-state.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-empty-state.mjs"
+    },
+    "./file-upload": {
+      "types": "./types/masmarino-gabarit-file-upload.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-file-upload.mjs"
+    },
+    "./floating-panel": {
+      "types": "./types/masmarino-gabarit-floating-panel.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-floating-panel.mjs"
+    },
+    "./format": {
+      "types": "./types/masmarino-gabarit-format.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-format.mjs"
+    },
+    "./funnel-chart": {
+      "types": "./types/masmarino-gabarit-funnel-chart.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-funnel-chart.mjs"
+    },
+    "./gauge-bar": {
+      "types": "./types/masmarino-gabarit-gauge-bar.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-gauge-bar.mjs"
+    },
+    "./git-field": {
+      "types": "./types/masmarino-gabarit-git-field.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-git-field.mjs"
+    },
+    "./icon": {
+      "types": "./types/masmarino-gabarit-icon.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-icon.mjs"
+    },
+    "./icon-marker": {
+      "types": "./types/masmarino-gabarit-icon-marker.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-icon-marker.mjs"
+    },
+    "./input": {
+      "types": "./types/masmarino-gabarit-input.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-input.mjs"
+    },
+    "./job-graph": {
+      "types": "./types/masmarino-gabarit-job-graph.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-job-graph.mjs"
+    },
+    "./job-status": {
+      "types": "./types/masmarino-gabarit-job-status.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-job-status.mjs"
+    },
+    "./line-chart": {
+      "types": "./types/masmarino-gabarit-line-chart.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-line-chart.mjs"
+    },
+    "./list-card": {
+      "types": "./types/masmarino-gabarit-list-card.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-list-card.mjs"
+    },
+    "./list-row": {
+      "types": "./types/masmarino-gabarit-list-row.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-list-row.mjs"
+    },
+    "./list-toolbar": {
+      "types": "./types/masmarino-gabarit-list-toolbar.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-list-toolbar.mjs"
+    },
+    "./menu": {
+      "types": "./types/masmarino-gabarit-menu.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-menu.mjs"
+    },
+    "./mfa-enrollment": {
+      "types": "./types/masmarino-gabarit-mfa-enrollment.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-mfa-enrollment.mjs"
+    },
+    "./mfa-settings": {
+      "types": "./types/masmarino-gabarit-mfa-settings.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-mfa-settings.mjs"
+    },
+    "./modal": {
+      "types": "./types/masmarino-gabarit-modal.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-modal.mjs"
+    },
+    "./nav-tabs": {
+      "types": "./types/masmarino-gabarit-nav-tabs.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-nav-tabs.mjs"
+    },
+    "./notification-dot": {
+      "types": "./types/masmarino-gabarit-notification-dot.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-notification-dot.mjs"
+    },
+    "./page-header": {
+      "types": "./types/masmarino-gabarit-page-header.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-page-header.mjs"
+    },
+    "./page-layout": {
+      "types": "./types/masmarino-gabarit-page-layout.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-page-layout.mjs"
+    },
+    "./pagination": {
+      "types": "./types/masmarino-gabarit-pagination.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-pagination.mjs"
+    },
+    "./panel": {
+      "types": "./types/masmarino-gabarit-panel.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-panel.mjs"
+    },
+    "./passkey-settings": {
+      "types": "./types/masmarino-gabarit-passkey-settings.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-passkey-settings.mjs"
+    },
+    "./pie-chart": {
+      "types": "./types/masmarino-gabarit-pie-chart.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-pie-chart.mjs"
+    },
+    "./popover": {
+      "types": "./types/masmarino-gabarit-popover.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-popover.mjs"
+    },
+    "./radio-group": {
+      "types": "./types/masmarino-gabarit-radio-group.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-radio-group.mjs"
+    },
+    "./save-status": {
+      "types": "./types/masmarino-gabarit-save-status.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-save-status.mjs"
+    },
+    "./search-bar": {
+      "types": "./types/masmarino-gabarit-search-bar.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-search-bar.mjs"
+    },
+    "./secret-reveal": {
+      "types": "./types/masmarino-gabarit-secret-reveal.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-secret-reveal.mjs"
+    },
+    "./segmented-control": {
+      "types": "./types/masmarino-gabarit-segmented-control.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-segmented-control.mjs"
+    },
+    "./select": {
+      "types": "./types/masmarino-gabarit-select.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-select.mjs"
+    },
+    "./skeleton": {
+      "types": "./types/masmarino-gabarit-skeleton.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-skeleton.mjs"
+    },
+    "./skeleton-list": {
+      "types": "./types/masmarino-gabarit-skeleton-list.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-skeleton-list.mjs"
+    },
+    "./slider": {
+      "types": "./types/masmarino-gabarit-slider.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-slider.mjs"
+    },
+    "./sparkline": {
+      "types": "./types/masmarino-gabarit-sparkline.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-sparkline.mjs"
+    },
+    "./spinner": {
+      "types": "./types/masmarino-gabarit-spinner.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-spinner.mjs"
+    },
+    "./stat-grid": {
+      "types": "./types/masmarino-gabarit-stat-grid.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-stat-grid.mjs"
+    },
+    "./stat-tile": {
+      "types": "./types/masmarino-gabarit-stat-tile.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-stat-tile.mjs"
+    },
+    "./stepper": {
+      "types": "./types/masmarino-gabarit-stepper.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-stepper.mjs"
+    },
+    "./switch": {
+      "types": "./types/masmarino-gabarit-switch.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-switch.mjs"
+    },
+    "./table": {
+      "types": "./types/masmarino-gabarit-table.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-table.mjs"
+    },
+    "./tabs": {
+      "types": "./types/masmarino-gabarit-tabs.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-tabs.mjs"
+    },
+    "./tag": {
+      "types": "./types/masmarino-gabarit-tag.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-tag.mjs"
+    },
+    "./tag-input": {
+      "types": "./types/masmarino-gabarit-tag-input.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-tag-input.mjs"
+    },
+    "./textarea": {
+      "types": "./types/masmarino-gabarit-textarea.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-textarea.mjs"
+    },
+    "./timeline-chart": {
+      "types": "./types/masmarino-gabarit-timeline-chart.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-timeline-chart.mjs"
+    },
+    "./toaster": {
+      "types": "./types/masmarino-gabarit-toaster.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-toaster.mjs"
+    },
+    "./tooltip": {
+      "types": "./types/masmarino-gabarit-tooltip.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-tooltip.mjs"
+    },
+    "./tree": {
+      "types": "./types/masmarino-gabarit-tree.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-tree.mjs"
+    },
+    "./user-chip": {
+      "types": "./types/masmarino-gabarit-user-chip.d.ts",
+      "default": "./fesm2022/masmarino-gabarit-user-chip.mjs"
     }
   },
   "peerDependenciesMeta": {

package/page-header/README.md

@@ -0,0 +1,56 @@
+# PageHeader
+
+The heading block at the top of a page: the title (the page's `<h1>`), badges
+on its row, one muted meta line under it and the page's actions on the right.
+Below a title-plus-actions width the actions wrap under the title instead of
+squeezing it.
+
+**Selector**: `gbt-page-header`
+
+## Inputs
+
+| Input          | Type          | Default | Role                                                                                                              |
+| -------------- | ------------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
+| `heading`      | `string`      | —       | Required. The title. It is `heading`, not `title`: a `title` attribute would stay on the host and show a tooltip. |
+| `headingLevel` | `1 \| 2 \| 3` | `1`     | `1` is the page title (once per page). `2` / `3` for a header repeated inside a page, a tab or a dialog.          |
+
+## Slots
+
+| Selector           | Role                                                                                              |
+| ------------------ | ------------------------------------------------------------------------------------------------- |
+| `[header-title]`   | On the title's row, right after it, outside the heading: a `#128` suffix, an icon…                |
+| `[header-badges]`  | Status or visibility badges on the same row. Collapses when empty.                                |
+| `[header-meta]`    | One muted line under the title (author, dates, a description). Collapses when empty.              |
+| `[header-actions]` | Right aligned, level with the title; wraps as a row of its own when narrow. Collapses when empty. |
+
+Empty slots collapse (`:empty`), including a slot filled by an `@if` that is currently false.
+
+## Example
+
+```html
+<gbt-page-header heading="harbor">
+  <gbt-badge header-badges>Public</gbt-badge>
+  <span header-meta>florian · A self-hosted Git forge</span>
+  <gbt-button header-actions variant="secondary" size="small" text="Follow" />
+</gbt-page-header>
+```
+
+An issue page, with a number after the title:
+
+```html
+<gbt-page-header heading="The label picker reloads in a loop">
+  <span header-title class="muted">#128</span>
+  <gbt-badge header-badges variant="success" icon="check">Open</gbt-badge>
+  <span header-meta><gbt-user-chip name="Alice Martin" /> opened this 2 days ago</span>
+</gbt-page-header>
+```
+
+## Layout
+
+The host is a block with a `1.5rem` bottom margin; the header has a hairline
+(`--gbt-hairline`) under it. Give the header the same width as the content
+below it: put both under the same `gbt-page-layout` or the same max-width.
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/page-layout/README.md

@@ -0,0 +1,76 @@
+# PageLayout
+
+The grid a page is built on: a main column, an optional side panel
+(`[page-aside]`) and an optional navigation column (`[page-nav]`, on the
+start side). It centres itself within a maximum width and **responds to the
+width it actually gets** (a container query), not to the window's: inside an
+application shell a 1024 px window leaves ~780 px beside a sidebar, which
+cannot hold a 300 px aside next to readable content.
+
+**Selector**: `gbt-page-layout`
+
+## Inputs
+
+| Input           | Type                                        | Default             | Role                                                                                              |
+| --------------- | ------------------------------------------- | ------------------- | ------------------------------------------------------------------------------------------------- |
+| `width`         | `'narrow' \| 'default' \| 'wide' \| 'full'` | `'default'`         | Max width, centred: 640 px (forms) \| 1200 px \| 1440 px \| none.                                 |
+| `asideWidth`    | `'sm' \| 'md' \| 'lg'`                      | `'md'`              | Aside column: 240 px \| 300 px \| 360 px.                                                         |
+| `asidePosition` | `'start' \| 'end'`                          | `'end'`             | Side of the aside when there is no nav column (with a nav, the aside always goes at the end).     |
+| `navLabel`      | `string`                                    | `'Page navigation'` | Accessible name of the `[page-nav]` landmark (the application shell has its own main navigation). |
+| `asideLabel`    | `string \| null`                            | `null`              | Accessible name of the `[page-aside]` landmark (a complementary region). No name when `null`.     |
+| `stickyNav`     | `boolean`                                   | `false`             | Keeps the nav column in view while a long main column scrolls (from two columns up).              |
+
+## Slots
+
+| Selector       | Role                                                                                                           |
+| -------------- | -------------------------------------------------------------------------------------------------------------- |
+| (default)      | The main column.                                                                                               |
+| `[page-nav]`   | A navigation column on the start side, rendered in a `<nav>` named by `navLabel`.                              |
+| `[page-aside]` | A side column, rendered in an `<aside>`. Typically a stack of [`gbt-panel`](../panel/README.md)s. |
+
+Empty `[page-nav]` and `[page-aside]` are hidden (`:empty`): no column, no gap, no empty landmark.
+The layout adds no `<main>`: the application shell already has one.
+
+## Columns (measured on the layout's own width)
+
+| Layout width   | Columns                                                                                                                              |
+| -------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
+| up to 768 px   | One column: nav, main, aside stacked in DOM order. The stacked aside opens with a hairline.                                          |
+| 769 to 1100 px | Main + aside, or nav + main (with an aside under main). Aside on the `asidePosition` side when there is no nav.                      |
+| from 1101 px   | Nav + main + aside side by side. The aside sticks (`top: 1rem`) while the main column scrolls, and so does the nav with `stickyNav`. |
+
+## Things to know
+
+- **`@if` around a slot**: content projected into `[page-aside]` / `[page-nav]` inside an `@if` needs a
+  **single root element** carrying the attribute: `@if (x) { <div page-aside>…</div> }`.
+- **Never make the layout a shrink-to-fit flex or grid item.** The host is a size container
+  (`container-type: inline-size`), which has no intrinsic width: give it a width or let it fill a block.
+- Header and layout should share a frame: put a `gbt-page-header` inside the same `width`, or use
+  `width="wide"` for both.
+- **Custom column widths**: `--gbt-page-aside-width` (240 / 300 / 360 px from `asideWidth`) and
+  `--gbt-page-nav-width` (240 px) are declared on the host, and setting either on the host (a class of
+  yours, a `style` binding) overrides the column width: `.blob-layout { --gbt-page-nav-width: 280px }`.
+- **Your own responsive rules** query the same container: `@container gbt-page-layout (min-width: 769px)`
+  for anything inside the layout follows the layout's own width, exactly like the layout does.
+
+## Example
+
+```html
+<gbt-page-header heading="harbor" />
+
+<gbt-page-layout width="wide" asideWidth="sm" navLabel="Repository files" [stickyNav]="true">
+  <div page-nav>…files…</div>
+
+  <article>…main content…</article>
+
+  @if (about()) {
+  <div page-aside>
+    <gbt-panel heading="About" [headingLevel]="2">…</gbt-panel>
+  </div>
+  }
+</gbt-page-layout>
+```
+
+## Accessibility
+
+See [AUDIT.md](AUDIT.md).

package/pagination/README.md

@@ -0,0 +1,73 @@
+# Pagination
+
+Page navigation for a long list or table — fully controlled, like
+`AppShell`'s `collapsed`: `Pagination` never slices your data or holds
+its own page state, it only tells you which page the user picked.
+
+**Selector**: `gbt-pagination`
+
+## Inputs
+
+| Input          | Type                         | Default                    | Role                                                                 |
+| -------------- | ---------------------------- | --------------------------- | --------------------------------------------------------------------- |
+| `page`         | `number`                     | `1`                         | The current page (1-indexed). Fully controlled — bind `[(page)]`.    |
+| `pageSize`     | `number`                     | `10`                        | Items per page, used with `totalItems` to compute the page count.   |
+| `totalItems`   | `number`                     | required                    | Total item count across all pages.                                  |
+| `siblingCount` | `number`                     | `1`                         | Page numbers shown on each side of the current page before an ellipsis takes over. |
+| `disabled`     | `boolean`                    | `false`                     | Disables every button and the page-size selector — e.g. while a page fetch is in flight, to prevent a second click from racing it. |
+| `ariaLabel`    | `string`                     | `'Pagination'`               | Accessible name of the `<nav>`.                                     |
+| `previousLabel`| `string`                     | `'Previous page'`            | Accessible name of the previous-page button.                        |
+| `nextLabel`    | `string`                     | `'Next page'`                | Accessible name of the next-page button.                            |
+| `pageLabel`    | `(page: number) => string`   | `` (page) => `Page ${page}` ``| Accessible name of each page-number button.                        |
+| `pageSizeOptions` | `number[]`                | `[]`                         | Page-size choices (e.g. `[10, 20, 30, 50, 100]`). Empty (default) hides the page-size selector entirely. |
+| `pageSizeLabel`   | `(size: number) => string`| `` (size) => `${size} / page` ``| Text for each option in the page-size selector.                  |
+| `pageSizeSelectLabel` | `string`               | `'Rows per page'`             | Visible label of the page-size selector.                          |
+| `showItemsSummary`| `boolean`                 | `false`                       | Shows "N of M items" next to the page-size selector.               |
+| `itemsSummaryLabel`| `(shown: number, total: number) => string` | `` (shown, total) => `${shown} of ${total} items` `` | Text of the items summary — `shown` already accounts for a shorter last page. |
+
+## Outputs
+
+| Output           | Type     | Role                                                          |
+| ---------------- | -------- | --------------------------------------------------------------- |
+| `pageChange`     | `number` | Emitted when a page number, or previous/next, is clicked — `Pagination` does not update `page` itself. Also emitted with `1` right after `pageSizeChange`, and automatically whenever the current `page` ends up outside `[1, pageCount]` (e.g. `totalItems` shrinks under a filter) — `Pagination` self-corrects instead of getting stuck with no page marked current. |
+| `pageSizeChange` | `number` | Emitted when a new page size is picked from the selector — `Pagination` does not update `pageSize` itself. |
+
+## Example
+
+```html
+<gbt-pagination
+  [totalItems]="users.length"
+  [pageSize]="pageSize"
+  [page]="page()"
+  (pageChange)="page.set($event)"
+/>
+```
+
+Long lists get a windowed display with an ellipsis (`1 … 4 5 6 7 8 … 20`)
+instead of every page number — widen or narrow the window with
+`siblingCount`.
+
+With `pageSizeOptions` and `showItemsSummary`: the items summary sits on
+the left, the page-size selector on the right, and the page numbers stay
+truly centered on the row regardless of how wide either side is:
+
+```html
+<gbt-pagination
+  [totalItems]="users.length"
+  [pageSize]="pageSize()"
+  [page]="page()"
+  [pageSizeOptions]="[10, 20, 30, 50, 100]"
+  [showItemsSummary]="true"
+  (pageChange)="page.set($event)"
+  (pageSizeChange)="pageSize.set($event)"
+/>
+```
+
+## With Table
+
+`Table` has no pagination logic of its own — it just renders whatever
+`data` it's given — so it composes with `Pagination` without any extra
+API on either side: slice the full dataset to the current page's slot
+yourself and drive both from the same `page` value. See the `Table`
+story `WithPagination` for a working example.
+

package/panel/README.md

@@ -0,0 +1,56 @@
+# Panel
+
+A flat side-panel section: a small heading, an optional action on its
+right, then the content. It sits on the page background (no card, no
+shadow); consecutive panels are separated by a hairline. Made for the
+`[page-aside]` of [`gbt-page-layout`](../page-layout/README.md)
+(about, metadata, participants, filters…).
+
+**Selector**: `gbt-panel`
+
+## Inputs
+
+| Input          | Type          | Default | Role                                                                                              |
+| -------------- | ------------- | ------- | ------------------------------------------------------------------------------------------------- |
+| `heading`      | `string`      | —       | Required. The small heading; it also names the `<section>` (`aria-labelledby`).                   |
+| `headingLevel` | `2 \| 3 \| 4` | `3`     | `3` under the page's `h1` + section `h2`s; `2` when the panel is a top-level section of the page. |
+
+## Slots
+
+| Selector          | Role                                                                 |
+| ----------------- | -------------------------------------------------------------------- |
+| `[panel-actions]` | Right of the heading (an icon button, a link). Collapses when empty. |
+| (default)         | The panel's content (14 px text in `--text-primary`).                |
+
+## Separator between panels
+
+A panel that directly follows another gets `margin-top: 1rem`, `padding-top: 1rem` and a
+`--gbt-hairline` border on top. Emulated view encapsulation cannot express "a panel after a panel"
+from inside the component, so this is one rule that is not scoped to the component
+(`gbt-panel + gbt-panel`), keyed on the element name. Put other content between two panels and the
+separator is gone: it is the panels' business, not a general divider.
+
+## Example
+
+```html
+<gbt-page-layout>
+  <p>Main content</p>
+
+  <div page-aside>
+    <gbt-panel heading="About" [headingLevel]="2">
+      <p>A self-hosted Git forge.</p>
+    </gbt-panel>
+    <gbt-panel heading="Contributors" [headingLevel]="2">
+      <gbt-button panel-actions variant="ghost" size="small" text="See all" />
+      <gbt-user-chip name="Alice Martin" />
+    </gbt-panel>
+  </div>
+</gbt-page-layout>
+```
+
+## Accessibility
+
+Each panel is a `<section>` labelled by its heading, so it is a named
+region for screen reader users. Pick `headingLevel` so the panels fit your
+outline (`2` for the panels of an aside next to a page `h1`, `3` inside a
+section). See [AUDIT.md](AUDIT.md).