@ojiepermana/angular-component 22.0.27

package/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/toast/README.md

@@ -0,0 +1,321 @@
+# Toast
+
+Imperative notification service wrapping `MatSnackBar` with shadcn styling and a Sonner-style API surface.
+
+## Import
+
+```ts
+import { ToastService } from '@ojiepermana/angular-component/toast';
+```
+
+## Application Setup
+
+Angular Material snack bars require animations to be configured once at application bootstrap.
+
+```ts
+import { bootstrapApplication } from '@angular/platform-browser';
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+
+bootstrapApplication(AppComponent, {
+  providers: [provideAnimationsAsync()],
+});
+```
+
+Use `provideNoopAnimations()` instead when the host application intentionally disables animations.
+
+## 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',
+});
+```
+
+### 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)`      | `MatSnackBarRef<unknown>` |
+| `success(options)`                 | `MatSnackBarRef<unknown>` |
+| `info(options)`                    | `MatSnackBarRef<unknown>` |
+| `warning(options)`                 | `MatSnackBarRef<unknown>` |
+| `error(options)`                   | `MatSnackBarRef<unknown>` |
+| `promise(taskOrFactory, messages)` | `Promise<T>`              |
+| `dismiss()`                        | `void`                    |
+
+### `ToastOptions`
+
+| Field                | Type                                                             | Default     |
+| -------------------- | ---------------------------------------------------------------- | ----------- |
+| `title`              | `string`                                                         | —           |
+| `description`        | `string`                                                         | —           |
+| `action`             | `string`                                                         | `''`        |
+| `variant`            | `'default' \| 'destructive' \| 'success' \| 'info' \| 'warning'` | `'default'` |
+| `durationMs`         | `number \| null`                                                 | `5000`      |
+| `horizontalPosition` | `MatSnackBarConfig['horizontalPosition']`                        | `'end'`     |
+| `verticalPosition`   | `MatSnackBarConfig['verticalPosition']`                          | `'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>` panel classes to the Angular Material snack-bar container.
+
+- `default` keeps the background and foreground tokens from the active theme.
+- `success` uses the primary theme tokens.
+- `info` uses the shared `info` tokens.
+- `warning` uses the shared `warning` tokens.
+- `error` maps to the destructive tokens.
+
+If you need to override a variant, target the container class and set the Material snack-bar CSS custom properties:
+
+```css
+.mat-mdc-snack-bar-container.toast-warning {
+  --mdc-snackbar-container-color: hsl(var(--warning));
+  --mdc-snackbar-supporting-text-color: hsl(var(--warning-foreground));
+  --mat-snack-bar-button-color: hsl(var(--warning-foreground));
+}
+```
+
+## Accessibility
+
+`MatSnackBar` manages live-region announcements automatically. Keep titles short, use `action` for a single primary follow-up, and avoid moving focus into the toast.
+
+## Angular Notes
+
+Inject the service where the interaction starts instead of creating a global host component. `MatSnackBar` shows one visible toast at a time, so `promise()` dismisses the loading state 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 still a focused `MatSnackBar` wrapper, not Sonner's stacked multi-toast viewport.
+
+# Toast
+
+Imperative notification service backed by `MatSnackBar`, styled for the local shadcn-inspired theme.
+
+The upstream shadcn toast page is deprecated in favor of Sonner. This entrypoint remains useful for lightweight single-message flows in Angular apps, while richer stacked notification workflows can move to a future Sonner-style surface.
+
+## Import
+
+```ts
+import { ToastService } from '@ojiepermana/angular-component/toast';
+```
+
+## App setup
+
+Enable browser or noop animations so the underlying snackbar overlay can render correctly.
+
+```ts
+import type { ApplicationConfig } from '@angular/core';
+import { provideAnimationsAsync } from '@angular/platform-browser/animations/async';
+
+export const appConfig: ApplicationConfig = {
+  providers: [provideAnimationsAsync()],
+};
+```
+
+Use `provideNoopAnimations()` instead when the host application deliberately disables animations.
+
+## Structure
+
+This entrypoint exports a service rather than a component tree. `ToastService` keeps the API at the same event-handling layer as your save, delete, archive, or publish action, while rendering is delegated to Angular Material overlays.
+
+## Basic usage
+
+```ts
+import { inject } from '@angular/core';
+import { ToastService } from '@ojiepermana/angular-component/toast';
+
+export class SaveButton {
+  private readonly toast = inject(ToastService);
+
+  save(): void {
+    this.toast.success({
+      title: 'Saved',
+      description: 'Your changes have been saved.',
+    });
+  }
+}
+```
+
+## Common patterns
+
+### Status shortcuts
+
+```ts
+this.toast.show({
+  title: 'Deployment queued',
+  description: 'We will notify you when the build is ready.',
+});
+
+this.toast.success({
+  title: 'Saved',
+  description: 'Your changes have been saved.',
+});
+
+this.toast.info({
+  title: 'Heads up',
+  description: 'The deployment window starts in 10 minutes.',
+});
+
+this.toast.warning({
+  title: 'Storage almost full',
+  description: 'Archive older uploads before the next sync.',
+});
+
+this.toast.error({
+  title: 'Failed to save',
+  description: 'Network error. Please retry.',
+});
+```
+
+### Persistent action
+
+For an important action, keep the toast open and handle the snackbar action from the returned reference.
+
+```ts
+const ref = this.toast.show({
+  title: 'Event archived',
+  description: 'Restore it from the calendar within the next minute.',
+  action: 'Undo',
+  durationMs: null,
+});
+
+ref.onAction().subscribe(() => {
+  this.toast.info({
+    title: 'Archive cancelled',
+    description: 'The event is back on the calendar.',
+  });
+});
+```
+
+### Promise helper
+
+Use `toast.promise()` when one async task should produce loading, success, and failure feedback in sequence.
+
+```ts
+await this.toast.promise(
+  () =>
+    new Promise<{ name: string }>((resolve) => {
+      window.setTimeout(() => resolve({ name: 'Summer launch checklist' }), 900);
+    }),
+  {
+    loading: 'Archiving draft...',
+    success: (draft) => `${draft.name} archived`,
+    error: 'Unable to archive draft',
+  },
+);
+```
+
+## API Reference
+
+### `ToastService`
+
+| Method                             | Returns                   | Notes                                                      |
+| ---------------------------------- | ------------------------- | ---------------------------------------------------------- |
+| `show(options)`                    | `MatSnackBarRef<unknown>` | Lowest-level method with full option control.              |
+| `success(options)`                 | `MatSnackBarRef<unknown>` | Shortcut for `variant: 'success'`.                         |
+| `info(options)`                    | `MatSnackBarRef<unknown>` | Angular-local semantic shortcut.                           |
+| `warning(options)`                 | `MatSnackBarRef<unknown>` | Angular-local semantic shortcut.                           |
+| `error(options)`                   | `MatSnackBarRef<unknown>` | Shortcut for `variant: 'destructive'`.                     |
+| `promise(taskOrFactory, messages)` | `Promise<T>`              | Shows loading first, then success or destructive feedback. |
+| `dismiss()`                        | `void`                    | Closes the active toast.                                   |
+
+### `ToastOptions`
+
+| Field                | Type                                                             | Default     | Notes                                                   |
+| -------------------- | ---------------------------------------------------------------- | ----------- | ------------------------------------------------------- |
+| `title`              | `string`                                                         | unset       | Primary message line.                                   |
+| `description`        | `string`                                                         | unset       | Optional secondary line.                                |
+| `action`             | `string`                                                         | `''`        | Single action label shown by the snackbar.              |
+| `variant`            | `'default' \| 'destructive' \| 'success' \| 'info' \| 'warning'` | `'default'` | Visual variant applied through `toast-*` panel classes. |
+| `durationMs`         | `number \| null`                                                 | `5000`      | Set to `null` to keep the toast open until dismissed.   |
+| `horizontalPosition` | `MatSnackBarConfig['horizontalPosition']`                        | `'end'`     | Snackbar x-axis placement.                              |
+| `verticalPosition`   | `MatSnackBarConfig['verticalPosition']`                          | `'bottom'`  | Snackbar y-axis placement.                              |
+
+### `ToastPromiseMessages<T>`
+
+| Field     | Type                                     | Notes                                               |
+| --------- | ---------------------------------------- | --------------------------------------------------- |
+| `loading` | `string`                                 | Required loading message while the task is pending. |
+| `success` | `string \| ((value: T) => string)`       | Static or data-derived success copy.                |
+| `error`   | `string \| ((error: unknown) => string)` | Static or error-derived destructive copy.           |
+
+## Styling and theming
+
+The service applies `toast-panel` and `toast-<variant>` classes on the snackbar container. The shared Material integration maps those classes to the local semantic tokens for default, destructive, success, info, and warning states, and preserves line breaks between `title` and `description`.
+
+## Accessibility
+
+`MatSnackBar` manages live-region announcements automatically. Keep toast copy short, reserve it for transient status updates, and prefer `durationMs: null` when the action button must stay available long enough for keyboard and assistive-technology users.
+
+## Keyboard interactions
+
+The toast body itself is not a roving-focus widget. Keyboard interaction is limited to the optional action button exposed by the snackbar when `action` is present.
+
+## Angular notes
+
+This API is intentionally Angular-first rather than a one-to-one port of Radix toast composition. You trigger notifications from event handlers or async workflows, not by managing a dedicated toast viewport in every template.
+
+## Source parity
+
+Default and destructive map most closely to the historical shadcn toast examples. `success`, `info`, and `warning` are Angular-local semantic additions that fit the service-style API better. The upstream shadcn page now points users to Sonner, so this entrypoint deliberately focuses on simple, single-message feedback instead of stacked queue management.

package/toggle/README.md

@@ -0,0 +1,131 @@
+# 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.