@ojiepermana/angular 22.1.11 → 22.1.12

package/component/carousel/README.md

@@ -0,0 +1,276 @@
+# Carousel
+
+A carousel with motion, drag gestures, keyboard navigation, and Embla-powered slide state.
+
+Use Carousel for image galleries, card reels, onboarding panels, and compact item pickers where adjacent content should be discoverable without leaving the current view.
+
+## Import
+
+```ts
+import {
+  CarouselComponent,
+  CarouselContentComponent,
+  CarouselItemComponent,
+  CarouselNextComponent,
+  CarouselPreviousComponent,
+  type CarouselApi,
+  type CarouselOptions,
+} from '@ojiepermana/angular/component/carousel';
+```
+
+## Usage
+
+Compose the carousel from a root, content track, items, and optional previous/next buttons.
+
+```html
+<Carousel class="w-full max-w-xs">
+  <CarouselContent>
+    <CarouselItem>...</CarouselItem>
+    <CarouselItem>...</CarouselItem>
+    <CarouselItem>...</CarouselItem>
+  </CarouselContent>
+  <button CarouselPrevious></button>
+  <button CarouselNext></button>
+</Carousel>
+```
+
+## Composition
+
+```text
+Carousel
+├── CarouselContent
+│   ├── CarouselItem
+│   └── CarouselItem
+├── button[CarouselPrevious]
+└── button[CarouselNext]
+```
+
+## Common patterns
+
+### Card slides
+
+```html
+<Carousel class="mx-auto w-full max-w-xs">
+  <CarouselContent>
+    @for (slide of slides; track slide.id) {
+    <CarouselItem [ariaLabel]="slide.label">
+      <div class="p-1">
+        <Card>
+          <CardContent class="flex aspect-square items-center justify-center p-6">
+            <span class="text-4xl font-semibold">{{ slide.value }}</span>
+          </CardContent>
+        </Card>
+      </div>
+    </CarouselItem>
+    }
+  </CarouselContent>
+  <button CarouselPrevious></button>
+  <button CarouselNext></button>
+</Carousel>
+```
+
+### Sizes
+
+Use basis utilities on each `CarouselItem` when multiple slides should be partially visible.
+
+```ts
+readonly startOptions: CarouselOptions = { align: 'start' };
+```
+
+```html
+<Carousel [opts]="startOptions" class="w-full max-w-sm">
+  <CarouselContent>
+    <CarouselItem class="basis-1/2 lg:basis-1/3">...</CarouselItem>
+    <CarouselItem class="basis-1/2 lg:basis-1/3">...</CarouselItem>
+    <CarouselItem class="basis-1/2 lg:basis-1/3">...</CarouselItem>
+  </CarouselContent>
+</Carousel>
+```
+
+### Spacing
+
+Match shadcn spacing by pairing a negative margin on `CarouselContent` with padding on `CarouselItem`.
+
+```html
+<Carousel class="w-full max-w-sm">
+  <CarouselContent class="-ml-2 md:-ml-4">
+    <CarouselItem class="basis-1/2 pl-2 md:pl-4 lg:basis-1/3">...</CarouselItem>
+    <CarouselItem class="basis-1/2 pl-2 md:pl-4 lg:basis-1/3">...</CarouselItem>
+    <CarouselItem class="basis-1/2 pl-2 md:pl-4 lg:basis-1/3">...</CarouselItem>
+  </CarouselContent>
+</Carousel>
+```
+
+### Vertical orientation
+
+Set `orientation="vertical"` and give the content viewport a height so Embla can measure the track.
+
+```ts
+readonly verticalOptions: CarouselOptions = { align: 'start' };
+```
+
+```html
+<Carousel orientation="vertical" [opts]="verticalOptions" class="w-full max-w-xs">
+  <CarouselContent class="-mt-1 h-67.5">
+    <CarouselItem class="basis-1/2 pt-1">...</CarouselItem>
+    <CarouselItem class="basis-1/2 pt-1">...</CarouselItem>
+    <CarouselItem class="basis-1/2 pt-1">...</CarouselItem>
+  </CarouselContent>
+</Carousel>
+```
+
+### Options
+
+Pass Embla options through `[opts]`. Keep the object as a class property so Angular does not create a new object every change detection pass.
+
+```ts
+readonly loopOptions: CarouselOptions = {
+  align: 'start',
+  loop: true,
+};
+```
+
+```html
+<Carousel [opts]="loopOptions">
+  <CarouselContent>
+    <CarouselItem>...</CarouselItem>
+    <CarouselItem>...</CarouselItem>
+    <CarouselItem>...</CarouselItem>
+  </CarouselContent>
+</Carousel>
+```
+
+### API and events
+
+The root component exposes `selectedIndex`, `slideCount`, `canScrollPrev`, and `canScrollNext` as signals. Use a template reference for simple status UI.
+
+```html
+<Carousel #carouselRef class="w-full max-w-xs">
+  <CarouselContent>
+    <CarouselItem>...</CarouselItem>
+    <CarouselItem>...</CarouselItem>
+    <CarouselItem>...</CarouselItem>
+  </CarouselContent>
+</Carousel>
+
+<p>Slide {{ carouselRef.selectedIndex() + 1 }} of {{ carouselRef.slideCount() }}</p>
+```
+
+Use `(apiReady)` when you need the lower-level Embla API.
+
+```ts
+connectCarousel(api: CarouselApi): void {
+  api.on('select', () => {
+    this.currentSlide.set(api.selectedScrollSnap() + 1);
+  });
+}
+```
+
+```html
+<Carousel (apiReady)="connectCarousel($event)"> ... </Carousel>
+```
+
+### Plugins
+
+Optional Embla plugins are passed through `[plugins]`. Install plugin packages separately.
+
+```ts
+import Autoplay from 'embla-carousel-autoplay';
+
+readonly plugins = [Autoplay({ delay: 2000 })];
+```
+
+```html
+<Carousel [plugins]="plugins">
+  <CarouselContent>
+    <CarouselItem>...</CarouselItem>
+  </CarouselContent>
+</Carousel>
+```
+
+### RTL
+
+Set both `dir="rtl"` and `opts.direction` so layout direction and Embla motion agree.
+
+```ts
+readonly rtlOptions: CarouselOptions = { direction: 'rtl' };
+```
+
+```html
+<section dir="rtl">
+  <Carousel dir="rtl" [opts]="rtlOptions" class="w-full max-w-xs">
+    <CarouselContent>
+      <CarouselItem>...</CarouselItem>
+      <CarouselItem>...</CarouselItem>
+      <CarouselItem>...</CarouselItem>
+    </CarouselContent>
+    <button CarouselPrevious class="rtl:rotate-180"></button>
+    <button CarouselNext class="rtl:rotate-180"></button>
+  </Carousel>
+</section>
+```
+
+## API reference
+
+### `CarouselComponent`
+
+| Input or output | Type                         | Default                                        |
+| --------------- | ---------------------------- | ---------------------------------------------- |
+| `orientation`   | `'horizontal' \| 'vertical'` | `'horizontal'`                                 |
+| `opts`          | `CarouselOptions`            | `{}`                                           |
+| `plugins`       | `readonly CarouselPlugin[]`  | `[]`                                           |
+| `keyboard`      | `boolean`                    | `true`                                         |
+| `label`         | `string`                     | `'Carousel'`                                   |
+| `class`         | `string`                     | `''`                                           |
+| `apiReady`      | `CarouselApi` output         | emitted after Embla initializes                |
+| `apiChange`     | `CarouselApi \| null` output | emitted when Embla initializes or is destroyed |
+
+### Root signals
+
+| Signal          | Type              |
+| --------------- | ----------------- |
+| `selectedIndex` | `Signal<number>`  |
+| `slideCount`    | `Signal<number>`  |
+| `canScrollPrev` | `Signal<boolean>` |
+| `canScrollNext` | `Signal<boolean>` |
+
+### Parts
+
+| Part                       | Inputs               |
+| -------------------------- | -------------------- |
+| `CarouselContent`          | `class`              |
+| `CarouselItem`             | `ariaLabel`, `class` |
+| `button[CarouselPrevious]` | `label`, `class`     |
+| `button[CarouselNext]`     | `label`, `class`     |
+
+## Styling and theming
+
+The primitive follows the shadcn layout recipe: root is `relative`, content owns the overflow-hidden viewport, and items are `basis-full` by default. Pass `class` to tune width, item basis, spacing, and control placement.
+
+Use theme-aware classes such as `border-border`, `bg-card`, `text-foreground`, `bg-background`, `hover:bg-accent`, and `focus-visible:ring-ring` for custom slide and control styling.
+
+## Accessibility
+
+- The root renders as a labelled `region` with `aria-roledescription="carousel"`.
+- Previous and next controls are native buttons with descriptive labels and disabled states.
+- Each item renders as a `group` with `aria-roledescription="slide"`; pass `ariaLabel` when the slide needs an explicit spoken label.
+- Keep interactive controls inside slides reachable by normal tab order and avoid hiding focus outlines.
+
+## Keyboard interactions
+
+- The root is focusable when `keyboard` is `true`.
+- Horizontal carousels use ArrowLeft and ArrowRight to move between slides.
+- Vertical carousels use ArrowUp and ArrowDown to move between slides.
+- Home moves to the first slide and End moves to the last slide.
+- Previous and next buttons also support native Enter and Space activation.
+
+## Angular notes
+
+- This implementation uses vanilla Embla Carousel rather than `embla-carousel-react`.
+- Embla initializes only in the browser, so server rendering can produce the static slide markup without touching the DOM API.
+- `orientation` controls Embla axis; if `opts.axis` is provided, the Angular `orientation` input wins.
+- Define `opts` and `plugins` as class properties to avoid unnecessary Embla reinitialization.
+
+## Source parity
+
+This Angular implementation follows the shadcn Carousel anatomy, options, API, events, plugins, and RTL guidance while translating React props into Angular inputs, outputs, signals, and standalone component imports.

package/component/checkbox/README.md

@@ -0,0 +1,153 @@
+# Checkbox
+
+A shadcn-style checkbox primitive built on a native `<input type="checkbox">`, with full `ControlValueAccessor` support for `ngModel` and reactive forms.
+
+## Import
+
+```ts
+import { CheckboxComponent } from '@ojiepermana/angular/component/checkbox';
+import { LabelComponent } from '@ojiepermana/angular/component/label';
+```
+
+## Usage
+
+Wrap the control and copy in `label[Label]` when the text should toggle the checkbox. This is the closest Angular equivalent to the upstream shadcn `Field` + `FieldLabel` composition.
+
+```html
+<label Label class="flex items-start gap-3">
+  <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
+<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
+<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 Label class="flex items-start gap-3 text-destructive">
+  <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 Label class="flex items-start gap-3">
+    <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
+<Checkbox
+  [ngModel]="selectAll()"
+  [indeterminate]="someRowsSelected()"
+  aria-label="Select all team members"
+  (checkedChange)="handleSelectAll($event)"
+/>
+```
+
+## API reference
+
+| Input              | Type                        | Default        | Notes                                                        |
+| ------------------ | --------------------------- | -------------- | ------------------------------------------------------------ |
+| `id`               | `string`                    | auto-generated | Set directly on the native checkbox 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.                               |
+| `disabled`         | `boolean`                   | `false`        | Disables the control; 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 checkbox host.                   |
+
+| Output          | Payload   |
+| --------------- | --------- |
+| `checkedChange` | `boolean` |
+
+Public method: `focus()`.
+
+## Styling and theming
+
+The component renders a native checkbox input that 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 the component's inline `styles` 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`, it is set directly on the native checkbox input; wrapper labels or `aria-labelledby` are usually the simplest Angular pattern.
+- Projected text still works if you prefer `<Checkbox>Accept</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/component/collapsible/README.md

@@ -0,0 +1,216 @@
+# 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 '@ojiepermana/angular/component/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
+Collapsible
+├── button[CollapsibleTrigger]
+└── CollapsibleContent
+```
+
+## Basic usage
+
+Bind `[(open)]` when the parent should control the disclosure state or seed a default open panel.
+
+```ts
+readonly detailsOpen = signal(false);
+```
+
+```html
+<Collapsible [(open)]="detailsOpen" class="w-full max-w-md rounded-lg border border-border p-3">
+  <button
+    CollapsibleTrigger
+    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>
+
+  <CollapsibleContent class="pt-3 text-sm text-muted-foreground">
+    Yes. The trigger and content follow the disclosure ARIA pattern and stay in normal layout flow.
+  </CollapsibleContent>
+</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[CollapsibleTrigger]` is a directive, so it can compose with the local button primitive on the same element.
+
+```html
+<Collapsible [(open)]="basicOpen" class="rounded-md border border-border p-2">
+  <button Button CollapsibleTrigger 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>
+
+  <CollapsibleContent class="px-2 pb-2 pt-1 text-sm text-muted-foreground">
+    This panel can reveal additional details without leaving the page.
+  </CollapsibleContent>
+</Collapsible>
+```
+
+### Settings drawer
+
+Wrap the trigger and content inside a card-like surface when the disclosure belongs to a small settings editor.
+
+```html
+<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 Input placeholder="Radius X" />
+      <input Input placeholder="Radius Y" />
+      <CollapsibleContent class="col-span-full grid grid-cols-2 gap-2 pt-0">
+        <input Input placeholder="Blur" />
+        <input Input placeholder="Spread" />
+      </CollapsibleContent>
+    </div>
+
+    <button
+      Button
+      CollapsibleTrigger
+      variant="outline"
+      size="icon"
+      aria-label="Toggle advanced fields"
+    >
+      <span aria-hidden="true">...</span>
+    </button>
+  </div>
+</Collapsible>
+```
+
+### Nested file tree
+
+Nested `Collapsible` roots work well for compact explorers and outline views.
+
+```html
+<Collapsible [(open)]="componentsOpen">
+  <button CollapsibleTrigger class="inline-flex items-center gap-2 text-sm font-medium">
+    components
+  </button>
+
+  <CollapsibleContent class="ml-5 mt-2 flex flex-col gap-1">
+    <Collapsible [(open)]="uiOpen">
+      <button CollapsibleTrigger class="inline-flex items-center gap-2 text-sm font-medium">
+        ui
+      </button>
+      <CollapsibleContent class="ml-5 mt-2 flex flex-col gap-1 text-sm text-muted-foreground">
+        <span>button.ts</span>
+        <span>collapsible.ts</span>
+      </CollapsibleContent>
+    </Collapsible>
+  </CollapsibleContent>
+</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">
+  <Collapsible [(open)]="rtlOpen" class="flex flex-col gap-2">
+    <button
+      CollapsibleTrigger
+      class="inline-flex items-center justify-between gap-2 text-sm font-medium"
+    >
+      تبديل التفاصيل
+    </button>
+    <CollapsibleContent 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>
+    </CollapsibleContent>
+  </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[CollapsibleTrigger]` is the interactive control. It manages `aria-expanded`, `aria-controls`, `data-state`, and root toggling.
+- `CollapsibleContent` 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[CollapsibleTrigger]` is a directive, not a component, so it can compose with `button[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.