@ojiepermana/angular 21.3.4 → 22.0.1

package/component/input-group/README.md

@@ -0,0 +1,239 @@
+# 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 `ui-input-group-addon` to place the addon at the inline or block edge.
+
+```html
+<ui-form-field>
+  <ui-form-label>Search</ui-form-label>
+  <ui-input-group>
+    <input ui-input-group-input uiFormControl placeholder="Search documentation..." />
+    <ui-input-group-addon>
+      <span aria-hidden="true">⌕</span>
+    </ui-input-group-addon>
+    <ui-input-group-addon align="inline-end">
+      <ui-input-group-text>12 results</ui-input-group-text>
+    </ui-input-group-addon>
+  </ui-input-group>
+  <ui-form-description
+    >Keep addons after the control in the DOM and use align for visual placement.</ui-form-description
+  >
+</ui-form-field>
+```
+
+## Composition
+
+```text
+ui-input-group
+├── input[ui-input-group-input] or textarea[ui-input-group-textarea]
+├── ui-input-group-addon
+│   ├── ui-input-group-text
+│   └── button[ui-input-group-button]
+└── ui-input-group-addon
+```
+
+## Common Patterns
+
+### Inline search
+
+```html
+<ui-input-group class="max-w-md">
+  <input ui-input-group-input placeholder="Search..." />
+  <ui-input-group-addon>
+    <span aria-hidden="true">⌕</span>
+  </ui-input-group-addon>
+  <ui-input-group-addon align="inline-end">
+    <ui-input-group-text>12 results</ui-input-group-text>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Text addons
+
+```html
+<ui-input-group>
+  <input ui-input-group-input placeholder="0.00" />
+  <ui-input-group-addon>
+    <ui-input-group-text>$</ui-input-group-text>
+  </ui-input-group-addon>
+  <ui-input-group-addon align="inline-end">
+    <ui-input-group-text>USD</ui-input-group-text>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Textarea footer
+
+```html
+<ui-input-group>
+  <textarea ui-input-group-textarea placeholder="Write a comment..."></textarea>
+  <ui-input-group-addon align="block-end">
+    <ui-input-group-text>0/280</ui-input-group-text>
+    <button ui-input-group-button type="button" size="sm" variant="default" class="ml-auto">Post</button>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Custom control
+
+```html
+<ui-input-group>
+  <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>
+  <ui-input-group-addon align="block-end">
+    <button ui-input-group-button type="button" variant="default" size="sm" class="ml-auto">Submit</button>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Keyboard shortcut badge
+
+```html
+<ui-input-group class="max-w-sm">
+  <input ui-input-group-input placeholder="Search..." />
+  <ui-input-group-addon>
+    <span aria-hidden="true">⌕</span>
+  </ui-input-group-addon>
+  <ui-input-group-addon 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>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+### Dropdown composition
+
+Use the local menu primitives when the grouped field needs scoped actions or search destinations.
+
+```html
+<ui-input-group>
+  <input ui-input-group-input placeholder="Enter file name" />
+  <ui-input-group-addon align="inline-end">
+    <button
+      ui-input-group-button
+      type="button"
+      size="icon-xs"
+      aria-label="Open file actions"
+      [uiMenuTrigger]="fileActionsMenu">
+      ⋯
+    </button>
+  </ui-input-group-addon>
+</ui-input-group>
+
+<ng-template uiMenuContent #fileActionsMenu="uiMenuContent">
+  <ui-menu-surface>
+    <ui-menu-label>File actions</ui-menu-label>
+    <button ui-menu-item type="button">Settings</button>
+    <button ui-menu-item type="button">Copy path</button>
+    <ui-menu-separator />
+    <button ui-menu-item type="button">Open location</button>
+  </ui-menu-surface>
+</ng-template>
+```
+
+### Spinner status row
+
+```html
+<ui-input-group>
+  <input ui-input-group-input placeholder="Saving changes..." />
+  <ui-input-group-addon align="inline-end">
+    <ui-input-group-text>Saving...</ui-input-group-text>
+    <span
+      aria-hidden="true"
+      class="inline-flex size-4 animate-spin rounded-full border-2 border-muted border-t-foreground"></span>
+  </ui-input-group-addon>
+</ui-input-group>
+```
+
+## 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
+
+- `ui-input-group` owns the shared border, focus ring, radius, and background surface.
+- `ui-input-group-addon` 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 `ui-form-label`, `ui-label`, or another accessible name source.
+- Give icon-only `ui-input-group-button` elements an `aria-label`.
+- Use `uiFormControl` inside `ui-form-field` 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
+
+- `ui-input-group-input` and `ui-input-group-textarea` 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 `ui-form-field`, `ui-form-label`, and `ui-form-description` 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/component/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
+ui-input-otp
+├── ui-input-otp-group
+│   ├── ui-input-otp-slot
+│   ├── ui-input-otp-slot
+│   └── ui-input-otp-slot
+├── ui-input-otp-separator
+└── ui-input-otp-group
+    ├── ui-input-otp-slot
+    ├── ui-input-otp-slot
+    └── ui-input-otp-slot
+```
+
+## 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
+<ui-form-field>
+  <ui-form-label>Verification code</ui-form-label>
+  <ui-input-otp [maxLength]="6" [pattern]="digitsPattern" [value]="code()" (valueChange)="code.set($event)">
+    <ui-input-otp-group>
+      <ui-input-otp-slot [index]="0" />
+      <ui-input-otp-slot [index]="1" />
+      <ui-input-otp-slot [index]="2" />
+      <ui-input-otp-slot [index]="3" />
+      <ui-input-otp-slot [index]="4" />
+      <ui-input-otp-slot [index]="5" />
+    </ui-input-otp-group>
+  </ui-input-otp>
+  <ui-form-description>Paste the code from your email or authenticator app.</ui-form-description>
+</ui-form-field>
+```
+
+## Common Patterns
+
+### Separator groups
+
+Split longer codes into smaller clusters when the verification flow benefits from visual chunking.
+
+```html
+<ui-input-otp [maxLength]="6" [pattern]="digitsPattern" [value]="code()" (valueChange)="code.set($event)">
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="0" />
+    <ui-input-otp-slot [index]="1" />
+  </ui-input-otp-group>
+  <ui-input-otp-separator />
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="2" />
+    <ui-input-otp-slot [index]="3" />
+  </ui-input-otp-group>
+  <ui-input-otp-separator />
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="4" />
+    <ui-input-otp-slot [index]="5" />
+  </ui-input-otp-group>
+</ui-input-otp>
+```
+
+### Reactive forms
+
+The root component implements `ControlValueAccessor` and also integrates directly with `ui-form-field`, so labels, descriptions, and invalid-state wiring work without `uiFormControl`.
+
+```ts
+readonly verificationForm = new FormGroup({
+  code: new FormControl('', {
+    nonNullable: true,
+    validators: [Validators.required, Validators.minLength(6)],
+  }),
+});
+```
+
+```html
+<ui-form-field>
+  <ui-form-label>Verification code</ui-form-label>
+  <ui-input-otp formControlName="code" [maxLength]="6" [pattern]="digitsPattern">
+    <ui-input-otp-group
+      class="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
+      <ui-input-otp-slot [index]="0" />
+      <ui-input-otp-slot [index]="1" />
+      <ui-input-otp-slot [index]="2" />
+    </ui-input-otp-group>
+    <ui-input-otp-separator class="mx-2" />
+    <ui-input-otp-group
+      class="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
+      <ui-input-otp-slot [index]="3" />
+      <ui-input-otp-slot [index]="4" />
+      <ui-input-otp-slot [index]="5" />
+    </ui-input-otp-group>
+  </ui-input-otp>
+  <ui-form-description>Enter the 6-digit code sent to m@example.com.</ui-form-description>
+  <ui-form-message />
+</ui-form-field>
+```
+
+### 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
+<ui-input-otp [maxLength]="6" [pattern]="digitsPattern" value="123456" disabled>
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="0" />
+    <ui-input-otp-slot [index]="1" />
+    <ui-input-otp-slot [index]="2" />
+  </ui-input-otp-group>
+  <ui-input-otp-separator />
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="3" />
+    <ui-input-otp-slot [index]="4" />
+    <ui-input-otp-slot [index]="5" />
+  </ui-input-otp-group>
+</ui-input-otp>
+```
+
+```html
+<ui-input-otp
+  aria-invalid="true"
+  [maxLength]="6"
+  [pattern]="digitsPattern"
+  [value]="invalidCode()"
+  (valueChange)="invalidCode.set($event)">
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="0" />
+    <ui-input-otp-slot [index]="1" />
+    <ui-input-otp-slot [index]="2" />
+  </ui-input-otp-group>
+  <ui-input-otp-separator />
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="3" />
+    <ui-input-otp-slot [index]="4" />
+    <ui-input-otp-slot [index]="5" />
+  </ui-input-otp-group>
+</ui-input-otp>
+```
+
+### Four digits and alphanumeric codes
+
+Use `REGEXP_ONLY_DIGITS` for numeric OTPs and `REGEXP_ONLY_DIGITS_AND_CHARS` for mixed recovery codes.
+
+```html
+<ui-input-otp [maxLength]="4" [pattern]="digitsPattern" [inputmode]="'numeric'">
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="0" />
+    <ui-input-otp-slot [index]="1" />
+    <ui-input-otp-slot [index]="2" />
+    <ui-input-otp-slot [index]="3" />
+  </ui-input-otp-group>
+</ui-input-otp>
+```
+
+```html
+<ui-input-otp [maxLength]="6" [pattern]="digitsAndCharsPattern" [inputmode]="'text'">
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="0" />
+    <ui-input-otp-slot [index]="1" />
+    <ui-input-otp-slot [index]="2" />
+  </ui-input-otp-group>
+  <ui-input-otp-separator />
+  <ui-input-otp-group>
+    <ui-input-otp-slot [index]="3" />
+    <ui-input-otp-slot [index]="4" />
+    <ui-input-otp-slot [index]="5" />
+  </ui-input-otp-group>
+</ui-input-otp>
+```
+
+## 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`     | `ui-input-otp-group`     | Groups adjacent slots into one bordered cluster.              |
+| `InputOtpSlotComponent`      | `ui-input-otp-slot`      | Requires an `index` and renders the focusable character slot. |
+| `InputOtpSeparatorComponent` | `ui-input-otp-separator` | 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 `ui-input-otp-group` when a layout needs taller or wider cells, for example:
+
+```html
+<ui-input-otp-group
+  class="*:data-[slot=input-otp-slot]:h-12 *:data-[slot=input-otp-slot]:w-11 *:data-[slot=input-otp-slot]:text-xl">
+  ...
+</ui-input-otp-group>
+```
+
+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.
+- `ui-form-field` 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 `uiFormControl`; 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.

package/component/input-otp/package.json

@@ -0,0 +1,4 @@
+{
+  "module": "../../fesm2022/ojiepermana-angular-component-input-otp.mjs",
+  "typings": "../../types/ojiepermana-angular-component-input-otp.d.ts"
+}