@ojiepermana/angular 22.1.11 → 22.1.12

package/component/button-group/README.md

@@ -0,0 +1,214 @@
+# Button Group
+
+Groups related action buttons, text pills, inputs, and nested control clusters into a single visual control boundary.
+
+Use Button Group for toolbars, split actions, search bars, and compact action clusters where neighboring controls should read as one control family rather than isolated buttons.
+
+## Import
+
+```ts
+import { ButtonComponent } from '@ojiepermana/angular/component/button';
+import {
+  ButtonGroupComponent,
+  ButtonGroupSeparatorComponent,
+  ButtonGroupTextComponent,
+} from '@ojiepermana/angular/component/button-group';
+import { InputComponent } from '@ojiepermana/angular/component/input';
+import {
+  InputGroupAddonComponent,
+  InputGroupComponent,
+  InputGroupInputComponent,
+  InputGroupTextComponent,
+} from '@ojiepermana/angular/component/input-group';
+```
+
+## Composition
+
+The Angular structure mirrors the shadcn composition while translating `asChild` to normal Angular content projection.
+
+```text
+ButtonGroup
+├── button[Button] or a[Button]
+├── input[Input] or textarea[Textarea]
+├── ButtonGroupText
+├── ButtonGroupSeparator
+└── ButtonGroup
+```
+
+## Basic usage
+
+Label the group with `aria-label` or `aria-labelledby` whenever the buttons act as a single tool cluster.
+
+```html
+<ButtonGroup aria-label="Search actions" class="w-full max-w-md">
+  <input Input placeholder="Search..." />
+  <button Button type="button" variant="outline" aria-label="Run search">Search</button>
+</ButtonGroup>
+```
+
+## Common patterns
+
+### Orientation
+
+Use `orientation="vertical"` when the group should stack actions instead of lining them up horizontally.
+
+```html
+<ButtonGroup orientation="vertical" aria-label="Zoom controls" class="h-fit">
+  <button Button type="button" variant="outline" size="icon">+</button>
+  <button Button type="button" variant="outline" size="icon">-</button>
+</ButtonGroup>
+```
+
+### Text and field pairing
+
+`ButtonGroupText` is the Angular translation of shadcn's `ButtonGroupText`. Project any semantic content inside it, including a native label.
+
+```html
+<ButtonGroup class="w-full max-w-lg">
+  <ButtonGroupText>
+    <label for="project-name">Project</label>
+  </ButtonGroupText>
+  <input Input id="project-name" placeholder="Type a name..." />
+</ButtonGroup>
+```
+
+### Separator
+
+Use `ButtonGroupSeparator` when filled or secondary buttons still need a visible division.
+
+```html
+<ButtonGroup aria-label="Clipboard actions">
+  <button Button type="button" variant="secondary" size="sm">Copy</button>
+  <ButtonGroupSeparator />
+  <button Button type="button" variant="secondary" size="sm">Paste</button>
+</ButtonGroup>
+```
+
+### Split action
+
+Split buttons are just two neighboring buttons with a separator between the primary action and the disclosure or icon action.
+
+```html
+<ButtonGroup aria-label="Create actions">
+  <button Button type="button" variant="secondary">Create</button>
+  <ButtonGroupSeparator />
+  <button Button type="button" variant="secondary" size="icon" aria-label="Open create menu">
+    +
+  </button>
+</ButtonGroup>
+```
+
+### Search input
+
+Button Group works directly with the local `Input` primitive because both controls own their border on the host element.
+
+```html
+<ButtonGroup aria-label="Repository search" class="w-full max-w-lg">
+  <input Input placeholder="Search repositories..." />
+  <button Button type="button" variant="outline" aria-label="Search">Search</button>
+</ButtonGroup>
+```
+
+### Nested groups
+
+Nest `ButtonGroup` when you want separate clusters with spacing between them while keeping each inner cluster visually fused.
+
+```html
+<ButtonGroup aria-label="Message composer" class="w-full max-w-xl">
+  <ButtonGroup>
+    <button Button type="button" variant="outline" size="icon" aria-label="Add attachment">
+      +
+    </button>
+  </ButtonGroup>
+
+  <ButtonGroup class="min-w-0 flex-1">
+    <InputGroup>
+      <input InputGroupInput placeholder="Send a message..." />
+      <InputGroupAddon align="inline-end">
+        <InputGroupText>⌘↵</InputGroupText>
+      </InputGroupAddon>
+    </InputGroup>
+  </ButtonGroup>
+</ButtonGroup>
+```
+
+### Popover companion
+
+Use a neighboring popover trigger when the primary button opens a short follow-up form or assistant prompt.
+
+```html
+<ButtonGroup aria-label="Copilot actions">
+  <button Button type="button" variant="outline">Copilot</button>
+  <button Button type="button" variant="outline" size="icon" aria-label="Open Copilot options">
+    ⋯
+  </button>
+</ButtonGroup>
+```
+
+## API reference
+
+### `ButtonGroupComponent`
+
+| Input         | Type                         | Default        |
+| ------------- | ---------------------------- | -------------- |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `class`       | `string`                     | `''`           |
+
+Host behavior:
+
+- Renders `role="group"`.
+- Adds `data-orientation` and `data-slot="button-group"`.
+- Collapses adjoining corner radius and internal border width with RTL-safe logical properties.
+
+### `ButtonGroupSeparatorComponent`
+
+| Input         | Type                         | Default      |
+| ------------- | ---------------------------- | ------------ |
+| `orientation` | `'horizontal' \| 'vertical'` | `'vertical'` |
+| `class`       | `string`                     | `''`         |
+
+### `ButtonGroupTextComponent`
+
+| Input   | Type     | Default |
+| ------- | -------- | ------- |
+| `class` | `string` | `''`    |
+
+Angular mapping note: there is no `asChild` input. Project the semantic element you need, such as `<label>` or `<span>`, inside `ButtonGroupText`.
+
+## Styling and theming
+
+- The root collapses adjacent corners and borders with logical start/end utilities so the same component works in LTR and RTL layouts.
+- Nested `ButtonGroup` children automatically create spacing between groups while preserving the fused inner boundaries of each nested group.
+- `ButtonGroupText` uses `border-border`, `bg-muted`, and shared radius tokens so it matches the rest of the component package.
+- `Input` and `InputGroup` compose cleanly inside Button Group because their border and radius live on the visible host. The current Material-backed `SelectField` does not expose the same host-level border contract yet, so the upstream Select example is intentionally not shipped as a parity demo.
+
+## Accessibility
+
+- `ButtonGroup` renders with `role="group"`; provide an accessible name with `aria-label` or `aria-labelledby` when the controls act as one tool cluster.
+- Button Group is for actions. If the clustered controls represent pressed or selected state, use a toggle-group style pattern instead.
+- Add `aria-label` to icon-only buttons inside the group.
+- `ButtonGroupText` is non-interactive content. Keep labels, helper text, or status copy inside it and leave action handling to the actual button or input controls.
+
+## Keyboard interactions
+
+- Tab order follows the DOM order of the projected controls.
+- Native buttons keep their built-in Enter and Space activation behavior.
+- Inputs and textareas keep their native editing behavior.
+- Popover and menu triggers inside a group keep the keyboard behavior of their own directives; the group container does not intercept those interactions.
+
+## Button Group vs Toggle Group
+
+- Use Button Group when each item performs an immediate action.
+- Use Toggle Group when each item represents persistent pressed, selected, or filter state.
+
+## Angular notes
+
+- Import `ButtonGroupComponent` plus only the child primitives you render on the page.
+- There is no React-style `asChild` prop. Angular templates already let you choose the semantic element directly.
+- Use nested `ButtonGroup` elements for spacing between related clusters rather than adding gap utilities to a single fused group.
+
+## Source parity
+
+This Angular implementation follows the shadcn Button Group surface with a grouped root, text pill, separator, nested-group spacing, dropdown and popover composition, and RTL-friendly border collapsing.
+
+The main documented deviation is the upstream Select example: the local `SelectField` remains Material-backed, so it is better composed next to the group in surrounding layout for now instead of being presented as a fused host-level group item.

package/component/calendar/README.md

@@ -0,0 +1,137 @@
+# Calendar
+
+Inline single-date calendar built on Angular Material `MatCalendar` and wrapped with shadcn-style theme tokens.
+
+Use Calendar when the date grid should stay visible in the page. Use `DatePickerComponent` when the same selection should live behind an input and popover trigger.
+
+## Import
+
+```ts
+import { CalendarComponent } from '@ojiepermana/angular/component/calendar';
+```
+
+## Date adapter
+
+The component self-provides a native `DateAdapter`, so it works out of the box in any
+consumer — including when federated into a host app that never wired one. You only need
+to add a date adapter at the application root if you want a non-native one or a custom
+locale (`MAT_DATE_LOCALE` flows in from the parent injector):
+
+```ts
+// app.config.ts — optional, only for a custom adapter/locale
+import { provideNativeDateAdapter } from '@angular/material/core';
+
+export const appConfig = {
+  providers: [provideNativeDateAdapter()],
+};
+```
+
+## Usage
+
+Bind `[(value)]` to a `Date | null` signal or component field. Use `startAt` when the first visible month should differ from the selected value.
+
+```html
+<Calendar [(value)]="selectedDate" [startAt]="selectedDate()" />
+```
+
+```ts
+protected readonly selectedDate = signal<Date | null>(new Date(2026, 4, 22));
+```
+
+## Common patterns
+
+### Constrained range
+
+Use `min` and `max` to disable dates outside an allowed window.
+
+```html
+<Calendar [(value)]="billingDate" [min]="minDate" [max]="maxDate" [startAt]="billingDate()" />
+```
+
+```ts
+protected readonly billingDate = signal<Date | null>(new Date(2026, 4, 15));
+protected readonly minDate = new Date(2026, 4, 5);
+protected readonly maxDate = new Date(2026, 4, 25);
+```
+
+### Disabled or booked dates
+
+Pass a `dateFilter` function. Angular Material expects the function to return `true` for selectable dates and `false` for disabled dates.
+
+```html
+<Calendar [(value)]="visitDate" [dateFilter]="availableDateFilter" [startAt]="visitDate()" />
+```
+
+```ts
+protected readonly bookedDates = [new Date(2026, 1, 12), new Date(2026, 1, 13)];
+
+protected readonly availableDateFilter = (candidate: Date | null): boolean =>
+  !!candidate && !this.bookedDates.some((bookedDate) => this.isSameDay(bookedDate, candidate));
+```
+
+### Presets
+
+Compose preset buttons around the calendar and update the same `value` model.
+
+```html
+<Calendar [(value)]="presetDate" [startAt]="presetDate()" class="border-0" />
+
+<button Button type="button" variant="outline" size="sm" (click)="selectPreset(7)">
+  In a week
+</button>
+```
+
+### Date and time
+
+Calendar owns the date. Native time inputs or `InputGroupComponent` can own the time value next to it.
+
+```html
+<Calendar [(value)]="meetingDate" [startAt]="meetingDate()" />
+
+<InputGroup>
+  <input InputGroupInput type="time" [value]="startTime()" (input)="updateStartTime($event)" />
+</InputGroup>
+```
+
+## API reference
+
+| Input / Model | Type                                | Default   |
+| ------------- | ----------------------------------- | --------- |
+| `value`       | `Date \| null`                      | `null`    |
+| `min`         | `Date \| null`                      | `null`    |
+| `max`         | `Date \| null`                      | `null`    |
+| `startAt`     | `Date \| null`                      | `null`    |
+| `startView`   | `'month' \| 'year' \| 'multi-year'` | `'month'` |
+| `dateFilter`  | `(date: Date \| null) => boolean`   | `null`    |
+| `disabled`    | `boolean`                           | `false`   |
+| `class`       | `string`                            | `''`      |
+
+Implements `ControlValueAccessor` — usable with `[(ngModel)]` and reactive forms.
+
+## Styling and theming
+
+The host uses `--border`, `--background`, `--foreground`, and `--radius`. Pass `class` for layout utilities such as `shadow-sm`, `border-0`, or `[--calendar-width:20rem]`.
+
+The inner Material calendar keeps Angular Material's a11y and navigation behavior while sitting inside the shadcn token wrapper. Use `DatePickerComponent` for popover input flows; this primitive intentionally stays inline.
+
+## Accessibility
+
+`MatCalendar` supplies the ARIA grid semantics, focus management, active date state, and disabled date handling. Provide a visible label or surrounding section heading when the calendar appears in a form-like surface.
+
+## Keyboard interactions
+
+- Arrow keys move between dates.
+- Page Up and Page Down move by month.
+- Home and End move to the start or end of the row.
+- Enter selects the focused date.
+
+## Angular notes
+
+- A native date adapter is built in; provide one at app bootstrap only for a custom adapter/locale.
+- `dateFilter` returns `true` for enabled dates, unlike some predicate APIs that return `true` for blocked dates.
+- `disabled` marks the host as inert and updates the CVA disabled state.
+- This component is a single-date primitive. Range selection is best modeled as a separate range primitive or by composing two calendars with application state.
+
+## Source parity
+
+The shadcn Calendar is built on React DayPicker. This Angular implementation maps the same inline calendar concept to `MatCalendar`, standalone imports, signal-friendly `[(value)]` binding, `min` and `max` constraints, `dateFilter` disabled dates, preset composition, and RTL-friendly container usage.

package/component/card/README.md

@@ -0,0 +1,232 @@
+# 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
+Card
+├── CardHeader
+│   ├── CardTitle
+│   ├── CardDescription
+│   └── CardAction
+├── CardContent
+└── CardFooter
+```
+
+## Basic usage
+
+```html
+<Card class="w-full max-w-sm">
+  <CardHeader>
+    <CardTitle>Card Title</CardTitle>
+    <CardDescription>Card Description</CardDescription>
+    <CardAction>
+      <button Button variant="link" size="sm">Action</button>
+    </CardAction>
+  </CardHeader>
+
+  <CardContent>
+    <p>Card Content</p>
+  </CardContent>
+
+  <CardFooter>
+    <p>Card Footer</p>
+  </CardFooter>
+</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
+<Card class="w-full max-w-sm">
+  <CardHeader>
+    <CardTitle>Login to your account</CardTitle>
+    <CardDescription>Enter your email below to login to your account</CardDescription>
+    <CardAction>
+      <button Button variant="link" size="sm">Sign Up</button>
+    </CardAction>
+  </CardHeader>
+
+  <CardContent>
+    <form class="grid gap-6">
+      <div class="grid gap-2">
+        <label Label for="email">Email</label>
+        <input Input id="email" type="email" placeholder="m@example.com" required />
+      </div>
+
+      <div class="grid gap-2">
+        <div class="flex items-center">
+          <label 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 Input id="password" type="password" required />
+      </div>
+    </form>
+  </CardContent>
+
+  <CardFooter class="flex-col gap-2">
+    <button Button class="w-full">Login</button>
+    <button Button variant="outline" class="w-full">Login with Google</button>
+  </CardFooter>
+</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
+<Card size="sm" class="w-full max-w-sm">
+  <CardHeader>
+    <CardTitle>Small Card</CardTitle>
+    <CardDescription>This card uses the small size variant.</CardDescription>
+  </CardHeader>
+  <CardContent>
+    <p class="text-sm text-muted-foreground">
+      Compact spacing for dense dashboards or inset panels.
+    </p>
+  </CardContent>
+  <CardFooter>
+    <button Button variant="outline" size="sm" class="w-full">Action</button>
+  </CardFooter>
+</Card>
+```
+
+### Image card
+
+Add media before the header when the card introduces an event, article, or campaign. `CardAction` still sits in the top-right of the header and can host a badge or button.
+
+```html
+<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"
+  />
+
+  <CardHeader>
+    <CardAction>
+      <Badge variant="secondary">Featured</Badge>
+    </CardAction>
+    <CardTitle>Design systems meetup</CardTitle>
+    <CardDescription>
+      A practical talk on component APIs, accessibility, and shipping faster.
+    </CardDescription>
+  </CardHeader>
+
+  <CardFooter>
+    <button Button class="w-full">View event</button>
+  </CardFooter>
+</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
+<Card dir="rtl" lang="ar" class="w-full max-w-sm text-right">
+  <CardHeader>
+    <CardTitle>تسجيل الدخول إلى حسابك</CardTitle>
+    <CardDescription>أدخل بريدك الإلكتروني أدناه لتسجيل الدخول إلى حسابك</CardDescription>
+    <CardAction>
+      <button Button variant="link" size="sm">إنشاء حساب</button>
+    </CardAction>
+  </CardHeader>
+  <CardContent>
+    <!-- same form fields as the login example -->
+  </CardContent>
+  <CardFooter class="flex-col gap-2">
+    <button Button class="w-full">تسجيل الدخول</button>
+    <button Button variant="outline" class="w-full">تسجيل الدخول باستخدام Google</button>
+  </CardFooter>
+</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`      | `CardHeader`             | Header grid that places `CardAction` in the top-right corner.           |
+| `CardTitleComponent`       | `CardTitle, [CardTitle]` | Semantic heading; `level` defaults to 3 or follows a native h1-h6 host. |
+| `CardDescriptionComponent` | `CardDescription`        | Supporting text under the title.                                        |
+| `CardActionComponent`      | `CardAction`             | Optional slot for badges, links, or buttons in the header.              |
+| `CardContentComponent`     | `CardContent`            | Main body area.                                                         |
+| `CardFooterComponent`      | `CardFooter`             | 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.
+- Use a native heading with `[CardTitle]`, or set `[level]` on `<CardTitle>`, so the title fits the surrounding heading hierarchy.
+- Label every form field inside `CardContent`.
+- 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.
+- `CardAction` does not alter focus order; it only positions header content visually.
+
+## Angular notes
+
+- `size` is declared only on `Card` and cascades to descendant part spacing and typography.
+- `CardAction` 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.