@forgeroute/ui 0.4.56 → 0.4.57

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@forgeroute/ui",
-  "version": "0.4.56",
+  "version": "0.4.57",
   "peerDependencies": {
     "@angular/common": ">=22.0.0",
     "@angular/core": ">=22.0.0",

package/types/forgeroute-ui.d.ts

@@ -1049,6 +1049,11 @@ export declare function isoKey(p: {
 export declare function parseTime(value: string | null | undefined): number | null;
 /** "9:00 AM" / "12:30 PM" from an `HH:mm` value (returned unchanged when it cannot be parsed; '' for null/undefined/non-strings). */
 export declare function formatTime(value: string | null | undefined): string;
+/**
+ * Joins a control's own `aria-describedby` ids with the ids a host passes through `[ariaDescribedBy]` (space separated, own ids first,
+ * duplicates dropped). Returns null when there is nothing to point at, so the attribute is absent.
+ */
+export declare function mergeDescribedBy(own: string | null | undefined, external: string | null | undefined): string | null;
 /**
  * One choice. `V` defaults to `string`, so existing `SelectOption[]` code is unchanged; `ui-select` itself accepts
  * `SelectOption<string | number>[]` (numeric values for `valueType="number"`).
@@ -1085,6 +1090,8 @@ export declare class SelectComponent implements ControlValueAccessor, Validator,
   readonly valueType: import("@angular/core").InputSignal<"string" | "number">;
   readonly required: import("@angular/core").InputSignal<boolean>;
   readonly hint: import("@angular/core").InputSignal<string>;
+  /** Id(s) of an external element that also describes this control (e.g. one shared error text for a group of fields). Space separated; MERGED after the control's own hint / error id in `aria-describedby`, never replacing it. Empty = unchanged. */
+  readonly ariaDescribedBy: import("@angular/core").InputSignal<string>;
   readonly error: import("@angular/core").InputSignal<string>;
   /** Reveal the built-in error messages now (e.g. after a failed Save click), without waiting for blur. */
   readonly showErrors: import("@angular/core").InputSignal<boolean>;
@@ -1098,7 +1105,7 @@ export declare class SelectComponent implements ControlValueAccessor, Validator,
   /** The selected option's `description` ('' when none is selected or it has none); hidden while an error shows. */
   protected readonly _selectedDescription: import("@angular/core").Signal<string>;
   /** ids of the texts that describe the select: the error / hint, then the selected option's description. */
-  protected readonly _describedBy: import("@angular/core").Signal<string>;
+  protected readonly _describedBy: import("@angular/core").Signal<string | null>;
   private readonly _reveal;
   private readonly _issue;
   /** True while the value breaks a built-in rule or the host passed an `[error]`. */
@@ -1170,6 +1177,11 @@ export declare class SelectComponent implements ControlValueAccessor, Validator,
       "required": false;
       "isSignal": true;
     };
+    "ariaDescribedBy": {
+      "alias": "ariaDescribedBy";
+      "required": false;
+      "isSignal": true;
+    };
     "error": {
       "alias": "error";
       "required": false;
@@ -2258,12 +2270,28 @@ export declare class ModalComponent implements OnInit, OnDestroy {
    * (e.g. while a save is running; the host closes it itself). Default `true` = today's behaviour.
    */
   readonly closable: import("@angular/core").InputSignal<boolean>;
+  /**
+   * Look of the dialog. `'default'` (today's dialog; a bottom sheet on a phone) or `'kiosk'`: a darker backdrop and a centred card on every screen
+   * size that never grows past the visible viewport (header and footer stay, the body scrolls, 100dvh with a 100vh fallback). Meant for full-attention
+   * dialogs such as a payment or bank-account entry; combine with `[closeOnBackdrop]="false"` and `[busy]`. See docs/modal-kiosk-and-bank-account-form.md.
+   */
+  readonly layout: import("@angular/core").InputSignal<"default" | "kiosk">;
+  /** `false` = a click on the backdrop does not close (a mis-click must not lose a half-filled payment form). Default `true`. */
+  readonly closeOnBackdrop: import("@angular/core").InputSignal<boolean>;
+  /** `false` = Escape does not close. Default `true`. */
+  readonly closeOnEscape: import("@angular/core").InputSignal<boolean>;
+  /**
+   * `true` while a request is running (e.g. a payment is processing): sets `aria-busy` on the dialog, disables the X button and blocks Escape and
+   * backdrop dismissal, whatever `closable` / `closeOnEscape` / `closeOnBackdrop` say. Default `false`.
+   */
+  readonly busy: import("@angular/core").InputSignal<boolean>;
   readonly close: import("@angular/core").OutputEmitterRef<void>;
   /**
    * Element that gets focus back when the dialog closes. Takes precedence over the element that was focused (or last
    * clicked / activated) when it opened; used only if it is still in the page and visible. Default null = the opener.
    */
   readonly returnFocusTo: import("@angular/core").InputSignal<HTMLElement | null>;
+  protected readonly kiosk: import("@angular/core").Signal<boolean>;
   protected readonly titleId: string;
   private readonly el;
   private readonly ren;
@@ -2276,6 +2304,8 @@ export declare class ModalComponent implements OnInit, OnDestroy {
   private readonly _interaction;
   constructor();
   onKeydown(event: KeyboardEvent): void;
+  /** Emits `close` when the dialog may be dismissed this way (not closable / busy / backdrop or Escape switched off = nothing). */
+  protected dismiss(via: 'backdrop' | 'escape' | 'close'): void;
   /** A focus-guard sentinel received focus (Tab left the dialog's tab order, e.g. out of an iframe): send it back inside. */
   protected onGuardFocus(which: 'start' | 'end', event?: FocusEvent): void;
   /** Initial focus — see `focusInitial` (autofocus target → first usable field → dialog container). */
@@ -2325,6 +2355,26 @@ export declare class ModalComponent implements OnInit, OnDestroy {
       "required": false;
       "isSignal": true;
     };
+    "layout": {
+      "alias": "layout";
+      "required": false;
+      "isSignal": true;
+    };
+    "closeOnBackdrop": {
+      "alias": "closeOnBackdrop";
+      "required": false;
+      "isSignal": true;
+    };
+    "closeOnEscape": {
+      "alias": "closeOnEscape";
+      "required": false;
+      "isSignal": true;
+    };
+    "busy": {
+      "alias": "busy";
+      "required": false;
+      "isSignal": true;
+    };
     "returnFocusTo": {
       "alias": "returnFocusTo";
       "required": false;
@@ -2332,7 +2382,7 @@ export declare class ModalComponent implements OnInit, OnDestroy {
     };
   }, {
     "close": "close";
-  }, never, ["*", "[modal-footer-left]", "[modal-footer-center]", "[modal-footer-right]"], true, never>;
+  }, never, ["[modal-header-end]", "*", "[modal-footer-left]", "[modal-footer-center]", "[modal-footer-right]"], true, never>;
 }
 export type ToastType = 'success' | 'error' | 'info';
 export declare class ToastService implements OnDestroy {
@@ -4598,6 +4648,130 @@ export declare class OptionCardComponent {
     "action": "action";
   }, never, ["*"], true, never>;
 }
+/** Default ACH debit authorization text (same wording the contractor bank-account kiosk used). */
+export declare const DEFAULT_BANK_MANDATE_TEXT: string;
+export type BankAccountType = 'checking' | 'savings';
+export type BankHolderType = 'individual' | 'company';
+/** What `(submitted)` emits: every text value trimmed, `mandateAccepted` always `true`. */
+export interface BankAccountFormValue {
+  routingNumber: string;
+  accountNumber: string;
+  accountType: BankAccountType;
+  accountHolderName: string;
+  holderType: BankHolderType;
+  mandateAccepted: true;
+}
+export declare const DEFAULT_BANK_ACCOUNT_TYPE_OPTIONS: SelectOption[];
+export declare const DEFAULT_BANK_HOLDER_TYPE_OPTIONS: SelectOption[];
+/**
+ * `ui-bank-account-form` - the US bank-account entry form (routing number, account number + confirmation, account type, holder name + type,
+ * ACH debit authorization). Built only from library inputs; it holds NO HTTP and no provider logic: the host listens to `(submitted)` and talks to
+ * its payment provider (Stripe `confirmUsBankAccountSetup`, Square, ...). See docs/modal-kiosk-and-bank-account-form.md.
+ *
+ * - Validation is inline through the inputs' own `[error]` / built-in rules. The routing number is only checked for 9 digits (no ABA checksum: the
+ *   provider validates the real number, and a client checksum would reject test numbers). Account numbers are 4-17 digits.
+ * - Messages show after blur, while a field holds something invalid, or while `[showErrors]` is true; a failed `submit()` reveals them all.
+ * - The form provides `UiFieldValidity` (`invalid` = not submittable), so a host can gate its own button with `viewChildren(UiFieldValidity)`,
+ *   or use `(validChange)`.
+ * - The host's footer button calls `form.submit()` (via `viewChild`); Enter in a text field submits too.
+ */
+export declare class BankAccountFormComponent implements UiFieldValidity {
+  /** Reveal every built-in error now (e.g. bind to a panel's `touched()`); `submit()` on an invalid form also reveals them. */
+  readonly showErrors: import("@angular/core").InputSignal<boolean>;
+  /** Disables every field and blocks `submit()`. */
+  readonly disabled: import("@angular/core").InputSignal<boolean>;
+  /** Like `disabled`, plus `aria-busy` on the host: a provider call is running. */
+  readonly busy: import("@angular/core").InputSignal<boolean>;
+  /** The authorization text next to the checkbox (it is the checkbox label). The unticked default is never changed by the form. */
+  readonly mandateText: import("@angular/core").InputSignal<string>;
+  /** Account type choices; values must stay `checking` / `savings`. */
+  readonly accountTypeOptions: import("@angular/core").InputSignal<SelectOption<string>[]>;
+  /** Holder type choices; values must stay `individual` / `company`. */
+  readonly holderTypeOptions: import("@angular/core").InputSignal<SelectOption<string>[]>;
+  /** Pre-fills the account holder name (e.g. the customer's name) whenever it changes; the user can edit it. */
+  readonly accountHolderNameDefault: import("@angular/core").InputSignal<string>;
+  /** Prefix of the inner test ids: `<prefix>-routing`, `-account`, `-confirm`, `-holder-name`, `-account-type`, `-holder-type`, `-mandate`. */
+  readonly testIdPrefix: import("@angular/core").InputSignal<string>;
+  /** Emits the typed payload when `submit()` runs on a valid form. */
+  readonly submitted: import("@angular/core").OutputEmitterRef<BankAccountFormValue>;
+  /** Emits `true` / `false` whenever the form becomes submittable / not (also once on init). */
+  readonly validChange: import("@angular/core").OutputEmitterRef<boolean>;
+  protected readonly routingNumber: import("@angular/core").WritableSignal<string>;
+  protected readonly accountNumber: import("@angular/core").WritableSignal<string>;
+  protected readonly confirmAccount: import("@angular/core").WritableSignal<string>;
+  protected readonly accountHolderName: import("@angular/core").WritableSignal<string>;
+  protected readonly accountType: import("@angular/core").WritableSignal<string>;
+  protected readonly holderType: import("@angular/core").WritableSignal<string>;
+  protected readonly mandateAccepted: import("@angular/core").WritableSignal<boolean>;
+  private readonly _touched;
+  protected readonly routingFormatter: (raw: string) => string;
+  protected readonly accountFormatter: (raw: string) => string;
+  protected readonly locked: import("@angular/core").Signal<boolean>;
+  protected readonly reveal: import("@angular/core").Signal<boolean>;
+  protected readonly routingError: import("@angular/core").Signal<"" | "Routing number must be 9 digits.">;
+  protected readonly accountError: import("@angular/core").Signal<"" | "Account number must be at least 4 digits.">;
+  protected readonly confirmError: import("@angular/core").Signal<"" | "Account numbers do not match.">;
+  /** First reason the form cannot be submitted ('' when it can). */
+  readonly errorMessage: import("@angular/core").Signal<"" | "Account holder name is required." | "Routing number is required." | "Routing number must be 9 digits." | "Account number is required." | "Account number must be at least 4 digits." | "Confirm account number is required." | "Account numbers do not match." | "Select a valid account type." | "Select a valid holder type." | "You must authorize ACH debits to continue.">;
+  /** True while the form cannot be submitted (`UiFieldValidity`). */
+  readonly invalid: import("@angular/core").Signal<boolean>;
+  /** True when the form can be submitted (ignores `disabled` / `busy`). */
+  readonly valid: import("@angular/core").Signal<boolean>;
+  private readonly _fields;
+  constructor();
+  protected id(name: string): string;
+  protected onEnter(event: Event): void;
+  /** Validates and, when valid, emits `submitted`. An invalid form reveals all messages and emits nothing. Ignored while `disabled` / `busy`. */
+  submit(): void;
+  /** Clears every field back to the defaults (checking, individual, authorization unticked, holder name = `accountHolderNameDefault`). */
+  reset(): void;
+  static ɵfac: i0.ɵɵFactoryDeclaration<BankAccountFormComponent, never>;
+  static ɵcmp: i0.ɵɵComponentDeclaration<BankAccountFormComponent, "ui-bank-account-form", never, {
+    "showErrors": {
+      "alias": "showErrors";
+      "required": false;
+      "isSignal": true;
+    };
+    "disabled": {
+      "alias": "disabled";
+      "required": false;
+      "isSignal": true;
+    };
+    "busy": {
+      "alias": "busy";
+      "required": false;
+      "isSignal": true;
+    };
+    "mandateText": {
+      "alias": "mandateText";
+      "required": false;
+      "isSignal": true;
+    };
+    "accountTypeOptions": {
+      "alias": "accountTypeOptions";
+      "required": false;
+      "isSignal": true;
+    };
+    "holderTypeOptions": {
+      "alias": "holderTypeOptions";
+      "required": false;
+      "isSignal": true;
+    };
+    "accountHolderNameDefault": {
+      "alias": "accountHolderNameDefault";
+      "required": false;
+      "isSignal": true;
+    };
+    "testIdPrefix": {
+      "alias": "testIdPrefix";
+      "required": false;
+      "isSignal": true;
+    };
+  }, {
+    "submitted": "submitted";
+    "validChange": "validChange";
+  }, never, never, true, never>;
+}
 export interface ActiveConfirm {
   title: string;
   message: string;
@@ -4786,6 +4960,8 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
   readonly inputmode: import("@angular/core").InputSignal<"" | "none" | "text" | "search" | "email" | "tel" | "url" | "decimal" | "numeric">;
   readonly readonly: import("@angular/core").InputSignal<boolean>;
   readonly hint: import("@angular/core").InputSignal<string>;
+  /** Id(s) of an external element that also describes this control (e.g. one shared error text for a group of fields). Space separated; MERGED after the control's own hint / error id in `aria-describedby`, never replacing it. Empty = unchanged. */
+  readonly ariaDescribedBy: import("@angular/core").InputSignal<string>;
   readonly error: import("@angular/core").InputSignal<string>;
   /** When true, automatically formats the value as a US phone number as the user types. */
   readonly phoneFormat: import("@angular/core").InputSignal<boolean>;
@@ -4971,6 +5147,11 @@ export declare class TextInputComponent implements ControlValueAccessor, Validat
       "required": false;
       "isSignal": true;
     };
+    "ariaDescribedBy": {
+      "alias": "ariaDescribedBy";
+      "required": false;
+      "isSignal": true;
+    };
     "error": {
       "alias": "error";
       "required": false;
@@ -5043,6 +5224,8 @@ export declare class TextareaInputComponent implements ControlValueAccessor, Val
   readonly required: import("@angular/core").InputSignal<boolean>;
   readonly readonly: import("@angular/core").InputSignal<boolean>;
   readonly hint: import("@angular/core").InputSignal<string>;
+  /** Id(s) of an external element that also describes this control (e.g. one shared error text for a group of fields). Space separated; MERGED after the control's own hint / error id in `aria-describedby`, never replacing it. Empty = unchanged. */
+  readonly ariaDescribedBy: import("@angular/core").InputSignal<string>;
   /**
    * Opt-in. `false` (default) = unchanged: a labelled field's hint renders INSIDE the `<label>` ("Label (hint)" is the accessible name,
    * no aria-describedby for it). `true` = the hint is a sibling of the label (`.ta-head` row, id `<textarea id>-hint`), the accessible
@@ -5065,6 +5248,7 @@ export declare class TextareaInputComponent implements ControlValueAccessor, Val
    * hint is replaced by the error) followed by the error. The label is the accessible NAME; the hint is the DESCRIPTION.
    */
   protected readonly _describedBy: import("@angular/core").Signal<string | null>;
+  private readonly _ownDescribedBy;
   private readonly _reveal;
   private readonly _issue;
   /** True while the value breaks a built-in rule or the host passed an `[error]`. */
@@ -5132,6 +5316,11 @@ export declare class TextareaInputComponent implements ControlValueAccessor, Val
       "required": false;
       "isSignal": true;
     };
+    "ariaDescribedBy": {
+      "alias": "ariaDescribedBy";
+      "required": false;
+      "isSignal": true;
+    };
     "hintAsDescription": {
       "alias": "hintAsDescription";
       "required": false;
@@ -5535,6 +5724,8 @@ export declare class DateInputComponent implements ControlValueAccessor, Validat
   readonly min: import("@angular/core").InputSignal<string>;
   readonly max: import("@angular/core").InputSignal<string>;
   readonly hint: import("@angular/core").InputSignal<string>;
+  /** Id(s) of an external element that also describes this control (e.g. one shared error text for a group of fields). Space separated; MERGED after the control's own hint / error id in `aria-describedby`, never replacing it. Empty = unchanged. */
+  readonly ariaDescribedBy: import("@angular/core").InputSignal<string>;
   readonly error: import("@angular/core").InputSignal<string>;
   /** Reveal the built-in error messages now (e.g. after a failed Save click), without waiting for blur. */
   readonly showErrors: import("@angular/core").InputSignal<boolean>;
@@ -5543,6 +5734,8 @@ export declare class DateInputComponent implements ControlValueAccessor, Validat
   private readonly _cvaDisabled;
   protected readonly disabled: import("@angular/core").Signal<boolean>;
   protected readonly _value: import("@angular/core").WritableSignal<string>;
+  /** `aria-describedby`: the error / hint text, then the host's `ariaDescribedBy` id(s). */
+  protected readonly _describedBy: import("@angular/core").Signal<string | null>;
   private readonly _reveal;
   private readonly _issue;
   /** True while the value breaks a built-in rule or the host passed an `[error]`. */
@@ -5597,6 +5790,11 @@ export declare class DateInputComponent implements ControlValueAccessor, Validat
       "required": false;
       "isSignal": true;
     };
+    "ariaDescribedBy": {
+      "alias": "ariaDescribedBy";
+      "required": false;
+      "isSignal": true;
+    };
     "error": {
       "alias": "error";
       "required": false;
@@ -5623,6 +5821,8 @@ export declare class DatetimeInputComponent implements ControlValueAccessor, Val
   readonly min: import("@angular/core").InputSignal<string>;
   readonly max: import("@angular/core").InputSignal<string>;
   readonly hint: import("@angular/core").InputSignal<string>;
+  /** Id(s) of an external element that also describes this control (e.g. one shared error text for a group of fields). Space separated; MERGED after the control's own hint / error id in `aria-describedby`, never replacing it. Empty = unchanged. */
+  readonly ariaDescribedBy: import("@angular/core").InputSignal<string>;
   readonly error: import("@angular/core").InputSignal<string>;
   /** Reveal the built-in error messages now (e.g. after a failed Save click), without waiting for blur. */
   readonly showErrors: import("@angular/core").InputSignal<boolean>;
@@ -5630,6 +5830,8 @@ export declare class DatetimeInputComponent implements ControlValueAccessor, Val
   private readonly _cvaDisabled;
   protected readonly disabled: import("@angular/core").Signal<boolean>;
   protected readonly _value: import("@angular/core").WritableSignal<string>;
+  /** `aria-describedby`: the error / hint text, then the host's `ariaDescribedBy` id(s). */
+  protected readonly _describedBy: import("@angular/core").Signal<string | null>;
   private readonly _reveal;
   private readonly _issue;
   /** True while the value breaks a built-in rule or the host passed an `[error]`. */
@@ -5682,6 +5884,11 @@ export declare class DatetimeInputComponent implements ControlValueAccessor, Val
       "required": false;
       "isSignal": true;
     };
+    "ariaDescribedBy": {
+      "alias": "ariaDescribedBy";
+      "required": false;
+      "isSignal": true;
+    };
     "error": {
       "alias": "error";
       "required": false;
@@ -5709,6 +5916,8 @@ export declare class TimeInputComponent implements ControlValueAccessor, Validat
   readonly min: import("@angular/core").InputSignal<string>;
   readonly max: import("@angular/core").InputSignal<string>;
   readonly hint: import("@angular/core").InputSignal<string>;
+  /** Id(s) of an external element that also describes this control (e.g. one shared error text for a group of fields). Space separated; MERGED after the control's own hint / error id in `aria-describedby`, never replacing it. Empty = unchanged. */
+  readonly ariaDescribedBy: import("@angular/core").InputSignal<string>;
   readonly error: import("@angular/core").InputSignal<string>;
   /** Reveal the built-in error messages now (e.g. after a failed Save click), without waiting for blur. */
   readonly showErrors: import("@angular/core").InputSignal<boolean>;
@@ -5718,6 +5927,8 @@ export declare class TimeInputComponent implements ControlValueAccessor, Validat
   protected readonly disabled: import("@angular/core").Signal<boolean>;
   protected readonly _value: import("@angular/core").WritableSignal<string>;
   protected readonly _inputId: string;
+  /** `aria-describedby`: the error / hint text, then the host's `ariaDescribedBy` id(s). */
+  protected readonly _describedBy: import("@angular/core").Signal<string | null>;
   private readonly _reveal;
   private readonly _issue;
   /** True while the value breaks a built-in rule or the host passed an `[error]`. */
@@ -5774,6 +5985,11 @@ export declare class TimeInputComponent implements ControlValueAccessor, Validat
       "required": false;
       "isSignal": true;
     };
+    "ariaDescribedBy": {
+      "alias": "ariaDescribedBy";
+      "required": false;
+      "isSignal": true;
+    };
     "error": {
       "alias": "error";
       "required": false;
@@ -6779,6 +6995,8 @@ export declare class CardListItemComponent {
   readonly actionLabel: import("@angular/core").InputSignal<string>;
   readonly actionTestId: import("@angular/core").InputSignal<string>;
   readonly actionAriaLabel: import("@angular/core").InputSignal<string>;
+  /** A built-in Edit / View / action / delete button shows (the row then keeps a minimum height so a badge and a chip never overlap). */
+  protected readonly hasBuiltInChip: import("@angular/core").Signal<boolean>;
   readonly editClick: import("@angular/core").OutputEmitterRef<void>;
   readonly viewClick: import("@angular/core").OutputEmitterRef<void>;
   readonly delete: import("@angular/core").OutputEmitterRef<void>;