@ojiepermana/angular 22.1.11 → 22.1.12

package/component/timeline/README.md

@@ -0,0 +1,94 @@
+# Timeline
+
+Display a series of events or steps in a vertical or horizontal timeline.
+
+This component is conceptually inspired by Flux Timeline. The Angular API, slot names, styling tokens, and examples are implemented for this library's shadcn-style component system.
+
+## Import
+
+```ts
+import {
+  TimelineBlockComponent,
+  TimelineComponent,
+  TimelineContentComponent,
+  TimelineIndicatorComponent,
+  TimelineItemComponent,
+  TimelineSubgridComponent,
+} from '@ojiepermana/angular/component/timeline';
+```
+
+## Usage
+
+```html
+<Timeline>
+  <TimelineItem status="complete">
+    <TimelineIndicator>1</TimelineIndicator>
+    <TimelineContent>
+      <h3 class="text-sm font-medium">Submit</h3>
+      <p class="text-muted-foreground">Complete the form and provide all necessary assets.</p>
+    </TimelineContent>
+  </TimelineItem>
+</Timeline>
+```
+
+## Composition
+
+```text
+Timeline
+|-- TimelineItem
+|   |-- TimelineIndicator
+|   `-- TimelineContent
+|-- TimelineItem
+|   `-- TimelineBlock
+|       `-- TimelineSubgrid
+```
+
+## Horizontal Status
+
+```html
+<Timeline horizontal>
+  <TimelineItem status="complete">
+    <TimelineIndicator>1</TimelineIndicator>
+    <TimelineContent>Order confirmed</TimelineContent>
+  </TimelineItem>
+  <TimelineItem status="current">
+    <TimelineIndicator>2</TimelineIndicator>
+    <TimelineContent>On its way</TimelineContent>
+  </TimelineItem>
+  <TimelineItem status="incomplete">
+    <TimelineIndicator>3</TimelineIndicator>
+    <TimelineContent>Delivered</TimelineContent>
+  </TimelineItem>
+</Timeline>
+```
+
+## Inputs
+
+| Part                         | Input        | Type                                 | Default    |
+| ---------------------------- | ------------ | ------------------------------------ | ---------- |
+| `TimelineComponent`          | `horizontal` | `boolean`                            | `false`    |
+| `TimelineComponent`          | `align`      | `start \| baseline \| center \| end` | `center`   |
+| `TimelineComponent`          | `size`       | `default \| lg`                      | `default`  |
+| `TimelineItemComponent`      | `status`     | `complete \| current \| incomplete`  | `null`     |
+| `TimelineItemComponent`      | `align`      | `start \| baseline \| center \| end` | root value |
+| `TimelineItemComponent`      | `size`       | `default \| lg`                      | root value |
+| `TimelineIndicatorComponent` | `variant`    | `default \| bare`                    | `default`  |
+| `TimelineIndicatorComponent` | `status`     | `complete \| current \| incomplete`  | item value |
+| `TimelineIndicatorComponent` | `color`      | standard color token                 | `null`     |
+
+## Spacing
+
+The root exposes CSS variables for spacing and indicator sizing.
+
+```html
+<Timeline class="[--timeline-item-gap:3rem] [--timeline-content-gap:1rem]">
+  <!-- timeline items -->
+</Timeline>
+```
+
+## Accessibility
+
+- Use semantic headings and text inside `TimelineContent`.
+- Give icon-only indicators an accessible label when the icon communicates meaning.
+- Keep chronological order in DOM order for screen readers.
+- Do not rely on color alone; pair status indicators with text content.

package/component/toast/README.md

@@ -0,0 +1,173 @@
+# Toast
+
+Imperative, dependency-free notification service that renders toasts into a live region (`role="status"`, `aria-live="polite"`) with shadcn styling and a Sonner-style API surface.
+
+## Import
+
+```ts
+import { ToastService } from '@ojiepermana/angular/component/toast';
+```
+
+## Application Setup
+
+No special bootstrap providers are required. `ToastService` is a dependency-free, `providedIn: 'root'` service that injects `DOCUMENT` and renders its own live-region container, so you can inject and use it directly.
+
+## Basic Usage
+
+```ts
+import { inject } from '@angular/core';
+import { ToastService } from '@ojiepermana/angular/component/toast';
+
+export class SaveButtonComponent {
+  private readonly toast = inject(ToastService);
+
+  save(): void {
+    this.toast.success({
+      title: 'Saved',
+      description: 'Your changes have been saved.',
+      action: 'Undo',
+    });
+  }
+
+  fail(): void {
+    this.toast.error({ title: 'Upload failed', description: 'Check your connection.' });
+  }
+}
+```
+
+## Common Patterns
+
+### Variants
+
+```ts
+this.toast.show({ title: 'Draft created' });
+this.toast.success({ title: 'Invoice paid' });
+this.toast.info({ title: 'Deploy starts in 10 minutes' });
+this.toast.warning({ title: 'Storage is almost full' });
+this.toast.error({ title: 'Payment failed' });
+```
+
+### Position
+
+```ts
+this.toast.show({
+  title: 'Event has been created',
+  horizontalPosition: 'start',
+  verticalPosition: 'top',
+});
+```
+
+### Persistent action
+
+For an important action, keep the toast open (`durationMs: null`) and handle the result from the returned `ToastRef`.
+
+```ts
+const ref = this.toast.show({
+  title: 'Event archived',
+  description: 'Restore it from the calendar within the next minute.',
+  action: 'Undo',
+  durationMs: null,
+});
+
+void ref.afterDismissed.then(({ dismissedByAction }) => {
+  if (dismissedByAction) {
+    this.toast.info({
+      title: 'Archive cancelled',
+      description: 'The event is back on the calendar.',
+    });
+  }
+});
+```
+
+### Promise State
+
+```ts
+void this.toast.promise(() => this.createEvent(), {
+  loading: 'Loading...',
+  success: (event) => `${event.name} has been created`,
+  error: 'Error',
+});
+```
+
+The loading toast uses `durationMs: null` internally so it stays visible until the promise settles.
+
+## API Reference
+
+### `ToastService`
+
+| Method                             | Returns      |
+| ---------------------------------- | ------------ |
+| `show(options: ToastOptions)`      | `ToastRef`   |
+| `success(options)`                 | `ToastRef`   |
+| `info(options)`                    | `ToastRef`   |
+| `warning(options)`                 | `ToastRef`   |
+| `error(options)`                   | `ToastRef`   |
+| `promise(taskOrFactory, messages)` | `Promise<T>` |
+| `dismiss()`                        | `void`       |
+
+### `ToastRef`
+
+| Member           | Type                                      | Notes                                                 |
+| ---------------- | ----------------------------------------- | ----------------------------------------------------- |
+| `dismiss()`      | `void`                                    | Dismisses this toast.                                 |
+| `afterDismissed` | `Promise<{ dismissedByAction: boolean }>` | Resolves with `dismissedByAction: true` via `action`. |
+
+### `ToastOptions`
+
+| Field                | Type                                                             | Default                  |
+| -------------------- | ---------------------------------------------------------------- | ------------------------ |
+| `title`              | `string`                                                         | —                        |
+| `description`        | `string`                                                         | —                        |
+| `action`             | `string`                                                         | —                        |
+| `dismissLabel`       | `string`                                                         | `'Dismiss notification'` |
+| `variant`            | `'default' \| 'destructive' \| 'success' \| 'info' \| 'warning'` | `'default'`              |
+| `durationMs`         | `number \| null`                                                 | `5000`                   |
+| `pauseOnInteraction` | `boolean`                                                        | `true`                   |
+| `horizontalPosition` | `'start' \| 'center' \| 'end' \| 'left' \| 'right'`              | `'end'`                  |
+| `verticalPosition`   | `'top' \| 'bottom'`                                              | `'bottom'`               |
+
+Set `durationMs` to `null` when the toast should stay visible until `dismiss()` is called.
+
+### `ToastPromiseMessages<T>`
+
+| Field     | Type                                     | Notes                                     |
+| --------- | ---------------------------------------- | ----------------------------------------- |
+| `loading` | `string`                                 | Title shown while the promise is pending. |
+| `success` | `string \| ((value: T) => string)`       | Title shown when the promise resolves.    |
+| `error`   | `string \| ((error: unknown) => string)` | Title shown when the promise rejects.     |
+
+## Styling And Theming
+
+The service applies `toast-panel` plus `toast-<variant>` classes to each toast `<div>`.
+
+- `default` keeps the `background`/`foreground` tokens from the active theme.
+- `success`, `info`, and `warning` map to the semantic status tokens
+  (`bg-success text-success-foreground`, and the same shape for the other two).
+  Those tokens are generated with a measured WCAG AA contrast guarantee, so every
+  variant stays readable in both modes without any override.
+- `destructive` (used by `error()`) maps to the destructive tokens.
+
+If you need to override a variant, target the toast class directly:
+
+```css
+.toast-panel.toast-warning {
+  background-color: hsl(var(--warning));
+  color: hsl(var(--warning-foreground));
+}
+```
+
+## Accessibility
+
+The service renders toasts into a `role="status"`, `aria-live="polite"` live region so screen readers announce them automatically. Timers pause while the pointer or keyboard focus is inside a toast, and every toast includes a labelled dismiss button.
+
+## Keyboard interactions
+
+The toast body itself is not a roving-focus widget. Tab reaches the optional action and dismiss buttons; focus pauses auto-dismiss until it leaves the toast.
+
+## Angular Notes
+
+Inject the service where the interaction starts instead of creating a global host component. Toasts stack in the live-region container, and `promise()` dismisses the loading toast before showing its success or error follow-up.
+
+## Source Parity
+
+This entrypoint is the local Angular mapping for shadcn Sonner as well as the simpler toast examples in the demo. It intentionally preserves the imperative API mental model, variant coverage, and placement controls while staying honest about the implementation boundary: the runtime surface is a focused, dependency-free live-region renderer, not Sonner's full multi-toast viewport.

package/component/toggle/README.md

@@ -0,0 +1,133 @@
+# Toggle
+
+A two-state button that can be either on or off.
+
+Use Toggle for persistent formatting, bookmarking, pinning, or filter state where a pressed button is the right semantic pattern.
+
+## Import
+
+```ts
+import { ToggleComponent } from '@ojiepermana/angular/component/toggle';
+```
+
+## Composition
+
+The Angular surface keeps the same single-host shape as shadcn and Radix while mapping it to a native button selector.
+
+```text
+button[Toggle]
+```
+
+## Basic usage
+
+Bind `[(pressed)]` when the parent should observe or control the state. The host always renders as a native button with `aria-pressed`.
+
+```ts
+readonly bookmarked = signal(false);
+```
+
+```html
+<button Toggle aria-label="Toggle bookmark" [(pressed)]="bookmarked" variant="outline" size="sm">
+  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+    <path d="M6 4.75c0-.41.34-.75.75-.75h10.5c.41 0 .75.34.75.75V20l-6-3.5L6 20V4.75Z" />
+  </svg>
+  Bookmark
+</button>
+```
+
+## Common patterns
+
+### Outline variant
+
+Use `variant="outline"` when the toggle should read like a bordered tool button.
+
+```html
+<button Toggle aria-label="Toggle italic" variant="outline">Italic</button>
+```
+
+### With text
+
+Project an icon and visible text when the label should stay on screen.
+
+```html
+<button Toggle aria-label="Toggle italic">
+  <svg aria-hidden="true" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.5">
+    <path d="M10 4h8" />
+    <path d="M6 20h8" />
+    <path d="M14 4 10 20" />
+  </svg>
+  Italic
+</button>
+```
+
+### Sizes
+
+The toggle supports the shadcn size names `sm`, `default`, and `lg`.
+
+```html
+<button Toggle size="sm" variant="outline" aria-label="Toggle small">Small</button>
+<button Toggle size="default" variant="outline" aria-label="Toggle default">Default</button>
+<button Toggle size="lg" variant="outline" aria-label="Toggle large">Large</button>
+```
+
+### Disabled state
+
+Set `[disabled]="true"` when the control should remain visible but unavailable.
+
+```html
+<button Toggle aria-label="Toggle bookmark" [disabled]="true">Bookmark</button>
+```
+
+### RTL
+
+Direction comes from the surrounding layout. The API stays the same.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <button Toggle aria-label="تبديل الإشارة المرجعية" variant="outline" size="sm">
+    إشارة مرجعية
+  </button>
+</div>
+```
+
+## API reference
+
+| Input or model | Type                        | Default     |
+| -------------- | --------------------------- | ----------- |
+| `pressed`      | `boolean`                   | `false`     |
+| `disabled`     | `boolean`                   | `false`     |
+| `variant`      | `'default' \| 'outline'`    | `'default'` |
+| `size`         | `'sm' \| 'default' \| 'lg'` | `'default'` |
+| `class`        | `string`                    | `''`        |
+
+Host: `button[Toggle]`.
+
+The host exposes `aria-pressed`, `data-state="on|off"`, `data-variant`, `data-size`, and `data-disabled` for styling and testing hooks.
+
+## Styling and theming
+
+The primitive uses the shared library color tokens for `foreground`, `accent`, `muted`, `input`, and `ring`.
+
+Use `class` to add width, shape, or layout utilities such as `rounded-full`, `w-full`, or responsive flex helpers.
+
+## Accessibility
+
+- `button[Toggle]` keeps the native button semantics and adds `aria-pressed` for the two-state pattern.
+- Provide an `aria-label` for icon-only toggles.
+- Use Toggle for persistent on/off state. If the control changes application state like a checkbox field, prefer the dedicated switch or checkbox primitive.
+- Disabled toggles remain visible but non-interactive.
+
+## Keyboard interactions
+
+- Native button behavior covers Tab focus plus Enter and Space activation.
+- Pressing Enter or Space toggles the `pressed` model through the native click event.
+
+## Angular notes
+
+- Import `ToggleComponent` into the standalone component that renders the host.
+- `[(pressed)]` is the Angular replacement for React's `pressed` and `onPressedChange` pairing.
+- The host always defaults to `type="button"` so it does not submit ancestor forms accidentally.
+
+## Source parity
+
+This Angular implementation follows the shadcn Toggle information architecture, variants, sizes, and RTL guidance while translating the runtime API to a native button host with signal-friendly two-way binding.

package/component/toggle-group/README.md

@@ -0,0 +1,234 @@
+# Toggle Group
+
+A set of two-state buttons that can be toggled on or off with either single or multiple selection.
+
+Use Toggle Group for formatting toolbars, persistent filters, view-mode switches, or any compact control cluster where each item represents a pressed state instead of an immediate action.
+
+## Import
+
+```ts
+import {
+  ToggleGroupComponent,
+  ToggleGroupItemDirective,
+} from '@ojiepermana/angular/component/toggle-group';
+```
+
+## Composition
+
+The Angular structure keeps the same root-plus-items shape as shadcn and Radix while translating the API to strongly typed Angular bindings.
+
+```text
+ToggleGroup
+├── button[ToggleGroupItem]
+└── button[ToggleGroupItem]
+```
+
+## Basic usage
+
+Use `[(value)]` for single-select groups and `[(values)]` for multi-select groups.
+
+```ts
+readonly alignment = signal<string | null>('center');
+readonly styles = signal<string[]>(['bold']);
+```
+
+```html
+<ToggleGroup type="single" [(value)]="alignment" variant="outline" aria-label="Text alignment">
+  <button ToggleGroupItem value="left" aria-label="Left aligned">Left</button>
+  <button ToggleGroupItem value="center" aria-label="Center aligned">Center</button>
+  <button ToggleGroupItem value="right" aria-label="Right aligned">Right</button>
+</ToggleGroup>
+```
+
+```html
+<ToggleGroup type="multiple" [(values)]="styles" variant="outline" aria-label="Text styles">
+  <button ToggleGroupItem value="bold" aria-label="Bold">Bold</button>
+  <button ToggleGroupItem value="italic" aria-label="Italic">Italic</button>
+  <button ToggleGroupItem value="underline" aria-label="Underline">Underline</button>
+</ToggleGroup>
+```
+
+## Common patterns
+
+### Outline
+
+Use `variant="outline"` when the group should read like a bordered toolbar or filter control.
+
+```html
+<ToggleGroup type="single" [(value)]="filter" variant="outline" aria-label="Message filters">
+  <button ToggleGroupItem value="all">All</button>
+  <button ToggleGroupItem value="missed">Missed</button>
+</ToggleGroup>
+```
+
+### Size
+
+Set `size` on the root so every child item scales together.
+
+```html
+<ToggleGroup
+  type="single"
+  [(value)]="alignment"
+  variant="outline"
+  size="lg"
+  aria-label="Large alignment"
+>
+  <button ToggleGroupItem value="left">Left</button>
+  <button ToggleGroupItem value="center">Center</button>
+  <button ToggleGroupItem value="right">Right</button>
+</ToggleGroup>
+```
+
+### Spacing
+
+Spacing defaults to `2`, matching the current shadcn docs. Use `spacing="0"` for connected items or larger values for looser toolbars.
+
+```html
+<ToggleGroup
+  type="single"
+  [(value)]="alignment"
+  variant="outline"
+  spacing="0"
+  aria-label="Connected alignment"
+>
+  <button ToggleGroupItem value="left">Left</button>
+  <button ToggleGroupItem value="center">Center</button>
+  <button ToggleGroupItem value="right">Right</button>
+</ToggleGroup>
+```
+
+### Vertical orientation
+
+Use `orientation="vertical"` to stack items while keeping the same roving-focus keyboard behavior.
+
+```html
+<ToggleGroup
+  type="multiple"
+  [(values)]="styles"
+  orientation="vertical"
+  spacing="1"
+  aria-label="Text styles"
+>
+  <button ToggleGroupItem value="bold" aria-label="Toggle bold">Bold</button>
+  <button ToggleGroupItem value="italic" aria-label="Toggle italic">Italic</button>
+  <button ToggleGroupItem value="underline" aria-label="Toggle underline">Underline</button>
+</ToggleGroup>
+```
+
+### Disabled group
+
+Disable the root when the whole cluster is unavailable.
+
+```html
+<ToggleGroup
+  type="multiple"
+  [(values)]="styles"
+  variant="outline"
+  [disabled]="true"
+  aria-label="Unavailable text styles"
+>
+  <button ToggleGroupItem value="bold">Bold</button>
+  <button ToggleGroupItem value="italic">Italic</button>
+  <button ToggleGroupItem value="underline">Underline</button>
+</ToggleGroup>
+```
+
+### Custom controlled state
+
+The selected value can drive any Angular signal, such as font weight, filters, or an editor mode.
+
+```ts
+readonly fontWeight = signal<string | null>('normal');
+```
+
+```html
+<ToggleGroup
+  type="single"
+  [(value)]="fontWeight"
+  variant="outline"
+  size="lg"
+  aria-label="Font weight"
+>
+  <button ToggleGroupItem value="light" class="min-w-24">Light</button>
+  <button ToggleGroupItem value="normal" class="min-w-24">Normal</button>
+  <button ToggleGroupItem value="medium" class="min-w-24">Medium</button>
+  <button ToggleGroupItem value="bold" class="min-w-24">Bold</button>
+</ToggleGroup>
+```
+
+### RTL
+
+Direction comes from the surrounding layout. Horizontal arrow navigation respects the active text direction automatically.
+
+```html
+<div dir="rtl" lang="ar" class="text-right">
+  <ToggleGroup type="single" [(value)]="view" variant="outline" aria-label="طريقة العرض">
+    <button ToggleGroupItem value="list">قائمة</button>
+    <button ToggleGroupItem value="grid">شبكة</button>
+    <button ToggleGroupItem value="cards">بطاقات</button>
+  </ToggleGroup>
+</div>
+```
+
+## API reference
+
+### `ToggleGroupComponent`
+
+| Input or model | Type                         | Default        |
+| -------------- | ---------------------------- | -------------- |
+| `type`         | `'single' \| 'multiple'`     | required       |
+| `value`        | `string \| null`             | `null`         |
+| `values`       | `string[]`                   | `[]`           |
+| `orientation`  | `'horizontal' \| 'vertical'` | `'horizontal'` |
+| `variant`      | `'default' \| 'outline'`     | `'default'`    |
+| `size`         | `'sm' \| 'default' \| 'lg'`  | `'default'`    |
+| `spacing`      | `0 \| 1 \| 2 \| 3 \| 4`      | `2`            |
+| `loop`         | `boolean`                    | `true`         |
+| `disabled`     | `boolean`                    | `false`        |
+| `dir`          | `'ltr' \| 'rtl' \| null`     | `null`         |
+| `class`        | `string`                     | `''`           |
+
+### `ToggleGroupItemDirective`
+
+| Input      | Type      | Default |
+| ---------- | --------- | ------- |
+| `value`    | `string`  | —       |
+| `disabled` | `boolean` | `false` |
+| `class`    | `string`  | `''`    |
+
+Host: `button[ToggleGroupItem]`.
+
+The item host exposes `aria-pressed`, `data-state="on|off"`, `data-variant`, `data-size`, `data-orientation`, and `data-disabled` for styling and testing hooks.
+
+## Styling and theming
+
+- Toggle Group items intentionally share the same `variant` and `size` contract as the standalone Toggle primitive, so grouped toolbars and standalone toggles stay visually aligned.
+- Use `spacing` for inter-item layout. When `spacing="0"`, the root collapses adjacent radius and borders so outline items read as a connected control.
+- Use `class` on the root or an item for width, alignment, or card-like custom presentations.
+
+## Accessibility
+
+- `ToggleGroup` renders `role="group"`; provide `aria-label` or `aria-labelledby` when the cluster needs an accessible name.
+- `button[ToggleGroupItem]` keeps native button semantics and exposes `aria-pressed` for the two-state pattern.
+- Add an `aria-label` to icon-only items.
+- Disabled items stay visible and are skipped by the group keyboard navigation.
+
+## Keyboard interactions
+
+- Tab moves focus to the pressed item or the first enabled item in the group.
+- Enter and Space activate or deactivate the current item through the native button click.
+- Arrow keys move focus through the group.
+- `Home` and `End` jump to the first or last enabled item.
+- Horizontal arrow movement respects RTL direction.
+
+## Angular notes
+
+- Use `[(value)]` in single mode and `[(values)]` in multiple mode instead of overloading one input with two types.
+- The item host selector is `button[ToggleGroupItem]`; consumers do not add `Toggle` separately.
+- The root owns roving focus, so consumer templates do not need extra CDK focus utilities.
+
+## Source parity
+
+This Angular implementation follows the current shadcn Toggle Group docs for outline styling, size scaling, spacing, vertical orientation, disabled groups, custom controlled state, RTL behavior, and the Radix roving-focus keyboard contract.
+
+The intentional Angular deviation is the binding split between `value` and `values`, which keeps signal types explicit for single and multiple modes.