@ojiepermana/angular 21.3.4 → 22.0.1

package/component/card/README.md

@@ -0,0 +1,220 @@
+# Card
+
+Displays a card with header, content, footer, an optional header action, and a compact size variant.
+
+Use Card for login panels, billing summaries, media/event highlights, and other grouped surfaces that need a clear title plus supporting actions.
+
+## Import
+
+```ts
+import {
+  CardActionComponent,
+  CardComponent,
+  CardContentComponent,
+  CardDescriptionComponent,
+  CardFooterComponent,
+  CardHeaderComponent,
+  CardTitleComponent,
+} from '@ojiepermana/angular/component/card';
+```
+
+## Composition
+
+The Angular structure matches the current shadcn card hierarchy while using Angular selectors.
+
+```text
+ui-card
+├── ui-card-header
+│   ├── ui-card-title
+│   ├── ui-card-description
+│   └── ui-card-action
+├── ui-card-content
+└── ui-card-footer
+```
+
+## Basic usage
+
+```html
+<ui-card class="w-full max-w-sm">
+  <ui-card-header>
+    <ui-card-title>Card Title</ui-card-title>
+    <ui-card-description>Card Description</ui-card-description>
+    <ui-card-action>
+      <button ui-button variant="link" size="sm">Action</button>
+    </ui-card-action>
+  </ui-card-header>
+
+  <ui-card-content>
+    <p>Card Content</p>
+  </ui-card-content>
+
+  <ui-card-footer>
+    <p>Card Footer</p>
+  </ui-card-footer>
+</ui-card>
+```
+
+## Common patterns
+
+### Login card
+
+The current shadcn preview uses the card as a login surface. In Angular, compose the card with button, input, and label primitives directly.
+
+```html
+<ui-card class="w-full max-w-sm">
+  <ui-card-header>
+    <ui-card-title>Login to your account</ui-card-title>
+    <ui-card-description>Enter your email below to login to your account</ui-card-description>
+    <ui-card-action>
+      <button ui-button variant="link" size="sm">Sign Up</button>
+    </ui-card-action>
+  </ui-card-header>
+
+  <ui-card-content>
+    <form class="grid gap-6">
+      <div class="grid gap-2">
+        <label ui-label for="email">Email</label>
+        <input ui-input id="email" type="email" placeholder="m@example.com" required />
+      </div>
+
+      <div class="grid gap-2">
+        <div class="flex items-center">
+          <label ui-label for="password">Password</label>
+          <a href="#forgot-password" class="ms-auto inline-block text-sm underline-offset-4 hover:underline">
+            Forgot your password?
+          </a>
+        </div>
+        <input ui-input id="password" type="password" required />
+      </div>
+    </form>
+  </ui-card-content>
+
+  <ui-card-footer class="flex-col gap-2">
+    <button ui-button class="w-full">Login</button>
+    <button ui-button variant="outline" class="w-full">Login with Google</button>
+  </ui-card-footer>
+</ui-card>
+```
+
+### Small size
+
+Use `size="sm"` on the root card when the surface should feel denser. The compact size cascades to header spacing, content padding, footer padding, and heading/body typography.
+
+```html
+<ui-card size="sm" class="w-full max-w-sm">
+  <ui-card-header>
+    <ui-card-title>Small Card</ui-card-title>
+    <ui-card-description>This card uses the small size variant.</ui-card-description>
+  </ui-card-header>
+  <ui-card-content>
+    <p class="text-sm text-muted-foreground">Compact spacing for dense dashboards or inset panels.</p>
+  </ui-card-content>
+  <ui-card-footer>
+    <button ui-button variant="outline" size="sm" class="w-full">Action</button>
+  </ui-card-footer>
+</ui-card>
+```
+
+### Image card
+
+Add media before the header when the card introduces an event, article, or campaign. `ui-card-action` still sits in the top-right of the header and can host a badge or button.
+
+```html
+<ui-card class="relative w-full max-w-sm overflow-hidden">
+  <div aria-hidden="true" class="pointer-events-none absolute inset-x-0 top-0 z-30 aspect-video bg-black/35"></div>
+  <img
+    src="https://avatar.vercel.sh/shadcn1"
+    alt="Event cover"
+    class="relative z-20 aspect-video w-full object-cover brightness-75 grayscale" />
+
+  <ui-card-header>
+    <ui-card-action>
+      <ui-badge variant="secondary">Featured</ui-badge>
+    </ui-card-action>
+    <ui-card-title>Design systems meetup</ui-card-title>
+    <ui-card-description> A practical talk on component APIs, accessibility, and shipping faster. </ui-card-description>
+  </ui-card-header>
+
+  <ui-card-footer>
+    <button ui-button class="w-full">View event</button>
+  </ui-card-footer>
+</ui-card>
+```
+
+### RTL
+
+Set `dir="rtl"` on the card host or a wrapper when the surrounding interface runs right to left. The composition stays the same.
+
+```html
+<ui-card dir="rtl" lang="ar" class="w-full max-w-sm text-right">
+  <ui-card-header>
+    <ui-card-title>تسجيل الدخول إلى حسابك</ui-card-title>
+    <ui-card-description>أدخل بريدك الإلكتروني أدناه لتسجيل الدخول إلى حسابك</ui-card-description>
+    <ui-card-action>
+      <button ui-button variant="link" size="sm">إنشاء حساب</button>
+    </ui-card-action>
+  </ui-card-header>
+  <ui-card-content>
+    <!-- same form fields as the login example -->
+  </ui-card-content>
+  <ui-card-footer class="flex-col gap-2">
+    <button ui-button class="w-full">تسجيل الدخول</button>
+    <button ui-button variant="outline" class="w-full">تسجيل الدخول باستخدام Google</button>
+  </ui-card-footer>
+</ui-card>
+```
+
+## API reference
+
+### `CardComponent`
+
+| Input   | Type                | Default     |
+| ------- | ------------------- | ----------- |
+| `size`  | `"default" \| "sm"` | `'default'` |
+| `class` | `string`            | `''`        |
+
+The selected size is also exposed on the host as `data-size`, which can be used for styling overrides.
+
+### Parts
+
+| Part                       | Selector              | Notes                                                             |
+| -------------------------- | --------------------- | ----------------------------------------------------------------- |
+| `CardHeaderComponent`      | `ui-card-header`      | Header grid that places `ui-card-action` in the top-right corner. |
+| `CardTitleComponent`       | `ui-card-title`       | Primary heading for the card.                                     |
+| `CardDescriptionComponent` | `ui-card-description` | Supporting text under the title.                                  |
+| `CardActionComponent`      | `ui-card-action`      | Optional slot for badges, links, or buttons in the header.        |
+| `CardContentComponent`     | `ui-card-content`     | Main body area.                                                   |
+| `CardFooterComponent`      | `ui-card-footer`      | Bottom action row or secondary metadata.                          |
+
+All card parts also accept a `class` input.
+
+## Styling and theming
+
+The root card uses the shared theme tokens `border-border`, `bg-card`, and `text-card-foreground` plus `shadow-sm`.
+
+Pass `class` to the root or any part to layer width, layout, spacing, media overflow, or custom action alignment without changing the primitive structure.
+
+The `size` input is the primary spacing control. Switching to `sm` reduces header spacing, content/footer padding, and title/description typography together.
+
+## Accessibility
+
+- Keep the card root non-interactive. Put clicks on native buttons or anchors inside the card.
+- Label every form field inside `ui-card-content`.
+- Provide meaningful alt text for media cards unless the image is purely decorative.
+- Do not rely on the card border or shadow alone to communicate state.
+
+## Keyboard interactions
+
+- The card primitives themselves are passive layout containers and do not enter the tab order.
+- Buttons, anchors, and inputs projected into the card keep their native Tab, Enter, and Space behavior.
+- `ui-card-action` does not alter focus order; it only positions header content visually.
+
+## Angular notes
+
+- `size` is declared only on `ui-card` and cascades to descendant part spacing and typography.
+- `ui-card-action` is the Angular equivalent of the current shadcn `CardAction` slot.
+- The login and RTL examples compose `ButtonComponent`, `InputComponent`, and `LabelComponent` directly with the card primitives.
+
+## Source parity
+
+This Angular implementation follows the current shadcn card docs, including `CardAction`, `size="sm"`, media cards, and the RTL login example, while translating the structure to Angular selectors and native controls.

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
+<ui-carousel class="w-full max-w-xs">
+  <ui-carousel-content>
+    <ui-carousel-item>...</ui-carousel-item>
+    <ui-carousel-item>...</ui-carousel-item>
+    <ui-carousel-item>...</ui-carousel-item>
+  </ui-carousel-content>
+  <button ui-carousel-previous></button>
+  <button ui-carousel-next></button>
+</ui-carousel>
+```
+
+## Composition
+
+```text
+ui-carousel
+├── ui-carousel-content
+│   ├── ui-carousel-item
+│   └── ui-carousel-item
+├── button[ui-carousel-previous]
+└── button[ui-carousel-next]
+```
+
+## Common patterns
+
+### Card slides
+
+```html
+<ui-carousel class="mx-auto w-full max-w-xs">
+  <ui-carousel-content>
+    @for (slide of slides; track slide.id) {
+    <ui-carousel-item [ariaLabel]="slide.label">
+      <div class="p-1">
+        <ui-card>
+          <ui-card-content class="flex aspect-square items-center justify-center p-6">
+            <span class="text-4xl font-semibold">{{ slide.value }}</span>
+          </ui-card-content>
+        </ui-card>
+      </div>
+    </ui-carousel-item>
+    }
+  </ui-carousel-content>
+  <button ui-carousel-previous></button>
+  <button ui-carousel-next></button>
+</ui-carousel>
+```
+
+### Sizes
+
+Use basis utilities on each `ui-carousel-item` when multiple slides should be partially visible.
+
+```ts
+readonly startOptions: CarouselOptions = { align: 'start' };
+```
+
+```html
+<ui-carousel [opts]="startOptions" class="w-full max-w-sm">
+  <ui-carousel-content>
+    <ui-carousel-item class="basis-1/2 lg:basis-1/3">...</ui-carousel-item>
+    <ui-carousel-item class="basis-1/2 lg:basis-1/3">...</ui-carousel-item>
+    <ui-carousel-item class="basis-1/2 lg:basis-1/3">...</ui-carousel-item>
+  </ui-carousel-content>
+</ui-carousel>
+```
+
+### Spacing
+
+Match shadcn spacing by pairing a negative margin on `ui-carousel-content` with padding on `ui-carousel-item`.
+
+```html
+<ui-carousel class="w-full max-w-sm">
+  <ui-carousel-content class="-ml-2 md:-ml-4">
+    <ui-carousel-item class="basis-1/2 pl-2 md:pl-4 lg:basis-1/3">...</ui-carousel-item>
+    <ui-carousel-item class="basis-1/2 pl-2 md:pl-4 lg:basis-1/3">...</ui-carousel-item>
+    <ui-carousel-item class="basis-1/2 pl-2 md:pl-4 lg:basis-1/3">...</ui-carousel-item>
+  </ui-carousel-content>
+</ui-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
+<ui-carousel orientation="vertical" [opts]="verticalOptions" class="w-full max-w-xs">
+  <ui-carousel-content class="-mt-1 h-67.5">
+    <ui-carousel-item class="basis-1/2 pt-1">...</ui-carousel-item>
+    <ui-carousel-item class="basis-1/2 pt-1">...</ui-carousel-item>
+    <ui-carousel-item class="basis-1/2 pt-1">...</ui-carousel-item>
+  </ui-carousel-content>
+</ui-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
+<ui-carousel [opts]="loopOptions">
+  <ui-carousel-content>
+    <ui-carousel-item>...</ui-carousel-item>
+    <ui-carousel-item>...</ui-carousel-item>
+    <ui-carousel-item>...</ui-carousel-item>
+  </ui-carousel-content>
+</ui-carousel>
+```
+
+### API and events
+
+The root component exposes `selectedIndex`, `slideCount`, `canScrollPrev`, and `canScrollNext` as signals. Use a template reference for simple status UI.
+
+```html
+<ui-carousel #carouselRef class="w-full max-w-xs">
+  <ui-carousel-content>
+    <ui-carousel-item>...</ui-carousel-item>
+    <ui-carousel-item>...</ui-carousel-item>
+    <ui-carousel-item>...</ui-carousel-item>
+  </ui-carousel-content>
+</ui-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
+<ui-carousel (apiReady)="connectCarousel($event)"> ... </ui-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
+<ui-carousel [plugins]="plugins">
+  <ui-carousel-content>
+    <ui-carousel-item>...</ui-carousel-item>
+  </ui-carousel-content>
+</ui-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">
+  <ui-carousel dir="rtl" [opts]="rtlOptions" class="w-full max-w-xs">
+    <ui-carousel-content>
+      <ui-carousel-item>...</ui-carousel-item>
+      <ui-carousel-item>...</ui-carousel-item>
+      <ui-carousel-item>...</ui-carousel-item>
+    </ui-carousel-content>
+    <button ui-carousel-previous class="rtl:rotate-180"></button>
+    <button ui-carousel-next class="rtl:rotate-180"></button>
+  </ui-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               |
+| ------------------------------ | -------------------- |
+| `ui-carousel-content`          | `class`              |
+| `ui-carousel-item`             | `ariaLabel`, `class` |
+| `button[ui-carousel-previous]` | `label`, `class`     |
+| `button[ui-carousel-next]`     | `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,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 '@ojiepermana/angular/component/checkbox';
+import { LabelComponent } from '@ojiepermana/angular/component/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.