@egose/shadcn-theme-ng 0.6.0 → 0.6.2

package/form-toggle/fesm2022/form-toggle.mjs

@@ -53,6 +53,8 @@ class EgFormToggle {
     ...(ngDevMode ? [{ debugName: "autoError" }] : /* istanbul ignore next */ []));
     hint = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "hint" }] : /* istanbul ignore next */ []));
+    /** Consumer-owned description IDs, merged with the displayed error or hint on the button. */
+    ariaDescribedBy = input(null, { ...(ngDevMode ? { debugName: "ariaDescribedBy" } : /* istanbul ignore next */ {}), alias: 'aria-describedby' });
     id = input(undefined, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "id" }] : /* istanbul ignore next */ []));
     disabled = input(false, { ...(ngDevMode ? { debugName: "disabled" } : /* istanbul ignore next */ {}), transform: booleanAttribute });
@@ -78,12 +80,14 @@ class EgFormToggle {
     ...(ngDevMode ? [{ debugName: "_status" }] : /* istanbul ignore next */ []));
     _submitted = signal(false, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "_submitted" }] : /* istanbul ignore next */ []));
+    _interacted = signal(false, /* @ts-ignore */
+    ...(ngDevMode ? [{ debugName: "_interacted" }] : /* istanbul ignore next */ []));
     /**
      * Displayed message: explicit `error()` wins; otherwise (when `autoError()`)
      * auto-resolved from the control's `ValidationErrors`. Plain method (not a
      * computed): `ValidationErrors` is not a signal, so the control must be read
      * fresh on every change-detection pass (`showError()` re-evaluates with it
-     * via the `_status`/`_submitted` signals).
+     * via the `_status`/`_submitted`/`_interacted` signals).
      */
     resolvedError() {
         const explicit = this.error();
@@ -96,20 +100,26 @@ class EgFormToggle {
     showError = computed(() => {
         this._status();
         this._submitted();
+        this._interacted();
         const control = this._controlDir?.control;
-        return (!!this.resolvedError() &&
-            !!control?.errors &&
-            (control.touched || control.dirty || !!this._formGroupDirective?.submitted));
+        return !!this.resolvedError() && !!control?.errors && (this._interacted() || this._submitted());
     }, /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "showError" }] : /* istanbul ignore next */ []));
     showHint = computed(() => !this.showError() && !!this.hint(), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "showHint" }] : /* istanbul ignore next */ []));
+    describedBy() {
+        const ids = [this.ariaDescribedBy(), this.showError() ? this.errorId() : this.showHint() ? this.hintId() : null];
+        return [...new Set(ids.filter(Boolean).join(' ').split(/\s+/).filter(Boolean))].join(' ') || null;
+    }
     _onChange;
     _onTouched;
     ngDoCheck() {
         const submitted = !!this._formGroupDirective?.submitted;
         if (this._submitted() !== submitted)
             this._submitted.set(submitted);
+        // Keep silent interaction updates (emitEvent: false) visible on the next check too.
+        const control = this._controlDir?.control;
+        this._interacted.set(!!control && (control.touched || control.dirty));
     }
     ngAfterViewInit() {
         // Resolved here (not earlier): this component IS the value accessor for
@@ -119,8 +129,11 @@ class EgFormToggle {
         this._controlDir = this._injector.get(FormControlName, null, { self: true, optional: true }) ?? null;
         const control = this._controlDir?.control;
         this._status.set(control?.status ?? null);
-        control?.statusChanges.pipe(takeUntilDestroyed(this._destroyRef)).subscribe((status) => {
-            this._status.set(status);
+        this._interacted.set(!!control && (control.touched || control.dirty));
+        // Touch/dirty/reset events must invalidate feedback even when status stays INVALID.
+        control?.events.pipe(takeUntilDestroyed(this._destroyRef)).subscribe(() => {
+            this._status.set(control.status);
+            this._interacted.set(control.touched || control.dirty);
         });
     }
     _handleStateChange(state) {
@@ -167,7 +180,7 @@ class EgFormToggle {
     $hintClass = computed(() => hlm("mt-0", this._shared.hintClass, this._config.hintClass, this.hintClass()), /* @ts-ignore */
     ...(ngDevMode ? [{ debugName: "$hintClass" }] : /* istanbul ignore next */ []));
     static ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: EgFormToggle, deps: [], target: i0.ɵɵFactoryTarget.Component });
-    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: EgFormToggle, isStandalone: true, selector: "eg-form-toggle", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, controlId: { classPropertyName: "controlId", publicName: "controlId", isSignal: true, isRequired: false, transformFunction: null }, error: { classPropertyName: "error", publicName: "error", isSignal: true, isRequired: false, transformFunction: null }, autoError: { classPropertyName: "autoError", publicName: "autoError", isSignal: true, isRequired: false, transformFunction: null }, hint: { classPropertyName: "hint", publicName: "hint", isSignal: true, isRequired: false, transformFunction: null }, id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, toggleClass: { classPropertyName: "toggleClass", publicName: "toggleClass", isSignal: true, isRequired: false, transformFunction: null }, labelClass: { classPropertyName: "labelClass", publicName: "labelClass", isSignal: true, isRequired: false, transformFunction: null }, errorClass: { classPropertyName: "errorClass", publicName: "errorClass", isSignal: true, isRequired: false, transformFunction: null }, hintClass: { classPropertyName: "hintClass", publicName: "hintClass", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class": "$userClass()" } }, providers: [EG_FORM_TOGGLE_VALUE_ACCESSOR, provideIcons({ lucideCheck })], ngImport: i0, template: "\n    @let lbl = label();\n    @let rqrd = required();\n\n    <div>\n      <div class=\"flex items-center gap-1\">\n        <button\n          hlmToggle\n          type=\"button\"\n          [id]=\"effectiveId()\"\n          [state]=\"_state() ? 'on' : 'off'\"\n          (stateChange)=\"_handleStateChange($event)\"\n          [disabled]=\"_disabled()\"\n          [variant]=\"variant()\"\n          [size]=\"size()\"\n          [class]=\"$toggleClass()\"\n        >\n          @if (_state()) {\n            <ng-icon name=\"lucideCheck\" />\n          }\n        </button>\n        @if (lbl) {\n          <label hlmLabel [for]=\"effectiveId()\" [class]=\"$labelClass()\"\n            >{{ lbl }}\n            @if (rqrd) {\n              <span class=\"text-red-500\">*</span>\n            }\n          </label>\n        }\n      </div>\n\n      @if (showError()) {\n        <hlm-error [id]=\"errorId()\" [class]=\"$errorClass()\">\n          {{ resolvedError() }}\n        </hlm-error>\n      } @else if (showHint()) {\n        <hlm-hint [id]=\"hintId()\" [class]=\"$hintClass()\">\n          {{ hint() }}\n        </hlm-hint>\n      }\n    </div>\n  ", isInline: true, dependencies: [{ kind: "directive", type: HlmToggle, selector: "button[hlmToggle]", inputs: ["variant", "size"] }, { kind: "directive", type: HlmError, selector: "hlm-error", inputs: ["class"] }, { kind: "directive", type: HlmHint, selector: "hlm-hint", inputs: ["class"] }, { kind: "directive", type: HlmLabel, selector: "[hlmLabel]", inputs: ["class"] }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
+    static ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "17.0.0", version: "22.1.3", type: EgFormToggle, isStandalone: true, selector: "eg-form-toggle", inputs: { label: { classPropertyName: "label", publicName: "label", isSignal: true, isRequired: false, transformFunction: null }, controlId: { classPropertyName: "controlId", publicName: "controlId", isSignal: true, isRequired: false, transformFunction: null }, error: { classPropertyName: "error", publicName: "error", isSignal: true, isRequired: false, transformFunction: null }, autoError: { classPropertyName: "autoError", publicName: "autoError", isSignal: true, isRequired: false, transformFunction: null }, hint: { classPropertyName: "hint", publicName: "hint", isSignal: true, isRequired: false, transformFunction: null }, ariaDescribedBy: { classPropertyName: "ariaDescribedBy", publicName: "aria-describedby", isSignal: true, isRequired: false, transformFunction: null }, id: { classPropertyName: "id", publicName: "id", isSignal: true, isRequired: false, transformFunction: null }, disabled: { classPropertyName: "disabled", publicName: "disabled", isSignal: true, isRequired: false, transformFunction: null }, required: { classPropertyName: "required", publicName: "required", isSignal: true, isRequired: false, transformFunction: null }, variant: { classPropertyName: "variant", publicName: "variant", isSignal: true, isRequired: false, transformFunction: null }, size: { classPropertyName: "size", publicName: "size", isSignal: true, isRequired: false, transformFunction: null }, userClass: { classPropertyName: "userClass", publicName: "class", isSignal: true, isRequired: false, transformFunction: null }, toggleClass: { classPropertyName: "toggleClass", publicName: "toggleClass", isSignal: true, isRequired: false, transformFunction: null }, labelClass: { classPropertyName: "labelClass", publicName: "labelClass", isSignal: true, isRequired: false, transformFunction: null }, errorClass: { classPropertyName: "errorClass", publicName: "errorClass", isSignal: true, isRequired: false, transformFunction: null }, hintClass: { classPropertyName: "hintClass", publicName: "hintClass", isSignal: true, isRequired: false, transformFunction: null } }, host: { properties: { "class": "$userClass()" } }, providers: [EG_FORM_TOGGLE_VALUE_ACCESSOR, provideIcons({ lucideCheck })], ngImport: i0, template: "\n    @let lbl = label();\n    @let rqrd = required();\n\n    <div>\n      <div class=\"flex items-center gap-1\">\n        <button\n          hlmToggle\n          type=\"button\"\n          [id]=\"effectiveId()\"\n          [attr.aria-describedby]=\"describedBy()\"\n          [attr.aria-invalid]=\"showError() ? 'true' : null\"\n          [state]=\"_state() ? 'on' : 'off'\"\n          (stateChange)=\"_handleStateChange($event)\"\n          [disabled]=\"_disabled()\"\n          [variant]=\"variant()\"\n          [size]=\"size()\"\n          [class]=\"$toggleClass()\"\n        >\n          @if (_state()) {\n            <ng-icon name=\"lucideCheck\" />\n          }\n        </button>\n        @if (lbl) {\n          <label hlmLabel [for]=\"effectiveId()\" [class]=\"$labelClass()\"\n            >{{ lbl }}\n            @if (rqrd) {\n              <span class=\"text-red-500\">*</span>\n            }\n          </label>\n        }\n      </div>\n\n      @if (showError()) {\n        <hlm-error [id]=\"errorId()\" [class]=\"$errorClass()\">\n          {{ resolvedError() }}\n        </hlm-error>\n      } @else if (showHint()) {\n        <hlm-hint [id]=\"hintId()\" [class]=\"$hintClass()\">\n          {{ hint() }}\n        </hlm-hint>\n      }\n    </div>\n  ", isInline: true, dependencies: [{ kind: "directive", type: HlmToggle, selector: "button[hlmToggle]", inputs: ["variant", "size"] }, { kind: "directive", type: HlmError, selector: "hlm-error", inputs: ["class"] }, { kind: "directive", type: HlmHint, selector: "hlm-hint", inputs: ["class"] }, { kind: "directive", type: HlmLabel, selector: "[hlmLabel]", inputs: ["class"] }, { kind: "component", type: NgIcon, selector: "ng-icon", inputs: ["name", "svg", "size", "strokeWidth", "color"] }], changeDetection: i0.ChangeDetectionStrategy.OnPush });
 }
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImport: i0, type: EgFormToggle, decorators: [{
             type: Component,
@@ -180,9 +193,9 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "22.1.3", ngImpor
                     changeDetection: ChangeDetectionStrategy.OnPush,
                     imports: [HlmToggle, HlmError, HlmHint, HlmLabel, NgIcon],
                     providers: [EG_FORM_TOGGLE_VALUE_ACCESSOR, provideIcons({ lucideCheck })],
-                    template: "\n    @let lbl = label();\n    @let rqrd = required();\n\n    <div>\n      <div class=\"flex items-center gap-1\">\n        <button\n          hlmToggle\n          type=\"button\"\n          [id]=\"effectiveId()\"\n          [state]=\"_state() ? 'on' : 'off'\"\n          (stateChange)=\"_handleStateChange($event)\"\n          [disabled]=\"_disabled()\"\n          [variant]=\"variant()\"\n          [size]=\"size()\"\n          [class]=\"$toggleClass()\"\n        >\n          @if (_state()) {\n            <ng-icon name=\"lucideCheck\" />\n          }\n        </button>\n        @if (lbl) {\n          <label hlmLabel [for]=\"effectiveId()\" [class]=\"$labelClass()\"\n            >{{ lbl }}\n            @if (rqrd) {\n              <span class=\"text-red-500\">*</span>\n            }\n          </label>\n        }\n      </div>\n\n      @if (showError()) {\n        <hlm-error [id]=\"errorId()\" [class]=\"$errorClass()\">\n          {{ resolvedError() }}\n        </hlm-error>\n      } @else if (showHint()) {\n        <hlm-hint [id]=\"hintId()\" [class]=\"$hintClass()\">\n          {{ hint() }}\n        </hlm-hint>\n      }\n    </div>\n  ",
+                    template: "\n    @let lbl = label();\n    @let rqrd = required();\n\n    <div>\n      <div class=\"flex items-center gap-1\">\n        <button\n          hlmToggle\n          type=\"button\"\n          [id]=\"effectiveId()\"\n          [attr.aria-describedby]=\"describedBy()\"\n          [attr.aria-invalid]=\"showError() ? 'true' : null\"\n          [state]=\"_state() ? 'on' : 'off'\"\n          (stateChange)=\"_handleStateChange($event)\"\n          [disabled]=\"_disabled()\"\n          [variant]=\"variant()\"\n          [size]=\"size()\"\n          [class]=\"$toggleClass()\"\n        >\n          @if (_state()) {\n            <ng-icon name=\"lucideCheck\" />\n          }\n        </button>\n        @if (lbl) {\n          <label hlmLabel [for]=\"effectiveId()\" [class]=\"$labelClass()\"\n            >{{ lbl }}\n            @if (rqrd) {\n              <span class=\"text-red-500\">*</span>\n            }\n          </label>\n        }\n      </div>\n\n      @if (showError()) {\n        <hlm-error [id]=\"errorId()\" [class]=\"$errorClass()\">\n          {{ resolvedError() }}\n        </hlm-error>\n      } @else if (showHint()) {\n        <hlm-hint [id]=\"hintId()\" [class]=\"$hintClass()\">\n          {{ hint() }}\n        </hlm-hint>\n      }\n    </div>\n  ",
                 }]
-        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], controlId: [{ type: i0.Input, args: [{ isSignal: true, alias: "controlId", required: false }] }], error: [{ type: i0.Input, args: [{ isSignal: true, alias: "error", required: false }] }], autoError: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoError", required: false }] }], hint: [{ type: i0.Input, args: [{ isSignal: true, alias: "hint", required: false }] }], id: [{ type: i0.Input, args: [{ isSignal: true, alias: "id", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], toggleClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "toggleClass", required: false }] }], labelClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "labelClass", required: false }] }], errorClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "errorClass", required: false }] }], hintClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "hintClass", required: false }] }] } });
+        }], propDecorators: { label: [{ type: i0.Input, args: [{ isSignal: true, alias: "label", required: false }] }], controlId: [{ type: i0.Input, args: [{ isSignal: true, alias: "controlId", required: false }] }], error: [{ type: i0.Input, args: [{ isSignal: true, alias: "error", required: false }] }], autoError: [{ type: i0.Input, args: [{ isSignal: true, alias: "autoError", required: false }] }], hint: [{ type: i0.Input, args: [{ isSignal: true, alias: "hint", required: false }] }], ariaDescribedBy: [{ type: i0.Input, args: [{ isSignal: true, alias: "aria-describedby", required: false }] }], id: [{ type: i0.Input, args: [{ isSignal: true, alias: "id", required: false }] }], disabled: [{ type: i0.Input, args: [{ isSignal: true, alias: "disabled", required: false }] }], required: [{ type: i0.Input, args: [{ isSignal: true, alias: "required", required: false }] }], variant: [{ type: i0.Input, args: [{ isSignal: true, alias: "variant", required: false }] }], size: [{ type: i0.Input, args: [{ isSignal: true, alias: "size", required: false }] }], userClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "class", required: false }] }], toggleClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "toggleClass", required: false }] }], labelClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "labelClass", required: false }] }], errorClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "errorClass", required: false }] }], hintClass: [{ type: i0.Input, args: [{ isSignal: true, alias: "hintClass", required: false }] }] } });
 
 /*
  * Public API Surface of form-toggle

package/form-toggle/types/form-toggle.d.ts

@@ -36,6 +36,8 @@ declare class EgFormToggle implements ControlValueAccessor, AfterViewInit, DoChe
      */
     autoError: _angular_core.InputSignal<boolean>;
     hint: _angular_core.InputSignal<string | undefined>;
+    /** Consumer-owned description IDs, merged with the displayed error or hint on the button. */
+    ariaDescribedBy: _angular_core.InputSignal<string | null>;
     id: _angular_core.InputSignal<string | undefined>;
     disabled: _angular_core.InputSignalWithTransform<boolean, BooleanInput>;
     required: _angular_core.InputSignal<boolean>;
@@ -49,16 +51,18 @@ declare class EgFormToggle implements ControlValueAccessor, AfterViewInit, DoChe
     protected readonly _disabled: _angular_core.Signal<boolean>;
     private readonly _status;
     private readonly _submitted;
+    private readonly _interacted;
     /**
      * Displayed message: explicit `error()` wins; otherwise (when `autoError()`)
      * auto-resolved from the control's `ValidationErrors`. Plain method (not a
      * computed): `ValidationErrors` is not a signal, so the control must be read
      * fresh on every change-detection pass (`showError()` re-evaluates with it
-     * via the `_status`/`_submitted` signals).
+     * via the `_status`/`_submitted`/`_interacted` signals).
      */
     protected resolvedError(): string | undefined;
     protected readonly showError: _angular_core.Signal<boolean>;
     protected readonly showHint: _angular_core.Signal<boolean>;
+    protected describedBy(): string | null;
     protected _onChange?: ChangeFn<boolean>;
     protected _onTouched?: TouchFn;
     ngDoCheck(): void;
@@ -80,7 +84,7 @@ declare class EgFormToggle implements ControlValueAccessor, AfterViewInit, DoChe
     $errorClass: _angular_core.Signal<string>;
     $hintClass: _angular_core.Signal<string>;
     static ɵfac: _angular_core.ɵɵFactoryDeclaration<EgFormToggle, never>;
-    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EgFormToggle, "eg-form-toggle", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "controlId": { "alias": "controlId"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "autoError": { "alias": "autoError"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "toggleClass": { "alias": "toggleClass"; "required": false; "isSignal": true; }; "labelClass": { "alias": "labelClass"; "required": false; "isSignal": true; }; "errorClass": { "alias": "errorClass"; "required": false; "isSignal": true; }; "hintClass": { "alias": "hintClass"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
+    static ɵcmp: _angular_core.ɵɵComponentDeclaration<EgFormToggle, "eg-form-toggle", never, { "label": { "alias": "label"; "required": false; "isSignal": true; }; "controlId": { "alias": "controlId"; "required": false; "isSignal": true; }; "error": { "alias": "error"; "required": false; "isSignal": true; }; "autoError": { "alias": "autoError"; "required": false; "isSignal": true; }; "hint": { "alias": "hint"; "required": false; "isSignal": true; }; "ariaDescribedBy": { "alias": "aria-describedby"; "required": false; "isSignal": true; }; "id": { "alias": "id"; "required": false; "isSignal": true; }; "disabled": { "alias": "disabled"; "required": false; "isSignal": true; }; "required": { "alias": "required"; "required": false; "isSignal": true; }; "variant": { "alias": "variant"; "required": false; "isSignal": true; }; "size": { "alias": "size"; "required": false; "isSignal": true; }; "userClass": { "alias": "class"; "required": false; "isSignal": true; }; "toggleClass": { "alias": "toggleClass"; "required": false; "isSignal": true; }; "labelClass": { "alias": "labelClass"; "required": false; "isSignal": true; }; "errorClass": { "alias": "errorClass"; "required": false; "isSignal": true; }; "hintClass": { "alias": "hintClass"; "required": false; "isSignal": true; }; }, {}, never, never, true, never>;
 }
 
 interface EgFormToggleConfig {

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/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(() => "pointer-events-none absolute inset-0 flex items-center 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(() => "dark:bg-input/30 border-input has-[brn-input-otp-slot[data-active=\"true\"]]:border-ring has-[brn-input-otp-slot[data-active=\"true\"]]:ring-ring/50 has-[brn-input-otp-slot[data-active=\"true\"]]:data-[matches-spartan-invalid=true]:ring-destructive/20 dark:has-[brn-input-otp-slot[data-active=\"true\"]]:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive has-[brn-input-otp-slot[data-active=\"true\"]]:data-[matches-spartan-invalid=true]:border-destructive size-9 border-y border-e text-sm shadow-xs transition-all outline-none first:rounded-s-md first:border-s last:rounded-e-md has-[brn-input-otp-slot[data-active=\"true\"]]:ring-3 relative flex items-center justify-center has-[brn-input-otp-slot[data-active=\"true\"]]:z-10");
+        classes(() => "dark:bg-input/30 border-input has-[[data-active=\"true\"]]:border-ring has-[[data-active=\"true\"]]:ring-ring/50 has-[[data-active=\"true\"]]:data-[matches-spartan-invalid=true]:ring-destructive/20 dark:has-[[data-active=\"true\"]]:data-[matches-spartan-invalid=true]:ring-destructive/40 data-[matches-spartan-invalid=true]:border-destructive has-[[data-active=\"true\"]]:data-[matches-spartan-invalid=true]:border-destructive size-9 border-y border-e text-sm shadow-xs transition-all outline-none first:rounded-s-md first:border-s last:rounded-e-md has-[[data-active=\"true\"]]:ring-3 relative flex items-center justify-center 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",
-  "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 />