@ojiepermana/angular 22.1.11 → 22.1.12

package/component/alert/README.md

@@ -0,0 +1,184 @@
+# Alert
+
+Displays a callout for user attention.
+
+Use Alert for inline status callouts, destructive warnings, upgrade prompts, and other situations where the message should stay anchored in the current page flow.
+
+## Import
+
+```ts
+import {
+  AlertActionComponent,
+  AlertComponent,
+  AlertDescriptionComponent,
+  AlertTitleComponent,
+} from '@ojiepermana/angular/component/alert';
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+```
+
+## Composition
+
+The Angular structure mirrors the shadcn composition while leaving icon choice to the consuming app.
+
+```text
+Alert
+├── svg (optional icon)
+├── AlertTitle
+├── AlertDescription
+└── AlertAction (optional)
+```
+
+## Usage
+
+```html
+<Alert class="max-w-md">
+  <svg aria-hidden="true" class="size-4"><!-- icon --></svg>
+  <AlertTitle>Heads up!</AlertTitle>
+  <AlertDescription>
+    You can add components and dependencies to your app using the CLI.
+  </AlertDescription>
+</Alert>
+
+<Alert class="max-w-md">
+  <AlertTitle>Dark mode is now available</AlertTitle>
+  <AlertDescription> Enable it under your profile settings to get started. </AlertDescription>
+  <AlertAction>
+    <button Button variant="outline" size="sm">Enable</button>
+  </AlertAction>
+</Alert>
+```
+
+## Common patterns
+
+### Basic
+
+Use an optional icon plus title and description for successful or informative states.
+
+```html
+<Alert class="max-w-md">
+  <svg aria-hidden="true" class="size-4"><!-- success icon --></svg>
+  <AlertTitle>Account updated successfully</AlertTitle>
+  <AlertDescription>
+    Your profile information has been saved. Changes will be reflected immediately.
+  </AlertDescription>
+</Alert>
+```
+
+### Destructive
+
+Apply `variant="destructive"` for failures, expired sessions, and other high-priority issues.
+
+```html
+<Alert variant="destructive" class="max-w-md">
+  <svg aria-hidden="true" class="size-4"><!-- warning icon --></svg>
+  <AlertTitle>Payment failed</AlertTitle>
+  <AlertDescription>
+    Your payment could not be processed. Please check your payment method and try again.
+  </AlertDescription>
+</Alert>
+```
+
+### Action
+
+Wrap a trailing control in `AlertAction`. The wrapper aligns the control at the end of the message and anchors it to the top-right on wider layouts.
+
+```html
+<Alert class="max-w-md">
+  <AlertTitle>Dark mode is now available</AlertTitle>
+  <AlertDescription> Enable it under your profile settings to get started. </AlertDescription>
+  <AlertAction>
+    <button Button variant="default" size="sm">Enable</button>
+  </AlertAction>
+</Alert>
+```
+
+### Custom colors
+
+Pass custom classes to the root when the alert should adopt a contextual palette.
+
+```html
+<Alert class="max-w-md border-amber-300 bg-amber-50 text-amber-950 [&>svg]:text-amber-700">
+  <svg aria-hidden="true" class="size-4"><!-- warning icon --></svg>
+  <AlertTitle>Your subscription will expire in 3 days.</AlertTitle>
+  <AlertDescription>
+    Renew now to avoid service interruption or upgrade to a paid plan to continue using the service.
+  </AlertDescription>
+</Alert>
+```
+
+### RTL
+
+For right-to-left interfaces, place the alert inside a container with `dir="rtl"` or manage direction globally in the app shell.
+
+```html
+<section dir="rtl" lang="ar" class="max-w-md text-right">
+  <Alert>
+    <svg aria-hidden="true" class="size-4"><!-- icon --></svg>
+    <AlertTitle>تم الدفع بنجاح</AlertTitle>
+    <AlertDescription>
+      تمت معالجة دفعتك البالغة 29.99 دولارًا. تم إرسال إيصال إلى عنوان بريدك الإلكتروني.
+    </AlertDescription>
+  </Alert>
+</section>
+```
+
+## API reference
+
+### `AlertComponent`
+
+| Input     | Type                         | Default     |
+| --------- | ---------------------------- | ----------- |
+| `variant` | `'default' \| 'destructive'` | `'default'` |
+| `class`   | `string`                     | `''`        |
+
+### `AlertTitleComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+### `AlertDescriptionComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+### `AlertActionComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+### Parts
+
+- `AlertTitle` renders the heading of the callout.
+- `AlertDescription` renders the supporting copy.
+- `AlertAction` is an optional layout wrapper for a trailing button or link.
+
+Re-export: `alertVariants` and `AlertVariant`.
+
+## Styling and theming
+
+Tokens consumed: `--border`, `--background`, `--foreground`, `--destructive`.
+Leading SVG children are auto-positioned via descendant selectors so an icon slots in cleanly without extra wrapper markup.
+
+Pass `class` to the root when you need wider layouts, custom color treatments, or embedded card styling. Pass `class` to the title, description, or action parts when a specific example needs spacing or typography overrides.
+
+## Accessibility
+
+The root has `role="alert"` so assistive technologies announce the message when
+it appears. For polite, non-interrupting messages, prefer a toast or another live-region pattern instead.
+
+When you include a call-to-action, keep the control a native `<button Button>` or `<a Button>` so standard keyboard and assistive-technology behavior remains intact.
+
+## Keyboard interactions
+
+The alert itself does not handle keyboard input. Any nested actions inherit native keyboard behavior from the projected button or link.
+
+## Angular notes
+
+The Angular version keeps the same shadcn parts while translating them to standalone imports, `input()` bindings, and utility-first host classes. Icons are application-level concerns, so bring your own icon component or inline SVG instead of expecting an icon export from the alert primitive.
+
+## Source parity
+
+This implementation follows the shadcn Alert structure and examples while adapting the API to Angular selectors, standalone imports, and the local button primitive for action content.

package/component/alert-dialog/README.md

@@ -0,0 +1,255 @@
+# Alert Dialog
+
+Displays a modal confirmation surface for important or destructive actions where the user is expected to respond before continuing.
+
+Use Alert Dialog for delete confirmations, permission prompts, and share or access decisions that should not dismiss accidentally on backdrop click.
+
+## Import
+
+```ts
+import {
+  AlertDialogActionComponent,
+  AlertDialogCancelComponent,
+  AlertDialogComponent,
+  AlertDialogContentComponent,
+  AlertDialogDescriptionComponent,
+  AlertDialogFooterComponent,
+  AlertDialogHeaderComponent,
+  AlertDialogMediaComponent,
+  AlertDialogTitleComponent,
+} from '@ojiepermana/angular/component/alert-dialog';
+```
+
+## Composition
+
+The Angular composition keeps the shadcn structure for content and actions, with one intentional mapping difference: shadcn `AlertDialogTrigger` becomes any external control that toggles the `open` signal.
+
+```text
+button[Button] (external trigger; sets the open signal)
+AlertDialog
+└── AlertDialogContent
+    ├── AlertDialogHeader
+    │   ├── AlertDialogMedia (optional)
+    │   ├── AlertDialogTitle
+    │   └── AlertDialogDescription
+    └── AlertDialogFooter
+        ├── button[AlertDialogCancel]
+        └── button[AlertDialogAction]
+```
+
+## Basic usage
+
+Use an external trigger to set the `open` model, then declare the alert content inside `AlertDialog`.
+
+```html
+<button type="button" Button variant="outline" (click)="confirmOpen.set(true)">Show Dialog</button>
+
+<AlertDialog
+  [(open)]="confirmOpen"
+  aria-labelledby="alert-title"
+  aria-describedby="alert-description"
+>
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogTitle id="alert-title">Are you absolutely sure?</AlertDialogTitle>
+      <AlertDialogDescription id="alert-description">
+        This action cannot be undone. This will permanently delete your account from our servers.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+
+    <AlertDialogFooter>
+      <button type="button" AlertDialogCancel>Cancel</button>
+      <button type="button" AlertDialogAction>Continue</button>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+## Common patterns
+
+### Small confirmation
+
+Set `size="sm"` on `AlertDialogContent` for shorter mobile-friendly confirmations.
+
+```html
+<AlertDialog [(open)]="smallOpen">
+  <AlertDialogContent size="sm">
+    <AlertDialogHeader>
+      <AlertDialogTitle>Allow accessory to connect?</AlertDialogTitle>
+      <AlertDialogDescription>
+        Do you want to allow the USB accessory to connect to this device?
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+
+    <AlertDialogFooter>
+      <button type="button" AlertDialogCancel>Don't allow</button>
+      <button type="button" AlertDialogAction>Allow</button>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Media
+
+Use `AlertDialogMedia` to add an icon or other leading visual treatment above the title on mobile and beside it on larger screens.
+
+```html
+<AlertDialog [(open)]="shareOpen">
+  <AlertDialogContent>
+    <AlertDialogHeader>
+      <AlertDialogMedia>
+        <svg
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          aria-hidden="true"
+        >
+          <path d="M12 5v14" />
+          <path d="M5 12h14" />
+          <circle cx="12" cy="12" r="8" />
+        </svg>
+      </AlertDialogMedia>
+      <AlertDialogTitle>Share this project?</AlertDialogTitle>
+      <AlertDialogDescription>
+        Anyone with the link will be able to view and edit this project.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+
+    <AlertDialogFooter>
+      <button type="button" AlertDialogCancel>Cancel</button>
+      <button type="button" AlertDialogAction>Share</button>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### Destructive action
+
+Pass `variant="destructive"` to `AlertDialogAction` when the primary action is destructive.
+
+```html
+<AlertDialog [(open)]="deleteOpen">
+  <AlertDialogContent size="sm">
+    <AlertDialogHeader>
+      <AlertDialogMedia class="border-destructive/20 bg-destructive/10 text-destructive">
+        <svg
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="1.75"
+          aria-hidden="true"
+        >
+          <path d="M3 6h18" />
+          <path d="M8 6V4h8v2" />
+          <path d="M8 10v6" />
+          <path d="M12 10v6" />
+          <path d="M16 10v6" />
+          <path d="M5 6l1 13h12l1-13" />
+        </svg>
+      </AlertDialogMedia>
+      <AlertDialogTitle>Delete chat?</AlertDialogTitle>
+      <AlertDialogDescription>
+        This permanently deletes the conversation and removes saved memories linked to it.
+      </AlertDialogDescription>
+    </AlertDialogHeader>
+
+    <AlertDialogFooter>
+      <button type="button" AlertDialogCancel>Cancel</button>
+      <button type="button" AlertDialogAction variant="destructive">Delete</button>
+    </AlertDialogFooter>
+  </AlertDialogContent>
+</AlertDialog>
+```
+
+### RTL
+
+Wrap the trigger and dialog in a `dir="rtl"` container or manage direction globally in the app shell.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <button type="button" Button variant="outline" (click)="rtlOpen.set(true)">إظهار الحوار</button>
+
+  <AlertDialog [(open)]="rtlOpen" aria-labelledby="rtl-title" aria-describedby="rtl-description">
+    <AlertDialogContent size="sm">
+      <AlertDialogHeader>
+        <AlertDialogTitle id="rtl-title">هل أنت متأكد تمامًا؟</AlertDialogTitle>
+        <AlertDialogDescription id="rtl-description">
+          لا يمكن التراجع عن هذا الإجراء. سيؤدي هذا إلى حذف حسابك نهائيًا من خوادمنا.
+        </AlertDialogDescription>
+      </AlertDialogHeader>
+      <AlertDialogFooter>
+        <button type="button" AlertDialogCancel>إلغاء</button>
+        <button type="button" AlertDialogAction>متابعة</button>
+      </AlertDialogFooter>
+    </AlertDialogContent>
+  </AlertDialog>
+</div>
+```
+
+## API reference
+
+### `AlertDialogComponent`
+
+| Input                  | Type             | Default   |
+| ---------------------- | ---------------- | --------- |
+| `open` (model)         | `boolean`        | `false`   |
+| `closeOnEscape`        | `boolean`        | `true`    |
+| `closeOnBackdropClick` | `boolean`        | `false`   |
+| `showCloseButton`      | `boolean`        | `false`   |
+| `closeButtonLabel`     | `string`         | `'Close'` |
+| `aria-labelledby`      | `string \| null` | `null`    |
+| `aria-describedby`     | `string \| null` | `null`    |
+| `class`                | `string`         | `''`      |
+
+Output: `openedChange: boolean`. Method: `close()`.
+
+### `AlertDialogContentComponent`
+
+| Input   | Type                | Default     |
+| ------- | ------------------- | ----------- |
+| `size`  | `'default' \| 'sm'` | `'default'` |
+| `class` | `string`            | `''`        |
+
+### Parts
+
+| Part                        | Purpose                                                            |
+| --------------------------- | ------------------------------------------------------------------ |
+| `AlertDialogHeader`         | Title, optional media, and supporting copy wrapper                 |
+| `AlertDialogTitle`          | Primary label announced when the dialog opens                      |
+| `AlertDialogDescription`    | Supporting copy announced after the title                          |
+| `AlertDialogMedia`          | Optional icon or visual cue for the decision                       |
+| `AlertDialogFooter`         | Action row                                                         |
+| `button[AlertDialogCancel]` | Secondary action with outline styling that closes the dialog       |
+| `button[AlertDialogAction]` | Primary action that closes the dialog and supports button variants |
+
+Lower-level behavior is based on the Radix Alert Dialog pattern: <https://www.radix-ui.com/primitives/docs/components/alert-dialog#api-reference>.
+
+## Styling and theming
+
+The surface reuses the shared dialog overlay and theme tokens, while the action parts reuse the same `buttonVariants` definitions as `Button`.
+
+Pass `class` to `AlertDialog` when you need custom max width or spacing, `size="sm"` to `AlertDialogContent` for compact confirmations, and `class` to `AlertDialogMedia` when a specific tone such as destructive emphasis is needed.
+
+## Accessibility
+
+- The surface renders with `role="dialog"` and `aria-modal="true"`.
+- Focus is trapped while the alert dialog is open and restored to the previously active element when it closes.
+- Backdrop click is disabled by default so confirmations do not dismiss accidentally.
+- Keep `AlertDialogTitle` and `AlertDialogDescription` short and descriptive so assistive technologies announce useful context immediately.
+
+## Keyboard interactions
+
+- `Tab` and `Shift+Tab` stay inside the modal while it is open.
+- `Escape` closes the alert dialog unless `closeOnEscape` is disabled.
+- Native button activation handles `Enter` and `Space` for cancel and action buttons.
+
+## Angular notes
+
+- This implementation intentionally maps shadcn `AlertDialogTrigger` to any external trigger that owns the `open` signal.
+- `button[AlertDialogCancel]` and `button[AlertDialogAction]` close the nearest ancestor alert dialog automatically by default.
+- Use `(click)` on the action button for side effects such as deleting or sharing, and keep `closeOnClick` enabled unless the flow needs to wait for an async result.
+
+## Source parity
+
+This Angular implementation keeps the shadcn information architecture, examples, and `size="sm"` content behavior while translating trigger ownership to Angular signals and dedicated attribute components for the footer actions.

package/component/aspect-ratio/README.md

@@ -0,0 +1,116 @@
+# Aspect Ratio
+
+Displays content within a fixed width-to-height ratio.
+
+Use Aspect Ratio for image frames, media placeholders, thumbnail cards, and any layout where the container height should derive from the available width.
+
+## Import
+
+```ts
+import { AspectRatioComponent } from '@ojiepermana/angular/component/aspect-ratio';
+```
+
+## Usage
+
+Bind a numeric ratio with `[ratio]`. The host renders as a block-level container with `position: relative`, so projected children can fill the box with `h-full w-full` or positioned overlays.
+
+```html
+<div class="w-full max-w-sm">
+  <AspectRatio [ratio]="16 / 9" class="overflow-hidden rounded-lg border border-border bg-muted/30">
+    <img
+      src="https://avatar.vercel.sh/shadcn1"
+      alt="Demo media"
+      class="h-full w-full object-cover"
+    />
+  </AspectRatio>
+</div>
+```
+
+## Common patterns
+
+### Landscape media
+
+Use `16 / 9` for hero images, video posters, and card thumbnails.
+
+```html
+<div class="max-w-sm">
+  <AspectRatio [ratio]="16 / 9" class="overflow-hidden rounded-lg bg-muted">
+    <img src="..." alt="Landscape" class="h-full w-full object-cover" />
+  </AspectRatio>
+</div>
+```
+
+### Square avatars or gallery tiles
+
+Use `1` for square media slots.
+
+```html
+<div class="max-w-48">
+  <AspectRatio [ratio]="1" class="overflow-hidden rounded-xl bg-muted">
+    <img src="..." alt="Square tile" class="h-full w-full object-cover" />
+  </AspectRatio>
+</div>
+```
+
+### Portrait cards
+
+Use `9 / 16` when the design calls for tall image treatments.
+
+```html
+<div class="max-w-40">
+  <AspectRatio [ratio]="9 / 16" class="overflow-hidden rounded-xl bg-muted">
+    <img src="..." alt="Portrait tile" class="h-full w-full object-cover" />
+  </AspectRatio>
+</div>
+```
+
+### Figure with caption
+
+Keep captions outside the ratio box so the media height stays stable while text can grow naturally.
+
+```html
+<figure class="max-w-sm">
+  <AspectRatio [ratio]="16 / 9" class="overflow-hidden rounded-lg border border-border bg-muted/30">
+    <img src="..." alt="Beautiful landscape" class="h-full w-full object-cover" />
+  </AspectRatio>
+  <figcaption class="mt-2 text-sm text-muted-foreground">Beautiful landscape</figcaption>
+</figure>
+```
+
+## API reference
+
+### `AspectRatioComponent`
+
+| Input   | Type     | Default  | Description                                                                                 |
+| ------- | -------- | -------- | ------------------------------------------------------------------------------------------- |
+| `ratio` | `number` | required | The desired width-to-height ratio. Use Angular expressions like `16 / 9`, `1`, or `9 / 16`. |
+| `class` | `string` | `''`     | Additional utility classes for the host container.                                          |
+
+## Styling and theming
+
+Base host classes: `relative block w-full`.
+
+Pass utility classes for rounded corners, borders, backgrounds, shadows, and max width. Add `overflow-hidden` when the projected media should be clipped to the container radius. The projected child should usually use `h-full w-full object-cover` for image-like content.
+
+## Accessibility
+
+Aspect Ratio has no built-in semantics beyond its host element. Accessibility comes from the projected content.
+
+- Provide meaningful `alt` text for images.
+- Prefer `<figure>` and `<figcaption>` when media needs visible labeling.
+- Do not place essential text only inside a background image.
+
+## Keyboard interactions
+
+Aspect Ratio has no keyboard interaction. It should not receive focus unless the projected content contains an interactive control.
+
+## Angular notes
+
+- Import `AspectRatioComponent` directly into the standalone component that owns the media layout.
+- Use `[ratio]` with a numeric Angular expression instead of a React prop like `ratio={16 / 9}`.
+- The component uses a block-level custom element so width utilities such as `w-full` and `max-w-sm` behave predictably.
+- The projected content is wrapped in an absolute fill container so overlays and full-height media stay aligned with the ratio box.
+
+## Source parity
+
+This Angular implementation follows the shadcn Aspect Ratio examples for landscape, square, portrait, and RTL-friendly media layouts while translating React props and fill behavior to Angular bindings and projected content.