@ojiepermana/angular 22.1.10 → 22.1.12

package/component/separator/README.md

@@ -0,0 +1,175 @@
+# Separator
+
+Visually or semantically separates content. Use Separator for subtle section
+breaks, split navigation rows, compact menu metadata, and stacked definition
+lists.
+
+## Import
+
+```ts
+import { SeparatorComponent } from '@ojiepermana/angular/component/separator';
+```
+
+## Basic usage
+
+Use the default separator for purely visual breaks. When the divider carries
+structure that assistive technology should announce, set
+`[decorative]="false"`.
+
+```html
+<Separator class="my-4" /> <Separator [decorative]="false" class="my-4" />
+```
+
+## Common patterns
+
+### Preview card
+
+This mirrors the upstream shadcn hero example: title block, separator, then the
+supporting description.
+
+```html
+<div
+  class="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card/40 p-5 text-sm"
+>
+  <div class="flex flex-col gap-1.5">
+    <div class="leading-none font-medium">shadcn/ui</div>
+    <div class="text-muted-foreground">The Foundation for your Design System</div>
+  </div>
+  <Separator />
+  <div class="text-muted-foreground">
+    A set of beautifully designed components that you can customize, extend, and build on.
+  </div>
+</div>
+```
+
+### Vertical row
+
+Use `orientation="vertical"` when the separator sits inside a horizontal flex
+row. Give the host an explicit height, or inherit it from a parent with defined
+cross-axis size.
+
+```html
+<div class="flex h-5 items-center gap-4 text-sm">
+  <div>Blog</div>
+  <Separator orientation="vertical" class="h-5" />
+  <div>Docs</div>
+  <Separator orientation="vertical" class="h-5" />
+  <div>Source</div>
+</div>
+```
+
+### Menu metadata
+
+Vertical separators work well between compact description groups.
+
+```html
+<div class="flex w-full max-w-2xl items-center gap-2 text-sm md:gap-4">
+  <div class="flex flex-col gap-1">
+    <span class="font-medium">Settings</span>
+    <span class="text-xs text-muted-foreground">Manage preferences</span>
+  </div>
+  <Separator orientation="vertical" class="h-10" />
+  <div class="flex flex-col gap-1">
+    <span class="font-medium">Account</span>
+    <span class="text-xs text-muted-foreground">Profile &amp; security</span>
+  </div>
+  <Separator orientation="vertical" class="hidden h-10 md:block" />
+  <div class="hidden flex-col gap-1 md:flex">
+    <span class="font-medium">Help</span>
+    <span class="text-xs text-muted-foreground">Support &amp; docs</span>
+  </div>
+</div>
+```
+
+### List rows
+
+Horizontal separators are the lightest-weight way to split dense stacked rows.
+
+```html
+<div class="flex w-full max-w-sm flex-col gap-2 text-sm">
+  <dl class="flex items-center justify-between gap-4">
+    <dt class="font-medium">Item 1</dt>
+    <dd class="text-muted-foreground">Value 1</dd>
+  </dl>
+  <Separator />
+  <dl class="flex items-center justify-between gap-4">
+    <dt class="font-medium">Item 2</dt>
+    <dd class="text-muted-foreground">Value 2</dd>
+  </dl>
+  <Separator />
+  <dl class="flex items-center justify-between gap-4">
+    <dt class="font-medium">Item 3</dt>
+    <dd class="text-muted-foreground">Value 3</dd>
+  </dl>
+</div>
+```
+
+### RTL
+
+The separator itself does not need an RTL-specific API. Set `dir="rtl"` on the
+surrounding container and translate neighboring content.
+
+```html
+<section
+  dir="rtl"
+  lang="ar"
+  class="flex w-full max-w-sm flex-col gap-4 rounded-xl border border-border bg-card/40 p-5 text-right text-sm"
+>
+  <div class="flex flex-col gap-1.5">
+    <div class="leading-none font-medium">shadcn/ui</div>
+    <div class="text-muted-foreground">الأساس لنظام التصميم الخاص بك</div>
+  </div>
+  <Separator />
+  <div class="text-muted-foreground">
+    مجموعة من المكونات المصممة بشكل جميل يمكنك تخصيصها وتوسيعها والبناء عليها.
+  </div>
+</section>
+```
+
+## API reference
+
+| Input         | Type                         | Default        | Description                                                    |
+| ------------- | ---------------------------- | -------------- | -------------------------------------------------------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Axis of the divider.                                           |
+| `decorative`  | `boolean`                    | `true`         | When `false`, sets `role="separator"` plus `aria-orientation`. |
+| `class`       | `string`                     | `''`           | Width, height, spacing, and visibility utilities.              |
+
+Native host attributes such as `dir`, `data-*`, and `id` still pass through to
+the custom element host.
+
+## Styling and theming
+
+Tokens consumed:
+
+- `bg-border` for the rule itself.
+
+Horizontal mode applies `h-px w-full`. Vertical mode applies `h-full w-px`.
+The host renders as a block-level custom element so width and height utilities
+behave predictably on the separator itself.
+
+## Accessibility
+
+- Separators are decorative by default and render with `role="none"`.
+- When the divider carries structure, set `[decorative]="false"` so assistive
+  technology sees a real `separator` with the correct `aria-orientation`.
+- Keep accessible names on the surrounding content; separators themselves do not
+  require labels.
+
+## Keyboard interactions
+
+Separator is not interactive and has no keyboard behavior of its own.
+
+## Angular notes
+
+- Because `Separator` is a custom element, vertical examples need a height
+  source from the parent or the host `class` input.
+- The block-level host class is intentional. It ensures horizontal separators
+  honor `w-full` and other layout utilities that would otherwise be unreliable
+  on an inline custom element.
+
+## Source parity
+
+This Angular implementation follows the shadcn separator preview plus the
+vertical, menu, list, and RTL examples. It adds Angular-specific guidance for
+semantic separators and for the custom-element host layout behavior needed to
+match the upstream visuals.

package/component/sheet/README.md

@@ -0,0 +1,190 @@
+# Sheet
+
+Edge-anchored overlay surface that extends Dialog into a side panel. The Sheet slides in from the top, right, bottom, or left edge of the viewport and is backed by CDK Overlay plus FocusTrap.
+
+## Import
+
+```ts
+import {
+  SheetCloseDirective,
+  SheetComponent,
+  SheetContentComponent,
+  SheetDescriptionComponent,
+  SheetFooterComponent,
+  SheetHeaderComponent,
+  SheetTitleComponent,
+} from '@ojiepermana/angular/component/sheet';
+```
+
+## Composition
+
+```text
+button[Button] (external trigger; sets the open signal)
+Sheet
+├── built-in close button (optional)
+├── SheetHeader
+│   ├── SheetTitle
+│   └── SheetDescription
+├── SheetContent (optional body / scroll region)
+└── SheetFooter
+    └── button[SheetClose] (optional custom close action)
+```
+
+The Angular surface intentionally keeps the trigger outside the overlay component. Instead of a JSX-style `SheetTrigger`, you open the sheet by setting the bound `open` signal from a regular button or link.
+
+## Basic Usage
+
+```ts
+import { signal } from '@angular/core';
+```
+
+```html
+<button type="button" Button variant="outline" (click)="open.set(true)">Edit profile</button>
+
+<Sheet
+  [(open)]="open"
+  aria-labelledby="sheet-title"
+  aria-describedby="sheet-description"
+  class="sm:max-w-md"
+>
+  <SheetHeader>
+    <SheetTitle id="sheet-title">Edit profile</SheetTitle>
+    <SheetDescription id="sheet-description">
+      Make changes to your profile here. Click save when you are done.
+    </SheetDescription>
+  </SheetHeader>
+
+  <SheetContent class="grid gap-4 py-4">
+    <div class="grid gap-2">
+      <label Label for="sheet-name">Name</label>
+      <input Input id="sheet-name" value="Pedro Duarte" />
+    </div>
+    <div class="grid gap-2">
+      <label Label for="sheet-username">Username</label>
+      <input Input id="sheet-username" value="@peduarte" />
+    </div>
+  </SheetContent>
+
+  <SheetFooter>
+    <button type="button" Button variant="outline" SheetClose>Cancel</button>
+    <button type="button" Button (click)="open.set(false)">Save changes</button>
+  </SheetFooter>
+</Sheet>
+```
+
+## Common Patterns
+
+### Side selection
+
+Use `side` to choose where the surface enters from. Right is the default for `Sheet`, while the `Drawer` alias defaults to bottom.
+
+```html
+<button type="button" Button variant="outline" (click)="rightOpen.set(true)">Right</button>
+<button type="button" Button variant="outline" (click)="leftOpen.set(true)">Left</button>
+
+<Sheet [(open)]="rightOpen" side="right" class="sm:max-w-md">...</Sheet>
+<Sheet [(open)]="leftOpen" side="left" class="sm:max-w-md">...</Sheet>
+```
+
+For `top` and `bottom`, add a height constraint such as `class="max-h-[55vh]"` when the body content can grow on shorter screens.
+
+### No close button
+
+Hide the default corner close affordance with `[showCloseButton]="false"` and own dismissal explicitly through the footer or body.
+
+```html
+<Sheet [(open)]="noCloseOpen" [showCloseButton]="false" class="sm:max-w-sm">
+  <SheetHeader>
+    <SheetTitle>No Close Button</SheetTitle>
+    <SheetDescription>
+      Hide the top-right control when dismissal should stay in the footer.
+    </SheetDescription>
+  </SheetHeader>
+
+  <SheetFooter class="sm:justify-start">
+    <button type="button" Button variant="outline" SheetClose>Close</button>
+  </SheetFooter>
+</Sheet>
+```
+
+### RTL
+
+Because the overlay surface renders through CDK Overlay, set `dir="rtl"` on projected content inside the sheet when the direction should be scoped to the open panel.
+
+```html
+<Sheet [(open)]="rtlOpen" [showCloseButton]="false" side="left" class="sm:max-w-md">
+  <div dir="rtl" lang="ar" class="flex flex-1 flex-col gap-4 text-right">
+    <SheetHeader>
+      <SheetTitle>تعديل الملف الشخصي</SheetTitle>
+      <SheetDescription>قم بإجراء تغييرات على ملفك الشخصي هنا ثم احفظها.</SheetDescription>
+    </SheetHeader>
+
+    <SheetContent class="grid gap-4 py-4">
+      <div class="grid gap-2">
+        <label Label for="sheet-rtl-name">الاسم</label>
+        <input Input id="sheet-rtl-name" value="بيدرو دوارتي" />
+      </div>
+    </SheetContent>
+
+    <SheetFooter class="sm:justify-start">
+      <button type="button" Button variant="outline" SheetClose>إغلاق</button>
+      <button type="button" Button (click)="rtlOpen.set(false)">حفظ التغييرات</button>
+    </SheetFooter>
+  </div>
+</Sheet>
+```
+
+## API Reference
+
+| Input                  | Type                                     | Default                                        |
+| ---------------------- | ---------------------------------------- | ---------------------------------------------- |
+| `open`                 | `boolean` model                          | `false`                                        |
+| `side`                 | `'top' \| 'right' \| 'bottom' \| 'left'` | `'right'` for `Sheet`, `'bottom'` for `Drawer` |
+| `closeOnEscape`        | `boolean`                                | `true`                                         |
+| `closeOnBackdropClick` | `boolean`                                | `true`                                         |
+| `showCloseButton`      | `boolean`                                | `true`                                         |
+| `closeButtonLabel`     | `string`                                 | `'Close'`                                      |
+| `aria-labelledby`      | `string \| null`                         | `null`                                         |
+| `aria-describedby`     | `string \| null`                         | `null`                                         |
+| `class`                | `string`                                 | `''`                                           |
+
+| Part                 | Purpose                                                        |
+| -------------------- | -------------------------------------------------------------- |
+| `SheetHeader`        | Title and supporting description wrapper                       |
+| `SheetTitle`         | Visible, accessible sheet title                                |
+| `SheetDescription`   | Supporting copy that can be referenced from `aria-describedby` |
+| `SheetContent`       | Optional body wrapper for forms, spacing, and scroll regions   |
+| `SheetFooter`        | Action row for primary and secondary controls                  |
+| `button[SheetClose]` | Angular-friendly equivalent of shadcn `SheetClose`             |
+
+## Styling And Theming
+
+- The surface uses theme border tokens such as `border-border` on its edge divider so it stays aligned with the current theme.
+- Left and right sheets default to `w-3/4 sm:max-w-sm`; add width utilities through the `class` input when a broader side panel is needed.
+- Top and bottom sheets stretch across the viewport edge. Use `max-h-*` or spacing utilities on the root `class` input when the body can grow.
+- `SheetContent` is the best place for internal scroll handling. Keep footer actions outside that overflow region when they must stay visible.
+- Entry animation comes from `--sheet-from` and automatically collapses to zero duration under `prefers-reduced-motion`.
+
+## Accessibility
+
+- The surface renders with `role="dialog"` and `aria-modal="true"`.
+- Focus is trapped with `FocusTrap` and restored to the previously focused element on close.
+- `Escape` and backdrop click close the sheet by default and can be disabled independently.
+- Use stable IDs for the visible title and description when the sheet contains forms or longer instructional copy.
+
+## Keyboard Interactions
+
+- `Tab` and `Shift+Tab` move focus within the trapped overlay.
+- `Escape` closes the sheet unless `closeOnEscape` is disabled.
+- `Enter` and `Space` activate the trigger, footer actions, and custom `SheetClose` controls through native button behavior.
+
+## Angular Notes
+
+- `Sheet` combines the upstream `Sheet` root and `SheetContent` overlay surface into a single Angular component.
+- `SheetContent` remains available as an internal body wrapper for layout, padding, and scroll regions.
+- `Drawer` is exported as a bottom-first alias over the same primitive when the interaction reads more naturally as a drawer.
+- `button[SheetClose]` and `a[SheetClose]` are the Angular-friendly equivalents of shadcn `SheetClose` for internal dismissal actions.
+
+## Source Parity
+
+The local Sheet follows the shadcn component information architecture and behavior, but translates trigger ownership to an external signal instead of a `SheetTrigger` child component. Lower-level dialog semantics and API expectations still map closely to the Radix Dialog reference at https://www.radix-ui.com/primitives/docs/components/dialog#api-reference.

package/component/skeleton/README.md

@@ -0,0 +1,158 @@
+# Skeleton
+
+Use Skeleton to show low-contrast placeholders while content is loading.
+
+The component mirrors shadcn/ui's Skeleton primitive: it supplies the pulsing muted surface, while dimensions, shape, and layout are provided by utility classes at the call site.
+
+## Import
+
+```ts
+import { SkeletonComponent } from '@ojiepermana/angular/component/skeleton';
+```
+
+## Usage
+
+Give each skeleton an explicit width, height, and optional radius. Without dimensions, the element exists in the DOM but will not create a visible placeholder.
+
+```html
+<Skeleton class="h-5 w-25 rounded-full" />
+```
+
+```html
+<div class="flex items-center gap-4">
+  <Skeleton class="h-12 w-12 rounded-full" />
+  <div class="space-y-2">
+    <Skeleton class="h-4 w-62.5" />
+    <Skeleton class="h-4 w-50" />
+  </div>
+</div>
+```
+
+## Common patterns
+
+### Avatar
+
+Use a round placeholder and two lines when loading profile identity, assignee, or author metadata.
+
+```html
+<div class="flex w-fit items-center gap-4">
+  <Skeleton class="size-10 shrink-0 rounded-full" />
+  <div class="grid gap-2">
+    <Skeleton class="h-4 w-37.5" />
+    <Skeleton class="h-4 w-25" />
+  </div>
+</div>
+```
+
+### Card
+
+Skeleton composes inside `Card` parts. Match the final loaded geometry to avoid layout shift.
+
+```html
+<Card class="w-full max-w-xs">
+  <CardHeader>
+    <div class="col-span-2 grid gap-2">
+      <Skeleton class="h-4 w-2/3" />
+      <Skeleton class="h-4 w-1/2" />
+    </div>
+  </CardHeader>
+  <CardContent>
+    <Skeleton class="aspect-video w-full" />
+  </CardContent>
+</Card>
+```
+
+### Text
+
+Use repeated bars and shorten the final line for paragraph rhythm.
+
+```html
+<div class="flex w-full max-w-xs flex-col gap-2">
+  <Skeleton class="h-4 w-full" />
+  <Skeleton class="h-4 w-full" />
+  <Skeleton class="h-4 w-3/4" />
+</div>
+```
+
+### Form
+
+Pair short label placeholders with wider control placeholders when loading form metadata.
+
+```html
+<div class="flex w-full max-w-xs flex-col gap-7">
+  <div class="flex flex-col gap-3">
+    <Skeleton class="h-4 w-20" />
+    <Skeleton class="h-8 w-full" />
+  </div>
+  <div class="flex flex-col gap-3">
+    <Skeleton class="h-4 w-24" />
+    <Skeleton class="h-8 w-full" />
+  </div>
+  <Skeleton class="h-8 w-24" />
+</div>
+```
+
+### Table
+
+Repeat rows with matching column proportions so tabular data keeps a stable footprint while loading.
+
+```html
+<div class="flex w-full max-w-sm flex-col gap-2">
+  @for (row of tableRows; track row) {
+  <div class="flex gap-4">
+    <Skeleton class="h-4 flex-1" />
+    <Skeleton class="h-4 w-24" />
+    <Skeleton class="h-4 w-20" />
+  </div>
+  }
+</div>
+```
+
+### RTL
+
+Skeleton is direction-agnostic. Put `dir="rtl"` on the wrapper when the placeholder should reserve right-to-left layout space.
+
+```html
+<div dir="rtl" lang="ar" class="flex items-center gap-4">
+  <Skeleton class="h-12 w-12 rounded-full" />
+  <div class="space-y-2">
+    <Skeleton class="h-4 w-62.5" />
+    <Skeleton class="h-4 w-50" />
+  </div>
+</div>
+```
+
+## API reference
+
+### `SkeletonComponent`
+
+| Input   | Type     | Default | Description                                           |
+| ------- | -------- | ------- | ----------------------------------------------------- |
+| `class` | `string` | `''`    | Supplies visible dimensions, shape, and extra layout. |
+
+## Styling and theming
+
+Base classes: `block animate-pulse rounded-md bg-muted`.
+
+The component consumes the shared muted theme token through `bg-muted`. Pass utility classes for width, height, radius, flex behavior, margins, and responsive variants. Because the host is block-level, width and height utilities behave like they do on the shadcn React `<div>` implementation.
+
+## Accessibility
+
+`Skeleton` emits `aria-hidden="true"` because it is decorative loading chrome. Pair it with status text, a live region, or a busy state on the loaded region when the loading state needs to be announced.
+
+Avoid replacing labels or meaningful headings with only skeletons for long periods. Keep the eventual content area stable and announce changes when data arrives.
+
+## Keyboard interactions
+
+Skeleton has no keyboard interaction. It should not receive focus and should not contain interactive content.
+
+## Angular notes
+
+- Import `SkeletonComponent` directly into the standalone component that renders the loading state.
+- The `class` input is intentionally the main API so Angular examples stay close to shadcn utility-class composition.
+- Use Angular control flow for repeated rows: `@for (row of tableRows; track row) { ... }`.
+- Keep placeholder dimensions close to the loaded content to reduce layout shift.
+
+## Source parity
+
+This Angular implementation follows the shadcn Skeleton docs and examples for preview, usage, Avatar, Card, Text, Form, Table, and RTL. React `className` becomes Angular `class`, and the primitive renders as a block-level custom element so sizing utilities match the upstream `<div>` behavior.