@edsis/ui 0.0.2

package/spinner/README.md

@@ -0,0 +1,160 @@
+# Spinner
+
+Displays a compact loading indicator for inline status, buttons, badges, input groups, and empty states.
+
+Use Spinner when work is in progress but the surrounding layout should stay visible and composable.
+
+## Import
+
+```ts
+import { SpinnerComponent } from '@edsis/ui/spinner';
+```
+
+Bring in companion entrypoints such as Button, Badge, Item, Empty, or Input Group only when the surrounding example needs them.
+
+## Basic usage
+
+By default, `ui-spinner` exposes `role="status"` with an accessible name of `Loading`.
+
+```html
+<ui-spinner aria-label="Loading invoices" />
+```
+
+## Common patterns
+
+### Size and color
+
+Use the `class` input to change size, color, or surrounding spacing.
+
+```html
+<div class="flex items-center gap-4">
+  <ui-spinner class="size-3" aria-label="Refreshing alerts" />
+  <ui-spinner class="size-4 text-primary" aria-label="Refreshing dashboard" />
+  <ui-spinner class="size-6 text-muted-foreground" aria-label="Loading analytics" />
+</div>
+```
+
+### Decorative inline status
+
+When nearby text already explains the loading state, mark the spinner as decorative so assistive technology does not hear duplicate status announcements.
+
+```html
+<button ui-button type="button" disabled class="gap-2">
+  <ui-spinner decorative />
+  Loading...
+</button>
+```
+
+### Button and badge composition
+
+There is no React-style `data-icon` API in the Angular library. Place `ui-spinner` before or after the visible label and use standard gap utilities on the host surface.
+
+```html
+<button ui-button type="button" variant="outline" disabled class="gap-2">
+  <ui-spinner decorative />
+  Please wait
+</button>
+
+<ui-badge class="gap-1.5">
+  <ui-spinner decorative class="size-3" />
+  Syncing
+</ui-badge>
+```
+
+### Item row
+
+The upstream preview maps cleanly to the local Item primitive.
+
+```html
+<ui-item variant="muted" class="w-full max-w-xs [--radius:1rem]">
+  <ui-item-media>
+    <ui-spinner decorative />
+  </ui-item-media>
+  <ui-item-content>
+    <ui-item-title>Processing payment...</ui-item-title>
+  </ui-item-content>
+  <ui-item-content class="flex-none justify-end">
+    <span class="text-sm tabular-nums">$100.00</span>
+  </ui-item-content>
+</ui-item>
+```
+
+### Input group status
+
+Spinner works as projected content inside `ui-input-group-addon` for inline or block-end status rows.
+
+```html
+<ui-input-group>
+  <input ui-input-group-input placeholder="Send a message..." disabled />
+  <ui-input-group-addon align="inline-end">
+    <ui-spinner decorative />
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Empty state
+
+Project the spinner into `ui-empty-media` when a request is still processing.
+
+```html
+<ui-empty class="w-full max-w-xl rounded-2xl border border-border bg-card/40">
+  <ui-empty-header>
+    <ui-empty-media variant="icon">
+      <ui-spinner decorative class="size-5" />
+    </ui-empty-media>
+    <ui-empty-title>Processing your request</ui-empty-title>
+    <ui-empty-description>Please wait while the operation completes.</ui-empty-description>
+  </ui-empty-header>
+</ui-empty>
+```
+
+### RTL
+
+Set `dir="rtl"` on the surrounding container or layout shell. The spinner stays direction-agnostic while the surrounding row flips logically.
+
+```html
+<section dir="rtl" lang="ar" class="w-full max-w-xs">
+  <ui-item variant="muted">
+    <ui-item-media>
+      <ui-spinner decorative />
+    </ui-item-media>
+    <ui-item-content>
+      <ui-item-title>جاري معالجة الدفع...</ui-item-title>
+    </ui-item-content>
+  </ui-item>
+</section>
+```
+
+## API reference
+
+| Input             | Type             | Default     | Notes                                                   |
+| ----------------- | ---------------- | ----------- | ------------------------------------------------------- |
+| `class`           | `string`         | `''`        | Controls size, color, and layout spacing.               |
+| `decorative`      | `boolean`        | `false`     | Removes status semantics and sets `aria-hidden="true"`. |
+| `aria-label`      | `string`         | `'Loading'` | Accessible name when the spinner stands alone.          |
+| `aria-labelledby` | `string \| null` | `null`      | Connects the spinner to nearby visible text.            |
+
+Native host attributes such as `id`, `dir`, `data-*`, and custom utility classes still pass through to the rendered custom element.
+
+## Styling and theming
+
+The spinner inherits `currentColor`, so it automatically matches the surrounding button, badge, item, or muted text color unless a utility overrides it.
+
+The default animation uses `animate-spin` and automatically stops under `prefers-reduced-motion`.
+
+## Accessibility
+
+- Default host is a named `status` element for standalone loading indicators.
+- Set `decorative` when nearby text already announces the loading state.
+- Use `aria-labelledby` instead of a second invisible label when visible copy already exists in the same row.
+- Keep the spinner paired with meaningful text or layout context for passive loading states.
+
+## Angular notes
+
+- `ui-spinner` is a standalone component with no providers or services.
+- Size and color remain utility-driven instead of introducing React-style variant props.
+- The `decorative` input is the Angular-first way to avoid repeated status announcements inside composed controls.
+
+## Source parity
+
+This Angular implementation follows the shadcn Spinner page closely for preview, sizing, buttons, badges, input groups, empty states, and RTL composition while translating the API to standalone imports, utility-driven styling, and explicit accessibility bindings.

package/switch/README.md

@@ -0,0 +1,166 @@
+# Switch
+
+A shadcn-style switch primitive built on Angular Material's `mat-slide-toggle`, with `ControlValueAccessor` support for `ngModel` and reactive forms.
+
+## Import
+
+```ts
+import { FormsModule } from '@angular/forms';
+import { SwitchComponent } from '@edsis/ui/switch';
+```
+
+Add `FormsModule` only when the host component uses `ngModel`. Reactive forms work through the same primitive.
+
+## Basic usage
+
+Use projected content for compact inline labels.
+
+```html
+<ui-switch [(ngModel)]="airplaneMode" name="airplane-mode">Airplane mode</ui-switch>
+```
+
+For helper text or card-like settings rows, move the copy outside the switch and connect it with `aria-labelledby` plus `aria-describedby`.
+
+```html
+<div class="flex items-start justify-between gap-4 rounded-xl border border-border bg-card/40 p-4">
+  <div class="space-y-1">
+    <p id="switch-share-label" class="font-medium">Share across devices</p>
+    <p id="switch-share-description" class="text-sm leading-5 text-muted-foreground">
+      Focus is shared across devices, and turns off when you leave the app.
+    </p>
+  </div>
+  <ui-switch
+    [ngModel]="shareAcrossDevices()"
+    (ngModelChange)="shareAcrossDevices.set($event)"
+    name="share-across-devices"
+    aria-labelledby="switch-share-label"
+    aria-describedby="switch-share-description" />
+</div>
+```
+
+Reactive forms continue to work through the component's value accessor.
+
+```html
+<ui-switch [formControl]="form.controls.notifications" aria-label="Email notifications" />
+```
+
+## Common patterns
+
+### Descriptive settings row
+
+Use `aria-labelledby` and `aria-describedby` when the visible copy sits outside the switch.
+
+```html
+<div class="flex items-start justify-between gap-4">
+  <div class="space-y-1">
+    <p id="setting-label" class="font-medium">Share across devices</p>
+    <p id="setting-description" class="text-sm text-muted-foreground">
+      Focus is shared across devices, and turns off when you leave the app.
+    </p>
+  </div>
+  <ui-switch
+    [ngModel]="shareAcrossDevices()"
+    (ngModelChange)="shareAcrossDevices.set($event)"
+    name="share-across-devices"
+    aria-labelledby="setting-label"
+    aria-describedby="setting-description" />
+</div>
+```
+
+### Choice card layout
+
+The upstream shadcn example wraps the whole field in a clickable label. This Angular primitive keeps the switch as the single interactive control and uses the surrounding card only for layout.
+
+```html
+<div class="rounded-xl border border-border bg-card/40 p-4">
+  <div class="flex items-start justify-between gap-4">
+    <div class="space-y-1">
+      <p id="notifications-label" class="font-medium">Enable notifications</p>
+      <p id="notifications-description" class="text-sm text-muted-foreground">
+        Receive notifications when focus mode is enabled or disabled.
+      </p>
+    </div>
+    <ui-switch
+      [ngModel]="notificationsEnabled()"
+      (ngModelChange)="notificationsEnabled.set($event)"
+      name="notifications-card"
+      aria-labelledby="notifications-label"
+      aria-describedby="notifications-description" />
+  </div>
+</div>
+```
+
+### Invalid state
+
+Forward `aria-invalid="true"` when validation should promote the switch into the destructive token set.
+
+```html
+<ui-switch
+  [ngModel]="acceptTerms()"
+  (ngModelChange)="acceptTerms.set($event)"
+  name="terms-switch"
+  aria-invalid="true"
+  aria-label="Accept terms and conditions" />
+```
+
+### Size
+
+Use `size="sm"` for denser settings lists and compact preference panes.
+
+```html
+<ui-switch size="sm" [(ngModel)]="compactPreference" name="compact-preference">Compact mode</ui-switch>
+```
+
+## API reference
+
+| Input              | Type                        | Default        | Notes                                                                     |
+| ------------------ | --------------------------- | -------------- | ------------------------------------------------------------------------- |
+| `id`               | `string`                    | auto-generated | Forwarded to Material; the focusable switch button becomes `<id>-button`. |
+| `name`             | `string \| null`            | `null`         | Forwarded to the underlying switch control.                               |
+| `disabled`         | `boolean`                   | `false`        | Merges with form-driven disabled state.                                   |
+| `required`         | `boolean`                   | `false`        | Forwarded to the underlying Material switch.                              |
+| `aria-label`       | `string \| null`            | `null`         | Use for compact or text-free switch controls.                             |
+| `aria-describedby` | `string \| null`            | `null`         | Links helper or error text outside the control.                           |
+| `aria-labelledby`  | `string \| null`            | `null`         | Best choice for descriptive rows and card layouts.                        |
+| `aria-invalid`     | `boolean \| string \| null` | `null`         | Switches the control into the destructive invalid treatment.              |
+| `size`             | `'default' \| 'sm'`         | `'default'`    | Smaller track for dense settings lists.                                   |
+| `class`            | `string`                    | `''`           | Adds utility classes to the wrapped Material host.                        |
+
+| Output          | Payload   |
+| --------------- | --------- |
+| `checkedChange` | `boolean` |
+
+Public method: `focus()`.
+
+## Styling and theming
+
+The component uses a Material bridge so the MDC switch structure is restyled with the library theme tokens.
+
+- Default track and handle colors use the shared `primary`, `input`, and `background` tokens.
+- `aria-invalid="true"` switches the switch into the destructive token set.
+- `size="sm"` tightens the track and handle sizing without creating a second entrypoint.
+- Pass spacing or alignment utilities through `class` when the switch needs to line up with multi-line content.
+
+Additional visual adjustments belong in `switch.component.css` inside the library.
+
+## Accessibility
+
+- Give the switch an accessible name through projected content, `aria-label`, or `aria-labelledby`.
+- Use `aria-describedby` for helper or error text rendered outside the control.
+- Prefer `aria-labelledby` over `label[for]` when the visible label is external, because Angular Material renders a focusable switch button rather than a labelable text input.
+- `aria-invalid` is forwarded to the underlying Material host for validation styling and assistive technology cues.
+
+## Keyboard interactions
+
+- `Tab` moves focus to the switch in DOM order.
+- `Space` toggles the checked state.
+
+## Angular notes
+
+- `ngModel`, reactive forms, and `checkedChange` all work with the same primitive.
+- Passing `id` forwards a stable base id to Angular Material; the focusable button receives the derived `<id>-button` id.
+- The direct `disabled` input and `setDisabledState()` from forms are merged, so either source can disable the control.
+
+## Source parity
+
+This Angular implementation follows the shadcn Switch examples while translating the upstream Field helpers and clickable-card label pattern into Angular-friendly descriptive containers, ARIA relationships, and signal-friendly state handling.

package/table/README.md

@@ -0,0 +1,291 @@
+# Table
+
+Responsive native table primitives for invoices, product lists, row actions, and compact data summaries.
+
+Use Table when information has real row and column relationships. The Angular primitive keeps shadcn's composition model while preserving semantic `<table>`, `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`, `<td>`, and `<caption>` elements.
+
+shadcn's `data-table` guide maps to this entrypoint rather than a separate Angular package surface. Compose Table with the local button, checkbox, input, badge, and dropdown-menu primitives when you need sorting, filtering, row selection, column visibility, row actions, or pagination.
+
+## Import
+
+```ts
+import {
+  TableBodyComponent,
+  TableCaptionComponent,
+  TableCellComponent,
+  TableComponent,
+  TableFooterComponent,
+  TableHeadComponent,
+  TableHeaderComponent,
+  TableRowComponent,
+} from '@edsis/ui/table';
+```
+
+Row action menus can compose with the local button and dropdown-menu primitives.
+
+```ts
+import { ButtonComponent } from '@edsis/ui/button';
+import {
+  MenuContentDirective,
+  MenuItemComponent,
+  MenuSeparatorComponent,
+  MenuSurfaceComponent,
+  MenuTriggerDirective,
+} from '@edsis/ui/dropdown-menu';
+```
+
+## Composition
+
+Apply the attribute-selector parts to the matching semantic table tags.
+
+```text
+ui-table
+|-- caption[ui-table-caption]
+|-- thead[ui-table-header]
+|   `-- tr[ui-table-row]
+|       |-- th[ui-table-head]
+|       |-- th[ui-table-head]
+|       |-- th[ui-table-head]
+|       `-- th[ui-table-head]
+|-- tbody[ui-table-body]
+|   `-- tr[ui-table-row]
+|       |-- td[ui-table-cell]
+|       |-- td[ui-table-cell]
+|       |-- td[ui-table-cell]
+|       `-- td[ui-table-cell]
+`-- tfoot[ui-table-footer]
+```
+
+## Usage
+
+Use `ui-table` as the responsive wrapper. Bind rows with Angular control flow and stable tracking.
+
+```html
+<ui-table>
+  <caption ui-table-caption>
+    A list of your recent invoices.
+  </caption>
+  <thead ui-table-header>
+    <tr ui-table-row>
+      <th ui-table-head class="w-25">Invoice</th>
+      <th ui-table-head>Status</th>
+      <th ui-table-head>Method</th>
+      <th ui-table-head class="text-right">Amount</th>
+    </tr>
+  </thead>
+  <tbody ui-table-body>
+    @for (invoice of invoices; track invoice.invoice) {
+    <tr ui-table-row>
+      <td ui-table-cell class="font-medium">{{ invoice.invoice }}</td>
+      <td ui-table-cell>{{ invoice.status }}</td>
+      <td ui-table-cell>{{ invoice.method }}</td>
+      <td ui-table-cell class="text-right">{{ invoice.amount }}</td>
+    </tr>
+    }
+  </tbody>
+</ui-table>
+```
+
+## Common patterns
+
+### Footer totals
+
+Use `tfoot[ui-table-footer]` for totals and summaries. `colspan` stays on the native `td`.
+
+```html
+<ui-table>
+  <caption ui-table-caption>
+    A list of your recent invoices.
+  </caption>
+  <thead ui-table-header>
+    ...
+  </thead>
+  <tbody ui-table-body>
+    ...
+  </tbody>
+  <tfoot ui-table-footer>
+    <tr ui-table-row>
+      <td ui-table-cell colspan="3">Total</td>
+      <td ui-table-cell class="text-right">$2,500.00</td>
+    </tr>
+  </tfoot>
+</ui-table>
+```
+
+### Row actions
+
+Compose action menus with `ui-button`, `uiMenuTrigger`, and the dropdown-menu surface.
+
+```html
+<ng-template uiMenuContent #productActionsMenu="uiMenuContent">
+  <ui-menu-surface class="w-36">
+    <button ui-menu-item>Edit</button>
+    <button ui-menu-item>Duplicate</button>
+    <ui-menu-separator />
+    <button ui-menu-item variant="destructive">Delete</button>
+  </ui-menu-surface>
+</ng-template>
+
+<ui-table>
+  <thead ui-table-header>
+    <tr ui-table-row>
+      <th ui-table-head>Product</th>
+      <th ui-table-head>Price</th>
+      <th ui-table-head class="text-right">Actions</th>
+    </tr>
+  </thead>
+  <tbody ui-table-body>
+    @for (product of products; track product.name) {
+    <tr ui-table-row>
+      <td ui-table-cell class="font-medium">{{ product.name }}</td>
+      <td ui-table-cell>{{ product.price }}</td>
+      <td ui-table-cell class="text-right">
+        <button
+          ui-button
+          type="button"
+          variant="ghost"
+          size="icon-sm"
+          [attr.aria-label]="'Open actions for ' + product.name"
+          [uiMenuTrigger]="productActionsMenu">
+          <span aria-hidden="true">...</span>
+        </button>
+      </td>
+    </tr>
+    }
+  </tbody>
+</ui-table>
+```
+
+### Data table guide mapping
+
+The upstream shadcn `data-table` page is a composition guide, not a standalone primitive. In this Angular library the same guidance starts with `@edsis/ui/table` and layers behavior around it.
+
+```ts
+import { BadgeComponent } from '@edsis/ui/badge';
+import { ButtonComponent } from '@edsis/ui/button';
+import { CheckboxComponent } from '@edsis/ui/checkbox';
+import {
+  MenuCheckboxItemComponent,
+  MenuContentDirective,
+  MenuGroupComponent,
+  MenuItemComponent,
+  MenuLabelComponent,
+  MenuSeparatorComponent,
+  MenuSurfaceComponent,
+  MenuTriggerDirective,
+} from '@edsis/ui/dropdown-menu';
+import { InputComponent } from '@edsis/ui/input';
+```
+
+Keep Table as the markup layer and put behavior in Angular signals, services, or a table state library. A small explicit pipeline is usually easier to maintain than a generic catch-all data-table wrapper.
+
+```ts
+readonly filterText = signal('');
+readonly sortState = signal<{ column: 'status' | 'email' | 'amount'; direction: 'asc' | 'desc' } | null>(null);
+readonly selectedIds = signal<ReadonlySet<string>>(new Set());
+
+readonly filteredRows = computed(() => {
+  const query = filterText().trim().toLowerCase();
+  return query ? rows.filter((row) => row.email.toLowerCase().includes(query)) : rows;
+});
+
+readonly sortedRows = computed(() => sortRows(filteredRows(), sortState()));
+readonly pageRows = computed(() => paginateRows(sortedRows(), currentPage(), pageSize));
+```
+
+Selected rows can use the shadcn-compatible `data-state="selected"` hook so row styling stays synchronized with the checkbox state.
+
+```html
+<ui-table>
+  <thead ui-table-header>
+    ...
+  </thead>
+  <tbody ui-table-body>
+    @for (row of filteredRows(); track row.id) {
+    <tr ui-table-row [attr.data-state]="selectedIds().has(row.id) ? 'selected' : null">
+      <td ui-table-cell>{{ row.title }}</td>
+      <td ui-table-cell>{{ row.status }}</td>
+      <td ui-table-cell class="text-right">{{ row.amount }}</td>
+    </tr>
+    }
+  </tbody>
+</ui-table>
+```
+
+### RTL
+
+Set direction on a wrapper or directly on `ui-table`. Keep alignment explicit for amount and numeric columns.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <ui-table>
+    <caption ui-table-caption>
+      قائمة بفواتيرك الأخيرة.
+    </caption>
+    <thead ui-table-header>
+      <tr ui-table-row>
+        <th ui-table-head class="w-25 text-right">الفاتورة</th>
+        <th ui-table-head class="text-right">الحالة</th>
+        <th ui-table-head class="text-right">الطريقة</th>
+        <th ui-table-head class="text-right">المبلغ</th>
+      </tr>
+    </thead>
+    <tbody ui-table-body>
+      ...
+    </tbody>
+  </ui-table>
+</div>
+```
+
+## API reference
+
+### `TableComponent`
+
+| Input   | Type     | Default | Description                                       |
+| ------- | -------- | ------- | ------------------------------------------------- |
+| `class` | `string` | `''`    | Classes applied to the rendered native `<table>`. |
+
+### Attribute parts
+
+| Part                    | Selector                    | Input   | Notes                                                   |
+| ----------------------- | --------------------------- | ------- | ------------------------------------------------------- |
+| `TableCaptionComponent` | `caption[ui-table-caption]` | `class` | Muted caption below the table.                          |
+| `TableHeaderComponent`  | `thead[ui-table-header]`    | `class` | Header section with row dividers.                       |
+| `TableBodyComponent`    | `tbody[ui-table-body]`      | `class` | Body section that removes the final row border.         |
+| `TableFooterComponent`  | `tfoot[ui-table-footer]`    | `class` | Footer section with muted background and top divider.   |
+| `TableRowComponent`     | `tr[ui-table-row]`          | `class` | Row hover state and `data-state="selected"` support.    |
+| `TableHeadComponent`    | `th[ui-table-head]`         | `class` | Header cell with muted foreground and nowrap text.      |
+| `TableCellComponent`    | `td[ui-table-cell]`         | `class` | Body or footer cell with compact padding and alignment. |
+
+## Styling and theming
+
+The root host is `relative block w-full overflow-x-auto`; the rendered table is `w-full caption-bottom text-sm`.
+
+Dividers use the shared `border-border` token, row hover uses `hover:bg-muted/50`, footer uses `bg-muted/50`, and selected rows respond to `data-state="selected"` with `bg-muted`.
+
+Pass utility classes to individual parts for column width, alignment, density, responsive visibility, and typography.
+
+## Accessibility
+
+- Use a `<caption ui-table-caption>` when the table conveys meaningful data.
+- Keep column headers in native `<th ui-table-head>` cells so screen readers can announce header relationships.
+- Use `scope`, `colspan`, `rowspan`, and `aria-sort` on native cells when your data model needs them.
+- Do not use Table for non-tabular layout. Use CSS grid or flex layouts for purely visual alignment.
+
+## Keyboard interactions
+
+Static tables do not add custom keyboard behavior. Focusable controls inside cells, such as action menu buttons, keep their own native or primitive-provided keyboard behavior.
+
+When composing a row menu, the trigger uses native button activation and the local menu handles Arrow Up, Arrow Down, Home, End, Tab dismissal, and typeahead.
+
+## Angular notes
+
+- All table parts are standalone components and can be imported directly.
+- The root `ui-table` wraps projected content in a native `<table>`, so child parts should be direct table descendants in normal HTML order.
+- Prefer Angular `@for` with a stable `track` expression for row rendering.
+- Keep sorting, filtering, pagination, and selection state outside the primitive; Table is intentionally presentational.
+- Attribute-selector primitives must be applied to their semantic tag, for example `th[ui-table-head]` and `td[ui-table-cell]`.
+
+## Source parity
+
+This Angular implementation follows the shadcn Table docs for preview, usage, composition, footer, actions, data-table guidance, and RTL. React component names map to Angular selectors, React `className` maps to `class`, and row action menus compose with the local Angular dropdown-menu primitives.