@ojiepermana/angular 22.1.10 → 22.1.12

package/README.md

@@ -1,30 +1,30 @@
 # @ojiepermana/angular
 
-Umbrella meta-package for the `@ojiepermana/*` design system (Angular v22+).
-Installing it pulls in the whole suite in one command; you then import from the
-per-feature **subpath entry points** that make up the public API.
+Accessible, tree-shakable Angular 22 design system from ojiepermana: UI components, charts, navigation shells, theme tokens, and an OpenAPI SDK generator.
+
+The ojiepermana design system for Angular v22+, published as **one package**.
+Components, charts, navigation shells, theme tokens, and the OpenAPI SDK
+generator all live behind subpath entry points of this single install.
 
 ```bash
 bun add @ojiepermana/angular
 # or: npm install @ojiepermana/angular
 ```
 
-This single install resolves all five libraries as direct dependencies:
-
-| Package                           | What it provides                                        |
-| --------------------------------- | ------------------------------------------------------- |
-| `@ojiepermana/angular-component`  | UI components (button, dialog, table, …) + `icon` utils |
-| `@ojiepermana/angular-chart`      | Chart families built on `d3-scale`/`d3-shape`           |
-| `@ojiepermana/angular-navigation` | App shell / navigation container                        |
-| `@ojiepermana/angular-theme`      | Theme provider, tokens, and Tailwind v4 CSS             |
-| `@ojiepermana/angular-sdk`        | OpenAPI → Angular SDK generator (schematics)            |
+| Subpath                      | What it provides                                        |
+| ---------------------------- | ------------------------------------------------------- |
+| `@ojiepermana/angular/component`  | UI components (button, dialog, table, …) + `icon` utils |
+| `@ojiepermana/angular/chart`      | Chart families built on `d3-scale`/`d3-shape`           |
+| `@ojiepermana/angular/navigation` | App shell / navigation container                        |
+| `@ojiepermana/angular/theme`      | Theme provider, tokens, and Tailwind v4 CSS             |
+| `@ojiepermana/angular/sdk`        | OpenAPI → Angular SDK generator (schematics)            |
 
 ## Peer dependencies
 
 You must already have Angular v22+ in your app (`@angular/common`, `@angular/core`,
-and for some libraries `@angular/forms`, `@angular/router`, `@angular/platform-browser`).
-`@angular/cdk` is pulled in automatically (it is a direct dependency of
-`-component`).
+plus `@angular/router` and `rxjs`). `@angular/cdk`, `@angular/forms`, and
+`@angular/platform-browser` are optional peers: install them when you use the
+surfaces that need them.
 
 **`@angular/material` is optional.** Only three components wrap Material and
 therefore require it: **`select`**, **`date-picker`**, and **`calendar`**. Install
@@ -39,9 +39,8 @@ Material.
 
 ## Importing — `@ojiepermana/angular/<lib>/<entry>`
 
-`@ojiepermana/angular` is the root: every component, chart, and service is reached
-through a nested subpath under it. Each subpath maps 1:1 to the matching
-`@ojiepermana/angular-<lib>` entry point and is fully tree-shakeable.
+Every component, chart, and service is reached through a nested subpath. Each
+subpath is its own entry point and is fully tree-shakeable.
 
 ```ts
 // Components — one entry point per component
@@ -56,10 +55,6 @@ import { BarChart } from '@ojiepermana/angular/chart/bar';
 import { provideUiTheme } from '@ojiepermana/angular/theme/styles';
 ```
 
-> The individual `@ojiepermana/angular-<lib>/<entry>` packages are still published
-> and importable directly, but the `@ojiepermana/angular/...` namespace above is the
-> recommended surface.
-
 **Subpaths only in production.** The bare `@ojiepermana/angular` root barrel
 re-exports the _entire_ design system (chart + component + navigation + sdk +
 theme). Importing from it pulls everything into your bundle, so reserve it for
@@ -80,13 +75,12 @@ stylesheet (the CSS ships inside the package and is reachable by name):
 
 ```css
 /* styles.css */
-@import '@ojiepermana/angular-theme/styles/css/index.css'; /* base + all color + neutral palettes */
+@import '@ojiepermana/angular/theme/styles/css/index.css'; /* base + all color + neutral palettes */
 @import 'tailwindcss';
-@import '@ojiepermana/angular-theme/styles/css/base/tailwind.css'; /* maps tokens → bg-primary, bg-brand, text-foreground, … */
+@import '@ojiepermana/angular/theme/styles/css/base/tailwind.css'; /* maps tokens → bg-primary, bg-brand, text-foreground, … */
 ```
 
-(The theme CSS lives in the `@ojiepermana/angular-theme` package, installed
-automatically as a dependency.) Then register the provider:
+Then register the provider:
 
 ```ts
 import { provideUiTheme } from '@ojiepermana/angular/theme/styles';
@@ -108,6 +102,18 @@ provideUiTheme({ icons: { materialSymbols: true } });
 For privacy / offline / strict-CSP setups, leave it off and self-host the font in
 your own stylesheet instead.
 
+## SDK schematics
+
+```bash
+ng add @ojiepermana/angular
+ng generate @ojiepermana/angular:sdk
+```
+
+## Links
+
+- Source: git+https://github.com/ojiepermana/angular.git
+- Documentation: https://github.com/ojiepermana/angular#readme
+
 ## License
 
 MIT. See the bundled `LICENSE` file.

package/chart/README.md

@@ -0,0 +1,272 @@
+# 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 @ojiepermana/angular
+npm install @ojiepermana/angular
+```
+
+## 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 '@ojiepermana/angular/chart';
+import { BarChart } from '@ojiepermana/angular/chart/bar';
+```
+
+### Supported chart entrypoints
+
+| Import path                          | Selector       | Best for                                                          |
+| ------------------------------------ | -------------- | ----------------------------------------------------------------- |
+| `@ojiepermana/angular/chart/bar`     | `ChartBar`     | grouped, stacked, horizontal, active, and mixed-color bar layouts |
+| `@ojiepermana/angular/chart/line`    | `ChartLine`    | trends, comparisons, and zoomable time-series lines               |
+| `@ojiepermana/angular/chart/area`    | `ChartArea`    | filled trend bands, stacked areas, and expanded percent views     |
+| `@ojiepermana/angular/chart/pie`     | `ChartPie`     | part-to-whole slices and donut charts                             |
+| `@ojiepermana/angular/chart/radar`   | `ChartRadar`   | multi-axis performance comparisons                                |
+| `@ojiepermana/angular/chart/radial`  | `ChartRadial`  | progress rings, radial comparisons, and center-metric summaries   |
+| `@ojiepermana/angular/chart/scatter` | `ChartScatter` | 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
+Chart
+├── ChartBar | ChartLine | ChartArea | ChartScatter
+│   ├── svg:g[ChartGrid]
+│   ├── svg:g[ChartAxisX]
+│   ├── svg:g[ChartAxisY]
+│   └── svg:g[ChartCrosshair] / svg:g[ChartBrush] (optional)
+├── ChartPie | ChartRadial | ChartRadar
+│   └── ChartPieCenter | ChartRadialCenter (optional)
+├── ChartTooltip
+├── ChartLegend
+└── ChartZoomControls (optional)
+```
+
+All child primitives read dimensions, series metadata, and scoped color tokens from `Chart`.
+
+## 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">
+  <Chart [config]="trafficChartConfig" chartId="traffic-overview">
+    <ChartBar [data]="trafficData" xKey="month">
+      <svg:g ChartGrid></svg:g>
+      <svg:g ChartAxisX></svg:g>
+      <svg:g ChartAxisY></svg:g>
+    </ChartBar>
+    <ChartTooltip [data]="trafficData" xKey="month" />
+    <ChartLegend />
+  </Chart>
+</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 `Chart`.
+4. Add `svg:g[ChartGrid]`, axis directives, `ChartTooltip`, and `ChartLegend` 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 '@ojiepermana/angular/chart/area';
+import { LineChart } from '@ojiepermana/angular/chart/line';
+```
+
+- `ChartLine` adds inputs such as `curve`, `showDots`, and `showValueLabels`.
+- `ChartArea` adds `stacked`, `expanded`, `gradient`, and `curve`.
+- `ChartBar` 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
+<Chart [config]="browserConfig" aspect="aspect-square">
+  <ChartPie
+    [data]="browserData"
+    nameKey="browser"
+    valueKey="visitors"
+    [seriesKeys]="browserSeriesKeys"
+    [innerRadius]="64"
+  >
+  </ChartPie>
+  <ChartTooltip [data]="browserData" xKey="browser" valueKey="visitors" indicator="dot" />
+  <ChartLegend />
+</Chart>
+```
+
+### Tooltip formatting
+
+`ChartTooltip` is where most presentational customization lives.
+
+```html
+<ChartTooltip
+  [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[ChartGrid]`  | none                                                                                                     | Adds cartesian grid lines behind bar, line, and area charts.    |
+| `svg:g[ChartAxisX]` | `tickCount`, `tickLine`, `tickFormat`                                                                    | Categorical axis for cartesian layouts.                         |
+| `svg:g[ChartAxisY]` | `tickCount`, `tickLine`, `tickFormat`                                                                    | Numeric axis for cartesian layouts.                             |
+| `ChartTooltip`      | `data`, `xKey`, `valueKey`, `indicator`, `label`, `labelKey`, `labelFormatter`, `formatter`, `hideLabel` | Handles default tooltip layout plus custom template projection. |
+| `ChartLegend`       | none                                                                                                     | Renders toggle buttons for visible series.                      |
+| `ChartZoomControls` | none                                                                                                     | Pair with zoomable line and scatter views.                      |
+| `ChartPieCenter`    | projected content                                                                                        | Centers labels or KPIs inside pie layouts.                      |
+| `ChartRadialCenter` | projected content                                                                                        | Centers labels or KPIs inside radial layouts.                   |
+
+### Chart families
+
+| Selector       | Key inputs                                                                                          |
+| -------------- | --------------------------------------------------------------------------------------------------- |
+| `ChartBar`     | `data`, `xKey`, `orientation`, `variant`, `colorKey`, `activeKey`, `activeValue`, `showValueLabels` |
+| `ChartLine`    | `data`, `xKey`, `curve`, `showDots`, `dotRadius`, `showValueLabels`                                 |
+| `ChartArea`    | `data`, `xKey`, `stacked`, `expanded`, `gradient`, `curve`                                          |
+| `ChartPie`     | `data`, `nameKey`, `valueKey`, `seriesKeys`, `innerRadius`, `activeIndex`, `activeOffset`           |
+| `ChartRadar`   | `data`, `axisKey`, `curve`, `levels`, `grid`, `showLabels`, `showDots`                              |
+| `ChartRadial`  | `data`, `nameKey`, `valueKey`, `seriesKeys`, `maxValue`, `showTrack`, `showValueLabels`             |
+| `ChartScatter` | `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.
+- `Chart` 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.
+- Every chart emits an equivalent screen-reader table for the displayed dataset.
+- Interactive marks use one roving tab stop per chart; arrow keys reach the remaining marks without flooding the page's Tab order.
+- `ChartTooltip` includes a polite live region so changing categories can be announced to assistive technology.
+- `ChartLegend` 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 one interactive mark per chart plus legend toggle buttons.
+- Arrow keys move between marks; Home and End jump to the first and last mark.
+- `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 `Chart`; 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 `Chart`, the relevant `chart-*`, `ChartTooltip`, and `ChartLegend` 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.
+
+## Why the d3 types are runtime dependencies
+
+`@types/d3-array`, `@types/d3-scale`, and `@types/d3-shape` sit in `dependencies`, not
+`devDependencies`, and that is deliberate: d3's types appear in this package's PUBLISHED type
+surface, so a consumer needs them installed to typecheck against it. In
+`@ojiepermana/angular/chart/core` alone, `CategoryScale` is `ScaleBand<string>`, `ValueScale` is
+`ScaleLinear<number, number>`, the cartesian context exposes `xScale`/`yScale` as signals of
+`ScaleLinear`, and `bandTicks`/`linearTicks` take those scales as parameters.
+
+Check it before moving them: build the library and look for `d3-` imports in
+`dist/chart/types/*.d.ts`. If they ever stop appearing there, the types can drop to
+`devDependencies`.
+
+## Support and security
+
+Angular 22.1–22.x CSR/browser usage is supported; SSR, prerendering, and hydration are not. See the
+bundled `SUPPORT.md`. Report suspected vulnerabilities privately using the instructions in the
+bundled `SECURITY.md`. This package is MIT licensed; see the bundled `LICENSE`.

package/component/README.md

@@ -0,0 +1,89 @@
+# @ojiepermana/angular/component
+
+Library ini berada di `library/component` dan diterbitkan sebagai subpath `component` dari paket tunggal `@ojiepermana/angular`.
+
+Library ini menggunakan pola secondary entry point per folder. Import yang disarankan adalah langsung ke subpath yang dibutuhkan, misalnya `@ojiepermana/angular/component/button` atau `@ojiepermana/angular/chart/bar`.
+
+## Build
+
+Paket dibangun sebagai satu kesatuan:
+
+```bash
+bun run ng -- build @ojiepermana/angular
+```
+
+Nama project di `angular.json` adalah `angular-component`. Artefak build akan ditulis ke `dist/component`.
+
+## Penggunaan Lokal
+
+Untuk import dari workspace ini, gunakan path berikut:
+
+```bash
+@ojiepermana/angular/component
+```
+
+Untuk komponen atau utilitas spesifik, gunakan subpath secondary entry point:
+
+```bash
+@ojiepermana/angular/component/button
+@ojiepermana/angular/chart/bar
+@ojiepermana/angular/component/icon
+@ojiepermana/angular/theme/styles
+```
+
+Untuk helper, gunakan entry point terfokus agar helper murni tidak menarik
+runtime overlay:
+
+```ts
+import { cn, injectUniqueId } from '@ojiepermana/angular/component/utils/core';
+import { connectedPositionFor } from '@ojiepermana/angular/component/utils/overlay';
+```
+
+`@ojiepermana/angular/component/utils` tetap tersedia sebagai compatibility
+barrel, tetapi kode baru sebaiknya memilih `utils/core` atau `utils/overlay`.
+
+## Unit Test
+
+Jalankan unit test library dengan perintah berikut:
+
+```bash
+bun run ng -- test angular-component
+```
+
+Runner test di workspace ini menggunakan Vitest melalui Angular build tooling.
+
+## Konvensi Selector
+
+Aturan baku agar semua tim memakai mental model yang sama:
+
+| Jenis primitif                                                            | Selector                     | Contoh                             |
+| ------------------------------------------------------------------------- | ---------------------------- | ---------------------------------- |
+| Menempel ke elemen HTML semantik (button, input, label, textarea, select) | Attribute selector           | `<button Button>`, `<input Input>` |
+| Container/komposit tanpa padanan elemen native                            | Element selector             | `<Card>`, `<Dialog>`, `<Tabs>`     |
+| Behavior tanpa render (trigger, content marker)                           | Directive `[Xxx]` PascalCase | `[PopoverTrigger]`, `[Tooltip]`    |
+
+Beberapa komponen menyediakan keduanya (`Label, label[Label]`) untuk
+markup fleksibel — gunakan bentuk attribute bila elemen native tersedia karena
+semantik & aksesibilitasnya gratis dari browser.
+
+## Dependensi runtime
+
+- `@angular/cdk` adalah **dependency langsung** paket ini (overlay/portal/a11y
+  dipakai oleh banyak komponen), jadi ikut terinstal otomatis — tidak ada lagi
+  error `Cannot find module '@angular/cdk/overlay'`.
+- `@angular/common`, `@angular/core`, `@angular/forms`,
+  `@angular/platform-browser`, dan `rxjs` tetap peer dependency (disediakan oleh
+  aplikasi Angular Anda).
+
+## Status Dependensi @angular/material
+
+`@angular/material` masih menjadi peer dependency opsional untuk
+`SelectField`, yang kembali menggunakan `MatSelect` dan `MatOption`. `Calendar`
+dan `DatePicker` tetap memakai primitif native/CDK, sehingga consumer yang tidak
+mengimpor `SelectField` tidak perlu memasang Material.
+
+## Support and security
+
+Angular 22.1–22.x CSR/browser usage is supported; SSR, prerendering, and hydration are not. See the
+bundled `SUPPORT.md`. Report suspected vulnerabilities privately using the instructions in the
+bundled `SECURITY.md`. This package is MIT licensed; see the bundled `LICENSE`.

package/component/accordion/README.md

@@ -0,0 +1,195 @@
+# Accordion
+
+Displays a vertically stacked set of interactive headings that reveal one or more content panels.
+
+Use Accordion for FAQ blocks, settings groups, and progressive disclosure where content should stay in the same page flow.
+
+## Import
+
+```ts
+import {
+  AccordionComponent,
+  AccordionContentComponent,
+  AccordionItemComponent,
+  AccordionTriggerComponent,
+} from '@ojiepermana/angular/component/accordion';
+```
+
+## Composition
+
+The Angular structure mirrors the shadcn and Radix composition while using Angular selectors and a native button trigger.
+
+```text
+Accordion
+├── AccordionItem
+│   ├── button[AccordionTrigger]
+│   └── AccordionContent
+└── AccordionItem
+    ├── button[AccordionTrigger]
+    └── AccordionContent
+```
+
+## Basic usage
+
+Use `Accordion` as the root, wrap each section in `AccordionItem`, place the clickable heading on a native button with `AccordionTrigger`, and project body copy into `AccordionContent`.
+
+Bind `[(value)]` when the parent should control the open state or seed a default open item.
+
+```html
+<Accordion [(value)]="openItem" type="single" class="w-full max-w-xl">
+  <AccordionItem value="item-1">
+    <button AccordionTrigger>Is it accessible?</button>
+    <AccordionContent>
+      Yes. The trigger and content follow the expected accordion ARIA wiring.
+    </AccordionContent>
+  </AccordionItem>
+</Accordion>
+```
+
+## Common patterns
+
+### Single-open FAQ
+
+Use `type="single"` when only one item should stay open at a time.
+
+```ts
+const basicOpen = signal<string | string[] | null>('item-1');
+
+<Accordion [(value)]="basicOpen" type="single" class="max-w-lg">
+  <AccordionItem value="item-1">...</AccordionItem>
+  <AccordionItem value="item-2">...</AccordionItem>
+  <AccordionItem value="item-3">...</AccordionItem>
+</Accordion>
+```
+
+### Multiple open sections
+
+Use `type="multiple"` when more than one panel should stay open. The bound value becomes a `string[]`.
+
+```ts
+const multipleOpen = signal<string[] | null>(['notifications']);
+
+<Accordion [(value)]="multipleOpen" type="multiple" class="max-w-lg">
+  <AccordionItem value="notifications">...</AccordionItem>
+  <AccordionItem value="privacy">...</AccordionItem>
+  <AccordionItem value="billing">...</AccordionItem>
+</Accordion>
+```
+
+### Disabled items
+
+Disable an individual item with `[disabled]="true"` on `AccordionItem`.
+
+```ts
+const disabledOpen = signal<string | string[] | null>('history');
+
+<Accordion [(value)]="disabledOpen" type="single" class="w-full">
+  <AccordionItem value="history">...</AccordionItem>
+  <AccordionItem value="premium" [disabled]="true">...</AccordionItem>
+  <AccordionItem value="email">...</AccordionItem>
+</Accordion>
+```
+
+### Bordered list
+
+Add borders on the root and the items when the accordion should read like a boxed settings list.
+
+```ts
+const borderOpen = signal<string | string[] | null>('billing');
+
+<Accordion [(value)]="borderOpen" type="single" class="max-w-lg rounded-lg border">
+  <AccordionItem value="billing" class="border-b px-4 last:border-b-0">...</AccordionItem>
+  <AccordionItem value="security" class="border-b px-4 last:border-b-0">...</AccordionItem>
+  <AccordionItem value="integrations" class="border-b px-4 last:border-b-0">...</AccordionItem>
+</Accordion>
+```
+
+### Inside a card
+
+Accordion works well inside `Card` when the disclosure belongs to a larger billing or account surface.
+
+```ts
+const cardOpen = signal<string | string[] | null>('plans');
+
+<Card class="w-full max-w-sm">
+  <CardHeader>
+    <CardTitle>Subscription and billing</CardTitle>
+    <CardDescription>Common questions about plans, payments, and cancellations.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <Accordion [(value)]="cardOpen" type="single">
+      <AccordionItem value="plans">...</AccordionItem>
+      <AccordionItem value="billing">...</AccordionItem>
+      <AccordionItem value="cancel">...</AccordionItem>
+    </Accordion>
+  </CardContent>
+</Card>
+```
+
+### RTL
+
+For right-to-left interfaces, set `dir="rtl"` on a wrapping container or manage direction globally in the app shell. The Accordion structure itself does not change.
+
+```html
+<section dir="rtl" lang="ar" class="max-w-md text-right">
+  <Accordion [(value)]="rtlOpen" type="single">
+    <AccordionItem value="item-1">...</AccordionItem>
+    <AccordionItem value="item-2">...</AccordionItem>
+    <AccordionItem value="item-3">...</AccordionItem>
+  </Accordion>
+</section>
+```
+
+## API reference
+
+### `AccordionComponent`
+
+| Input           | Type                         | Default    |
+| --------------- | ---------------------------- | ---------- |
+| `type`          | `'single' \| 'multiple'`     | `'single'` |
+| `collapsible`   | `boolean`                    | `true`     |
+| `value` (model) | `string \| string[] \| null` | `null`     |
+| `class`         | `string`                     | `''`       |
+
+### `AccordionItemComponent`
+
+| Input      | Type      | Default |
+| ---------- | --------- | ------- |
+| `value`    | `string`  | —       |
+| `disabled` | `boolean` | `false` |
+| `class`    | `string`  | `''`    |
+
+### Parts
+
+- `button[AccordionTrigger]` renders the interactive heading and manages `aria-controls` plus `aria-expanded`.
+- `AccordionContent` renders the panel region and links back to the trigger with `aria-labelledby`.
+- Lower-level primitive behavior is based on the Radix Accordion pattern: <https://www.radix-ui.com/primitives/docs/components/accordion#api-reference>.
+
+## Styling and theming
+
+Pass `class` to the root or item parts to tune width, spacing, borders, and embedded-card layouts.
+
+The component follows the shared library theme tokens, so standard utility classes such as `border`, `rounded-lg`, `bg-card`, `text-foreground`, and spacing utilities work as expected.
+
+## Accessibility
+
+- Trigger has `aria-expanded` and `aria-controls` pointing at the content id.
+- Content has `role="region"` and `aria-labelledby` pointing back at the trigger id.
+- `disabled` items remain visible but non-interactive and are marked with `aria-disabled`.
+- Keep trigger text descriptive and avoid placing nested interactive controls inside the trigger button.
+
+## Keyboard interactions
+
+- Native button activation covers Enter and Space.
+- Tab order follows the DOM order of the triggers and content.
+
+## Angular notes
+
+- The component uses Angular signal-based `model()` binding for `value`.
+- For `type="single"`, the value is a `string | null`.
+- For `type="multiple"`, the value is a `string[] | null`.
+- Seed the initial open state with a signal rather than a separate `defaultValue` prop.
+
+## Source parity
+
+This Angular implementation follows the shadcn Accordion concepts while translating the examples to Angular selectors, standalone imports, and signal-friendly bindings.