@frame-kit/ui-ng 0.0.1

package/ui/numbered-list/README.md

@@ -0,0 +1,187 @@
+# fk-numbered-list
+
+A token-driven numbered list for ordered procedures and step-by-step instructions. Ships as a pair: `fk-numbered-list` is the container, `fk-numbered-list-item` is the renderable row — use either a data-driven `items` input or content projection with `<fk-numbered-list-item>` children. Numbering is automatic via CSS counters.
+
+---
+
+## API
+
+### `fk-numbered-list`
+
+#### Inputs
+
+| Input       | Type                                  | Default | Description                                                                         |
+| ----------- | ------------------------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `items`     | `readonly NumberedListItem[] \| null` | `null`  | Data-driven rows. When `null`, the list projects `<fk-numbered-list-item>` children |
+| `size`      | `NumberedListSize`                    | `"md"`  | Default size inherited by items: `"sm"`, `"md"`, `"lg"`                             |
+| `className` | `string`                              | `''`    | Additional CSS classes merged onto the host element                                 |
+| `id`        | `string \| null`                      | `null`  | Optional ID applied to the inner `role="list"` container                            |
+| `ariaLabel` | `string \| null`                      | `null`  | Accessible label on the inner `role="list"` container                               |
+
+### `fk-numbered-list-item`
+
+#### Inputs
+
+| Input       | Type                       | Default | Description                                              |
+| ----------- | -------------------------- | ------- | -------------------------------------------------------- |
+| `size`      | `NumberedListSize \| null` | `null`  | Per-item size override. Falls through to the parent list |
+| `className` | `string`                   | `''`    | Additional CSS classes merged onto the host element      |
+| `id`        | `string \| null`           | `null`  | Optional ID applied to the host element                  |
+| `ariaLabel` | `string \| null`           | `null`  | Accessible label when the label alone is insufficient    |
+
+#### Content
+
+`fk-numbered-list-item` projects its label content:
+
+```html
+<fk-numbered-list-item>Your step text here</fk-numbered-list-item>
+```
+
+### Outputs
+
+None on either component.
+
+---
+
+## Features
+
+- Two usage modes — data-driven (`items` input) or content-projection (`<fk-numbered-list-item>` children)
+- Automatic numbering via CSS counters — no manual index tracking
+- Items inherit the list's `size` via element-injector DI; the per-item `size` input overrides the parent
+- Three size steps that scale label typography
+- Semantic `role="list"` / `role="listitem"` pairing; item roles are only advertised when inside an `fk-numbered-list` container, so standalone items don't announce orphan list semantics
+
+---
+
+## Quick Start
+
+Data-driven:
+
+```html
+<fk-numbered-list [items]="steps" />
+```
+
+```ts
+readonly steps = [
+  { label: "Open the page" },
+  { label: "Click the button" },
+  { label: "Confirm the change" },
+];
+```
+
+Content-projection:
+
+```html
+<fk-numbered-list>
+  <fk-numbered-list-item>Open the page</fk-numbered-list-item>
+  <fk-numbered-list-item>Click the button</fk-numbered-list-item>
+  <fk-numbered-list-item>Confirm the change</fk-numbered-list-item>
+</fk-numbered-list>
+```
+
+---
+
+## Import
+
+```ts
+import { NumberedListComponent, NumberedListItemComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [NumberedListComponent, NumberedListItemComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selectors
+
+```html
+<fk-numbered-list></fk-numbered-list> <fk-numbered-list-item></fk-numbered-list-item>
+```
+
+---
+
+## Examples
+
+### Procedure with data-driven items
+
+```html
+<fk-numbered-list [items]="steps" />
+```
+
+### Sizing
+
+```html
+<fk-numbered-list [items]="steps" size="sm" />
+<fk-numbered-list [items]="steps" size="md" />
+<fk-numbered-list [items]="steps" size="lg" />
+```
+
+### Mixed sizes per item
+
+```html
+<fk-numbered-list size="md">
+  <fk-numbered-list-item>Standard step</fk-numbered-list-item>
+  <fk-numbered-list-item size="lg">A larger emphasised step</fk-numbered-list-item>
+  <fk-numbered-list-item>Standard step</fk-numbered-list-item>
+</fk-numbered-list>
+```
+
+---
+
+## Accessibility
+
+- `fk-numbered-list` renders `<div role="list">` so list semantics survive the `list-style: none` reset (Safari otherwise strips the implicit list role).
+- `fk-numbered-list-item` sets `role="listitem"` only when nested inside an `fk-numbered-list` — this avoids announcing orphan list items when the component is used standalone.
+- The number badge is generated by a CSS counter on a pseudo-element marked `aria-hidden="true"` — the projected label is the assistive-tech-readable content. Screen readers announce the list items in order via the parent's list role.
+- Set `ariaLabel` on the list when the surrounding context doesn't already name the procedure.
+
+---
+
+## Design Tokens
+
+```scss
+/* Container */
+--fk-numbered-list-margin-top;
+--fk-numbered-list-row-gap;
+
+/* Item */
+--fk-numbered-list-item-gap;
+--fk-numbered-list-item-color;
+--fk-numbered-list-item-line-height;
+
+--fk-numbered-list-item-sm-font-size;
+--fk-numbered-list-item-md-font-size;
+--fk-numbered-list-item-lg-font-size;
+
+/* Number badge */
+--fk-numbered-list-badge-size;
+--fk-numbered-list-badge-radius;
+--fk-numbered-list-badge-bg;
+--fk-numbered-list-badge-color;
+--fk-numbered-list-badge-font-size;
+--fk-numbered-list-badge-font-weight;
+```
+
+Override in your app stylesheet:
+
+```scss
+:root {
+  --fk-numbered-list-row-gap: 1rem;
+  --fk-numbered-list-badge-bg: var(--fk-color-success-light);
+  --fk-numbered-list-badge-color: var(--fk-color-success);
+}
+```
+
+---
+
+## Behavior Notes
+
+- Data-driven mode internally renders `fk-numbered-list-item` per row, so the DOM is identical whether you use `[items]` or content projection.
+- Numbering is purely visual via CSS counters. Each new `fk-numbered-list` instance restarts the counter at 1, so multiple lists on the same page each number from one independently.
+- The default top margin (`--fk-numbered-list-margin-top`) matches `fk-icon-list` so vertical rhythm is consistent when the two are used side by side in the same docs section.

package/ui/pagination/README.md

@@ -0,0 +1,174 @@
+# fk-pagination
+
+A table/list pagination control with page navigation, page-size selector, and range summary.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type             | Default             | Description                                          |
+| ----------------- | ---------------- | ------------------- | ---------------------------------------------------- |
+| `page`            | `number`         | **required**        | Current page number (1-based)                        |
+| `take`            | `number`         | **required**        | Number of items per page                             |
+| `itemCount`       | `number`         | **required**        | Total number of items across all pages               |
+| `pageSizeOptions` | `number[]`       | `[10, 20, 50, 100]` | Options shown in the "Rows per page" dropdown        |
+| `showFirstLast`   | `boolean`        | `false`             | Show "First page" and "Last page" navigation buttons |
+| `className`       | `string`         | `''`                | Additional CSS classes for the host element          |
+| `id`              | `string \| null` | `null`              | ID bound to the host element                         |
+| `ariaLabel`       | `string \| null` | `null`              | `aria-label` bound to the host element               |
+
+### Outputs
+
+| Output       | Type              | Description                                            |
+| ------------ | ----------------- | ------------------------------------------------------ |
+| `pageChange` | `PageChangeEvent` | Emitted on page or page-size change (`{ page, take }`) |
+
+---
+
+## Features
+
+- Displays a human-readable range summary (e.g. "1 -- 20 of 100")
+- Previous / Next navigation buttons with automatic disabled state
+- Optional First / Last page buttons via `showFirstLast`
+- Built-in "Rows per page" dropdown with configurable options
+- Page resets to 1 when page size changes
+- Unique auto-generated ID for the page-size select element
+- Token-driven styling for full theme customization
+
+---
+
+## Quick Start
+
+```html
+<fk-pagination [page]="currentPage" [take]="pageSize" [itemCount]="totalItems" (pageChange)="onPageChange($event)"></fk-pagination>
+```
+
+```ts
+onPageChange(event: PageChangeEvent): void {
+  this.currentPage = event.page;
+  this.pageSize = event.take;
+  this.loadData();
+}
+```
+
+---
+
+## Import
+
+```ts
+import { PaginationComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [PaginationComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-pagination></fk-pagination>
+```
+
+---
+
+## Examples
+
+### Basic pagination
+
+```html
+<fk-pagination [page]="page" [take]="take" [itemCount]="totalItems" (pageChange)="onPageChange($event)"></fk-pagination>
+```
+
+### With first/last buttons
+
+```html
+<fk-pagination [page]="page" [take]="take" [itemCount]="totalItems" [showFirstLast]="true" (pageChange)="onPageChange($event)"></fk-pagination>
+```
+
+### Custom page size options
+
+```html
+<fk-pagination [page]="page" [take]="take" [itemCount]="totalItems" [pageSizeOptions]="[5, 25, 50]" (pageChange)="onPageChange($event)"></fk-pagination>
+```
+
+---
+
+## Accessibility
+
+- Navigation buttons use `aria-label` attributes ("Previous page", "Next page", "First page", "Last page")
+- The navigation wrapper has `role="navigation"` with `aria-label="Pagination"`
+- Arrow SVGs are marked `aria-hidden="true"`
+- The page-size `<select>` is associated with its label via a unique auto-generated `id`
+- Disabled buttons use the native `disabled` attribute
+
+---
+
+## Design Tokens
+
+```scss
+/* Layout */
+--fk-pagination-gap
+--fk-pagination-padding
+--fk-pagination-padding-inline
+--fk-pagination-controls-gap
+--fk-pagination-nav-gap
+
+/* Typography */
+--fk-pagination-font-family
+--fk-pagination-font-size
+--fk-pagination-color
+--fk-pagination-label-color
+--fk-pagination-page-info-color
+--fk-pagination-page-info-min-width
+
+/* Border */
+--fk-pagination-border-width
+--fk-pagination-border-color
+
+/* Page-size select */
+--fk-pagination-select-padding-block
+--fk-pagination-select-padding-left
+--fk-pagination-select-padding-right
+--fk-pagination-select-chevron-offset
+--fk-pagination-select-color
+--fk-pagination-select-bg
+--fk-pagination-select-border-color
+--fk-pagination-select-border-radius
+--fk-pagination-select-focus-border-color
+--fk-pagination-select-focus-ring
+
+/* Navigation buttons */
+--fk-pagination-btn-size
+--fk-pagination-btn-color
+--fk-pagination-btn-bg
+--fk-pagination-btn-bg-hover
+--fk-pagination-btn-border-color
+--fk-pagination-btn-border-color-hover
+--fk-pagination-btn-border-radius
+--fk-pagination-btn-disabled-opacity
+--fk-pagination-btn-focus-border-color
+--fk-pagination-btn-focus-ring
+
+/* Arrow icon */
+--fk-pagination-arrow-size
+```
+
+---
+
+## Behavior Notes
+
+- `pageCount` is always >= 1. When `itemCount` is 0, `pageCount` is 1 (not 0) so the UI shows "1 / 1" rather than "1 / 0". This matches the backend `PageMetaDto` contract
+- `rangeStart` returns 0 when `itemCount` is 0, otherwise `(page - 1) * take + 1`
+- `rangeEnd` is clamped to `itemCount` so the last page never overshoots the total
+- Navigation methods (`goToNext`, `goToPrevious`, `goToFirst`, `goToLast`) are no-ops when the target page is out of bounds
+- Changing the page size always resets `page` to 1 in the emitted event
+- Each component instance receives a unique select ID (`fk-pagination-take-<n>`) via an incrementing module-level counter

package/ui/progress-bar/README.md

@@ -0,0 +1,223 @@
+# fk-progress-bar
+
+A token-driven progress bar component for indicating how far along a single task or process is, with determinate and indeterminate modes.
+
+---
+
+## API
+
+### Inputs
+
+| Input             | Type                                              | Default         | Description                                    |
+| ----------------- | ------------------------------------------------- | --------------- | ---------------------------------------------- |
+| `value`           | `number`                                          | `0`             | Current value, clamped to 0–max                |
+| `max`             | `number`                                          | `100`           | Maximum value                                  |
+| `mode`            | `'determinate' \| 'indeterminate'`                | `'determinate'` | Bar mode                                       |
+| `size`            | `'sm' \| 'md' \| 'lg'`                            | `'md'`          | Bar height preset                              |
+| `variant`         | `'default' \| 'success' \| 'warning' \| 'danger'` | `'default'`     | Semantic color variant                         |
+| `color`           | `string \| null`                                  | `null`          | Custom fill color (overrides variant)          |
+| `trackColor`      | `string \| null`                                  | `null`          | Custom track/background color                  |
+| `height`          | `string \| null`                                  | `null`          | Custom height (e.g. `'4px'`), overrides `size` |
+| `showValue`       | `boolean`                                         | `false`         | Show percentage label beside the bar           |
+| `striped`         | `boolean`                                         | `false`         | Animated stripe pattern on the fill            |
+| `ariaLabel`       | `string \| null`                                  | `null`          | Accessible label                               |
+| `ariaDescribedBy` | `string \| null`                                  | `null`          | ARIA described-by ID                           |
+| `id`              | `string \| null`                                  | `null`          | Element ID                                     |
+| `className`       | `string`                                          | `''`            | Additional CSS classes merged onto the host    |
+
+### Outputs
+
+None.
+
+---
+
+## Features
+
+- Determinate and indeterminate modes
+- Three size presets (sm, md, lg) plus custom height override
+- Four semantic color variants plus custom color override
+- Animated stripe pattern
+- Optional percentage label
+- Token-driven styling with two-tier fallbacks
+- Full ARIA progressbar semantics
+- Respects `prefers-reduced-motion`
+
+---
+
+## Quick Start
+
+```html
+<fk-progress-bar [value]="45"></fk-progress-bar>
+```
+
+---
+
+## Import
+
+```ts
+import { ProgressBarComponent } from '@frame-kit/ui-ng';
+```
+
+```ts
+@Component({
+  selector: 'app-example',
+  imports: [ProgressBarComponent],
+  templateUrl: './example.component.html',
+})
+export class ExampleComponent {}
+```
+
+---
+
+## Selector
+
+```html
+<fk-progress-bar></fk-progress-bar>
+```
+
+---
+
+## Examples
+
+### Default
+
+```html
+<fk-progress-bar [value]="60"></fk-progress-bar>
+```
+
+### With percentage label
+
+```html
+<fk-progress-bar [value]="72" [showValue]="true"></fk-progress-bar>
+```
+
+### Sizes
+
+```html
+<fk-progress-bar [value]="60" size="sm"></fk-progress-bar>
+<fk-progress-bar [value]="60" size="md"></fk-progress-bar>
+<fk-progress-bar [value]="60" size="lg"></fk-progress-bar>
+```
+
+### Semantic variants
+
+```html
+<fk-progress-bar [value]="80" variant="success"></fk-progress-bar>
+<fk-progress-bar [value]="50" variant="warning"></fk-progress-bar>
+<fk-progress-bar [value]="30" variant="danger"></fk-progress-bar>
+```
+
+### Striped
+
+```html
+<fk-progress-bar [value]="65" [striped]="true"></fk-progress-bar>
+```
+
+### Indeterminate
+
+```html
+<fk-progress-bar mode="indeterminate"></fk-progress-bar>
+```
+
+### Custom colors
+
+```html
+<fk-progress-bar [value]="50" color="#8b5cf6" trackColor="#ede9fe"></fk-progress-bar>
+```
+
+### Custom max
+
+```html
+<fk-progress-bar [value]="3" [max]="10" [showValue]="true"></fk-progress-bar>
+```
+
+---
+
+## Accessibility
+
+`fk-progress-bar` applies `role="progressbar"` on the host element with full ARIA value attributes.
+
+Accessibility behavior:
+
+- `aria-valuemin`, `aria-valuemax`, and `aria-valuenow` reflect current state
+- `aria-valuetext` provides a human-readable value (e.g. "45%" or "Loading...")
+- In indeterminate mode, `aria-valuenow`, `aria-valuemax`, and `aria-valuemin` are removed
+- Supports `ariaLabel` and `ariaDescribedBy` for additional context
+
+### Recommended
+
+```html
+<fk-progress-bar [value]="progress" ariaLabel="Upload progress"></fk-progress-bar>
+```
+
+---
+
+## Design Tokens
+
+`fk-progress-bar` is styled entirely through design tokens.
+
+### Component-specific tokens
+
+```
+--fk-progress-bar-height-sm
+--fk-progress-bar-height-md
+--fk-progress-bar-height-lg
+--fk-progress-bar-radius
+--fk-progress-bar-bg
+--fk-progress-bar-fill
+--fk-progress-bar-fill-success
+--fk-progress-bar-fill-warning
+--fk-progress-bar-fill-danger
+--fk-progress-bar-label-color
+--fk-progress-bar-label-size
+--fk-progress-bar-label-weight
+--fk-progress-bar-label-gap
+--fk-progress-bar-transition
+--fk-progress-bar-animation-duration
+```
+
+### Shared tokens
+
+```
+--fk-color-primary
+--fk-color-success
+--fk-color-warning
+--fk-color-danger
+--fk-color-surface-muted
+--fk-color-text
+--fk-radius-full
+--fk-rhythm-1
+--fk-rhythm-2
+--fk-rhythm-3
+--fk-typography-caption-font-size
+--fk-font-weight-medium
+```
+
+### Customizing Tokens
+
+Override tokens in your application's stylesheet:
+
+```scss
+:root {
+  --fk-progress-bar-fill: #6366f1;
+  --fk-progress-bar-radius: 4px;
+  --fk-progress-bar-height-md: 0.75rem;
+}
+```
+
+Or scope overrides to a specific context:
+
+```scss
+.compact-layout fk-progress-bar {
+  --fk-progress-bar-height-md: 0.25rem;
+}
+```
+
+---
+
+## Behavior Notes
+
+- Values are clamped to the range 0–max; negative values resolve to 0, values above max resolve to max
+- When `max` is 0, percentage resolves to 0 to avoid division by zero
+- `color` input overrides the variant fill color via inline style
+- Stripe and indeterminate animations are disabled when `prefers-reduced-motion: reduce` is active