@edsis/ui 0.0.2

package/chart/README.md

@@ -0,0 +1,249 @@
+# Chart
+
+Angular chart primitives and chart families inspired by shadcn Chart.
+
+In this repository, shadcn's single Chart page maps to the dedicated `/ui/chart/*` demo route group so each chart family can keep focused, production-like examples without forcing everything into one `/ui/shadcn/chart` page.
+
+Use Chart for dashboards, KPI cards, trend comparisons, radial summaries, and interactive data views where one shared config should drive labels, colors, legends, and tooltip copy.
+
+## Installation
+
+```bash
+bun add @edsis/ui
+npm install @edsis/ui
+```
+
+## Import
+
+Import shared primitives from the chart root entrypoint, then import the concrete chart family from its granular subpath.
+
+```ts
+import {
+  ChartAxisX,
+  ChartAxisY,
+  ChartContainer,
+  ChartGrid,
+  ChartLegend,
+  ChartTooltip,
+  type ChartConfig,
+} from '@edsis/ui/chart';
+import { BarChart } from '@edsis/ui/chart/bar';
+```
+
+### Supported chart entrypoints
+
+| Import path               | Selector           | Best for                                                          |
+| ------------------------- | ------------------ | ----------------------------------------------------------------- |
+| `@edsis/ui/chart/bar`     | `ui-bar-chart`     | grouped, stacked, horizontal, active, and mixed-color bar layouts |
+| `@edsis/ui/chart/line`    | `ui-line-chart`    | trends, comparisons, and zoomable time-series lines               |
+| `@edsis/ui/chart/area`    | `ui-area-chart`    | filled trend bands, stacked areas, and expanded percent views     |
+| `@edsis/ui/chart/pie`     | `ui-pie-chart`     | part-to-whole slices and donut charts                             |
+| `@edsis/ui/chart/radar`   | `ui-radar-chart`   | multi-axis performance comparisons                                |
+| `@edsis/ui/chart/radial`  | `ui-radial-chart`  | progress rings, radial comparisons, and center-metric summaries   |
+| `@edsis/ui/chart/scatter` | `ui-scatter-chart` | XY correlation plots and point clouds                             |
+
+## Composition
+
+The Angular structure keeps the same high-level idea as shadcn Chart: define a shared chart config once, then compose a specific chart type with optional grid, axis, tooltip, legend, and center content.
+
+```text
+ui-chart-container
+├── ui-bar-chart | ui-line-chart | ui-area-chart | ui-scatter-chart
+│   ├── svg:g[ui-chart-grid]
+│   ├── svg:g[ui-chart-axis-x]
+│   ├── svg:g[ui-chart-axis-y]
+│   └── svg:g[ui-chart-crosshair] / svg:g[ui-chart-brush] (optional)
+├── ui-pie-chart | ui-radial-chart | ui-radar-chart
+│   └── ui-pie-center | ui-radial-center (optional)
+├── ui-chart-tooltip
+├── ui-chart-legend
+└── ui-chart-zoom-controls (optional)
+```
+
+All child primitives read dimensions, series metadata, and scoped color tokens from `ui-chart-container`.
+
+## Basic usage
+
+Start with a readonly `ChartConfig`, keep the dataset in any shape that makes sense for your feature, and map the chart to the relevant keys.
+
+```ts
+const trafficChartConfig = {
+  desktop: { label: 'Desktop', color: 'var(--chart-1)' },
+  mobile: { label: 'Mobile', color: 'var(--chart-2)' },
+} satisfies ChartConfig;
+
+const trafficData = [
+  { month: 'January', desktop: 186, mobile: 80 },
+  { month: 'February', desktop: 305, mobile: 200 },
+  { month: 'March', desktop: 237, mobile: 120 },
+  { month: 'April', desktop: 73, mobile: 190 },
+  { month: 'May', desktop: 209, mobile: 130 },
+  { month: 'June', desktop: 214, mobile: 140 },
+];
+```
+
+```html
+<div class="w-full max-w-3xl">
+  <ui-chart-container [config]="trafficChartConfig" chartId="traffic-overview">
+    <ui-bar-chart [data]="trafficData" xKey="month">
+      <svg:g ui-chart-grid></svg:g>
+      <svg:g ui-chart-axis-x></svg:g>
+      <svg:g ui-chart-axis-y></svg:g>
+    </ui-bar-chart>
+    <ui-chart-tooltip [data]="trafficData" xKey="month" />
+    <ui-chart-legend />
+  </ui-chart-container>
+</div>
+```
+
+## Common patterns
+
+### First chart flow
+
+The closest Angular equivalent to the upstream shadcn walkthrough is:
+
+1. Define your dataset.
+2. Define `ChartConfig` so labels and colors stay decoupled from the raw data.
+3. Wrap the chart in `ui-chart-container`.
+4. Add `svg:g[ui-chart-grid]`, axis directives, `ui-chart-tooltip`, and `ui-chart-legend` only where they add value.
+
+This keeps the chart family focused while still letting the shared primitives manage the common UI pieces.
+
+### Swapping chart families
+
+The same `ChartConfig` can back multiple chart families. In most cases you only swap the concrete chart import and the family-specific inputs.
+
+```ts
+import { AreaChart } from '@edsis/ui/chart/area';
+import { LineChart } from '@edsis/ui/chart/line';
+```
+
+- `ui-line-chart` adds inputs such as `curve`, `showDots`, and `showValueLabels`.
+- `ui-area-chart` adds `stacked`, `expanded`, `gradient`, and `curve`.
+- `ui-bar-chart` adds `orientation`, `variant`, `colorKey`, `activeKey`, and `activeValue`.
+
+### Pie and radial summaries
+
+For donut, pie, and radial progress layouts, use `nameKey` plus `valueKey` instead of `xKey`.
+
+```html
+<ui-chart-container [config]="browserConfig" aspect="aspect-square">
+  <ui-pie-chart
+    [data]="browserData"
+    nameKey="browser"
+    valueKey="visitors"
+    [seriesKeys]="browserSeriesKeys"
+    [innerRadius]="64">
+  </ui-pie-chart>
+  <ui-chart-tooltip [data]="browserData" xKey="browser" valueKey="visitors" indicator="dot" />
+  <ui-chart-legend />
+</ui-chart-container>
+```
+
+### Tooltip formatting
+
+`ui-chart-tooltip` is where most presentational customization lives.
+
+```html
+<ui-chart-tooltip
+  [data]="activityData"
+  xKey="date"
+  indicator="line"
+  labelKey="views"
+  [labelFormatter]="longDateFormatter"
+  [formatter]="compactNumberFormatter" />
+```
+
+Use `valueKey` for single-value radial and pie datasets, `hideLabel` when the card already provides the label context, and `indicator="none"` when you want a copy-first tooltip layout.
+
+### Per-row colors and active emphasis
+
+Use `colorKey` when the dataset itself carries a color token such as `fill`, and use `activeKey` plus `activeValue` when one category should be visually emphasized without rewriting the whole series config.
+
+## API reference
+
+### `ChartContainer`
+
+| Input     | Type             | Default          |
+| --------- | ---------------- | ---------------- |
+| `config`  | `ChartConfig`    | —                |
+| `aspect`  | `string`         | `'aspect-video'` |
+| `chartId` | `string \| null` | auto-generated   |
+
+`ChartConfig` is a readonly record of series keys to labels, icons, colors, or theme-aware light/dark color maps.
+
+```ts
+type ChartConfig = Readonly<
+  Record<
+    string,
+    {
+      label?: string;
+      icon?: Type<unknown>;
+      color?: string;
+      theme?: Readonly<Record<'light' | 'dark', string>>;
+    }
+  >
+>;
+```
+
+### Shared primitives
+
+| Part                     | Key inputs                                                                                               | Notes                                                           |
+| ------------------------ | -------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `svg:g[ui-chart-grid]`   | none                                                                                                     | Adds cartesian grid lines behind bar, line, and area charts.    |
+| `svg:g[ui-chart-axis-x]` | `tickCount`, `tickLine`, `tickFormat`                                                                    | Categorical axis for cartesian layouts.                         |
+| `svg:g[ui-chart-axis-y]` | `tickCount`, `tickLine`, `tickFormat`                                                                    | Numeric axis for cartesian layouts.                             |
+| `ui-chart-tooltip`       | `data`, `xKey`, `valueKey`, `indicator`, `label`, `labelKey`, `labelFormatter`, `formatter`, `hideLabel` | Handles default tooltip layout plus custom template projection. |
+| `ui-chart-legend`        | none                                                                                                     | Renders toggle buttons for visible series.                      |
+| `ui-chart-zoom-controls` | none                                                                                                     | Pair with zoomable line and scatter views.                      |
+| `ui-pie-center`          | projected content                                                                                        | Centers labels or KPIs inside pie layouts.                      |
+| `ui-radial-center`       | projected content                                                                                        | Centers labels or KPIs inside radial layouts.                   |
+
+### Chart families
+
+| Selector           | Key inputs                                                                                          |
+| ------------------ | --------------------------------------------------------------------------------------------------- |
+| `ui-bar-chart`     | `data`, `xKey`, `orientation`, `variant`, `colorKey`, `activeKey`, `activeValue`, `showValueLabels` |
+| `ui-line-chart`    | `data`, `xKey`, `curve`, `showDots`, `dotRadius`, `showValueLabels`                                 |
+| `ui-area-chart`    | `data`, `xKey`, `stacked`, `expanded`, `gradient`, `curve`                                          |
+| `ui-pie-chart`     | `data`, `nameKey`, `valueKey`, `seriesKeys`, `innerRadius`, `activeIndex`, `activeOffset`           |
+| `ui-radar-chart`   | `data`, `axisKey`, `curve`, `levels`, `grid`, `showLabels`, `showDots`                              |
+| `ui-radial-chart`  | `data`, `nameKey`, `valueKey`, `seriesKeys`, `maxValue`, `showTrack`, `showValueLabels`             |
+| `ui-scatter-chart` | `data`, `xKey`, `yKey`, `sizeKey`, `seriesKey`, `xDomain`, `yDomain`                                |
+
+## Styling and theming
+
+- Prefer CSS variables such as `var(--chart-1)` and `var(--chart-2)` in `ChartConfig`. This matches the current shadcn guidance and the theme tokens shipped by this library.
+- `ui-chart-container` scopes generated `--color-<series>` variables to the chart instance, so tooltip rows, legends, and series shapes stay aligned.
+- Use `theme: { light, dark }` on a series config entry when the chart needs different values per color scheme.
+- Keep the parent container responsible for width, and use the `aspect` input when the default `aspect-video` does not match the layout.
+- Use `colorKey` only when the dataset should override per-series colors with a row-specific token such as `fill`.
+
+## Accessibility
+
+- Chart hosts expose an `aria-label` summary describing the chart type, category count, and visible series.
+- Interactive marks such as bars, dots, and slices are keyboard focusable where the layout supports activation.
+- `ui-chart-tooltip` includes a polite live region so changing categories can be announced to assistive technology.
+- `ui-chart-legend` uses native buttons with `aria-pressed` to reflect hidden and visible series state.
+- Keep surrounding card copy descriptive so the chart has enough context when read outside its visual layout.
+
+## Keyboard interactions
+
+- `Tab` reaches interactive bars, dots, slices, and legend toggle buttons.
+- `Enter` and `Space` trigger the same click behavior as pointer activation on interactive marks.
+- Focusing a supported data mark updates the shared active point so tooltip content stays reachable without hover.
+
+## Angular notes
+
+- Keep chart config objects readonly and signal-friendly. A top-level `const` or signal-backed computed config works well.
+- Every chart family must live inside `ui-chart-container`; that container provides dimensions, series visibility state, and scoped color variables to descendants.
+- Use an explicit `chartId` when multiple charts of the same family appear on one page or when tests need a stable selector.
+- The local shadcn mapping for Chart lives in the dedicated `/ui/chart` overview route with focused family demos under `/ui/chart/*`.
+
+## Source parity
+
+This Angular package follows the shadcn Chart information architecture and theming concepts, but it does not mirror the React API one-to-one.
+
+- shadcn uses Recharts components directly and layers `ChartTooltipContent` and `ChartLegendContent` around them.
+- This Angular library ships standalone chart families plus shared primitives, so you compose `ui-chart-container`, the relevant `ui-*-chart`, `ui-chart-tooltip`, and `ui-chart-legend` instead of wiring Recharts JSX.
+- The dedicated `/ui/chart/*` route group is the intentional local mapping for shadcn Chart in this repo; no duplicate `/ui/shadcn/chart` page is required.

package/checkbox/README.md

@@ -0,0 +1,149 @@
+# Checkbox
+
+A shadcn-style checkbox primitive built on Angular Material's `mat-checkbox`, with full `ControlValueAccessor` support for `ngModel` and reactive forms.
+
+## Import
+
+```ts
+import { CheckboxComponent } from '@edsis/ui/checkbox';
+import { LabelComponent } from '@edsis/ui/label';
+```
+
+## Usage
+
+Wrap the control and copy in `label[ui-label]` when the text should toggle the checkbox. This is the closest Angular equivalent to the upstream shadcn `Field` + `FieldLabel` composition.
+
+```html
+<label ui-label class="flex items-start gap-3">
+  <ui-checkbox [(ngModel)]="accepted" name="terms-checkbox" class="mt-0.5" />
+  <span class="grid gap-1 leading-none">
+    <span>Accept terms and conditions</span>
+    <span class="text-sm font-normal leading-5 text-muted-foreground">
+      By clicking this checkbox, you agree to the terms.
+    </span>
+  </span>
+</label>
+```
+
+Reactive forms continue to work through the component's value accessor.
+
+```html
+<ui-checkbox [formControl]="form.controls.marketingOptIn" aria-label="Receive product updates" />
+```
+
+## Common patterns
+
+### Controlled checked state
+
+Use `checkedChange` when the parent owns the signal and you want to keep the checkbox controlled without wrapping a form model.
+
+```ts
+const marketingOptIn = signal(false);
+```
+
+```html
+<ui-checkbox
+  [ngModel]="marketingOptIn()"
+  (checkedChange)="marketingOptIn.set($event)"
+  aria-label="Receive product updates" />
+```
+
+### Invalid state
+
+Forward `aria-invalid="true"` to switch the control into the destructive invalid treatment.
+
+```html
+<label ui-label class="flex items-start gap-3 text-destructive">
+  <ui-checkbox aria-invalid="true" name="terms-checkbox-invalid" class="mt-0.5" />
+  <span class="grid gap-1 leading-none">
+    <span>Accept terms and conditions</span>
+    <span class="text-sm font-normal leading-5 text-muted-foreground">
+      Choose this before continuing to checkout.
+    </span>
+  </span>
+</label>
+```
+
+### Grouped preferences
+
+Use a semantic `fieldset` for a checkbox list.
+
+```html
+<fieldset class="space-y-3">
+  <legend class="text-sm font-semibold">Show these items on the desktop:</legend>
+  @for (item of groupOptions; track item.id) {
+  <label ui-label class="flex items-start gap-3">
+    <ui-checkbox
+      [ngModel]="desktopItems().has(item.id)"
+      (checkedChange)="toggleDesktopItem(item.id, $event)"
+      [name]="item.id"
+      class="mt-0.5" />
+    <span class="font-normal">{{ item.label }}</span>
+  </label>
+  }
+</fieldset>
+```
+
+### Table row selection
+
+Use `indeterminate` for the select-all checkbox and set `data-state="selected"` on the selected row so the table highlight stays in sync.
+
+```html
+<ui-checkbox
+  [ngModel]="selectAll()"
+  [indeterminate]="someRowsSelected()"
+  aria-label="Select all team members"
+  (checkedChange)="handleSelectAll($event)" />
+```
+
+## API reference
+
+| Input              | Type                        | Default        | Notes                                                                    |
+| ------------------ | --------------------------- | -------------- | ------------------------------------------------------------------------ |
+| `id`               | `string`                    | auto-generated | Forwarded to Angular Material; the native input id becomes `<id>-input`. |
+| `name`             | `string \| null`            | `null`         | Forwarded to the native checkbox input.                                  |
+| `indeterminate`    | `boolean`                   | `false`        | Useful for select-all patterns.                                          |
+| `required`         | `boolean`                   | `false`        | Forwarded to the native input.                                           |
+| `aria-label`       | `string \| null`            | `null`         | Use for icon-only or table selection checkboxes.                         |
+| `aria-describedby` | `string \| null`            | `null`         | Links helper or error text outside the checkbox.                         |
+| `aria-labelledby`  | `string \| null`            | `null`         | Alternative to projected text or wrapper labels.                         |
+| `aria-invalid`     | `boolean \| string \| null` | `null`         | Switches the control into the destructive invalid treatment.             |
+| `class`            | `string`                    | `''`           | Adds utility classes to the wrapped Material checkbox host.              |
+
+| Output          | Payload   |
+| --------------- | --------- |
+| `checkedChange` | `boolean` |
+
+Public method: `focus()`.
+
+## Styling and theming
+
+The component uses a Material bridge so Angular Material's structural markup is restyled through the library theme tokens.
+
+- Default borders and icon color use the shared `input` and `primary` tokens.
+- `aria-invalid="true"` switches the control to the `destructive` token set.
+- Pass spacing or alignment utilities through the `class` input when the checkbox needs to align with multi-line content.
+
+Extra visual adjustments belong in `checkbox.component.css` inside the library.
+
+## Accessibility
+
+- Always give the checkbox an accessible name via wrapper label text, projected content, `aria-label`, or `aria-labelledby`.
+- Use `aria-describedby` to connect helper or error text rendered outside the checkbox.
+- Use `indeterminate` for tri-state list headers and table select-all behavior.
+- `required` and `name` are forwarded to the underlying native input.
+
+## Keyboard interactions
+
+- `Tab` moves focus to the checkbox in DOM order.
+- `Space` toggles the checked state.
+
+## Angular notes
+
+- `ngModel`, reactive forms, and `checkedChange` all work with the same primitive.
+- When you pass `id`, Angular Material derives the native input id as `<id>-input`; wrapper labels or `aria-labelledby` are usually the simplest Angular pattern.
+- Projected text still works if you prefer `<ui-checkbox>Accept</ui-checkbox>` for compact markup.
+
+## Source parity
+
+This Angular implementation follows the shadcn Checkbox examples while mapping the upstream `Field` helpers to Angular-native label wrappers, `fieldset` composition, semantic table rows, and signal-friendly state handling.

package/collapsible/README.md

@@ -0,0 +1,191 @@
+# Collapsible
+
+Displays an interactive disclosure region that expands and collapses inline content.
+
+Use Collapsible for settings drawers, detail rows, compact status cards, and nested explorers where content should stay in the same document flow.
+
+## Import
+
+```ts
+import { CollapsibleComponent, CollapsibleContentComponent, CollapsibleTriggerDirective } from '@edsis/ui/collapsible';
+```
+
+## Composition
+
+The Angular composition follows the shadcn and Radix structure while using a root component, a trigger directive on a native button, and a content component.
+
+```text
+ui-collapsible
+├── button[ui-collapsible-trigger]
+└── ui-collapsible-content
+```
+
+## Basic usage
+
+Bind `[(open)]` when the parent should control the disclosure state or seed a default open panel.
+
+```ts
+readonly detailsOpen = signal(false);
+```
+
+```html
+<ui-collapsible [(open)]="detailsOpen" class="w-full max-w-md rounded-lg border border-border p-3">
+  <button
+    ui-collapsible-trigger
+    class="inline-flex w-full items-center justify-between gap-2 text-left text-sm font-medium">
+    Can I use this in my project?
+    <span aria-hidden="true">+</span>
+  </button>
+
+  <ui-collapsible-content class="pt-3 text-sm text-muted-foreground">
+    Yes. The trigger and content follow the disclosure ARIA pattern and stay in normal layout flow.
+  </ui-collapsible-content>
+</ui-collapsible>
+```
+
+## Common patterns
+
+### Controlled state
+
+Use a signal boolean with `[(open)]` when another control needs to observe or update the open state.
+
+```ts
+readonly isOpen = signal(false);
+
+toggleFromElsewhere(): void {
+  this.isOpen.update((value) => !value);
+}
+```
+
+### Button composition
+
+`button[ui-collapsible-trigger]` is a directive, so it can compose with the local button primitive on the same element.
+
+```html
+<ui-collapsible [(open)]="basicOpen" class="rounded-md border border-border p-2">
+  <button ui-button ui-collapsible-trigger variant="ghost" class="w-full justify-between px-2">
+    Product details
+    <svg aria-hidden="true" class="h-4 w-4" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+      <polyline points="6 9 12 15 18 9" />
+    </svg>
+  </button>
+
+  <ui-collapsible-content class="px-2 pb-2 pt-1 text-sm text-muted-foreground">
+    This panel can reveal additional details without leaving the page.
+  </ui-collapsible-content>
+</ui-collapsible>
+```
+
+### Settings drawer
+
+Wrap the trigger and content inside a card-like surface when the disclosure belongs to a small settings editor.
+
+```html
+<ui-collapsible [(open)]="settingsOpen" class="rounded-lg border border-border p-4">
+  <div class="flex items-start gap-3">
+    <div class="grid flex-1 grid-cols-2 gap-2">
+      <input ui-input placeholder="Radius X" />
+      <input ui-input placeholder="Radius Y" />
+      <ui-collapsible-content class="col-span-full grid grid-cols-2 gap-2 pt-0">
+        <input ui-input placeholder="Blur" />
+        <input ui-input placeholder="Spread" />
+      </ui-collapsible-content>
+    </div>
+
+    <button ui-button ui-collapsible-trigger variant="outline" size="icon" aria-label="Toggle advanced fields">
+      <span aria-hidden="true">...</span>
+    </button>
+  </div>
+</ui-collapsible>
+```
+
+### Nested file tree
+
+Nested `ui-collapsible` roots work well for compact explorers and outline views.
+
+```html
+<ui-collapsible [(open)]="componentsOpen">
+  <button ui-collapsible-trigger class="inline-flex items-center gap-2 text-sm font-medium">components</button>
+
+  <ui-collapsible-content class="ml-5 mt-2 flex flex-col gap-1">
+    <ui-collapsible [(open)]="uiOpen">
+      <button ui-collapsible-trigger class="inline-flex items-center gap-2 text-sm font-medium">ui</button>
+      <ui-collapsible-content class="ml-5 mt-2 flex flex-col gap-1 text-sm text-muted-foreground">
+        <span>button.ts</span>
+        <span>collapsible.ts</span>
+      </ui-collapsible-content>
+    </ui-collapsible>
+  </ui-collapsible-content>
+</ui-collapsible>
+```
+
+### RTL
+
+For right-to-left interfaces, set `dir="rtl"` on a wrapping container or the collapsible root.
+
+```html
+<section dir="rtl" lang="ar" class="max-w-md text-right">
+  <ui-collapsible [(open)]="rtlOpen" class="flex flex-col gap-2">
+    <button ui-collapsible-trigger class="inline-flex items-center justify-between gap-2 text-sm font-medium">
+      تبديل التفاصيل
+    </button>
+    <ui-collapsible-content class="flex flex-col gap-2 text-sm">
+      <div class="rounded-md border border-border px-4 py-2">عنوان الشحن</div>
+      <div class="rounded-md border border-border px-4 py-2">2x سماعات الاستوديو</div>
+    </ui-collapsible-content>
+  </ui-collapsible>
+</section>
+```
+
+## API reference
+
+### `CollapsibleComponent`
+
+| Input          | Type      | Default |
+| -------------- | --------- | ------- |
+| `open` (model) | `boolean` | `false` |
+| `disabled`     | `boolean` | `false` |
+| `class`        | `string`  | `''`    |
+
+### `CollapsibleContentComponent`
+
+| Input        | Type      | Default |
+| ------------ | --------- | ------- |
+| `forceMount` | `boolean` | `false` |
+| `class`      | `string`  | `''`    |
+
+### Parts
+
+- `button[ui-collapsible-trigger]` is the interactive control. It manages `aria-expanded`, `aria-controls`, `data-state`, and root toggling.
+- `ui-collapsible-content` is the panel region. It applies `role="region"`, `aria-labelledby`, `data-state`, and optional persistent projection via `forceMount`.
+- Lower-level behavior follows the Radix Collapsible model: <https://www.radix-ui.com/primitives/docs/components/collapsible#api-reference>.
+
+## Styling and theming
+
+Pass `class` to the root or content, and use the native `class` attribute on the trigger button. The root and content expose `data-state="open" | "closed"` so surrounding styles or transitions can react to the current disclosure state.
+
+Use theme tokens such as `border-border`, `bg-card`, `text-muted-foreground`, and spacing utilities to match the rest of the library.
+
+## Accessibility
+
+- The primitive follows the disclosure WAI-ARIA pattern.
+- Trigger is a native button, so Enter and Space work without extra key handling.
+- Trigger receives `aria-controls` and `aria-expanded`; content receives `role="region"` and `aria-labelledby`.
+- `disabled` keeps the control visible while preventing interaction.
+
+## Keyboard interactions
+
+- `Enter` toggles the collapsible.
+- `Space` toggles the collapsible.
+- Tab order follows the DOM order of the trigger and any focusable controls inside the content.
+
+## Angular notes
+
+- `[(open)]` is the Angular equivalent of shadcn's `open` and `onOpenChange` props.
+- `button[ui-collapsible-trigger]` is a directive, not a component, so it can compose with `button[ui-button]` on the same element.
+- `forceMount` keeps projected content rendered even when the panel is closed, which is useful for measuring or animating content without re-creating it.
+- The local API intentionally does not add an `asChild` prop; Angular composition is handled through selectors and host directives instead.
+
+## Source parity
+
+This Angular implementation follows the shadcn Collapsible structure and examples while translating the API to standalone Angular imports, signal-backed state, button-directive composition, and Angular-friendly RTL guidance.