@ojiepermana/angular 21.3.3 → 22.0.1

package/component/dialog/README.md

@@ -0,0 +1,237 @@
+# Dialog
+
+Displays a modal surface over the current page, traps focus while open, and restores focus to the previously active element when it closes.
+
+Use Dialog for confirmation flows, compact forms, link sharing, and long-form review tasks that should keep the user in the current context.
+
+## Import
+
+```ts
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+import {
+  DialogCloseDirective,
+  DialogComponent,
+  DialogContentComponent,
+  DialogDescriptionComponent,
+  DialogFooterComponent,
+  DialogHeaderComponent,
+  DialogTitleComponent,
+} from '@ojiepermana/angular/component/dialog';
+import { InputComponent } from '@ojiepermana/angular/component/input';
+import { LabelComponent } from '@ojiepermana/angular/component/label';
+```
+
+## Composition
+
+The Angular composition tracks the shadcn structure, with one intentional mapping difference: shadcn `DialogTrigger` becomes any external control that toggles the `open` signal.
+
+```text
+button[ui-button] (external trigger; sets the open signal)
+ui-dialog
+├── built-in close button (optional)
+├── ui-dialog-header
+│   ├── ui-dialog-title
+│   └── ui-dialog-description
+├── ui-dialog-content (optional body wrapper)
+└── ui-dialog-footer
+    └── button[ui-dialog-close] (optional custom close action)
+```
+
+## Basic usage
+
+Use an external button or link to toggle the `open` signal, then declare the dialog structure inside `ui-dialog`.
+
+```html
+<button type="button" ui-button variant="outline" (click)="open.set(true)">Edit profile</button>
+
+<ui-dialog [(open)]="open" aria-labelledby="dialog-title" aria-describedby="dialog-description" class="sm:max-w-sm">
+  <ui-dialog-header>
+    <ui-dialog-title id="dialog-title">Edit profile</ui-dialog-title>
+    <ui-dialog-description id="dialog-description">
+      Make changes to your profile here. Click save when you are done.
+    </ui-dialog-description>
+  </ui-dialog-header>
+
+  <ui-dialog-content class="grid gap-4 py-2">
+    <div class="grid gap-2">
+      <label ui-label for="name">Name</label>
+      <input ui-input id="name" value="Pedro Duarte" />
+    </div>
+    <div class="grid gap-2">
+      <label ui-label for="username">Username</label>
+      <input ui-input id="username" value="@peduarte" />
+    </div>
+  </ui-dialog-content>
+
+  <ui-dialog-footer>
+    <button type="button" ui-button variant="outline" ui-dialog-close>Cancel</button>
+    <button type="button" ui-button (click)="open.set(false)">Save changes</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+## Common patterns
+
+### Destructive confirmation
+
+Use a short title, short body copy, and explicit cancel/confirm actions for destructive flows.
+
+```html
+<button type="button" ui-button variant="destructive" (click)="confirmOpen.set(true)">Delete project</button>
+
+<ui-dialog [(open)]="confirmOpen">
+  <ui-dialog-header>
+    <ui-dialog-title>Delete this project?</ui-dialog-title>
+    <ui-dialog-description>
+      This action cannot be undone. This permanently deletes your project.
+    </ui-dialog-description>
+  </ui-dialog-header>
+  <ui-dialog-footer>
+    <button type="button" ui-button variant="outline" ui-dialog-close>Cancel</button>
+    <button type="button" ui-button variant="destructive" (click)="confirmOpen.set(false)">Delete</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+### Custom close button
+
+Hide the built-in corner close control with `[showCloseButton]="false"` and place `button[ui-dialog-close]` wherever dismissal should live.
+
+```html
+<ui-dialog [(open)]="shareOpen" [showCloseButton]="false" class="sm:max-w-md">
+  <ui-dialog-header>
+    <ui-dialog-title>Share link</ui-dialog-title>
+    <ui-dialog-description> Anyone who has this link can view this workspace. </ui-dialog-description>
+  </ui-dialog-header>
+  <ui-dialog-content class="grid gap-4 py-2">
+    <div class="grid gap-2">
+      <label ui-label for="share-link">Link</label>
+      <input ui-input id="share-link" readonly value="https://ui.shadcn.com/docs/components/radix/dialog" />
+    </div>
+  </ui-dialog-content>
+  <ui-dialog-footer class="sm:justify-start">
+    <button type="button" ui-button ui-dialog-close>Close</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+### No close button
+
+Use `[showCloseButton]="false"` without an internal close action when Escape and backdrop dismissal are enough.
+
+```html
+<ui-dialog [(open)]="noCloseOpen" [showCloseButton]="false">
+  <ui-dialog-header>
+    <ui-dialog-title>No Close Button</ui-dialog-title>
+    <ui-dialog-description>
+      Dismiss this dialog with Escape, the backdrop, or another action you control.
+    </ui-dialog-description>
+  </ui-dialog-header>
+</ui-dialog>
+```
+
+### Sticky footer for long content
+
+Move the scroll region into `ui-dialog-content` and keep the footer outside that overflow container so primary actions remain visible.
+
+```html
+<ui-dialog [(open)]="stickyOpen" [showCloseButton]="false" class="max-h-[85vh] overflow-hidden p-0 sm:max-w-lg">
+  <ui-dialog-header class="px-6 pt-6">
+    <ui-dialog-title>Sticky Footer</ui-dialog-title>
+    <ui-dialog-description>Keep actions visible while the content scrolls.</ui-dialog-description>
+  </ui-dialog-header>
+  <ui-dialog-content class="max-h-[45vh] overflow-y-auto px-6 pb-6">
+    <!-- long content -->
+  </ui-dialog-content>
+  <ui-dialog-footer class="border-t border-border bg-background px-6 py-4 sm:justify-start">
+    <button type="button" ui-button variant="outline" ui-dialog-close>Close</button>
+    <button type="button" ui-button (click)="stickyOpen.set(false)">Save changes</button>
+  </ui-dialog-footer>
+</ui-dialog>
+```
+
+### RTL
+
+Wrap the trigger and dialog in a `dir="rtl"` container or set direction globally in the app shell.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <button type="button" ui-button variant="outline" (click)="rtlOpen.set(true)">فتح الحوار</button>
+
+  <ui-dialog [(open)]="rtlOpen" [showCloseButton]="false" class="sm:max-w-sm">
+    <ui-dialog-header>
+      <ui-dialog-title>تعديل الملف الشخصي</ui-dialog-title>
+      <ui-dialog-description> قم بإجراء تغييرات على ملفك الشخصي هنا. انقر فوق حفظ عند الانتهاء. </ui-dialog-description>
+    </ui-dialog-header>
+    <ui-dialog-content class="grid gap-4 py-2">
+      <div class="grid gap-2">...</div>
+      <div class="grid gap-2">...</div>
+    </ui-dialog-content>
+    <ui-dialog-footer>
+      <button type="button" ui-button variant="outline" ui-dialog-close>إلغاء</button>
+      <button type="button" ui-button (click)="rtlOpen.set(false)">حفظ التغييرات</button>
+    </ui-dialog-footer>
+  </ui-dialog>
+</div>
+```
+
+## API reference
+
+### `DialogComponent`
+
+| Input                  | Type             | Default   |
+| ---------------------- | ---------------- | --------- |
+| `open` (model)         | `boolean`        | `false`   |
+| `closeOnEscape`        | `boolean`        | `true`    |
+| `closeOnBackdropClick` | `boolean`        | `true`    |
+| `showCloseButton`      | `boolean`        | `true`    |
+| `closeButtonLabel`     | `string`         | `'Close'` |
+| `aria-labelledby`      | `string \| null` | `null`    |
+| `aria-describedby`     | `string \| null` | `null`    |
+| `class`                | `string`         | `''`      |
+
+Output: `openedChange: boolean`. Method: `close()`.
+
+### Parts
+
+| Part                      | Purpose                                                  |
+| ------------------------- | -------------------------------------------------------- |
+| `ui-dialog-header`        | Title and description wrapper                            |
+| `ui-dialog-title`         | Primary dialog label                                     |
+| `ui-dialog-description`   | Supporting copy announced by assistive tech              |
+| `ui-dialog-content`       | Optional body wrapper for forms, grids, and scroll areas |
+| `ui-dialog-footer`        | Action row                                               |
+| `button[ui-dialog-close]` | Custom close action mapped to shadcn `DialogClose`       |
+
+Lower-level behavior is based on the Radix Dialog pattern: <https://www.radix-ui.com/primitives/docs/components/dialog#api-reference>.
+
+## Styling and theming
+
+The dialog surface uses the shared theme tokens for background, border, foreground, and ring colors. Pass `class` to `ui-dialog` when you need to adjust width, max height, overflow strategy, or padding for a specific modal pattern.
+
+Use `ui-dialog-content` and `ui-dialog-footer` classes to create scroll regions, sticky action rows, or wider content layouts without forking the primitive.
+
+## Accessibility
+
+- The surface renders with `role="dialog"` and `aria-modal="true"`.
+- Focus is trapped inside with `FocusTrap` from `@angular/cdk/a11y`.
+- Focus returns to the previously active element when the dialog closes.
+- Escape and backdrop dismissal are enabled by default but can be disabled for stricter flows.
+- Keep titles and descriptions concise so screen readers announce useful context immediately.
+
+## Keyboard interactions
+
+- `Tab` and `Shift+Tab` stay inside the dialog while it is open.
+- `Escape` closes the dialog unless `closeOnEscape` is disabled.
+- Native button activation handles `Enter` and `Space` for dialog actions.
+
+## Angular notes
+
+- This implementation intentionally maps shadcn `DialogTrigger` to an external control that owns the `open` signal.
+- `button[ui-dialog-close]` is the Angular-friendly equivalent of shadcn `DialogClose` for internal dismissal actions.
+- Seed open state with a signal in the owning component and keep the dialog content declarative.
+- Hide the built-in close affordance with `[showCloseButton]="false"` when the footer or body owns dismissal explicitly.
+
+## Source parity
+
+This Angular implementation follows the shadcn Dialog information architecture and examples while translating the interaction model to Angular selectors, signal-driven state, and explicit ownership of the trigger outside the modal content.

package/component/drawer/README.md

@@ -0,0 +1,145 @@
+# Drawer
+
+Bottom-first modal drawer built on the local Sheet overlay primitive. It mirrors the shadcn Drawer composition while using Angular signals and explicit standalone imports.
+
+## Import
+
+```ts
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+import {
+  DrawerCloseDirective,
+  DrawerComponent,
+  DrawerContentComponent,
+  DrawerDescriptionComponent,
+  DrawerFooterComponent,
+  DrawerHeaderComponent,
+  DrawerTitleComponent,
+} from '@ojiepermana/angular/component/drawer';
+```
+
+## Usage
+
+```ts
+import { ChangeDetectionStrategy, Component, signal } from '@angular/core';
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+import {
+  DrawerCloseDirective,
+  DrawerComponent,
+  DrawerDescriptionComponent,
+  DrawerFooterComponent,
+  DrawerHeaderComponent,
+  DrawerTitleComponent,
+} from '@ojiepermana/angular/component/drawer';
+
+@Component({
+  selector: 'app-drawer-example',
+  changeDetection: ChangeDetectionStrategy.OnPush,
+  imports: [
+    ButtonComponent,
+    DrawerCloseDirective,
+    DrawerComponent,
+    DrawerDescriptionComponent,
+    DrawerFooterComponent,
+    DrawerHeaderComponent,
+    DrawerTitleComponent,
+  ],
+  template: `
+    <button type="button" ui-button variant="outline" (click)="open.set(true)">Open Drawer</button>
+
+    <ui-drawer [(open)]="open" aria-labelledby="drawer-title" aria-describedby="drawer-description">
+      <div class="mx-auto w-full max-w-sm">
+        <ui-drawer-header>
+          <ui-drawer-title id="drawer-title">Move Goal</ui-drawer-title>
+          <ui-drawer-description id="drawer-description">Set your daily activity goal.</ui-drawer-description>
+        </ui-drawer-header>
+        <ui-drawer-footer>
+          <button type="button" ui-button>Submit</button>
+          <button type="button" ui-button variant="outline" ui-drawer-close>Cancel</button>
+        </ui-drawer-footer>
+      </div>
+    </ui-drawer>
+  `,
+})
+export class DrawerExampleComponent {
+  protected readonly open = signal(false);
+}
+```
+
+## Common Patterns
+
+### Sides
+
+Drawer defaults to `bottom`, matching the common shadcn and Vaul pattern. Set `side` when the drawer should enter from a different edge.
+
+```html
+<ui-drawer [(open)]="open" side="right" aria-labelledby="drawer-side-title">
+  <ui-drawer-header>
+    <ui-drawer-title id="drawer-side-title">Scrollable Content</ui-drawer-title>
+  </ui-drawer-header>
+  <ui-drawer-content class="max-h-[50vh] overflow-y-auto px-1">
+    <!-- long content -->
+  </ui-drawer-content>
+</ui-drawer>
+```
+
+### Responsive Dialog
+
+Use a desktop breakpoint in the owning component and render Dialog for larger viewports, Drawer for smaller viewports. Keep both surfaces bound to the same `open` signal so trigger and submit actions stay consistent.
+
+```html
+@if (isDesktop()) {
+<ui-dialog [(open)]="open">...</ui-dialog>
+} @else {
+<ui-drawer [(open)]="open">...</ui-drawer>
+}
+```
+
+## API Reference
+
+### DrawerComponent
+
+| Input                  | Type                                     | Default                    |
+| ---------------------- | ---------------------------------------- | -------------------------- |
+| `open`                 | `boolean` model                          | `false`                    |
+| `side`                 | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` for `ui-drawer` |
+| `closeOnEscape`        | `boolean`                                | `true`                     |
+| `closeOnBackdropClick` | `boolean`                                | `true`                     |
+| `aria-labelledby`      | `string \| null`                         | `null`                     |
+| `aria-describedby`     | `string \| null`                         | `null`                     |
+| `class`                | `string`                                 | empty string               |
+
+### Parts
+
+| Part                                            | Purpose                                                                              |
+| ----------------------------------------------- | ------------------------------------------------------------------------------------ |
+| `ui-drawer-header`                              | Title and description wrapper.                                                       |
+| `ui-drawer-title`                               | Accessible title. Provide an `id` and connect it with `aria-labelledby`.             |
+| `ui-drawer-description`                         | Supporting text. Provide an `id` and connect it with `aria-describedby` when useful. |
+| `ui-drawer-content`                             | Optional scroll/body region inside the surface.                                      |
+| `ui-drawer-footer`                              | Action row.                                                                          |
+| `button[ui-drawer-close]`, `a[ui-drawer-close]` | Projected close action equivalent to shadcn `DrawerClose`.                           |
+
+## Styling And Theming
+
+The drawer uses the same theme tokens as Sheet: `bg-background`, `border-border`, `text-foreground`, and `text-muted-foreground`. Pass `class` to tune dimensions such as `max-h-[85vh]`, `sm:max-w-md`, or side-specific scroll behavior.
+
+## Accessibility
+
+- The surface renders with `role="dialog"` and `aria-modal="true"`.
+- Focus is trapped inside the CDK overlay while open and restored to the previously focused element on close.
+- Provide `aria-labelledby` and `aria-describedby` when the drawer contains a title and description.
+- Use native buttons for open, submit, and close actions.
+
+## Keyboard Interactions
+
+- `Tab` and `Shift+Tab` move within the focus-trapped drawer content.
+- `Escape` closes the drawer when `closeOnEscape` is `true`.
+- Enter and Space activate native buttons, including `button[ui-drawer-close]`.
+
+## Angular Notes
+
+The Angular Drawer deliberately uses an external trigger button and `[(open)]` signal binding instead of a `DrawerTrigger` component. This keeps ownership of state explicit and avoids hidden context wiring across overlay portals. `DrawerComponent` is exported as an alias over the same implementation as `SheetComponent`, so fixes to focus management, backdrop dismissal, and edge positioning are shared.
+
+## Source Parity
+
+shadcn Drawer is built on Vaul and includes drag gestures and scale-background options. This Angular version maps the core modal drawer behavior to CDK Overlay and FocusTrap: bottom-first direction, side selection, focus trapping, Escape/backdrop dismissal, close actions, scrollable content, responsive dialog composition, and RTL-friendly content. It does not implement Vaul drag gestures.