@ojiepermana/angular-component 22.0.27

package/slider/README.md

@@ -0,0 +1,207 @@
+# Slider
+
+Selects one or more numeric values from a bounded range.
+
+This entrypoint now exports two related Angular surfaces:
+
+- `Slider` via `SliderRootComponent` for shadcn-style single-thumb, range,
+  multiple-thumb, vertical, disabled, and RTL examples.
+- `input[Slider]` via `SliderInputDirective` for browser-native range inputs
+  when labels and forms should stay on the native path.
+
+## Import
+
+```ts
+import { SliderInputDirective, SliderRootComponent } from '@ojiepermana/angular-component/slider';
+```
+
+## Structure
+
+Use `Slider` when you want the richer shadcn-style component.
+
+```html
+<Slider [value]="[75]" />
+```
+
+Keep `input[Slider]` when a plain native range input is still the best fit.
+
+```html
+<input type="range" Slider />
+```
+
+## Basic usage
+
+```ts
+const volume = signal<readonly number[]>([75]);
+
+<Slider
+  aria-label="Volume"
+  [min]="0"
+  [max]="100"
+  [step]="1"
+  [value]="volume()"
+  (valueChange)="volume.set($event)"
+  class="w-full max-w-sm" />
+```
+
+## Common patterns
+
+### Range
+
+Two values render a range slider.
+
+```ts
+const priceRange = signal<readonly number[]>([25, 50]);
+
+<Slider
+  aria-label="Price range"
+  min="0"
+  max="100"
+  step="5"
+  [value]="priceRange()"
+  (valueChange)="priceRange.set($event)"
+  [thumbLabels]="['Minimum price', 'Maximum price']" />
+```
+
+### Multiple thumbs
+
+Three or more values render several thumbs in sorted order.
+
+```ts
+const equalizer = signal<readonly number[]>([10, 20, 70]);
+
+<Slider
+  aria-label="Equalizer"
+  min="0"
+  max="100"
+  step="10"
+  [value]="equalizer()"
+  (valueChange)="equalizer.set($event)"
+  [thumbLabels]="['Bass', 'Mid', 'Treble']" />
+```
+
+### Vertical
+
+Set `orientation="vertical"` and provide an explicit height through `class`.
+
+```html
+<div class="flex items-center gap-6">
+  <Slider aria-label="Primary level" orientation="vertical" [value]="[50]" class="h-40" />
+  <Slider aria-label="Secondary level" orientation="vertical" [value]="[25]" class="h-40" />
+</div>
+```
+
+### Controlled slider
+
+Drive the values from a signal when nearby UI should react immediately.
+
+```ts
+const temperatureRange = signal<readonly number[]>([30, 70]);
+
+<Slider
+  aria-label="Temperature range"
+  min="0"
+  max="100"
+  step="5"
+  [value]="temperatureRange()"
+  (valueChange)="temperatureRange.set($event)"
+  [thumbLabels]="['Minimum temperature', 'Maximum temperature']" />
+```
+
+### Disabled state
+
+```html
+<Slider aria-label="Disabled notifications volume" [value]="[50]" disabled />
+```
+
+### RTL
+
+The component follows the surrounding document direction automatically.
+
+```html
+<section dir="rtl" lang="ar" class="w-full max-w-sm text-right">
+  <Slider aria-label="مستوى الصوت" [value]="[75]" class="w-full" />
+</section>
+```
+
+### Native input companion
+
+Use the exported native directive when the browser-native range input is still
+the best Angular fit for forms and `label[for]` wiring.
+
+```html
+<label for="native-volume" class="mb-2 block">Volume</label>
+<input id="native-volume" type="range" Slider min="0" max="100" step="1" class="w-full max-w-sm" />
+```
+
+## API reference
+
+| Input or output                                       | Type                         | Notes                                                                                     |
+| ----------------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------- |
+| `value`                                               | `readonly number[]`          | Array of sorted thumb values. One item renders a single thumb.                            |
+| `valueChange`                                         | `readonly number[]`          | Emits the next array whenever a thumb moves.                                              |
+| `min`                                                 | `number`                     | Lower bound for every thumb.                                                              |
+| `max`                                                 | `number`                     | Upper bound for every thumb.                                                              |
+| `step`                                                | `number`                     | Drag and keyboard increment.                                                              |
+| `orientation`                                         | `'horizontal' \| 'vertical'` | Vertical sliders need an explicit height via `class`.                                     |
+| `disabled`                                            | `boolean`                    | Disables drag and keyboard interaction.                                                   |
+| `thumbLabels`                                         | `readonly string[]`          | Optional accessible labels for each thumb.                                                |
+| `aria-label` / `aria-labelledby` / `aria-describedby` | `string \| null`             | Applied to thumb semantics. Prefer `thumbLabels` when several thumbs need distinct names. |
+| `class`                                               | `string`                     | Width and height utilities on the host component.                                         |
+
+`SliderInputDirective` keeps the native `<input type="range">` API and passes
+through ordinary input attributes directly.
+
+## Styling and theming
+
+The rich `Slider` component uses:
+
+- `--secondary` for the track.
+- `--primary` for the active range.
+- `--background` for the thumb surface.
+- `--primary` for the thumb border.
+- `--ring` for the focus-visible outline.
+
+Apply width and height utilities through the host `class`, for example
+`w-full`, `max-w-sm`, or `h-40` for vertical sliders.
+
+The native input companion keeps its styling in [slider.component.css](./slider.component.css).
+
+## Accessibility
+
+- Each thumb exposes `role="slider"` with `aria-valuemin`, `aria-valuemax`,
+  `aria-valuenow`, and `aria-orientation`.
+- Provide `thumbLabels` when the slider has several thumbs so each one has a
+  distinct accessible name.
+- Use `aria-describedby` for helper text, units, or validation guidance.
+- The focused thumb stays tabbable while sibling thumbs use roving `tabindex`.
+- When you need browser-native label semantics, use `SliderInputDirective`
+  instead of forcing the rich component into a native-input role.
+
+## Keyboard interactions
+
+For `Slider`:
+
+- Arrow keys adjust the value by `step`.
+- `Page Up` and `Page Down` move by a larger increment.
+- `Home` and `End` jump the active thumb to its local minimum or maximum bound.
+- Pointer dragging and track clicks move the nearest thumb.
+
+For `SliderInputDirective`, keyboard behavior follows the browser-native range
+input model.
+
+## Angular notes
+
+- Prefer `Slider` when you need shadcn-style parity: range selection,
+  multiple thumbs, vertical layout, or explicit thumb labels.
+- Prefer `SliderInputDirective` when the control should remain a real native
+  input inside Angular forms or a traditional field layout.
+- The two exports are complementary rather than replacements for one another.
+
+## Source parity
+
+This Angular entrypoint now covers the main shadcn Radix slider examples:
+single-thumb preview, range, multiple thumbs, vertical, controlled, disabled,
+and RTL. The native `input[Slider]` directive remains intentionally exported
+as an Angular companion for browser-native range inputs instead of disappearing
+behind the richer component.

package/spinner/README.md

@@ -0,0 +1,160 @@
+# Spinner
+
+Displays a compact loading indicator for inline status, buttons, badges, input groups, and empty states.
+
+Use Spinner when work is in progress but the surrounding layout should stay visible and composable.
+
+## Import
+
+```ts
+import { SpinnerComponent } from '@ojiepermana/angular-component/spinner';
+```
+
+Bring in companion entrypoints such as Button, Badge, Item, Empty, or Input Group only when the surrounding example needs them.
+
+## Basic usage
+
+By default, `Spinner` exposes `role="status"` with an accessible name of `Loading`.
+
+```html
+<Spinner aria-label="Loading invoices" />
+```
+
+## Common patterns
+
+### Size and color
+
+Use the `class` input to change size, color, or surrounding spacing.
+
+```html
+<div class="flex items-center gap-4">
+  <Spinner class="size-3" aria-label="Refreshing alerts" />
+  <Spinner class="size-4 text-primary" aria-label="Refreshing dashboard" />
+  <Spinner class="size-6 text-muted-foreground" aria-label="Loading analytics" />
+</div>
+```
+
+### Decorative inline status
+
+When nearby text already explains the loading state, mark the spinner as decorative so assistive technology does not hear duplicate status announcements.
+
+```html
+<button Button type="button" disabled class="gap-2">
+  <Spinner decorative />
+  Loading...
+</button>
+```
+
+### Button and badge composition
+
+There is no React-style `data-icon` API in the Angular library. Place `Spinner` before or after the visible label and use standard gap utilities on the host surface.
+
+```html
+<button Button type="button" variant="outline" disabled class="gap-2">
+  <Spinner decorative />
+  Please wait
+</button>
+
+<Badge class="gap-1.5">
+  <Spinner decorative class="size-3" />
+  Syncing
+</Badge>
+```
+
+### Item row
+
+The upstream preview maps cleanly to the local Item primitive.
+
+```html
+<Item variant="muted" class="w-full max-w-xs [--radius:1rem]">
+  <ItemMedia>
+    <Spinner decorative />
+  </ItemMedia>
+  <ItemContent>
+    <ItemTitle>Processing payment...</ItemTitle>
+  </ItemContent>
+  <ItemContent class="flex-none justify-end">
+    <span class="text-sm tabular-nums">$100.00</span>
+  </ItemContent>
+</Item>
+```
+
+### Input group status
+
+Spinner works as projected content inside `InputGroupAddon` for inline or block-end status rows.
+
+```html
+<InputGroup>
+  <input InputGroupInput placeholder="Send a message..." disabled />
+  <InputGroupAddon align="inline-end">
+    <Spinner decorative />
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Empty state
+
+Project the spinner into `EmptyMedia` when a request is still processing.
+
+```html
+<Empty class="w-full max-w-xl rounded-2xl border border-border bg-card/40">
+  <EmptyHeader>
+    <EmptyMedia variant="icon">
+      <Spinner decorative class="size-5" />
+    </EmptyMedia>
+    <EmptyTitle>Processing your request</EmptyTitle>
+    <EmptyDescription>Please wait while the operation completes.</EmptyDescription>
+  </EmptyHeader>
+</Empty>
+```
+
+### RTL
+
+Set `dir="rtl"` on the surrounding container or layout shell. The spinner stays direction-agnostic while the surrounding row flips logically.
+
+```html
+<section dir="rtl" lang="ar" class="w-full max-w-xs">
+  <Item variant="muted">
+    <ItemMedia>
+      <Spinner decorative />
+    </ItemMedia>
+    <ItemContent>
+      <ItemTitle>جاري معالجة الدفع...</ItemTitle>
+    </ItemContent>
+  </Item>
+</section>
+```
+
+## API reference
+
+| Input             | Type             | Default     | Notes                                                   |
+| ----------------- | ---------------- | ----------- | ------------------------------------------------------- |
+| `class`           | `string`         | `''`        | Controls size, color, and layout spacing.               |
+| `decorative`      | `boolean`        | `false`     | Removes status semantics and sets `aria-hidden="true"`. |
+| `aria-label`      | `string`         | `'Loading'` | Accessible name when the spinner stands alone.          |
+| `aria-labelledby` | `string \| null` | `null`      | Connects the spinner to nearby visible text.            |
+
+Native host attributes such as `id`, `dir`, `data-*`, and custom utility classes still pass through to the rendered custom element.
+
+## Styling and theming
+
+The spinner inherits `currentColor`, so it automatically matches the surrounding button, badge, item, or muted text color unless a utility overrides it.
+
+The default animation uses `animate-spin` and automatically stops under `prefers-reduced-motion`.
+
+## Accessibility
+
+- Default host is a named `status` element for standalone loading indicators.
+- Set `decorative` when nearby text already announces the loading state.
+- Use `aria-labelledby` instead of a second invisible label when visible copy already exists in the same row.
+- Keep the spinner paired with meaningful text or layout context for passive loading states.
+
+## Angular notes
+
+- `Spinner` is a standalone component with no providers or services.
+- Size and color remain utility-driven instead of introducing React-style variant props.
+- The `decorative` input is the Angular-first way to avoid repeated status announcements inside composed controls.
+
+## Source parity
+
+This Angular implementation follows the shadcn Spinner page closely for preview, sizing, buttons, badges, input groups, empty states, and RTL composition while translating the API to standalone imports, utility-driven styling, and explicit accessibility bindings.

package/switch/README.md

@@ -0,0 +1,166 @@
+# Switch
+
+A shadcn-style switch primitive built on Angular Material's `mat-slide-toggle`, with `ControlValueAccessor` support for `ngModel` and reactive forms.
+
+## Import
+
+```ts
+import { FormsModule } from '@angular/forms';
+import { SwitchComponent } from '@ojiepermana/angular-component/switch';
+```
+
+Add `FormsModule` only when the host component uses `ngModel`. Reactive forms work through the same primitive.
+
+## Basic usage
+
+Use projected content for compact inline labels.
+
+```html
+<Switch [(ngModel)]="airplaneMode" name="airplane-mode">Airplane mode</Switch>
+```
+
+For helper text or card-like settings rows, move the copy outside the switch and connect it with `aria-labelledby` plus `aria-describedby`.
+
+```html
+<div class="flex items-start justify-between gap-4 rounded-xl border border-border bg-card/40 p-4">
+  <div class="space-y-1">
+    <p id="switch-share-label" class="font-medium">Share across devices</p>
+    <p id="switch-share-description" class="text-sm leading-5 text-muted-foreground">
+      Focus is shared across devices, and turns off when you leave the app.
+    </p>
+  </div>
+  <Switch
+    [ngModel]="shareAcrossDevices()"
+    (ngModelChange)="shareAcrossDevices.set($event)"
+    name="share-across-devices"
+    aria-labelledby="switch-share-label"
+    aria-describedby="switch-share-description" />
+</div>
+```
+
+Reactive forms continue to work through the component's value accessor.
+
+```html
+<Switch [formControl]="form.controls.notifications" aria-label="Email notifications" />
+```
+
+## Common patterns
+
+### Descriptive settings row
+
+Use `aria-labelledby` and `aria-describedby` when the visible copy sits outside the switch.
+
+```html
+<div class="flex items-start justify-between gap-4">
+  <div class="space-y-1">
+    <p id="setting-label" class="font-medium">Share across devices</p>
+    <p id="setting-description" class="text-sm text-muted-foreground">
+      Focus is shared across devices, and turns off when you leave the app.
+    </p>
+  </div>
+  <Switch
+    [ngModel]="shareAcrossDevices()"
+    (ngModelChange)="shareAcrossDevices.set($event)"
+    name="share-across-devices"
+    aria-labelledby="setting-label"
+    aria-describedby="setting-description" />
+</div>
+```
+
+### Choice card layout
+
+The upstream shadcn example wraps the whole field in a clickable label. This Angular primitive keeps the switch as the single interactive control and uses the surrounding card only for layout.
+
+```html
+<div class="rounded-xl border border-border bg-card/40 p-4">
+  <div class="flex items-start justify-between gap-4">
+    <div class="space-y-1">
+      <p id="notifications-label" class="font-medium">Enable notifications</p>
+      <p id="notifications-description" class="text-sm text-muted-foreground">
+        Receive notifications when focus mode is enabled or disabled.
+      </p>
+    </div>
+    <Switch
+      [ngModel]="notificationsEnabled()"
+      (ngModelChange)="notificationsEnabled.set($event)"
+      name="notifications-card"
+      aria-labelledby="notifications-label"
+      aria-describedby="notifications-description" />
+  </div>
+</div>
+```
+
+### Invalid state
+
+Forward `aria-invalid="true"` when validation should promote the switch into the destructive token set.
+
+```html
+<Switch
+  [ngModel]="acceptTerms()"
+  (ngModelChange)="acceptTerms.set($event)"
+  name="terms-switch"
+  aria-invalid="true"
+  aria-label="Accept terms and conditions" />
+```
+
+### Size
+
+Use `size="sm"` for denser settings lists and compact preference panes.
+
+```html
+<Switch size="sm" [(ngModel)]="compactPreference" name="compact-preference">Compact mode</Switch>
+```
+
+## API reference
+
+| Input              | Type                        | Default        | Notes                                                                     |
+| ------------------ | --------------------------- | -------------- | ------------------------------------------------------------------------- |
+| `id`               | `string`                    | auto-generated | Forwarded to Material; the focusable switch button becomes `<id>-button`. |
+| `name`             | `string \| null`            | `null`         | Forwarded to the underlying switch control.                               |
+| `disabled`         | `boolean`                   | `false`        | Merges with form-driven disabled state.                                   |
+| `required`         | `boolean`                   | `false`        | Forwarded to the underlying Material switch.                              |
+| `aria-label`       | `string \| null`            | `null`         | Use for compact or text-free switch controls.                             |
+| `aria-describedby` | `string \| null`            | `null`         | Links helper or error text outside the control.                           |
+| `aria-labelledby`  | `string \| null`            | `null`         | Best choice for descriptive rows and card layouts.                        |
+| `aria-invalid`     | `boolean \| string \| null` | `null`         | Switches the control into the destructive invalid treatment.              |
+| `size`             | `'default' \| 'sm'`         | `'default'`    | Smaller track for dense settings lists.                                   |
+| `class`            | `string`                    | `''`           | Adds utility classes to the wrapped Material host.                        |
+
+| Output          | Payload   |
+| --------------- | --------- |
+| `checkedChange` | `boolean` |
+
+Public method: `focus()`.
+
+## Styling and theming
+
+The component uses a Material bridge so the MDC switch structure is restyled with the library theme tokens.
+
+- Default track and handle colors use the shared `primary`, `input`, and `background` tokens.
+- `aria-invalid="true"` switches the switch into the destructive token set.
+- `size="sm"` tightens the track and handle sizing without creating a second entrypoint.
+- Pass spacing or alignment utilities through `class` when the switch needs to line up with multi-line content.
+
+Additional visual adjustments belong in `switch.component.css` inside the library.
+
+## Accessibility
+
+- Give the switch an accessible name through projected content, `aria-label`, or `aria-labelledby`.
+- Use `aria-describedby` for helper or error text rendered outside the control.
+- Prefer `aria-labelledby` over `label[for]` when the visible label is external, because Angular Material renders a focusable switch button rather than a labelable text input.
+- `aria-invalid` is forwarded to the underlying Material host for validation styling and assistive technology cues.
+
+## Keyboard interactions
+
+- `Tab` moves focus to the switch in DOM order.
+- `Space` toggles the checked state.
+
+## Angular notes
+
+- `ngModel`, reactive forms, and `checkedChange` all work with the same primitive.
+- Passing `id` forwards a stable base id to Angular Material; the focusable button receives the derived `<id>-button` id.
+- The direct `disabled` input and `setDisabledState()` from forms are merged, so either source can disable the control.
+
+## Source parity
+
+This Angular implementation follows the shadcn Switch examples while translating the upstream Field helpers and clickable-card label pattern into Angular-friendly descriptive containers, ARIA relationships, and signal-friendly state handling.