@egose/shadcn-theme-ng-tw 0.6.0 → 0.6.2

package/input-otp/README.md

@@ -61,7 +61,7 @@ import { HlmInputOtpModule } from '@egose/shadcn-theme-ng/input-otp';
 export class MyModule {}
 ```
 
-Exported from `src/public-api.ts`: `HlmInputOtp`, `HlmInputOtpGroup`, `HlmInputOtpSeparator`, `HlmInputOtpSlot`, `HlmInputOtpFakeCaret`, plus `HlmInputOtpImports` and `HlmInputOtpModule`.
+Exported from `src/public-api.ts`: `HlmInputOtp`, `HlmInputOtpControl`, `HlmInputOtpGroup`, `HlmInputOtpSeparator`, `HlmInputOtpSlot`, `HlmInputOtpFakeCaret`, plus `HlmInputOtpImports` and `HlmInputOtpModule`.
 
 ## Anatomy / Structure
 
@@ -88,6 +88,32 @@ Brain inputs on `brn-input-otp` (from `@spartan-ng/brain/input-otp`): `length` (
 
 ## API reference
 
+### `hlm-input-otp` — `HlmInputOtpControl`
+
+Use this component for native-input accessibility forwarding. It extends `BrnInputOtp` with
+a declarative input template and retains its inputs, outputs, CVA, paste and focus behavior.
+`HlmInputOtpImports` / `HlmInputOtpModule` include it; a separate brain import is unnecessary.
+Compose it with `HlmInputOtpSlot` (the raw brain slot's private injection token is not supported).
+
+- `[aria-describedby]` (`string | null`, default `null`) reaches the native input and merges
+  with enclosing Spartan field description IDs, deduplicated. Bind only IDs of mounted elements.
+- `required` (boolean-coerced, default `false`) exposes native `aria-required`. Add Angular
+  validators separately; native `aria-invalid` follows the bound form control.
+- `inputId` connects a normal `<label for>` to the one focusable native input.
+
+```html
+<label for="verification">Verification code</label>
+<hlm-input-otp [length]="4" inputId="verification" aria-describedby="verification-help" required>
+  <div hlmInputOtpGroup>
+    <hlm-input-otp-slot index="0" />
+    <hlm-input-otp-slot index="1" />
+    <hlm-input-otp-slot index="2" />
+    <hlm-input-otp-slot index="3" />
+  </div>
+</hlm-input-otp>
+<p id="verification-help">Enter the four-character code.</p>
+```
+
 ### `brn-input-otp[hlmInputOtp]` — `HlmInputOtp`
 
 Pure styling directive (`data-slot="input-otp"`, flex row, dims on `has-disabled`). No inputs/outputs — bind `length`, `value`, `disabled`, `inputId`, … on the `brn-input-otp` element itself.
@@ -102,7 +128,7 @@ Slot cluster wrapper (`data-slot="input-otp-group"`). No inputs/outputs. Use one
 | ------- | -------------------------------------------------- | -------------------------------------------------------- |
 | `index` | `number` (**required**, `numberAttribute` coerced) | Zero-based position of the character this slot displays. |
 
-Renders `<brn-input-otp-slot [index]>` internally; active slot gets the `ring` highlight, invalid state the destructive border.
+Under `brn-input-otp`, renders `<brn-input-otp-slot [index]>`; under `hlm-input-otp`, reads the adapter's public context and renders the same character/caret and state attributes declaratively. Active slots get the `ring` highlight.
 
 ### `hlm-input-otp-separator` — `HlmInputOtpSeparator`
 
@@ -267,17 +293,15 @@ export class LengthsExample {}
 
 ```ts
 import { Component, signal } from '@angular/core';
-import { BrnInputOtp } from '@spartan-ng/brain/input-otp';
 import { HlmInputOtpImports } from '@egose/shadcn-theme-ng/input-otp';
 import { HlmError } from '@egose/shadcn-theme-ng/form-field';
 
 @Component({
   standalone: true,
-  imports: [BrnInputOtp, HlmInputOtpImports, HlmError],
+  imports: [HlmInputOtpImports, HlmError],
   template: `
     <label for="otp-verify">Verification code</label>
-    <brn-input-otp
-      hlmInputOtp
+    <hlm-input-otp
       [length]="6"
       inputId="otp-verify"
       inputMode="numeric"
@@ -286,7 +310,7 @@ import { HlmError } from '@egose/shadcn-theme-ng/form-field';
       [value]="code()"
       (valueChange)="code.set($event); error.set(null)"
       (completed)="verify()"
-      aria-describedby="otp-error"
+      [aria-describedby]="error() ? 'otp-error' : null"
     >
       <div hlmInputOtpGroup>
         <hlm-input-otp-slot index="0" />
@@ -299,7 +323,7 @@ import { HlmError } from '@egose/shadcn-theme-ng/form-field';
         <hlm-input-otp-slot index="4" />
         <hlm-input-otp-slot index="5" />
       </div>
-    </brn-input-otp>
+    </hlm-input-otp>
     @if (error()) {
       <hlm-error id="otp-error">{{ error() }}</hlm-error>
     }
@@ -366,7 +390,7 @@ export class PasteExample {
 
 - Always render a visible `<label>` bound via `inputId` — the hidden native input is what AT focuses; without the label the purpose is unclear.
 - `inputMode="numeric"` (digits) vs `text` (alphanumeric) selects the right mobile keyboard; `inputAutocomplete="one-time-code"` lets browsers/OS autofill SMS codes.
-- Announce failures with a text error (`<hlm-error>` + `aria-describedby`), never by slot color alone.
+- Associate failures with text (`<hlm-error>` + `hlm-input-otp`'s `[aria-describedby]`), never by slot color alone. The legacy brain component has no native description input. `HlmError` is not a live region; browser DOM/focus tests do not establish screen-reader announcements.
 - Keep `length` aligned with what the backend expects and validate `minLength(length)` on the form control so incomplete codes cannot submit.
 
 ## Theming / CSS variables

package/input-otp/fesm2022/input-otp.mjs

@@ -1,9 +1,12 @@
 import * as i0 from '@angular/core';
-import { Directive, ChangeDetectionStrategy, Component, input, numberAttribute, NgModule } from '@angular/core';
+import { Directive, input, booleanAttribute, forwardRef, ChangeDetectionStrategy, Component, inject, computed, numberAttribute, NgModule } from '@angular/core';
 import { classes } from '@egose/shadcn-theme-ng-tw/utils';
+import { NG_VALUE_ACCESSOR } from '@angular/forms';
+import * as i1 from '@spartan-ng/brain/field';
+import { BrnFieldControlDescribedBy, provideBrnLabelable, BrnFieldControl } from '@spartan-ng/brain/field';
+import { BrnInputOtp, BrnInputOtpSlot } from '@spartan-ng/brain/input-otp';
 import { NgIcon, provideIcons } from '@ng-icons/core';
 import { lucideMinus } from '@ng-icons/lucide';
-import { BrnInputOtpSlot } from '@spartan-ng/brain/input-otp';
 
 class HlmInputOtp {
     constructor() {
@@ -20,6 +23,83 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
                 }]
         }], ctorParameters: () => [] });
 
+/**
+ * BrnInputOtp's CVA and editing behavior with declarative native-input ARIA forwarding.
+ * Use with HlmInputOtpSlot; the legacy brn-input-otp skin remains available.
+ */
+class HlmInputOtpControl extends BrnInputOtp {
+    /** Native input description IDs, merged with enclosing Spartan field descriptions. */
+    ariaDescribedBy = input(null, { ...(ngDevMode ? { debugName: "ariaDescribedBy" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
+    required = input(false, { ...(ngDevMode ? { debugName: "required" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
+    static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmInputOtpControl, deps: null, target: i0.ɵɵFactoryTarget.Component });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmInputOtpControl, isStandalone: true, selector: "hlm-input-otp", inputs: { ariaDescribedBy: { classPropertyName: "ariaDescribedBy", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null } }, providers: [
+            { provide: BrnInputOtp, useExisting: forwardRef(() => HlmInputOtpControl) },
+            { provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => HlmInputOtpControl), multi: true },
+            provideBrnLabelable(HlmInputOtpControl),
+        ], usesInheritance: true, hostDirectives: [{ directive: i1.BrnFieldControl }, { directive: HlmInputOtp }], ngImport: i0, template: `
+    <ng-content />
+    <div [style]="containerStyles()">
+      <input
+        #otpInput
+        data-slot="input-otp"
+        [id]="inputId()"
+        [class]="inputClass()"
+        [autocomplete]="inputAutocomplete()"
+        [style]="inputStyles()"
+        [disabled]="_disabled()"
+        [inputMode]="inputMode()"
+        [value]="value() ?? ''"
+        brnFieldControlDescribedBy
+        [aria-describedby]="ariaDescribedBy()"
+        [attr.aria-required]="required() || null"
+        [attr.aria-invalid]="invalid?.() ? 'true' : null"
+        (input)="onInputChange($event)"
+        (paste)="onPaste($event)"
+        (focus)="_focused.set(true)"
+        (blur)="onBlur()"
+      />
+    </div>
+  `, isInline: true, dependencies: [{ kind: "directive", type: BrnFieldControlDescribedBy, selector: "[brnFieldControlDescribedBy]", inputs: ["aria-describedby"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmInputOtpControl, decorators: [{
+            type: Component,
+            args: [{
+                    selector: 'hlm-input-otp',
+                    changeDetection: ChangeDetectionStrategy.OnPush,
+                    imports: [BrnFieldControlDescribedBy],
+                    hostDirectives: [BrnFieldControl, HlmInputOtp],
+                    providers: [
+                        { provide: BrnInputOtp, useExisting: forwardRef(() => HlmInputOtpControl) },
+                        { provide: NG_VALUE_ACCESSOR, useExisting: forwardRef(() => HlmInputOtpControl), multi: true },
+                        provideBrnLabelable(HlmInputOtpControl),
+                    ],
+                    template: `
+    <ng-content />
+    <div [style]="containerStyles()">
+      <input
+        #otpInput
+        data-slot="input-otp"
+        [id]="inputId()"
+        [class]="inputClass()"
+        [autocomplete]="inputAutocomplete()"
+        [style]="inputStyles()"
+        [disabled]="_disabled()"
+        [inputMode]="inputMode()"
+        [value]="value() ?? ''"
+        brnFieldControlDescribedBy
+        [aria-describedby]="ariaDescribedBy()"
+        [attr.aria-required]="required() || null"
+        [attr.aria-invalid]="invalid?.() ? 'true' : null"
+        (input)="onInputChange($event)"
+        (paste)="onPaste($event)"
+        (focus)="_focused.set(true)"
+        (blur)="onBlur()"
+      />
+    </div>
+  `,
+                }]
+        }], propDecorators: { ariaDescribedBy: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-describedby", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }] } });
+
 class HlmInputOtpFakeCaret {
     constructor() {
         classes(() => 'tw:pointer-events-none tw:absolute tw:inset-0 tw:flex tw:items-center tw:justify-center');
@@ -74,16 +154,34 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
         }], ctorParameters: () => [] });
 
 class HlmInputOtpSlot {
+    _control = inject(HlmInputOtpControl, { optional: true });
+    _slot = computed(() => this._control?.context()[this.index()], /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_slot" }] : /* istanbul ignore next */ []));
     /** The index of the slot to render the char or a fake caret */
     index = input.required({ ...(ngDevMode ? { debugName: "index" } : /* istanbul ignore next */ {}), transform: numberAttribute });
     constructor() {
-        classes(() => 'tw:dark:bg-input/30 tw:border-input tw:has-[brn-input-otp-slot[data-active="true"]]:border-ring tw:has-[brn-input-otp-slot[data-active="true"]]:ring-ring/50 tw:has-[brn-input-otp-slot[data-active="true"]]:data-[matches-spartan-invalid=true]:ring-destructive/20 tw:dark:has-[brn-input-otp-slot[data-active="true"]]:data-[matches-spartan-invalid=true]:ring-destructive/40 tw:data-[matches-spartan-invalid=true]:border-destructive tw:has-[brn-input-otp-slot[data-active="true"]]:data-[matches-spartan-invalid=true]:border-destructive tw:size-9 tw:border-y tw:border-e tw:text-sm tw:shadow-xs tw:transition-all tw:outline-none tw:first:rounded-s-md tw:first:border-s tw:last:rounded-e-md tw:has-[brn-input-otp-slot[data-active="true"]]:ring-3 tw:relative tw:flex tw:items-center tw:justify-center tw:has-[brn-input-otp-slot[data-active="true"]]:z-10');
+        classes(() => 'tw:dark:bg-input/30 tw:border-input tw:has-[[data-active="true"]]:border-ring tw:has-[[data-active="true"]]:ring-ring/50 tw:has-[[data-active="true"]]:data-[matches-spartan-invalid=true]:ring-destructive/20 tw:dark:has-[[data-active="true"]]:data-[matches-spartan-invalid=true]:ring-destructive/40 tw:data-[matches-spartan-invalid=true]:border-destructive tw:has-[[data-active="true"]]:data-[matches-spartan-invalid=true]:border-destructive tw:size-9 tw:border-y tw:border-e tw:text-sm tw:shadow-xs tw:transition-all tw:outline-none tw:first:rounded-s-md tw:first:border-s tw:last:rounded-e-md tw:has-[[data-active="true"]]:ring-3 tw:relative tw:flex tw:items-center tw:justify-center tw:has-[[data-active="true"]]:z-10');
     }
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmInputOtpSlot, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.1.0", version: "22.1.3", type: HlmInputOtpSlot, isStandalone: true, selector: "hlm-input-otp-slot", inputs: { index: { classPropertyName: "index", publicName: "index", isSignal: true, isRequired: true, transformFunction: null } }, host: { attributes: { "data-slot": "input-otp-slot" } }, ngImport: i0, template: `
-    <brn-input-otp-slot [index]="index()">
-      <hlm-input-otp-fake-caret />
-    </brn-input-otp-slot>
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: HlmInputOtpSlot, isStandalone: true, selector: "hlm-input-otp-slot", inputs: { index: { classPropertyName: "index", publicName: "index", isSignal: true, isRequired: true, transformFunction: null } }, host: { attributes: { "data-slot": "input-otp-slot" } }, ngImport: i0, template: `
+    @if (_control) {
+      <span
+        [attr.data-active]="_slot()?.isActive"
+        [attr.data-invalid]="_control.invalid?.() ? 'true' : null"
+        [attr.data-touched]="_control.touched?.() ? 'true' : null"
+        [attr.data-dirty]="_control.dirty?.() ? 'true' : null"
+        [attr.data-matches-spartan-invalid]="_control.spartanInvalid?.() ? 'true' : null"
+      >
+        {{ _slot()?.char }}
+        @if (_slot()?.hasFakeCaret) {
+          <hlm-input-otp-fake-caret />
+        }
+      </span>
+    } @else {
+      <brn-input-otp-slot [index]="index()">
+        <hlm-input-otp-fake-caret />
+      </brn-input-otp-slot>
+    }
   `, isInline: true, dependencies: [{ kind: "component", type: BrnInputOtpSlot, selector: "brn-input-otp-slot", inputs: ["index", "forceInvalid"] }, { kind: "component", type: HlmInputOtpFakeCaret, selector: "hlm-input-otp-fake-caret" }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmInputOtpSlot, decorators: [{
@@ -94,9 +192,24 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     host: { 'data-slot': 'input-otp-slot' },
                     template: `
-    <brn-input-otp-slot [index]="index()">
-      <hlm-input-otp-fake-caret />
-    </brn-input-otp-slot>
+    @if (_control) {
+      <span
+        [attr.data-active]="_slot()?.isActive"
+        [attr.data-invalid]="_control.invalid?.() ? 'true' : null"
+        [attr.data-touched]="_control.touched?.() ? 'true' : null"
+        [attr.data-dirty]="_control.dirty?.() ? 'true' : null"
+        [attr.data-matches-spartan-invalid]="_control.spartanInvalid?.() ? 'true' : null"
+      >
+        {{ _slot()?.char }}
+        @if (_slot()?.hasFakeCaret) {
+          <hlm-input-otp-fake-caret />
+        }
+      </span>
+    } @else {
+      <brn-input-otp-slot [index]="index()">
+        <hlm-input-otp-fake-caret />
+      </brn-input-otp-slot>
+    }
   `,
                 }]
         }], ctorParameters: () => [], propDecorators: { index: [{ type: i0.Input, args: [{ isSignal: true, alias: "index", required: true }] }] } });
@@ -106,6 +219,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
  */
 const HlmInputOtpImports = [
     HlmInputOtp,
+    HlmInputOtpControl,
     HlmInputOtpGroup,
     HlmInputOtpSeparator,
     HlmInputOtpSlot,
@@ -114,10 +228,12 @@ const HlmInputOtpImports = [
 class HlmInputOtpModule {
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: HlmInputOtpModule, deps: [], target: i0.ɵɵFactoryTarget.NgModule });
     static ɵmod = i0.ɵɵngDeclareNgModule({ minVersion: "14.0.0", version: "22.1.3", ngImport: i0, type: HlmInputOtpModule, imports: [HlmInputOtp,
+            HlmInputOtpControl,
             HlmInputOtpGroup,
             HlmInputOtpSeparator,
             HlmInputOtpSlot,
             HlmInputOtpFakeCaret], exports: [HlmInputOtp,
+            HlmInputOtpControl,
             HlmInputOtpGroup,
             HlmInputOtpSeparator,
             HlmInputOtpSlot,
@@ -137,5 +253,5 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
  * Generated bundle index. Do not edit.
  */
 
-export { HlmInputOtp, HlmInputOtpFakeCaret, HlmInputOtpGroup, HlmInputOtpImports, HlmInputOtpModule, HlmInputOtpSeparator, HlmInputOtpSlot };
+export { HlmInputOtp, HlmInputOtpControl, HlmInputOtpFakeCaret, HlmInputOtpGroup, HlmInputOtpImports, HlmInputOtpModule, HlmInputOtpSeparator, HlmInputOtpSlot };
 

package/input-otp/types/input-otp.d.ts

@@ -1,5 +1,7 @@
 import * as i0 from '@angular/core';
-import { NumberInput } from '@angular/cdk/coercion';
+import { BooleanInput, NumberInput } from '@angular/cdk/coercion';
+import { BrnInputOtp } from '@spartan-ng/brain/input-otp';
+import * as i1 from '@spartan-ng/brain/field';
 
 declare class HlmInputOtp {
     constructor();
@@ -7,6 +9,18 @@ declare class HlmInputOtp {
     static ɵdir: i0.ɵɵDirectiveDeclaration<HlmInputOtp, "brn-input-otp[hlmInputOtp], brn-input-otp[hlm]", never, {}, {}, never, never, true, never>;
 }
 
+/**
+ * BrnInputOtp's CVA and editing behavior with declarative native-input ARIA forwarding.
+ * Use with HlmInputOtpSlot; the legacy brn-input-otp skin remains available.
+ */
+declare class HlmInputOtpControl extends BrnInputOtp {
+    /** Native input description IDs, merged with enclosing Spartan field descriptions. */
+    readonly ariaDescribedBy: i0.InputSignal<string | null>;
+    readonly required: i0.InputSignalWithTransform<boolean, BooleanInput>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<HlmInputOtpControl, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<HlmInputOtpControl, "hlm-input-otp", never, { "ariaDescribedBy": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; }, {}, never, ["*"], true, [{ directive: typeof i1.BrnFieldControl; inputs: {}; outputs: {}; }, { directive: typeof HlmInputOtp; inputs: {}; outputs: {}; }]>;
+}
+
 declare class HlmInputOtpFakeCaret {
     constructor();
     static ɵfac: i0.ɵɵFactoryDeclaration<HlmInputOtpFakeCaret, never>;
@@ -26,6 +40,12 @@ declare class HlmInputOtpSeparator {
 }
 
 declare class HlmInputOtpSlot {
+    protected readonly _control: HlmInputOtpControl | null;
+    protected readonly _slot: i0.Signal<{
+        char: string | null;
+        isActive: boolean;
+        hasFakeCaret: boolean;
+    } | undefined>;
     /** The index of the slot to render the char or a fake caret */
     readonly index: i0.InputSignalWithTransform<number, NumberInput>;
     constructor();
@@ -33,11 +53,11 @@ declare class HlmInputOtpSlot {
     static ɵcmp: i0.ɵɵComponentDeclaration<HlmInputOtpSlot, "hlm-input-otp-slot", never, { "index": { "alias": "index"; "required": true; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
-declare const HlmInputOtpImports: readonly [typeof HlmInputOtp, typeof HlmInputOtpGroup, typeof HlmInputOtpSeparator, typeof HlmInputOtpSlot, typeof HlmInputOtpFakeCaret];
+declare const HlmInputOtpImports: readonly [typeof HlmInputOtp, typeof HlmInputOtpControl, typeof HlmInputOtpGroup, typeof HlmInputOtpSeparator, typeof HlmInputOtpSlot, typeof HlmInputOtpFakeCaret];
 declare class HlmInputOtpModule {
     static ɵfac: i0.ɵɵFactoryDeclaration<HlmInputOtpModule, never>;
-    static ɵmod: i0.ɵɵNgModuleDeclaration<HlmInputOtpModule, never, [typeof HlmInputOtp, typeof HlmInputOtpGroup, typeof HlmInputOtpSeparator, typeof HlmInputOtpSlot, typeof HlmInputOtpFakeCaret], [typeof HlmInputOtp, typeof HlmInputOtpGroup, typeof HlmInputOtpSeparator, typeof HlmInputOtpSlot, typeof HlmInputOtpFakeCaret]>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<HlmInputOtpModule, never, [typeof HlmInputOtp, typeof HlmInputOtpControl, typeof HlmInputOtpGroup, typeof HlmInputOtpSeparator, typeof HlmInputOtpSlot, typeof HlmInputOtpFakeCaret], [typeof HlmInputOtp, typeof HlmInputOtpControl, typeof HlmInputOtpGroup, typeof HlmInputOtpSeparator, typeof HlmInputOtpSlot, typeof HlmInputOtpFakeCaret]>;
     static ɵinj: i0.ɵɵInjectorDeclaration<HlmInputOtpModule>;
 }
 
-export { HlmInputOtp, HlmInputOtpFakeCaret, HlmInputOtpGroup, HlmInputOtpImports, HlmInputOtpModule, HlmInputOtpSeparator, HlmInputOtpSlot };
+export { HlmInputOtp, HlmInputOtpControl, HlmInputOtpFakeCaret, HlmInputOtpGroup, HlmInputOtpImports, HlmInputOtpModule, HlmInputOtpSeparator, HlmInputOtpSlot };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@egose/shadcn-theme-ng-tw",
-  "version": "0.6.0",
+  "version": "0.6.2",
   "description": "Angular shadcn UI theme",
   "author": "Junmin Ahn",
   "bundles": [

package/pagination/README.md

@@ -144,12 +144,21 @@ For the `tw:` build, swap the specifier to `@egose/shadcn-theme-ng-tw/pagination
 | `currentPage`  | **model (required)** | `number`                                     | Two-way: `[(currentPage)]`. Clicks set it; out-of-range values are auto-corrected via `outOfBoundCorrection` |
 | `itemsPerPage` | **model (required)** | `number`                                     | Two-way: `[(itemsPerPage)]`, bound to the page-size `hlm-select`                                             |
 | `totalItems`   | input (required)     | `number` (number coercion)                   | Server or client total; `0`/negative collapses to a single empty page                                        |
-| `maxSize`      | input                | `number`, default `7` (number coercion)      | Max page links in the window (ellipsis logic from `ngx-pagination`)                                          |
+| `maxSize`      | input                | `number`, default `7` (number coercion)      | Window entries including ellipses; floored and bounded to 1–100; invalid/non-positive uses 7                 |
 | `showEdges`    | input                | `boolean`, default `true` (boolean coercion) | Shows prev/next edge buttons (hidden on first/last page respectively)                                        |
 | `pageSizes`    | input                | `number[]`, default `[10, 20, 50, 100]`      | Page-size menu; the current size is merged in + sorted if missing                                            |
 
 Layout: `flex justify-between` row — left count summary (`<b>total</b> total items | <b>pages</b> pages`), center pager, right `hlm-select` page-size picker. Previous/next are plain click handlers (`goToPrevious/goToNext`); page links set `currentPage` directly without routing.
 
+#### Normalization and numeric limits (both numbered pagers)
+
+- Page count is `ceil(totalItems / itemsPerPage)`, at least 1 and at most `Number.MAX_SAFE_INTEGER`. Finite positive fractional totals/sizes retain that division behavior, including sizes below 1. Overflowing positive division saturates at the safe-integer page limit.
+- Empty, negative or non-finite totals use one page. Non-positive or non-finite sizes (`0`, negative, `NaN`, `Infinity`) also use one page, **without rewriting `itemsPerPage`**. Supply a finite positive size to resume paging. The models are numeric; template number attributes such as `totalItems` and `maxSize` are coerced by Angular.
+- Finite `currentPage` values are floored and clamped to `[1, lastPage]`; non-finite values become 1. Changes to totals, size or the external page are reconciled by an effect, emitting `currentPageChange` once per correction. Valid models emit nothing. Bind `[(currentPage)]` to receive corrections.
+- All derived signals, including the page list, are side-effect-free. Rendering uses the corrected page immediately. Previous/next disappear at their bounds, and direct client-state navigation handlers are also clamped. Empty results show active page 1 and neither edge.
+- `maxSize` / helper `paginationRange` is a window-entry budget, including ellipses. Finite positive values are floored and clamped to **1–100**; non-finite/non-positive values fall back to **7**. Ranges below 5 use a contiguous window containing the active page; larger ranges retain the first/last/ellipsis layout. Work and allocation are proportional to `min(pageCount, normalizedRange)`, never to an unbounded total or range. The array-returning helper API is unchanged.
+- The summary displays the supplied total; normalization controls page count/navigation and does not repair the application's data. For asynchronous server loading, keep the last known total until the new count arrives if a temporary zero should not reset the page.
+
 ### `HlmNumberedPaginationQueryParams` (`hlm-numbered-pagination-query-params`)
 
 Same models/inputs as `HlmNumberedPagination` **plus**:
@@ -160,11 +169,13 @@ Same models/inputs as `HlmNumberedPagination` **plus**:
 
 Every link (prev/numbered/next) navigates via `RouterLink` with `[queryParams]="{ page }"` and `queryParamsHandling="merge"`. The active page renders with `link === undefined` (no navigation) + `isActive`.
 
+The component **does not subscribe to the route or navigate on correction/size changes**. The parent reads `?page=` and supplies `currentPage`; link clicks navigate, then the parent's route subscription updates that model. Corrections emit `currentPageChange` but leave the URL unchanged. To canonicalize a corrected page in the URL, handle that output in the parent with `router.navigate([], { relativeTo: route, queryParams: { page }, queryParamsHandling: 'merge', replaceUrl: true })`. Keep unrelated parameters when doing so. Page-size URL persistence is also parent-owned.
+
 ### Helpers
 
 | Symbol                                                                    | Signature                                                 | Notes                                                                                                    |
 | ------------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
-| `outOfBoundCorrection(totalItems, itemsPerPage, currentPage)`             | `(number, number, number) => number`                      | Clamps to `[1, totalPages]` (from `ngx-pagination`)                                                      |
+| `outOfBoundCorrection(totalItems, itemsPerPage, currentPage)`             | `(number, number, number) => number`                      | Pure floor/clamp using the normalization policy above; empty/invalid paging returns 1                    |
 | `createPageArray(currentPage, itemsPerPage, totalItems, paginationRange)` | `(number, number, number, number) => (number \| '...')[]` | Window with `'...'` gaps; powers both numbered pagers                                                    |
 | `Page`                                                                    | `type Page = number \| '...'`                             | Not exported from public-api (internal to the pager file) — redeclare locally if you type custom windows |
 
@@ -246,7 +257,8 @@ export class PagerClientComponent {
 ### 3. Router `?page=` pager (server-driven)
 
 ```ts
-import { Component, signal, effect } from '@angular/core';
+import { Component, signal } from '@angular/core';
+import { takeUntilDestroyed } from '@angular/core/rxjs-interop';
 import { ActivatedRoute } from '@angular/router';
 import { HlmPaginationImports } from '@egose/shadcn-theme-ng/pagination';
 
@@ -261,7 +273,7 @@ import { HlmPaginationImports } from '@egose/shadcn-theme-ng/pagination';
       [totalItems]="total()"
       link="."
     />
-    <p class="tw:text-sm tw:text-muted-foreground">URL holds ?page={{ page }}.</p>
+    <p class="tw:text-sm tw:text-muted-foreground">Displayed page: {{ page() }}.</p>
   `,
 })
 export class PagerQueryComponent {
@@ -270,13 +282,10 @@ export class PagerQueryComponent {
   readonly total = signal(320);
 
   constructor(route: ActivatedRoute) {
-    effect(() => {
-      // keep ?page= as the source of truth on back/forward + deep links
-      const sub = route.queryParamMap.subscribe((params) => {
-        const p = Number(params.get('page') ?? 1);
-        this.page.set(Number.isFinite(p) && p >= 1 ? Math.floor(p) : 1);
-      });
-      return () => sub.unsubscribe();
+    // Read deep links and back/forward changes; the pager corrects model bounds.
+    // Corrections here update the displayed page, not the URL.
+    route.queryParamMap.pipe(takeUntilDestroyed()).subscribe((params) => {
+      this.page.set(Number(params.get('page') ?? 1));
     });
   }
 }
@@ -330,7 +339,7 @@ import { HlmPaginationImports, createPageArray } from '@egose/shadcn-theme-ng/pa
   template: `
     <nav hlmPagination>
       <ul hlmPaginationContent>
-        @for (p of window(); track p) {
+        @for (p of window(); track $index) {
           <li hlmPaginationItem>
             @if (p === '...') {
               <hlm-pagination-ellipsis />