@ojiepermana/angular-component 22.0.27

package/input-group/README.md

@@ -0,0 +1,237 @@
+# Input Group
+
+Grouped input primitives for prefixes, suffixes, stacked helper rows, and inline actions.
+
+Use Input Group when the field and its addon content should read as a single control boundary instead of separate neighboring elements.
+
+## Import
+
+```ts
+import {
+  FormControlDirective,
+  FormDescriptionComponent,
+  FormFieldComponent,
+  FormLabelComponent,
+} from '@ojiepermana/angular-component/form';
+import {
+  InputGroupAddonComponent,
+  InputGroupButtonComponent,
+  InputGroupComponent,
+  InputGroupInputComponent,
+  InputGroupTextComponent,
+  InputGroupTextareaComponent,
+} from '@ojiepermana/angular-component/input-group';
+```
+
+## Usage
+
+Keep the input or textarea first in the DOM, then append one or more addons after it.
+Use the `align` input on `InputGroupAddon` to place the addon at the inline or block edge.
+
+```html
+<FormField>
+  <FormLabel>Search</FormLabel>
+  <InputGroup>
+    <input InputGroupInput FormControl placeholder="Search documentation..." />
+    <InputGroupAddon>
+      <span aria-hidden="true">⌕</span>
+    </InputGroupAddon>
+    <InputGroupAddon align="inline-end">
+      <InputGroupText>12 results</InputGroupText>
+    </InputGroupAddon>
+  </InputGroup>
+  <FormDescription>Keep addons after the control in the DOM and use align for visual placement.</FormDescription>
+</FormField>
+```
+
+## Composition
+
+```text
+InputGroup
+├── input[InputGroupInput] or textarea[InputGroupTextarea]
+├── InputGroupAddon
+│   ├── InputGroupText
+│   └── button[InputGroupButton]
+└── InputGroupAddon
+```
+
+## Common Patterns
+
+### Inline search
+
+```html
+<InputGroup class="max-w-md">
+  <input InputGroupInput placeholder="Search..." />
+  <InputGroupAddon>
+    <span aria-hidden="true">⌕</span>
+  </InputGroupAddon>
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>12 results</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Text addons
+
+```html
+<InputGroup>
+  <input InputGroupInput placeholder="0.00" />
+  <InputGroupAddon>
+    <InputGroupText>$</InputGroupText>
+  </InputGroupAddon>
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>USD</InputGroupText>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Textarea footer
+
+```html
+<InputGroup>
+  <textarea InputGroupTextarea placeholder="Write a comment..."></textarea>
+  <InputGroupAddon align="block-end">
+    <InputGroupText>0/280</InputGroupText>
+    <button InputGroupButton type="button" size="sm" variant="default" class="ml-auto">Post</button>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Custom control
+
+```html
+<InputGroup>
+  <textarea
+    data-slot="input-group-control"
+    class="min-h-20 w-full resize-none bg-transparent px-3 py-2.5 text-sm outline-none placeholder:text-muted-foreground"
+    placeholder="Use any custom control that matches the group contract..."></textarea>
+  <InputGroupAddon align="block-end">
+    <button InputGroupButton type="button" variant="default" size="sm" class="ml-auto">Submit</button>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Keyboard shortcut badge
+
+```html
+<InputGroup class="max-w-sm">
+  <input InputGroupInput placeholder="Search..." />
+  <InputGroupAddon>
+    <span aria-hidden="true">⌕</span>
+  </InputGroupAddon>
+  <InputGroupAddon align="inline-end">
+    <span
+      aria-hidden="true"
+      class="inline-flex h-6 items-center rounded-md border border-border bg-background px-2 font-mono text-[11px] font-medium text-foreground shadow-sm">
+      ⌘K
+    </span>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+### Dropdown composition
+
+Use the local menu primitives when the grouped field needs scoped actions or search destinations.
+
+```html
+<InputGroup>
+  <input InputGroupInput placeholder="Enter file name" />
+  <InputGroupAddon align="inline-end">
+    <button
+      InputGroupButton
+      type="button"
+      size="icon-xs"
+      aria-label="Open file actions"
+      [MenuTrigger]="fileActionsMenu">
+      ⋯
+    </button>
+  </InputGroupAddon>
+</InputGroup>
+
+<ng-template MenuContent #fileActionsMenu="MenuContent">
+  <MenuSurface>
+    <MenuLabel>File actions</MenuLabel>
+    <button MenuItem type="button">Settings</button>
+    <button MenuItem type="button">Copy path</button>
+    <MenuSeparator />
+    <button MenuItem type="button">Open location</button>
+  </MenuSurface>
+</ng-template>
+```
+
+### Spinner status row
+
+```html
+<InputGroup>
+  <input InputGroupInput placeholder="Saving changes..." />
+  <InputGroupAddon align="inline-end">
+    <InputGroupText>Saving...</InputGroupText>
+    <span
+      aria-hidden="true"
+      class="inline-flex size-4 animate-spin rounded-full border-2 border-muted border-t-foreground"></span>
+  </InputGroupAddon>
+</InputGroup>
+```
+
+## API Reference
+
+### `InputGroupComponent`
+
+| Input   | Type     | Default      |
+| ------- | -------- | ------------ |
+| `class` | `string` | empty string |
+
+### `InputGroupAddonComponent`
+
+| Input   | Type                                                          | Default          |
+| ------- | ------------------------------------------------------------- | ---------------- |
+| `align` | `'inline-start', 'inline-end', 'block-start', or 'block-end'` | `'inline-start'` |
+| `class` | `string`                                                      | empty string     |
+
+### `InputGroupButtonComponent`
+
+| Input     | Type                                  | Default      |
+| --------- | ------------------------------------- | ------------ |
+| `variant` | `ButtonVariant`                       | `'ghost'`    |
+| `size`    | `'xs', 'icon-xs', 'sm', or 'icon-sm'` | `'xs'`       |
+| `class`   | `string`                              | empty string |
+
+### `InputGroupInputComponent` and `InputGroupTextareaComponent`
+
+| Input   | Type     | Default      |
+| ------- | -------- | ------------ |
+| `class` | `string` | empty string |
+
+All other native input and textarea attributes pass through unchanged.
+
+## Styling And Theming
+
+- `InputGroup` owns the shared border, focus ring, radius, and background surface.
+- `InputGroupAddon` uses logical separators so start and end alignments still read correctly in RTL layouts.
+- Override `--radius` on the group root when the grouped field should be sharper or more pill-shaped.
+- Add spacing or typography utilities through `class` on any primitive without breaking the core layout contract.
+
+## Accessibility
+
+- Keep the input or textarea before addons in the DOM so tab order and assistive reading order stay predictable.
+- Provide a visible label with `FormLabel`, `Label`, or another accessible name source.
+- Give icon-only `InputGroupButton` elements an `aria-label`.
+- Use `FormControl` inside `FormField` when labels, descriptions, and invalid messaging should auto-wire to the grouped control.
+
+## Keyboard Interactions
+
+- Text input and textarea editing remain native.
+- Buttons inside addons participate in the normal tab sequence after the text control.
+- Changing `align` only affects visual placement; it does not change keyboard order.
+
+## Angular Notes
+
+- `InputGroupInput` and `InputGroupTextarea` are attribute selectors on native controls, so native input and textarea behavior remains intact.
+- For custom controls, set `data-slot="input-group-control"` and provide your own spacing utilities so the wrapper can still coordinate focus and addon layout.
+- Upstream shadcn `Field` examples map to the local `FormField`, `FormLabel`, and `FormDescription` primitives rather than a separate `field` runtime component.
+
+## Source Parity
+
+This Angular implementation covers the core shadcn Input Group primitives, all four addon alignments, textarea support, custom control guidance, and RTL composition.
+
+Keyboard shortcut badges, dropdown triggers, and spinner/status rows are composed from the same primitives plus the local menu surface and inline status markup instead of requiring input-group-specific wrappers.

package/input-otp/README.md

@@ -0,0 +1,278 @@
+# Input OTP
+
+Accessible one-time password input with grouped slots, copy-paste distribution, roving focus, signal-friendly control, and reactive-form support.
+
+Use Input OTP for verification codes, step-up authentication, banking PIN entry, and short recovery codes where each character should be visually separated without losing keyboard or paste ergonomics.
+
+## Import
+
+```ts
+import {
+  InputOtpComponent,
+  InputOtpGroupComponent,
+  InputOtpSeparatorComponent,
+  InputOtpSlotComponent,
+  REGEXP_ONLY_DIGITS,
+  REGEXP_ONLY_DIGITS_AND_CHARS,
+} from '@ojiepermana/angular-component/input-otp';
+```
+
+When the code input belongs to a richer field layout, pair it with the existing form primitives:
+
+```ts
+import {
+  FormDescriptionComponent,
+  FormFieldComponent,
+  FormLabelComponent,
+  FormMessageComponent,
+} from '@ojiepermana/angular-component/form';
+```
+
+## Composition
+
+The Angular structure follows the shadcn Input OTP information architecture while translating it to standalone selectors.
+
+```text
+InputOtp
+├── InputOtpGroup
+│   ├── InputOtpSlot
+│   ├── InputOtpSlot
+│   └── InputOtpSlot
+├── InputOtpSeparator
+└── InputOtpGroup
+    ├── InputOtpSlot
+    ├── InputOtpSlot
+    └── InputOtpSlot
+```
+
+## Basic Usage
+
+Use the root component for value flow and the projected parts for layout.
+
+```ts
+protected readonly code = signal('');
+protected readonly digitsPattern = REGEXP_ONLY_DIGITS;
+```
+
+```html
+<FormField>
+  <FormLabel>Verification code</FormLabel>
+  <InputOtp [maxLength]="6" [pattern]="digitsPattern" [value]="code()" (valueChange)="code.set($event)">
+    <InputOtpGroup>
+      <InputOtpSlot [index]="0" />
+      <InputOtpSlot [index]="1" />
+      <InputOtpSlot [index]="2" />
+      <InputOtpSlot [index]="3" />
+      <InputOtpSlot [index]="4" />
+      <InputOtpSlot [index]="5" />
+    </InputOtpGroup>
+  </InputOtp>
+  <FormDescription>Paste the code from your email or authenticator app.</FormDescription>
+</FormField>
+```
+
+## Common Patterns
+
+### Separator groups
+
+Split longer codes into smaller clusters when the verification flow benefits from visual chunking.
+
+```html
+<InputOtp [maxLength]="6" [pattern]="digitsPattern" [value]="code()" (valueChange)="code.set($event)">
+  <InputOtpGroup>
+    <InputOtpSlot [index]="0" />
+    <InputOtpSlot [index]="1" />
+  </InputOtpGroup>
+  <InputOtpSeparator />
+  <InputOtpGroup>
+    <InputOtpSlot [index]="2" />
+    <InputOtpSlot [index]="3" />
+  </InputOtpGroup>
+  <InputOtpSeparator />
+  <InputOtpGroup>
+    <InputOtpSlot [index]="4" />
+    <InputOtpSlot [index]="5" />
+  </InputOtpGroup>
+</InputOtp>
+```
+
+### Reactive forms
+
+The root component implements `ControlValueAccessor` and also integrates directly with `FormField`, so labels, descriptions, and invalid-state wiring work without `FormControl`.
+
+```ts
+readonly verificationForm = new FormGroup({
+  code: new FormControl('', {
+    nonNullable: true,
+    validators: [Validators.required, Validators.minLength(6)],
+  }),
+});
+```
+
+```html
+<FormField>
+  <FormLabel>Verification code</FormLabel>
+  <InputOtp formControlName="code" [maxLength]="6" [pattern]="digitsPattern">
+    <InputOtpGroup
+      class="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
+      <InputOtpSlot [index]="0" />
+      <InputOtpSlot [index]="1" />
+      <InputOtpSlot [index]="2" />
+    </InputOtpGroup>
+    <InputOtpSeparator class="mx-2" />
+    <InputOtpGroup
+      class="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
+      <InputOtpSlot [index]="3" />
+      <InputOtpSlot [index]="4" />
+      <InputOtpSlot [index]="5" />
+    </InputOtpGroup>
+  </InputOtp>
+  <FormDescription>Enter the 6-digit code sent to m@example.com.</FormDescription>
+  <FormMessage />
+</FormField>
+```
+
+### Disabled and invalid states
+
+Use the native `disabled` input when the code should remain visible but unavailable, and forward `aria-invalid="true"` when an expired or rejected code needs the destructive treatment.
+
+```html
+<InputOtp [maxLength]="6" [pattern]="digitsPattern" value="123456" disabled>
+  <InputOtpGroup>
+    <InputOtpSlot [index]="0" />
+    <InputOtpSlot [index]="1" />
+    <InputOtpSlot [index]="2" />
+  </InputOtpGroup>
+  <InputOtpSeparator />
+  <InputOtpGroup>
+    <InputOtpSlot [index]="3" />
+    <InputOtpSlot [index]="4" />
+    <InputOtpSlot [index]="5" />
+  </InputOtpGroup>
+</InputOtp>
+```
+
+```html
+<InputOtp
+  aria-invalid="true"
+  [maxLength]="6"
+  [pattern]="digitsPattern"
+  [value]="invalidCode()"
+  (valueChange)="invalidCode.set($event)">
+  <InputOtpGroup>
+    <InputOtpSlot [index]="0" />
+    <InputOtpSlot [index]="1" />
+    <InputOtpSlot [index]="2" />
+  </InputOtpGroup>
+  <InputOtpSeparator />
+  <InputOtpGroup>
+    <InputOtpSlot [index]="3" />
+    <InputOtpSlot [index]="4" />
+    <InputOtpSlot [index]="5" />
+  </InputOtpGroup>
+</InputOtp>
+```
+
+### Four digits and alphanumeric codes
+
+Use `REGEXP_ONLY_DIGITS` for numeric OTPs and `REGEXP_ONLY_DIGITS_AND_CHARS` for mixed recovery codes.
+
+```html
+<InputOtp [maxLength]="4" [pattern]="digitsPattern" [inputmode]="'numeric'">
+  <InputOtpGroup>
+    <InputOtpSlot [index]="0" />
+    <InputOtpSlot [index]="1" />
+    <InputOtpSlot [index]="2" />
+    <InputOtpSlot [index]="3" />
+  </InputOtpGroup>
+</InputOtp>
+```
+
+```html
+<InputOtp [maxLength]="6" [pattern]="digitsAndCharsPattern" [inputmode]="'text'">
+  <InputOtpGroup>
+    <InputOtpSlot [index]="0" />
+    <InputOtpSlot [index]="1" />
+    <InputOtpSlot [index]="2" />
+  </InputOtpGroup>
+  <InputOtpSeparator />
+  <InputOtpGroup>
+    <InputOtpSlot [index]="3" />
+    <InputOtpSlot [index]="4" />
+    <InputOtpSlot [index]="5" />
+  </InputOtpGroup>
+</InputOtp>
+```
+
+## API Reference
+
+### `InputOtpComponent`
+
+| Input              | Type                       | Default           |
+| ------------------ | -------------------------- | ----------------- |
+| `maxLength`        | `number`                   | `6`               |
+| `value`            | `string`                   | `undefined`       |
+| `pattern`          | `RegExp \| string \| null` | `null`            |
+| `required`         | `boolean`                  | `false`           |
+| `disabled`         | `boolean`                  | `false`           |
+| `inputmode`        | `string \| null`           | `'numeric'`       |
+| `autocomplete`     | `string \| null`           | `'one-time-code'` |
+| `aria-label`       | `string \| null`           | `null`            |
+| `aria-labelledby`  | `string \| null`           | `null`            |
+| `aria-describedby` | `string \| null`           | `null`            |
+| `class`            | `string`                   | `''`              |
+
+### Output
+
+| Output        | Type     |
+| ------------- | -------- |
+| `valueChange` | `string` |
+
+### Parts
+
+| Part                         | Selector            | Notes                                                         |
+| ---------------------------- | ------------------- | ------------------------------------------------------------- |
+| `InputOtpGroupComponent`     | `InputOtpGroup`     | Groups adjacent slots into one bordered cluster.              |
+| `InputOtpSlotComponent`      | `InputOtpSlot`      | Requires an `index` and renders the focusable character slot. |
+| `InputOtpSeparatorComponent` | `InputOtpSeparator` | Inserts an optional visual separator between groups.          |
+
+Convenience exports: `REGEXP_ONLY_DIGITS` and `REGEXP_ONLY_DIGITS_AND_CHARS`.
+
+## Styling and Theming
+
+The component exposes shadcn-style `data-slot` hooks on the root, group, separator, and slot hosts. Use `*:data-[slot=input-otp-slot]` utilities on `InputOtpGroup` when a layout needs taller or wider cells, for example:
+
+```html
+<InputOtpGroup
+  class="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
+  ...
+</InputOtpGroup>
+```
+
+The default styles use the shared border, ring, destructive, foreground, and muted-foreground tokens from the library theme.
+
+## Accessibility
+
+- Each slot is a real input with an accessible name that includes its position in the sequence.
+- `FormField` labels and descriptions wire to the component automatically when the OTP lives inside the field wrapper.
+- `aria-invalid="true"` on the root forwards the destructive treatment across the slot set.
+- Keep the surrounding label and helper text descriptive. Users should understand where the code came from and how many characters are expected.
+
+## Keyboard Interactions
+
+- Typing a character replaces the current slot and advances focus.
+- Paste distributes accepted characters from the current slot onward.
+- Arrow keys move across slots and flip direction under RTL layouts.
+- `Backspace` removes the current or previous slot and shifts the remaining value left.
+- `Delete` removes the current slot and shifts the remaining value left.
+
+## Angular Notes
+
+- Use `[value]` plus `(valueChange)` for signal-backed local state.
+- Use `formControlName`, `[formControl]`, or `[(ngModel)]` for form-driven flows.
+- There is no separate `defaultValue` input; seed the initial code with the bound signal or form control value.
+- Unlike native inputs, this component does not need `FormControl`; it integrates with the form-field context directly.
+
+## Source Parity
+
+This Angular slice keeps the shadcn composition, grouped separators, pattern filtering, paste handling, and verification-form examples. The deliberate Angular deviation is the runtime implementation: each slot is a visible input coordinated by the root CVA instead of the upstream single hidden-input package. Browser one-time-code autofill works best through the first slot with the default `autocomplete="one-time-code"` behavior.