@ojiepermana/angular 22.1.10 → 22.1.12

package/component/pagination/README.md

@@ -0,0 +1,151 @@
+# Pagination
+
+Compact page navigation with previous and next controls, windowed page numbers, optional icon-only mode, and localized labels.
+
+Use Pagination when a feature page needs to move through a paged API result, a dense table footer, or a navigable list of routes or guides.
+
+## Import
+
+```ts
+import { PaginationComponent } from '@ojiepermana/angular/component/pagination';
+```
+
+## Structure
+
+The Angular package intentionally wraps the shadcn multi-part composition in a single standalone primitive.
+
+```text
+Pagination
+├── previous button
+├── page buttons and ellipsis
+└── next button
+```
+
+## Basic usage
+
+Bind `[(page)]` to a signal and keep your collection, router state, or server request outside the primitive.
+
+```html
+<Pagination
+  [(page)]="currentPage"
+  [total]="totalPages"
+  [siblingCount]="1"
+  (pageChange)="load($event)"
+/>
+```
+
+## Common patterns
+
+### Navigation data
+
+Keep the rendered collection in sync with the pager through `computed()`.
+
+```ts
+const navigationPage = signal(1);
+const pageSize = 4;
+
+const navigationItems = [
+  { title: 'Introduction', route: '/docs/introduction' },
+  { title: 'Accordion', route: '/ui/shadcn/accordion' },
+  { title: 'Button', route: '/ui/shadcn/button' },
+  { title: 'Input', route: '/ui/shadcn/input' },
+  // ...more items
+];
+
+const totalPages = Math.ceil(navigationItems.length / pageSize);
+const visibleItems = computed(() => {
+  const start = (navigationPage() - 1) * pageSize;
+  return navigationItems.slice(start, start + pageSize);
+});
+```
+
+### Icons only
+
+Hide page numbers and visible labels when the pager sits next to a dense table or feed footer.
+
+```html
+<Pagination
+  [(page)]="compactPage"
+  [total]="9"
+  [showPageNumbers]="false"
+  previousText=""
+  nextText=""
+  class="mx-0 w-auto"
+/>
+```
+
+### RTL and translated labels
+
+Translate the previous and next text and provide a page formatter when locale-specific numerals should appear.
+
+```ts
+const arabicDigits = ['٠', '١', '٢', '٣', '٤', '٥', '٦', '٧', '٨', '٩'];
+const toArabicNumerals = (page: number): string =>
+  page
+    .toString()
+    .split('')
+    .map((digit) => arabicDigits[Number(digit)] ?? digit)
+    .join('');
+```
+
+```html
+<section dir="rtl" lang="ar" class="text-right">
+  <Pagination
+    [(page)]="rtlPage"
+    [total]="7"
+    previousText="السابق"
+    nextText="التالي"
+    previousAriaLabel="الانتقال إلى الصفحة السابقة"
+    nextAriaLabel="الانتقال إلى الصفحة التالية"
+    [formatPageLabel]="toArabicNumerals"
+  />
+</section>
+```
+
+## API reference
+
+| Input               | Type                       | Default                   | Description                                                            |
+| ------------------- | -------------------------- | ------------------------- | ---------------------------------------------------------------------- |
+| `page` (model)      | `number`                   | `1`                       | Two-way bound current page.                                            |
+| `total`             | `number`                   | `1`                       | Total number of pages available.                                       |
+| `siblingCount`      | `number`                   | `1`                       | Page buttons shown on either side of the active page.                  |
+| `showPageNumbers`   | `boolean`                  | `true`                    | Hide numbered page buttons for compact previous and next only layouts. |
+| `previousText`      | `string`                   | `'Previous'`              | Visible previous label. Set to an empty string for icon-only mode.     |
+| `nextText`          | `string`                   | `'Next'`                  | Visible next label. Set to an empty string for icon-only mode.         |
+| `previousAriaLabel` | `string`                   | `'Go to previous page'`   | Accessible name for the previous button.                               |
+| `nextAriaLabel`     | `string`                   | `'Go to next page'`       | Accessible name for the next button.                                   |
+| `formatPageLabel`   | `(page: number) => string` | `page => page.toString()` | Formats the rendered page label.                                       |
+| `class`             | `string`                   | `''`                      | Extra container classes.                                               |
+
+| Output       | Payload  | Description                                          |
+| ------------ | -------- | ---------------------------------------------------- |
+| `pageChange` | `number` | Emits the next page number after a user interaction. |
+
+## Styling and theming
+
+Pagination reuses `buttonVariants`, so the previous and next controls plus numbered page buttons inherit the same shape, focus ring, and theme tokens as the Button primitive.
+
+Pass `class` to adjust width and alignment, for example `mx-0 w-auto` in a table footer or `justify-start` when the pager should align to the left edge of a card.
+
+## Accessibility
+
+- The root renders as `<nav role="navigation" aria-label="pagination">`.
+- The active page is marked with `aria-current="page"`.
+- Previous and next disable natively at the start and end of the available range.
+- Ellipses are `aria-hidden="true"`.
+- When visible text is removed for icon-only mode, keep meaningful aria labels on the previous and next buttons.
+
+## Keyboard interactions
+
+- Tab moves focus through the previous button, page buttons, and next button in DOM order.
+- Enter and Space activate the focused button through native button semantics.
+
+## Angular notes
+
+- Keep the paged collection outside the component and derive the visible slice with `computed()`.
+- Import `PaginationComponent` into the standalone feature component that renders the pager.
+- `showPageNumbers`, `previousText`, `nextText`, and `formatPageLabel` are deliberate Angular-specific conveniences that cover the upstream icon-only and RTL guidance without exposing React-style child parts.
+
+## Source parity
+
+shadcn documents Pagination as several composable parts such as `PaginationLink`, `PaginationPrevious`, and `PaginationNext`. This Angular implementation intentionally collapses that structure into one primitive so route-driven and data-driven pagination can be wired quickly while still matching the upstream previous, next, ellipsis, compact, and RTL behavior.

package/component/pillbox/README.md

@@ -0,0 +1,68 @@
+# Pillbox
+
+Multi-value selection primitives inspired by Flux Pillbox and implemented with local shadcn-style Angular patterns.
+
+## Import
+
+```ts
+import {
+  PillboxComponent,
+  PillboxOptionComponent,
+  PillboxOptionCreateComponent,
+  PillboxOptionEmptyComponent,
+  PillboxSelectedDirective,
+} from '@ojiepermana/angular/component/pillbox';
+```
+
+## Usage
+
+```html
+<Pillbox multiple placeholder="Choose tags..." [(ngModel)]="selectedTags">
+  <PillboxOption value="design">Design</PillboxOption>
+  <PillboxOption value="development">Development</PillboxOption>
+  <PillboxOption value="marketing">Marketing</PillboxOption>
+</Pillbox>
+```
+
+## Composition
+
+- `Pillbox` owns the trigger, selected pills, search state, option filtering, and form control integration.
+- `PillboxOption` projects the visible option content and stores the option value.
+- `ng-template[PillboxSelected]` customizes the rendered selected pill content for an option.
+- `PillboxOptionCreate` emits create requests when the search query is long enough and does not match an existing option.
+- `PillboxOptionEmpty` customizes empty and loading messages.
+
+## Inputs
+
+### PillboxComponent
+
+| Input               | Type                      | Default               | Description                                                                |
+| ------------------- | ------------------------- | --------------------- | -------------------------------------------------------------------------- |
+| `placeholder`       | `string`                  | `'Choose options...'` | Text shown when nothing is selected.                                       |
+| `searchPlaceholder` | `string`                  | `'Search...'`         | Placeholder for the dropdown search input.                                 |
+| `size`              | `'default' \| 'sm'`       | `'default'`           | Trigger and pill density.                                                  |
+| `variant`           | `'default' \| 'combobox'` | `'default'`           | Use `combobox` to place the search input directly in the trigger.          |
+| `multiple`          | `boolean`                 | `false`               | Emits an array of selected values when enabled.                            |
+| `searchable`        | `boolean`                 | `false`               | Adds a search input to the dropdown for the default variant.               |
+| `filter`            | `boolean`                 | `true`                | Enables client-side filtering. Disable it for backend-driven option lists. |
+| `compareWith`       | `(a, b) => boolean`       | `Object.is`           | Matches bound values to options. Compare by key for object values.         |
+| `clearable`         | `boolean`                 | `true`                | Shows a clear-all control when values are selected.                        |
+| `disabled`          | `boolean`                 | `false`               | Prevents interaction.                                                      |
+| `invalid`           | `boolean`                 | `false`               | Applies error styling and `aria-invalid`.                                  |
+| `loading`           | `boolean`                 | `false`               | Shows loading copy through the empty option when no options match.         |
+
+## Events
+
+| Output         | Payload   | Description                                                               |
+| -------------- | --------- | ------------------------------------------------------------------------- |
+| `valueChange`  | `unknown` | Emits the selected array for `multiple` mode or a single value otherwise. |
+| `searchChange` | `string`  | Emits whenever the search query changes.                                  |
+| `create`       | `string`  | Emits the current query from `PillboxOptionCreate`.                       |
+| `openedChange` | `boolean` | Emits when the option list opens or closes.                               |
+
+## Accessibility
+
+- Use a visible label or `aria-label`/`aria-labelledby` on `Pillbox`.
+- Use `multiple` when binding to an array of values.
+- Provide readable option labels; set `label` or `selectedLabel` when custom option content is not textual.
+- Keep create actions explicit and validate new values in the owning form or backend.

package/component/popover/README.md

@@ -0,0 +1,54 @@
+# Popover
+
+Anchored floating panel with CDK overlay. Click the trigger to toggle.
+
+## Import
+
+```ts
+import {
+  PopoverTriggerDirective,
+  PopoverContentDirective,
+} from '@ojiepermana/angular/component/popover';
+```
+
+## Usage
+
+```html
+<button Button [PopoverTrigger]="content" side="bottom" align="start">Open</button>
+
+<ng-template PopoverContent #content="PopoverContent">
+  <div class="w-64 rounded-md border bg-popover p-4 text-popover-foreground shadow-md">
+    Popover body
+  </div>
+</ng-template>
+```
+
+## API
+
+### `PopoverTriggerDirective` (`[PopoverTrigger]`)
+
+| Input            | Type                                     | Default    |
+| ---------------- | ---------------------------------------- | ---------- |
+| `PopoverTrigger` | `PopoverContentDirective`                | —          |
+| `side`           | `'top' \| 'right' \| 'bottom' \| 'left'` | `'bottom'` |
+| `align`          | `'start' \| 'center' \| 'end'`           | `'center'` |
+| `disabled`       | `boolean`                                | `false`    |
+
+Exposes `isOpen()` signal. Trigger automatically sets `aria-haspopup="dialog"`
+and `aria-expanded` on the host.
+
+### `PopoverContentDirective` (`ng-template[PopoverContent]`)
+
+Marker directive that exposes the template via `exportAs="PopoverContent"`.
+
+## Accessibility
+
+- Close on `Escape`.
+- Close on backdrop click.
+- Trigger reflects state via `aria-expanded` and `aria-haspopup`.
+- Opening moves focus to the first tabbable element in the pane, or to the pane
+  itself when it holds none. The pane is a non-modal dialog, so focus is placed
+  there but never trapped: `Tab` walks straight back out into the page.
+- `Escape`, and closing from the trigger, return focus to the trigger. Dismissal
+  by a pointer press outside does not, because that press is already handing
+  focus to whatever was pressed.

package/component/progress/README.md

@@ -0,0 +1,160 @@
+# Progress
+
+Displays an indicator showing the completion progress of a task, typically as a
+slim passive progress bar.
+
+Use Progress for uploads, background jobs, onboarding steps, and other cases
+where the user should understand status without directly interacting with the
+bar itself.
+
+## Import
+
+```ts
+import { ProgressComponent } from '@ojiepermana/angular/component/progress';
+```
+
+For the visible label and slider-driven examples below, also import the existing
+label and slider entrypoints:
+
+```ts
+import { LabelComponent } from '@ojiepermana/angular/component/label';
+import { SliderComponent } from '@ojiepermana/angular/component/slider';
+```
+
+## Basic usage
+
+Provide an accessible name directly when the bar stands on its own.
+
+```html
+<ProgressBar [value]="33" aria-label="Upload progress" class="w-full max-w-sm" />
+```
+
+## Common patterns
+
+### Visible label row
+
+The current shadcn Radix docs place Progress inside a Field layout with a
+visible label and percentage. In Angular, keep the visible copy outside the
+bar and connect it with `aria-labelledby`.
+
+```html
+<label id="progress-upload-label" class="mb-2 flex items-center gap-3">
+  <span>Upload progress</span>
+  <span class="ms-auto text-muted-foreground">66%</span>
+</label>
+
+<ProgressBar [value]="66" aria-labelledby="progress-upload-label" class="w-full max-w-sm" />
+```
+
+Use `aria-labelledby` here instead of `label[for]`, because `ProgressBar` is a
+custom element with `role="progressbar"`, not a native labelable form control.
+
+### Controlled progress
+
+Keep the progress bar passive and let surrounding controls own the interaction.
+The built-in range slider directive works well for the same pattern shown in the
+upstream docs.
+
+```ts
+const controlledValue = signal(50);
+
+<Label id="progress-controlled-label" class="mb-2 flex items-center gap-3">
+  <span>Upload progress</span>
+  <span class="ms-auto text-muted-foreground">{{ controlledValue() }}%</span>
+</Label>
+
+<ProgressBar [value]="controlledValue()" aria-labelledby="progress-controlled-label" class="w-full" />
+
+<Label for="progress-controlled-slider" class="mb-2 block">Adjust progress</Label>
+<input
+  id="progress-controlled-slider"
+  type="range"
+  Slider
+  min="0"
+  max="100"
+  step="1"
+  [value]="controlledValue()"
+  (input)="onControlledInput($event)" />
+```
+
+### Indeterminate loading
+
+Switch to `indeterminate` when work is running but no stable percentage is
+available yet.
+
+```html
+<ProgressBar [indeterminate]="true" aria-label="Loading deployment" class="w-full max-w-sm" />
+```
+
+### RTL
+
+Follow the upstream guidance by setting `dir="rtl"` on the surrounding
+container and flipping the bar with `rtl:rotate-180`.
+
+```html
+<section dir="rtl" lang="ar" class="w-full max-w-sm text-right">
+  <label id="progress-rtl-label" class="mb-2 flex items-center gap-3">
+    <span>تقدم الرفع</span>
+    <span class="ms-auto text-muted-foreground">٦٦%</span>
+  </label>
+
+  <ProgressBar [value]="66" aria-labelledby="progress-rtl-label" class="w-full rtl:rotate-180" />
+</section>
+```
+
+## API reference
+
+| Input             | Type             | Default |
+| ----------------- | ---------------- | ------- |
+| `value`           | `number \| null` | `0`     |
+| `max`             | `number`         | `100`   |
+| `indeterminate`   | `boolean`        | `false` |
+| `aria-label`      | `string \| null` | `null`  |
+| `aria-labelledby` | `string \| null` | `null`  |
+| `class`           | `string`         | `''`    |
+
+Native host attributes such as `id`, `dir`, and `data-*` still pass through to
+the rendered custom element and can be used for surrounding composition.
+
+## Styling and theming
+
+Tokens consumed:
+
+- `--secondary` for the track.
+- `--primary` for the indicator.
+
+Use the `class` input for width and layout utilities such as `w-full`,
+`max-w-sm`, or `rtl:rotate-180`. Indeterminate state is animated via a CSS
+keyframe that respects `prefers-reduced-motion`.
+
+## Accessibility
+
+- Host is `role="progressbar"`.
+- Determinate mode sets `aria-valuemin="0"`, `aria-valuemax="max"`, and
+  `aria-valuenow="clamped value"`.
+- Indeterminate mode omits `aria-valuenow` and adds `data-state="indeterminate"`.
+- Always provide an accessible name via `aria-label` or `aria-labelledby`.
+- If visible label text already exists on the page, connect it with
+  `aria-labelledby` instead of relying on native label semantics.
+
+## Keyboard interactions
+
+Progress is passive and not focusable by default. Any keyboard interaction
+belongs to surrounding controls such as the slider used in the controlled
+example.
+
+## Angular notes
+
+- Keep Progress focused on status display. Do not nest buttons or other
+  interactive controls inside the bar.
+- Drive determinate state from signals, reactive forms, or any other existing
+  Angular state source.
+- For visible label rows, `Label` is a good lightweight companion, but plain
+  text with the right ARIA wiring works too.
+
+## Source parity
+
+This Angular implementation follows the shadcn Radix progress examples while
+translating `Field` and `FieldLabel` to ordinary Angular markup plus explicit
+ARIA wiring. The controlled example reuses the existing range slider directive,
+and the RTL pattern matches the upstream `rtl:rotate-180` approach.

package/component/radio/README.md

@@ -0,0 +1,212 @@
+# Radio Group
+
+Accessible exclusive-choice control composed from `RadioGroup` and `Radio`.
+
+## Import
+
+```ts
+import {
+  FormContentComponent,
+  FormDescriptionComponent,
+  FormFieldComponent,
+  FormFieldsetComponent,
+  FormLegendComponent,
+  FormTitleComponent,
+} from '@ojiepermana/angular/component/form';
+import { LabelComponent } from '@ojiepermana/angular/component/label';
+import { RadioComponent, RadioGroupComponent } from '@ojiepermana/angular/component/radio';
+```
+
+## Composition
+
+The upstream shadcn `RadioGroup` examples map to the existing Angular radio and form primitives.
+
+```text
+RadioGroup
+├── label[Label]
+│   ├── Radio
+│   └── FormContent
+│       ├── FormTitle
+│       └── p[FormDescription]
+└── label[Label]
+    ├── Radio
+    └── copy or FormContent
+```
+
+## Basic Usage
+
+Use `RadioGroup` as the value owner and wrap each option in `label[Label]` when the whole row should toggle the radio.
+
+```html
+<RadioGroup name="density" [(ngModel)]="density" class="w-fit">
+  <label Label class="flex items-center gap-3">
+    <Radio value="default" />
+    <span>Default</span>
+  </label>
+  <label Label class="flex items-center gap-3">
+    <Radio value="comfortable" />
+    <span>Comfortable</span>
+  </label>
+  <label Label class="flex items-center gap-3">
+    <Radio value="compact" />
+    <span>Compact</span>
+  </label>
+</RadioGroup>
+```
+
+Reactive forms also work because the group implements `ControlValueAccessor`.
+
+## Common Patterns
+
+### Descriptive rows
+
+Map the shadcn `Field` and `FieldContent` helpers to `FormField` and `FormContent`.
+
+```html
+<RadioGroup name="density" [(ngModel)]="density" class="w-full max-w-md">
+  <label Label class="block rounded-xl border border-border bg-card/40 p-4">
+    <FormField orientation="horizontal" class="gap-4">
+      <Radio value="default" />
+      <FormContent>
+        <FormTitle>Default</FormTitle>
+        <p FormDescription>Standard spacing for most use cases.</p>
+      </FormContent>
+    </FormField>
+  </label>
+</RadioGroup>
+```
+
+### Choice cards
+
+Wrap each plan card in `label[Label]` so the full surface toggles the choice.
+
+```html
+<RadioGroup name="plan" [(ngModel)]="selectedPlan" class="w-full max-w-md">
+  <label Label class="block rounded-xl border border-border bg-card/40 p-4">
+    <FormField orientation="horizontal" class="items-start gap-4">
+      <FormContent>
+        <FormTitle>Pro</FormTitle>
+        <p FormDescription>For growing businesses.</p>
+      </FormContent>
+      <Radio value="pro" />
+    </FormField>
+  </label>
+</RadioGroup>
+```
+
+### Semantic fieldsets
+
+Use a real fieldset and legend when the radio list answers one grouped question.
+
+```html
+<fieldset FormFieldset class="max-w-md rounded-xl border border-border bg-card/40 p-5">
+  <legend FormLegend variant="label">Subscription plan</legend>
+  <p class="text-sm leading-6 text-muted-foreground">
+    Yearly and lifetime plans offer significant savings.
+  </p>
+
+  <RadioGroup name="subscription-plan" [(ngModel)]="subscriptionPlan" class="mt-4">
+    <label Label class="block rounded-lg border border-border/70 bg-background/80 p-3">
+      <FormField orientation="horizontal" class="gap-4">
+        <Radio value="monthly" />
+        <FormContent>
+          <FormTitle>Monthly ($9.99/month)</FormTitle>
+        </FormContent>
+      </FormField>
+    </label>
+  </RadioGroup>
+</fieldset>
+```
+
+### Validation and helper text
+
+Forward helper and error relationships from the group when the descriptive copy sits outside the individual items.
+
+```html
+<FormField invalid class="max-w-md rounded-xl border border-destructive/40 bg-destructive/5 p-5">
+  <FormTitle>Notification Preferences</FormTitle>
+  <p id="notification-help" class="text-sm leading-6 text-muted-foreground">
+    Choose how you want to receive notifications.
+  </p>
+
+  <RadioGroup
+    name="notification-preferences"
+    [(ngModel)]="notificationPreference"
+    aria-describedby="notification-help notification-error"
+    aria-invalid="true"
+  >
+    <label Label class="block rounded-lg border border-destructive/40 bg-background/80 p-3">
+      <FormField orientation="horizontal" class="gap-4">
+        <Radio value="email" />
+        <FormContent>
+          <FormTitle>Email only</FormTitle>
+        </FormContent>
+      </FormField>
+    </label>
+  </RadioGroup>
+
+  <p id="notification-error" class="text-sm font-medium text-destructive">
+    Select one delivery channel before saving notification settings.
+  </p>
+</FormField>
+```
+
+## API Reference
+
+### `RadioGroupComponent`
+
+| Input              | Type                                   | Default      | Notes                                                        |
+| ------------------ | -------------------------------------- | ------------ | ------------------------------------------------------------ |
+| `name`             | `string`                               | `''`         | Shared native `name` so the browser groups the radios.       |
+| `orientation`      | `'horizontal' \| 'vertical'`           | `'vertical'` | Switches between stacked rows and inline columns.            |
+| `aria-label`       | `string \| null`                       | `null`       | Use when the group needs an explicit accessible name.        |
+| `aria-labelledby`  | `string \| null`                       | `null`       | Alternative to `aria-label` for external group headings.     |
+| `aria-describedby` | `string \| null`                       | `null`       | Connects helper or error text outside the group.             |
+| `aria-invalid`     | `boolean \| 'true' \| 'false' \| null` | `null`       | Marks the group invalid for validation-driven presentations. |
+| `class`            | `string`                               | `''`         | Adds utility classes to the wrapped group host.              |
+
+| Output        | Payload  |
+| ------------- | -------- |
+| `valueChange` | `string` |
+
+Public method: `focus()`.
+
+### `RadioComponent`
+
+| Input      | Type      | Default |
+| ---------- | --------- | ------- |
+| `value`    | `string`  | —       |
+| `disabled` | `boolean` | `false` |
+| `class`    | `string`  | `''`    |
+
+## Styling and Theming
+
+The radio primitives render native radio inputs (no Material dependency) and restyle them through the shared theme tokens.
+
+- The selected dot uses the `primary` token.
+- Unselected outlines use the `input` token rather than current text color.
+- The group uses CSS grid; horizontal orientation flips to `grid-flow-col auto-cols-max`.
+- Card-style layouts and invalid treatments are best handled by surrounding `label[Label]` and `FormField` composition.
+
+## Accessibility
+
+- Use a real `fieldset` and `legend` when the radio list answers one grouped question.
+- Wrap each option in `label[Label]` when the whole row or card should toggle the control.
+- Use `aria-describedby` on `RadioGroup` to connect helper or error text rendered outside the option rows.
+- Use `aria-invalid` on `RadioGroup` when validation fails and the group should be announced as invalid.
+
+## Keyboard Interactions
+
+- `Tab` moves focus to the selected item or first enabled item in the group.
+- Arrow keys move between options using native radio-group behavior.
+- `Space` selects the focused option.
+
+## Angular Notes
+
+- `RadioGroup` owns the selected value and works with both `ngModel` and reactive forms.
+- `Radio` represents only the selectable item; visible copy usually lives beside it in a wrapper label or `FormContent` block.
+- The shadcn `Field` family maps to the existing `form` entrypoint rather than a separate radio-specific helper package.
+
+## Source Parity
+
+This Angular implementation follows the same high-value shadcn radio-group examples: descriptive rows, choice cards, semantic fieldsets, disabled states, invalid messaging, and RTL. The deliberate difference is the use of the existing `form` and `label` primitives instead of introducing a separate runtime `Field` API.