@edsis/ui 0.0.2

package/pagination/README.md

@@ -0,0 +1,144 @@
+# Pagination
+
+Compact page navigation with previous and next controls, windowed page numbers, optional icon-only mode, and localized labels.
+
+Use Pagination when a feature page needs to move through a paged API result, a dense table footer, or a navigable list of routes or guides.
+
+## Import
+
+```ts
+import { PaginationComponent } from '@edsis/ui/pagination';
+```
+
+## Structure
+
+The Angular package intentionally wraps the shadcn multi-part composition in a single standalone primitive.
+
+```text
+ui-pagination
+├── previous button
+├── page buttons and ellipsis
+└── next button
+```
+
+## Basic usage
+
+Bind `[(page)]` to a signal and keep your collection, router state, or server request outside the primitive.
+
+```html
+<ui-pagination [(page)]="currentPage" [total]="totalPages" [siblingCount]="1" (pageChange)="load($event)" />
+```
+
+## Common patterns
+
+### Navigation data
+
+Keep the rendered collection in sync with the pager through `computed()`.
+
+```ts
+const navigationPage = signal(1);
+const pageSize = 4;
+
+const navigationItems = [
+  { title: 'Introduction', route: '/docs/introduction' },
+  { title: 'Accordion', route: '/ui/shadcn/accordion' },
+  { title: 'Button', route: '/ui/shadcn/button' },
+  { title: 'Input', route: '/ui/shadcn/input' },
+  // ...more items
+];
+
+const totalPages = Math.ceil(navigationItems.length / pageSize);
+const visibleItems = computed(() => {
+  const start = (navigationPage() - 1) * pageSize;
+  return navigationItems.slice(start, start + pageSize);
+});
+```
+
+### Icons only
+
+Hide page numbers and visible labels when the pager sits next to a dense table or feed footer.
+
+```html
+<ui-pagination
+  [(page)]="compactPage"
+  [total]="9"
+  [showPageNumbers]="false"
+  previousText=""
+  nextText=""
+  class="mx-0 w-auto" />
+```
+
+### RTL and translated labels
+
+Translate the previous and next text and provide a page formatter when locale-specific numerals should appear.
+
+```ts
+const arabicDigits = ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩'];
+const toArabicNumerals = (page: number): string =>
+  page
+    .toString()
+    .split('')
+    .map((digit) => arabicDigits[Number(digit)] ?? digit)
+    .join('');
+```
+
+```html
+<section dir="rtl" lang="ar" class="text-right">
+  <ui-pagination
+    [(page)]="rtlPage"
+    [total]="7"
+    previousText="السابق"
+    nextText="التالي"
+    previousAriaLabel="الانتقال إلى الصفحة السابقة"
+    nextAriaLabel="الانتقال إلى الصفحة التالية"
+    [formatPageLabel]="toArabicNumerals" />
+</section>
+```
+
+## API reference
+
+| Input               | Type                       | Default                   | Description                                                            |
+| ------------------- | -------------------------- | ------------------------- | ---------------------------------------------------------------------- |
+| `page` (model)      | `number`                   | `1`                       | Two-way bound current page.                                            |
+| `total`             | `number`                   | `1`                       | Total number of pages available.                                       |
+| `siblingCount`      | `number`                   | `1`                       | Page buttons shown on either side of the active page.                  |
+| `showPageNumbers`   | `boolean`                  | `true`                    | Hide numbered page buttons for compact previous and next only layouts. |
+| `previousText`      | `string`                   | `'Previous'`              | Visible previous label. Set to an empty string for icon-only mode.     |
+| `nextText`          | `string`                   | `'Next'`                  | Visible next label. Set to an empty string for icon-only mode.         |
+| `previousAriaLabel` | `string`                   | `'Go to previous page'`   | Accessible name for the previous button.                               |
+| `nextAriaLabel`     | `string`                   | `'Go to next page'`       | Accessible name for the next button.                                   |
+| `formatPageLabel`   | `(page: number) => string` | `page => page.toString()` | Formats the rendered page label.                                       |
+| `class`             | `string`                   | `''`                      | Extra container classes.                                               |
+
+| Output       | Payload  | Description                                          |
+| ------------ | -------- | ---------------------------------------------------- |
+| `pageChange` | `number` | Emits the next page number after a user interaction. |
+
+## Styling and theming
+
+Pagination reuses `buttonVariants`, so the previous and next controls plus numbered page buttons inherit the same shape, focus ring, and theme tokens as the Button primitive.
+
+Pass `class` to adjust width and alignment, for example `mx-0 w-auto` in a table footer or `justify-start` when the pager should align to the left edge of a card.
+
+## Accessibility
+
+- The root renders as `<nav role="navigation" aria-label="pagination">`.
+- The active page is marked with `aria-current="page"`.
+- Previous and next disable natively at the start and end of the available range.
+- Ellipses are `aria-hidden="true"`.
+- When visible text is removed for icon-only mode, keep meaningful aria labels on the previous and next buttons.
+
+## Keyboard interactions
+
+- Tab moves focus through the previous button, page buttons, and next button in DOM order.
+- Enter and Space activate the focused button through native button semantics.
+
+## Angular notes
+
+- Keep the paged collection outside the component and derive the visible slice with `computed()`.
+- Import `PaginationComponent` into the standalone feature component that renders the pager.
+- `showPageNumbers`, `previousText`, `nextText`, and `formatPageLabel` are deliberate Angular-specific conveniences that cover the upstream icon-only and RTL guidance without exposing React-style child parts.
+
+## Source parity
+
+shadcn documents Pagination as several composable parts such as `PaginationLink`, `PaginationPrevious`, and `PaginationNext`. This Angular implementation intentionally collapses that structure into one primitive so route-driven and data-driven pagination can be wired quickly while still matching the upstream previous, next, ellipsis, compact, and RTL behavior.

package/pillbox/README.md

@@ -0,0 +1,67 @@
+# Pillbox
+
+Multi-value selection primitives inspired by Flux Pillbox and implemented with local shadcn-style Angular patterns.
+
+## Import
+
+```ts
+import {
+  PillboxComponent,
+  PillboxOptionComponent,
+  PillboxOptionCreateComponent,
+  PillboxOptionEmptyComponent,
+  PillboxSelectedDirective,
+} from '@edsis/ui/pillbox';
+```
+
+## Usage
+
+```html
+<ui-pillbox multiple placeholder="Choose tags..." [(ngModel)]="selectedTags">
+  <ui-pillbox-option value="design">Design</ui-pillbox-option>
+  <ui-pillbox-option value="development">Development</ui-pillbox-option>
+  <ui-pillbox-option value="marketing">Marketing</ui-pillbox-option>
+</ui-pillbox>
+```
+
+## Composition
+
+- `ui-pillbox` owns the trigger, selected pills, search state, option filtering, and form control integration.
+- `ui-pillbox-option` projects the visible option content and stores the option value.
+- `ng-template[uiPillboxSelected]` customizes the rendered selected pill content for an option.
+- `ui-pillbox-option-create` emits create requests when the search query is long enough and does not match an existing option.
+- `ui-pillbox-option-empty` customizes empty and loading messages.
+
+## Inputs
+
+### PillboxComponent
+
+| Input               | Type                      | Default               | Description                                                                |
+| ------------------- | ------------------------- | --------------------- | -------------------------------------------------------------------------- |
+| `placeholder`       | `string`                  | `'Choose options...'` | Text shown when nothing is selected.                                       |
+| `searchPlaceholder` | `string`                  | `'Search...'`         | Placeholder for the dropdown search input.                                 |
+| `size`              | `'default' \| 'sm'`       | `'default'`           | Trigger and pill density.                                                  |
+| `variant`           | `'default' \| 'combobox'` | `'default'`           | Use `combobox` to place the search input directly in the trigger.          |
+| `multiple`          | `boolean`                 | `false`               | Emits an array of selected values when enabled.                            |
+| `searchable`        | `boolean`                 | `false`               | Adds a search input to the dropdown for the default variant.               |
+| `filter`            | `boolean`                 | `true`                | Enables client-side filtering. Disable it for backend-driven option lists. |
+| `clearable`         | `boolean`                 | `true`                | Shows a clear-all control when values are selected.                        |
+| `disabled`          | `boolean`                 | `false`               | Prevents interaction.                                                      |
+| `invalid`           | `boolean`                 | `false`               | Applies error styling and `aria-invalid`.                                  |
+| `loading`           | `boolean`                 | `false`               | Shows loading copy through the empty option when no options match.         |
+
+## Events
+
+| Output         | Payload   | Description                                                               |
+| -------------- | --------- | ------------------------------------------------------------------------- |
+| `valueChange`  | `unknown` | Emits the selected array for `multiple` mode or a single value otherwise. |
+| `searchChange` | `string`  | Emits whenever the search query changes.                                  |
+| `create`       | `string`  | Emits the current query from `ui-pillbox-option-create`.                  |
+| `openedChange` | `boolean` | Emits when the option list opens or closes.                               |
+
+## Accessibility
+
+- Use a visible label or `aria-label`/`aria-labelledby` on `ui-pillbox`.
+- Use `multiple` when binding to an array of values.
+- Provide readable option labels; set `label` or `selectedLabel` when custom option content is not textual.
+- Keep create actions explicit and validate new values in the owning form or backend.

package/popover/README.md

@@ -0,0 +1,43 @@
+# Popover
+
+Anchored floating panel with CDK overlay. Click the trigger to toggle.
+
+## Import
+
+```ts
+import { PopoverTriggerDirective, PopoverContentDirective } from '@edsis/ui/popover';
+```
+
+## Usage
+
+```html
+<button ui-button [uiPopoverTrigger]="content" side="bottom" align="start">Open</button>
+
+<ng-template uiPopoverContent #content="uiPopoverContent">
+  <div class="w-64 rounded-md border bg-popover p-4 text-popover-foreground shadow-md">Popover body</div>
+</ng-template>
+```
+
+## API
+
+### `PopoverTriggerDirective` (`[uiPopoverTrigger]`)
+
+| Input              | Type                                     | Default    |
+| ------------------ | ---------------------------------------- | ---------- |
+| `uiPopoverTrigger` | `PopoverContentDirective`                | —          |
+| `side`             | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` |
+| `align`            | `'start' \| 'center' \| 'end'`           | `'center'` |
+| `disabled`         | `boolean`                                | `false`    |
+
+Exposes `isOpen()` signal. Trigger automatically sets `aria-haspopup="dialog"`
+and `aria-expanded` on the host.
+
+### `PopoverContentDirective` (`ng-template[uiPopoverContent]`)
+
+Marker directive that exposes the template via `exportAs="uiPopoverContent"`.
+
+## Accessibility
+
+- Close on `Escape`.
+- Close on backdrop click.
+- Trigger reflects state via `aria-expanded` and `aria-haspopup`.

package/progress/README.md

@@ -0,0 +1,160 @@
+# Progress
+
+Displays an indicator showing the completion progress of a task, typically as a
+slim passive progress bar.
+
+Use Progress for uploads, background jobs, onboarding steps, and other cases
+where the user should understand status without directly interacting with the
+bar itself.
+
+## Import
+
+```ts
+import { ProgressComponent } from '@edsis/ui/progress';
+```
+
+For the visible label and slider-driven examples below, also import the existing
+label and slider entrypoints:
+
+```ts
+import { LabelComponent } from '@edsis/ui/label';
+import { SliderComponent } from '@edsis/ui/slider';
+```
+
+## Basic usage
+
+Provide an accessible name directly when the bar stands on its own.
+
+```html
+<ui-progress [value]="33" aria-label="Upload progress" class="w-full max-w-sm" />
+```
+
+## Common patterns
+
+### Visible label row
+
+The current shadcn Radix docs place Progress inside a Field layout with a
+visible label and percentage. In Angular, keep the visible copy outside the
+bar and connect it with `aria-labelledby`.
+
+```html
+<ui-label id="progress-upload-label" class="mb-2 flex items-center gap-3">
+  <span>Upload progress</span>
+  <span class="ms-auto text-muted-foreground">66%</span>
+</ui-label>
+
+<ui-progress [value]="66" aria-labelledby="progress-upload-label" class="w-full max-w-sm" />
+```
+
+Use `aria-labelledby` here instead of `label[for]`, because `ui-progress` is a
+custom element with `role="progressbar"`, not a native labelable form control.
+
+### Controlled progress
+
+Keep the progress bar passive and let surrounding controls own the interaction.
+The built-in range slider directive works well for the same pattern shown in the
+upstream docs.
+
+```ts
+const controlledValue = signal(50);
+
+<ui-label id="progress-controlled-label" class="mb-2 flex items-center gap-3">
+  <span>Upload progress</span>
+  <span class="ms-auto text-muted-foreground">{{ controlledValue() }}%</span>
+</ui-label>
+
+<ui-progress [value]="controlledValue()" aria-labelledby="progress-controlled-label" class="w-full" />
+
+<ui-label for="progress-controlled-slider" class="mb-2 block">Adjust progress</ui-label>
+<input
+  id="progress-controlled-slider"
+  type="range"
+  ui-slider
+  min="0"
+  max="100"
+  step="1"
+  [value]="controlledValue()"
+  (input)="onControlledInput($event)" />
+```
+
+### Indeterminate loading
+
+Switch to `indeterminate` when work is running but no stable percentage is
+available yet.
+
+```html
+<ui-progress [indeterminate]="true" aria-label="Loading deployment" class="w-full max-w-sm" />
+```
+
+### RTL
+
+Follow the upstream guidance by setting `dir="rtl"` on the surrounding
+container and flipping the bar with `rtl:rotate-180`.
+
+```html
+<section dir="rtl" lang="ar" class="w-full max-w-sm text-right">
+  <ui-label id="progress-rtl-label" class="mb-2 flex items-center gap-3">
+    <span>تقدم الرفع</span>
+    <span class="ms-auto text-muted-foreground">٦٦%</span>
+  </ui-label>
+
+  <ui-progress [value]="66" aria-labelledby="progress-rtl-label" class="w-full rtl:rotate-180" />
+</section>
+```
+
+## API reference
+
+| Input             | Type             | Default |
+| ----------------- | ---------------- | ------- |
+| `value`           | `number \| null` | `0`     |
+| `max`             | `number`         | `100`   |
+| `indeterminate`   | `boolean`        | `false` |
+| `aria-label`      | `string \| null` | `null`  |
+| `aria-labelledby` | `string \| null` | `null`  |
+| `class`           | `string`         | `''`    |
+
+Native host attributes such as `id`, `dir`, and `data-*` still pass through to
+the rendered custom element and can be used for surrounding composition.
+
+## Styling and theming
+
+Tokens consumed:
+
+- `--secondary` for the track.
+- `--primary` for the indicator.
+
+Use the `class` input for width and layout utilities such as `w-full`,
+`max-w-sm`, or `rtl:rotate-180`. Indeterminate state is animated via a CSS
+keyframe that respects `prefers-reduced-motion`.
+
+## Accessibility
+
+- Host is `role="progressbar"`.
+- Determinate mode sets `aria-valuemin="0"`, `aria-valuemax="max"`, and
+  `aria-valuenow="clamped value"`.
+- Indeterminate mode omits `aria-valuenow` and adds `data-state="indeterminate"`.
+- Always provide an accessible name via `aria-label` or `aria-labelledby`.
+- If visible label text already exists on the page, connect it with
+  `aria-labelledby` instead of relying on native label semantics.
+
+## Keyboard interactions
+
+Progress is passive and not focusable by default. Any keyboard interaction
+belongs to surrounding controls such as the slider used in the controlled
+example.
+
+## Angular notes
+
+- Keep Progress focused on status display. Do not nest buttons or other
+  interactive controls inside the bar.
+- Drive determinate state from signals, reactive forms, or any other existing
+  Angular state source.
+- For visible label rows, `ui-label` is a good lightweight companion, but plain
+  text with the right ARIA wiring works too.
+
+## Source parity
+
+This Angular implementation follows the shadcn Radix progress examples while
+translating `Field` and `FieldLabel` to ordinary Angular markup plus explicit
+ARIA wiring. The controlled example reuses the existing range slider directive,
+and the RTL pattern matches the upstream `rtl:rotate-180` approach.

package/radio/README.md

@@ -0,0 +1,209 @@
+# Radio Group
+
+Accessible exclusive-choice control composed from `ui-radio-group` and `ui-radio`.
+
+## Import
+
+```ts
+import {
+  FormContentComponent,
+  FormDescriptionComponent,
+  FormFieldComponent,
+  FormFieldsetComponent,
+  FormLegendComponent,
+  FormTitleComponent,
+} from '@edsis/ui/form';
+import { LabelComponent } from '@edsis/ui/label';
+import { RadioComponent, RadioGroupComponent } from '@edsis/ui/radio';
+```
+
+## Composition
+
+The upstream shadcn `RadioGroup` examples map to the existing Angular radio and form primitives.
+
+```text
+ui-radio-group
+├── label[ui-label]
+│   ├── ui-radio
+│   └── ui-form-content
+│       ├── ui-form-title
+│       └── p[ui-form-description]
+└── label[ui-label]
+    ├── ui-radio
+    └── copy or ui-form-content
+```
+
+## Basic Usage
+
+Use `ui-radio-group` as the value owner and wrap each option in `label[ui-label]` when the whole row should toggle the radio.
+
+```html
+<ui-radio-group name="density" [(ngModel)]="density" class="w-fit">
+  <label ui-label class="flex items-center gap-3">
+    <ui-radio value="default" />
+    <span>Default</span>
+  </label>
+  <label ui-label class="flex items-center gap-3">
+    <ui-radio value="comfortable" />
+    <span>Comfortable</span>
+  </label>
+  <label ui-label class="flex items-center gap-3">
+    <ui-radio value="compact" />
+    <span>Compact</span>
+  </label>
+</ui-radio-group>
+```
+
+Reactive forms also work because the group implements `ControlValueAccessor`.
+
+## Common Patterns
+
+### Descriptive rows
+
+Map the shadcn `Field` and `FieldContent` helpers to `ui-form-field` and `ui-form-content`.
+
+```html
+<ui-radio-group name="density" [(ngModel)]="density" class="w-full max-w-md">
+  <label ui-label class="block rounded-xl border border-border bg-card/40 p-4">
+    <ui-form-field orientation="horizontal" class="gap-4">
+      <ui-radio value="default" />
+      <ui-form-content>
+        <ui-form-title>Default</ui-form-title>
+        <p ui-form-description>Standard spacing for most use cases.</p>
+      </ui-form-content>
+    </ui-form-field>
+  </label>
+</ui-radio-group>
+```
+
+### Choice cards
+
+Wrap each plan card in `label[ui-label]` so the full surface toggles the choice.
+
+```html
+<ui-radio-group name="plan" [(ngModel)]="selectedPlan" class="w-full max-w-md">
+  <label ui-label class="block rounded-xl border border-border bg-card/40 p-4">
+    <ui-form-field orientation="horizontal" class="items-start gap-4">
+      <ui-form-content>
+        <ui-form-title>Pro</ui-form-title>
+        <p ui-form-description>For growing businesses.</p>
+      </ui-form-content>
+      <ui-radio value="pro" />
+    </ui-form-field>
+  </label>
+</ui-radio-group>
+```
+
+### Semantic fieldsets
+
+Use a real fieldset and legend when the radio list answers one grouped question.
+
+```html
+<fieldset ui-form-fieldset class="max-w-md rounded-xl border border-border bg-card/40 p-5">
+  <legend ui-form-legend variant="label">Subscription plan</legend>
+  <p class="text-sm leading-6 text-muted-foreground">Yearly and lifetime plans offer significant savings.</p>
+
+  <ui-radio-group name="subscription-plan" [(ngModel)]="subscriptionPlan" class="mt-4">
+    <label ui-label class="block rounded-lg border border-border/70 bg-background/80 p-3">
+      <ui-form-field orientation="horizontal" class="gap-4">
+        <ui-radio value="monthly" />
+        <ui-form-content>
+          <ui-form-title>Monthly ($9.99/month)</ui-form-title>
+        </ui-form-content>
+      </ui-form-field>
+    </label>
+  </ui-radio-group>
+</fieldset>
+```
+
+### Validation and helper text
+
+Forward helper and error relationships from the group when the descriptive copy sits outside the individual items.
+
+```html
+<ui-form-field invalid class="max-w-md rounded-xl border border-destructive/40 bg-destructive/5 p-5">
+  <ui-form-title>Notification Preferences</ui-form-title>
+  <p id="notification-help" class="text-sm leading-6 text-muted-foreground">
+    Choose how you want to receive notifications.
+  </p>
+
+  <ui-radio-group
+    name="notification-preferences"
+    [(ngModel)]="notificationPreference"
+    aria-describedby="notification-help notification-error"
+    aria-invalid="true">
+    <label ui-label class="block rounded-lg border border-destructive/40 bg-background/80 p-3">
+      <ui-form-field orientation="horizontal" class="gap-4">
+        <ui-radio value="email" />
+        <ui-form-content>
+          <ui-form-title>Email only</ui-form-title>
+        </ui-form-content>
+      </ui-form-field>
+    </label>
+  </ui-radio-group>
+
+  <p id="notification-error" class="text-sm font-medium text-destructive">
+    Select one delivery channel before saving notification settings.
+  </p>
+</ui-form-field>
+```
+
+## API Reference
+
+### `RadioGroupComponent`
+
+| Input              | Type                         | Default      | Notes                                                        |
+| ------------------ | ---------------------------- | ------------ | ------------------------------------------------------------ |
+| `name`             | `string`                     | `''`         | Forwarded to the underlying Material radio group.            |
+| `orientation`      | `'horizontal' \| 'vertical'` | `'vertical'` | Switches between stacked rows and inline columns.            |
+| `aria-label`       | `string \| null`             | `null`       | Use when the group needs an explicit accessible name.        |
+| `aria-labelledby`  | `string \| null`             | `null`       | Alternative to `aria-label` for external group headings.     |
+| `aria-describedby` | `string \| null`             | `null`       | Connects helper or error text outside the group.             |
+| `aria-invalid`     | `boolean \| string \| null`  | `null`       | Marks the group invalid for validation-driven presentations. |
+| `class`            | `string`                     | `''`         | Adds utility classes to the wrapped group host.              |
+
+| Output        | Payload  |
+| ------------- | -------- |
+| `valueChange` | `string` |
+
+Public method: `focus()`.
+
+### `RadioComponent`
+
+| Input      | Type      | Default |
+| ---------- | --------- | ------- |
+| `value`    | `string`  | —       |
+| `disabled` | `boolean` | `false` |
+| `class`    | `string`  | `''`    |
+
+## Styling and Theming
+
+The radio primitives wrap Angular Material's structural radio markup and restyle it through the shared theme tokens.
+
+- The selected dot uses the `primary` token.
+- Unselected outlines use the `input` token rather than current text color.
+- The group uses CSS grid; horizontal orientation flips to `grid-flow-col auto-cols-max`.
+- Card-style layouts and invalid treatments are best handled by surrounding `label[ui-label]` and `ui-form-field` composition.
+
+## Accessibility
+
+- Use a real `fieldset` and `legend` when the radio list answers one grouped question.
+- Wrap each option in `label[ui-label]` when the whole row or card should toggle the control.
+- Use `aria-describedby` on `ui-radio-group` to connect helper or error text rendered outside the option rows.
+- Use `aria-invalid` on `ui-radio-group` when validation fails and the group should be announced as invalid.
+
+## Keyboard Interactions
+
+- `Tab` moves focus to the selected item or first enabled item in the group.
+- Arrow keys move between options using Angular Material's radio-group behavior.
+- `Space` selects the focused option.
+
+## Angular Notes
+
+- `ui-radio-group` owns the selected value and works with both `ngModel` and reactive forms.
+- `ui-radio` represents only the selectable item; visible copy usually lives beside it in a wrapper label or `ui-form-content` block.
+- The shadcn `Field` family maps to the existing `form` entrypoint rather than a separate radio-specific helper package.
+
+## Source Parity
+
+This Angular implementation follows the same high-value shadcn radio-group examples: descriptive rows, choice cards, semantic fieldsets, disabled states, invalid messaging, and RTL. The deliberate difference is the use of the existing `form` and `label` primitives instead of introducing a separate runtime `Field` API.