@rdlabo/ionic-angular-kit 0.0.13 → 0.0.15

package/types/rdlabo-ionic-angular-kit.d.ts

@@ -1,10 +1,9 @@
 import * as i0 from '@angular/core';
-import { InjectionToken, EnvironmentProviders, OnInit, ElementRef, WritableSignal } from '@angular/core';
-import { ModalOptions, PopoverOptions, ToastOptions, AlertController, ActionSheetController } from '@ionic/angular/standalone';
+import { InjectionToken, EnvironmentProviders, InputSignalWithTransform, OnInit, ElementRef, WritableSignal } from '@angular/core';
+import { ModalOptions, PopoverOptions, ToastOptions, LoadingOptions, AlertController, ActionSheetController } from '@ionic/angular/standalone';
 import { PluginListenerHandle } from '@capacitor/core';
-import { BehaviorSubject, Observable } from 'rxjs';
-import { BRLMPrinterModelName, BRLMPrinterLabelName, BRLMPrintOptions } from '@rdlabo/capacitor-brotherprint';
 import { RouterStateSnapshot, UrlTree, CanActivateFn } from '@angular/router';
+import { Observable } from 'rxjs';
 import { HttpRequest, HttpResponse, HttpErrorResponse, HttpEvent, HttpInterceptorFn } from '@angular/common/http';
 import { ImpactStyle } from '@capacitor/haptics';
 
@@ -143,6 +142,83 @@ interface KitModalPresentOptions extends Omit<ModalOptions, 'component' | 'compo
      */
     watchKeyboard?: boolean;
 }
+/**
+ * Optional static metadata a modal component may declare to make {@link KitOverlayController.presentModal}
+ * type-safe in its dismiss data: the value passed to `dismiss()` is inferred from `modalReturn`.
+ *
+ * @remarks
+ * Props do *not* need to be declared here — {@link KitOverlayController.presentModal} infers them directly
+ * from the component's `input()` fields (see {@link ModalPropsOf}), so `input()` stays the single source of
+ * truth and can never drift from a hand-written declaration. Only the dismiss-data shape, which has no
+ * counterpart on the component, is declared — as a `declare static modalReturn` phantom type with no runtime
+ * value, so it adds nothing to the bundle.
+ *
+ * @example
+ * ```ts
+ * export class EditPage {
+ *   declare static modalReturn: { saved: boolean };
+ *   readonly id = input.required<number>();   // props are inferred from here
+ *   readonly note = input<string>();          // default-less input() → optional prop
+ * }
+ *
+ * // Caller — `id` is required (input.required), `note` optional; result is `{ saved: boolean } | undefined`:
+ * const result = await overlay.presentModal(EditPage, { id: 1 });
+ * ```
+ */
+interface ModalMetadata<R = unknown> {
+    /** Shape of the data the modal resolves with when dismissed. */
+    modalReturn?: R;
+}
+/**
+ * Write type of a signal `input()` field (unwraps `input.required`, `input()` and transform inputs).
+ *
+ * @remarks
+ * Matched with `any` (not `unknown`): `InputSignalWithTransform`'s `TransformT` is contravariant, so
+ * `InputSignal<number>` is not assignable to `InputSignalWithTransform<unknown, unknown>`.
+ */
+type InputWriteType<F> = F extends InputSignalWithTransform<any, infer W> ? W : never;
+/** Instance type of a component constructor; `never` for non-class components (string / HTMLElement refs). */
+type InstanceOf<C> = C extends abstract new (...args: never[]) => infer I ? I : never;
+/** Keys of the `input()` signal fields on a component instance. */
+type InputFieldKeys<I> = {
+    [K in keyof I]-?: I[K] extends InputSignalWithTransform<any, any> ? K : never;
+}[keyof I];
+/**
+ * Props object inferred from a component's `input()` fields. Required vs. optional is decided by the write
+ * type: `input.required<T>()` / `input<T>(default)` yield `T` (no `undefined`) → required prop, while a
+ * default-less `input<T>()` yields `T | undefined` → optional prop.
+ *
+ * @remarks
+ * Angular's types cannot distinguish `input.required<T>()` from a defaulted `input<T>(default)` — both are
+ * `InputSignal<T>` — so a defaulted input is (safely) treated as required. Declare inputs you want to omit at
+ * the call site as default-less `input<T>()`.
+ */
+type ModalPropsOf<I> = {
+    [K in InputFieldKeys<I> as undefined extends InputWriteType<I[K]> ? never : K]: InputWriteType<I[K]>;
+} & {
+    [K in InputFieldKeys<I> as undefined extends InputWriteType<I[K]> ? K : never]?: InputWriteType<I[K]>;
+};
+/** `input()` keys whose write type excludes `undefined` (required / defaulted inputs). Empty when none. */
+type RequiredInputKeys<I> = {
+    [K in InputFieldKeys<I>]: undefined extends InputWriteType<I[K]> ? never : K;
+}[InputFieldKeys<I>];
+/**
+ * Dismiss-data type inferred from a component's static {@link ModalMetadata.modalReturn}. A component that
+ * declares no `modalReturn` resolves to `void`: it is treated as returning no dismiss data, so the compiler
+ * rejects any attempt to read the result. Declare `modalReturn` on modals that do resolve with data.
+ */
+type ModalReturnOf<C> = C extends {
+    modalReturn: infer R;
+} ? R : void;
+/** Loose trailing args (optional, untyped props) — used when a component exposes no signal `input()` fields. */
+type LooseModalPresentArgs = [componentProps?: ModalOptions['componentProps'], options?: KitModalPresentOptions];
+/**
+ * Trailing `presentModal` args derived from a component's `input()` fields: props are inferred and typed via
+ * {@link ModalPropsOf}. When the component declares at least one required input the props argument is required;
+ * when every input is optional the props argument itself is optional. Components with no signal inputs (plain
+ * classes, `@Input()`-decorator components, or non-class refs) fall back to loose, untyped props.
+ */
+type ModalPresentArgs<C, I = InstanceOf<C>> = [I] extends [never] ? LooseModalPresentArgs : [InputFieldKeys<I>] extends [never] ? LooseModalPresentArgs : [RequiredInputKeys<I>] extends [never] ? [componentProps?: ModalPropsOf<I>, options?: KitModalPresentOptions] : [componentProps: ModalPropsOf<I>, options?: KitModalPresentOptions];
 /**
  * Options for {@link KitOverlayController.alertClose}.
  */
@@ -182,7 +258,7 @@ interface KitAlertConfirmOptions extends KitAlertCloseOptions {
  * constructor(private readonly overlay: KitOverlayController) {}
  *
  * async edit(): Promise<void> {
- *   const result = await this.overlay.presentModal<EditResult>(EditPage, { id: 1 });
+ *   const result = await this.overlay.presentModal(EditPage, { id: 1 });
  *   if (result) {
  *     await this.overlay.presentToast({ message: 'Saved' });
  *   }
@@ -202,12 +278,18 @@ declare class KitOverlayController {
      * @remarks
      * Presenting a modal triggers light native haptic feedback as an intentional kit UX choice,
      * consistent with {@link presentPopover} and {@link presentToast}.
+     *
+     * Props are inferred from the component's `input()` fields (see {@link ModalPropsOf}): required inputs
+     * become required props, so the compiler rejects a call that omits them. The return type is inferred from
+     * a static `modalReturn` (see {@link ModalMetadata}); a component with no `modalReturn` resolves to `void`
+     * — the modal is treated as returning no dismiss data.
      * @example
      * ```ts
-     * const data = await overlay.presentModal<{ saved: boolean }>(EditPage, { id: 1 }, { watchKeyboard: true });
+     * // Inferred — `id` required (input.required), `note` optional; result is `{ saved: boolean } | undefined`:
+     * const result = await overlay.presentModal(EditPage, { id: 1 });
      * ```
      */
-    presentModal<O = unknown>(component: ModalOptions['component'], componentProps?: ModalOptions['componentProps'], options?: KitModalPresentOptions): Promise<O | undefined>;
+    presentModal<C extends ModalOptions['component']>(component: C, ...args: ModalPresentArgs<C>): Promise<ModalReturnOf<C> | undefined>;
     /**
      * Present a popover and resolve with the data passed to its dismissal.
      *
@@ -287,6 +369,59 @@ declare class KitOverlayController {
     static ɵprov: i0.ɵɵInjectableDeclaration<KitOverlayController>;
 }
 
+/**
+ * Reference-counted wrapper around Ionic's `LoadingController` that keeps at most one loading
+ * indicator on screen across concurrent async work.
+ *
+ * @remarks
+ * Each {@link presentLoading} increments a counter and each {@link dismissLoading} decrements it; the
+ * indicator is presented on the `0 → 1` transition and dismissed on the `N → 0` transition. This
+ * removes the flicker / "stuck spinner" bugs that come from every service calling
+ * `LoadingController.create/dismiss` independently.
+ *
+ * All operations are serialized through an internal promise chain, so a `create → present` sequence
+ * can never interleave with a concurrent `dismiss`. That is what makes the counter race-safe: a
+ * dismiss that arrives while the indicator is still being presented runs *after* `present()` settles
+ * and therefore tears the element down instead of leaving it orphaned on screen.
+ *
+ * Always pair every `presentLoading()` with exactly one `dismissLoading()` — a `try/finally` is the
+ * safest shape.
+ *
+ * @example
+ * ```ts
+ * constructor(private readonly loading: KitLoadingController) {}
+ *
+ * async save(): Promise<void> {
+ *   await this.loading.presentLoading({ message: 'Saving…' });
+ *   try {
+ *     await this.api.save();
+ *   } finally {
+ *     await this.loading.dismissLoading();
+ *   }
+ * }
+ * ```
+ */
+declare class KitLoadingController {
+    #private;
+    /**
+     * Show the loading indicator, or join the one already on screen.
+     *
+     * @param options - Ionic loading options; only applied by the call that actually creates the
+     *   indicator (the `0 → 1` transition). Ignored while an indicator is already present.
+     * @returns a Promise that resolves once the indicator is on screen (or immediately when one already is)
+     */
+    presentLoading(options?: LoadingOptions): Promise<void>;
+    /**
+     * Release one reference; dismiss the indicator once the last reference is gone.
+     *
+     * @returns a Promise that resolves once the reference is released (and the indicator dismissed if
+     *   this was the last one). No-ops when the counter is already at zero.
+     */
+    dismissLoading(): Promise<void>;
+    static ɵfac: i0.ɵɵFactoryDeclaration<KitLoadingController, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<KitLoadingController>;
+}
+
 /**
  * Content for {@link KitReloadAlertController.present}.
  */
@@ -550,236 +685,6 @@ type KitKeyboardAdjust = 'transform' | 'offset' | 'keyboard-offset';
  */
 declare const kitKeyboardInit: (elementRef: ElementRef, type: KitKeyboardAdjust) => Promise<PluginListenerHandle[]>;
 
-/**
- * Theme configuration injected via `provideKitTheme()` and consumed by `KitThemeController`.
- *
- * @remarks
- * All fields are required; the consuming application supplies a complete configuration so every app
- * in the fleet has the same shape. The class lists absorb the per-app CSS drift: the kit toggles
- * `darkClasses` on when dark and `lightClasses` on when light, so an app that only uses Ionic's
- * palette passes `darkClasses: ['ion-palette-dark'], lightClasses: []`, while an app with an extra
- * design-system palette adds its own classes (e.g. `darkClasses: ['ion-palette-dark', 'a2ui-dark']`,
- * `lightClasses: ['a2ui-light']`).
- */
-interface KitThemeConfig {
-    /** Key under which the chosen theme (`'light'` | `'dark'`) is persisted via `KitStorageService`. */
-    readonly storageKey: string;
-    /** Classes toggled **on** the document element when the dark theme is active. */
-    readonly darkClasses: readonly string[];
-    /** Classes toggled **on** the document element when the light theme is active. */
-    readonly lightClasses: readonly string[];
-}
-/**
- * Injection token carrying the {@link KitThemeConfig} for `KitThemeController`.
- *
- * @remarks
- * Provide it through {@link provideKitTheme} rather than registering it directly.
- */
-declare const KIT_THEME_CONFIG: InjectionToken<KitThemeConfig>;
-/**
- * Wire `KitThemeController` into the application.
- *
- * @param config - theme configuration: the storage key and the light/dark class lists
- * @returns environment providers to add to the application's provider list
- * @example
- * ```ts
- * bootstrapApplication(AppComponent, {
- *   providers: [
- *     provideKitTheme({
- *       storageKey: StorageKeyEnum.theme,
- *       darkClasses: ['ion-palette-dark', 'a2ui-dark'],
- *       lightClasses: ['a2ui-light'],
- *     }),
- *   ],
- * });
- * ```
- */
-declare const provideKitTheme: (config: KitThemeConfig) => EnvironmentProviders;
-
-/** The active theme mode. */
-type KitThemeMode = 'light' | 'dark';
-/**
- * Light/dark theme controller: persists the user's choice, follows the OS setting until the user
- * overrides it, toggles the configured palette classes, and syncs the native Android status bar.
- *
- * @remarks
- * Consolidates the theme logic that had drifted across the fleet into one behavior. Notably it fixes
- * a latent leak in one variant where the system-theme listener stayed registered after a manual
- * toggle: {@link changeTheme} always detaches the listener via {@link removeEventListener} before
- * applying the forced theme, so a later OS change can no longer silently flip an app the user pinned.
- *
- * - **Persistence** — the chosen mode is stored via {@link KitStorageService} under the configured key.
- * - **Follow OS until overridden** — on boot with nothing stored, it tracks
- *   `prefers-color-scheme` (idempotent registration); once the user calls {@link changeTheme} it stops
- *   following and honors the explicit choice.
- * - **Class toggling** — toggles {@link KitThemeConfig.darkClasses} on when dark and
- *   {@link KitThemeConfig.lightClasses} on when light, absorbing per-app CSS differences via config.
- * - **Native status bar** — on Android native only, mirrors the Ionic behavior of setting the status
- *   bar style to match (iOS derives it from the web content, so it is intentionally left untouched).
- *
- * Subscribe to {@link themeSubject} to reflect the current mode in the UI (e.g. a settings toggle).
- *
- * @example
- * ```ts
- * // On boot (app.component):
- * inject(KitThemeController).setDefaultThemeMode();
- *
- * // From a settings toggle:
- * const theme = inject(KitThemeController);
- * theme.themeSubject.subscribe((mode) => this.isDark.set(mode === 'dark'));
- * theme.changeTheme(true);
- * ```
- */
-declare class KitThemeController {
-    #private;
-    /**
-     * Emits the active theme, seeded with `'light'`.
-     *
-     * @remarks
-     * A `BehaviorSubject`, so a late subscriber immediately receives the current mode; it emits again
-     * on every {@link setDefaultThemeMode} / {@link changeTheme} and on OS theme changes while following.
-     */
-    readonly themeSubject: BehaviorSubject<KitThemeMode>;
-    /**
-     * Apply the persisted theme, or start following the OS setting when nothing is stored yet.
-     *
-     * @remarks
-     * Call once on boot (e.g. from `app.component`).
-     *
-     * @returns a Promise that resolves once the initial theme has been applied
-     */
-    setDefaultThemeMode(): Promise<void>;
-    /**
-     * Force a theme, persist it, and stop following the OS setting.
-     *
-     * @param isDark - `true` for the dark theme, `false` for light
-     * @returns a Promise that resolves once the theme has been persisted and applied
-     */
-    changeTheme(isDark: boolean): Promise<void>;
-    static ɵfac: i0.ɵɵFactoryDeclaration<KitThemeController, never>;
-    static ɵprov: i0.ɵɵInjectableDeclaration<KitThemeController>;
-}
-
-/**
- * Options for {@link kitRequestReview}.
- */
-interface KitRequestReviewOptions {
-    /**
-     * Key under which the timestamp of the last review request is stored (via `@capacitor/preferences`).
-     *
-     * @remarks
-     * Supplied by the caller so the kit ships no storage keys of its own; each app passes its own enum
-     * value.
-     */
-    readonly storageKey: string;
-    /**
-     * Minimum number of months between review prompts.
-     *
-     * @remarks
-     * A prompt is only shown when this much time has elapsed since the last one (or when there is no
-     * record yet), so the OS review dialog is never nagged repeatedly.
-     */
-    readonly throttleMonths: number;
-}
-/**
- * Request the native in-app review dialog, throttled so the user is prompted at most once per window.
- *
- * @remarks
- * A plain function — no DI needed (`@capacitor/preferences`, `@capacitor-community/in-app-review` and
- * `Capacitor` are all static), so the caller invokes it directly and passes its own config rather
- * than injecting a controller. A no-op on non-native platforms. When enough time has elapsed since
- * the last prompt (per {@link KitRequestReviewOptions.throttleMonths}, tracked under
- * {@link KitRequestReviewOptions.storageKey}), it briefly waits for the app to settle, calls
- * `InAppReview.requestReview()`, and records the new timestamp. The wait/throttle/record sequence
- * was previously copy-pasted verbatim across the fleet; centralizing it means a single place to tune
- * the prompt cadence.
- *
- * @param options - the storage key and throttle window; see {@link KitRequestReviewOptions}
- * @returns a Promise that resolves once the request has been made (or immediately if throttled / on web)
- * @example
- * ```ts
- * await kitRequestReview({ storageKey: StorageEnum.lastRequestRate, throttleMonths: 3 });
- * ```
- */
-declare const kitRequestReview: (options: KitRequestReviewOptions) => Promise<void>;
-
-/**
- * Rotate a base64 image 90°, returning a new base64 data URL of the same MIME type.
- *
- * @remarks
- * Pure DOM/canvas work — no DI. Used before sending a label to the printer when the artwork must be
- * turned to match the tape orientation. Extracted verbatim from the fleet's printer services so the
- * canvas handling lives in one place.
- *
- * @param imageData - a base64 data URL (e.g. `data:image/png;base64,...`)
- * @returns a Promise resolving to the rotated image as a base64 data URL
- */
-declare const kitRotationImage: (imageData: string) => Promise<string>;
-/** Options for {@link kitDomToPng}. */
-interface KitDomToPngOptions {
-    /** When `true`, the rendered PNG is rotated 90° via {@link kitRotationImage}. Defaults to `false`. */
-    readonly rotate?: boolean;
-    /** Rendering scale passed to `dom-to-image-more`. Defaults to `3` (the fleet's print resolution). */
-    readonly scale?: number;
-}
-/**
- * Render a DOM element to a base64 PNG for label printing, with the fleet's device-specific fixes.
- *
- * @remarks
- * Pure function — no DI (reads the platform from `Capacitor`, uses the global `document`), so the
- * caller presents its own loading UI around it. Centralizes the hard-won device quirks: on iOS it
- * pads width/height by 2px (otherwise the bottom is clipped), on Android it does not (the padding
- * introduces a black line). Retries the `dom-to-image-more` render up to 10 times because the first
- * pass can occasionally return empty. This is exactly the kind of plumbing where a future fix should
- * land in every app at once.
- *
- * @param element - the element to rasterize (e.g. the label preview host)
- * @param options - rendering options; see {@link KitDomToPngOptions}
- * @returns a Promise resolving to the PNG as a base64 data URL (empty string if every attempt failed)
- * @example
- * ```ts
- * const loading = await this.#loadingCtrl.create({ message: this.text.generating });
- * await loading.present();
- * const png = await kitDomToPng(this.preview().nativeElement, { rotate: true });
- * await loading.dismiss();
- * ```
- */
-declare const kitDomToPng: (element: HTMLElement, options?: KitDomToPngOptions) => Promise<string>;
-/** Parameters for {@link kitBuildBrotherPrintSettings}. */
-interface KitBrotherPrintSettingsParams {
-    /** The target printer model. */
-    readonly modelName: BRLMPrinterModelName;
-    /** The label artwork as a base64 data URL (the `data:...,` prefix is stripped internally). */
-    readonly printBase64: string;
-    /** The selected label/paper (its `W<width>H<height>` code drives the tape dimensions). */
-    readonly label: BRLMPrinterLabelName;
-    /** Number of copies to print. Passed by the caller (apps differ: some use the print option, some fix 1). */
-    readonly numberOfCopies: number;
-    /** Halftone threshold for the print. */
-    readonly halftoneThreshold: number;
-}
-/**
- * Assemble the Brother `BRLMPrintOptions` for a die-cut label print, minus the transport fields.
- *
- * @remarks
- * Pure function — no DI. Centralizes the fleet's canonical print settings (fit-page scale, centered,
- * best quality, threshold halftone, 2mm/1mm margins, `gapLength` 2.0) and the tape sizing derived
- * from the label's `W<width>H<height>` code. The caller merges the printer's `port` / `channelInfo`
- * onto the result before calling `BrotherPrint.printImage()`, so channel selection and loading UI stay
- * in the app.
- *
- * @param params - model, artwork, label, copies, and halftone threshold; see {@link KitBrotherPrintSettingsParams}
- * @returns the `BRLMPrintOptions` ready to be spread with `{ port, channelInfo }`
- * @example
- * ```ts
- * const settings = kitBuildBrotherPrintSettings({
- *   modelName, printBase64, label, numberOfCopies: printOptions.printNum, halftoneThreshold: printOptions.halftoneThreshold,
- * });
- * await BrotherPrint.printImage({ ...settings, port: channel.port, channelInfo: channel.channelInfo });
- * ```
- */
-declare const kitBuildBrotherPrintSettings: (params: KitBrotherPrintSettingsParams) => BRLMPrintOptions;
-
 /**
  * Discriminated set of authentication states the guards react to.
  *
@@ -1331,5 +1236,5 @@ declare const kitChangeEventDisabled: (completeEvent: WritableSignal<HTMLIonInfi
  */
 declare const kitCreateDidEnter: (el: ElementRef) => Observable<boolean>;
 
-export { KIT_AUTH_CONFIG, KIT_HTTP_CONFIG, KIT_OVERLAY_CONFIG, KIT_THEME_CONFIG, KitAutofillDirective, KitOverlayController, KitReloadAlertController, KitStorageService, KitThemeController, arrayConcatById, disableHandler, kitAuthInterceptor, kitBuildBrotherPrintSettings, kitChangeEventDisabled, kitCreateDidEnter, kitDomToPng, kitImpact, kitKeyboardInit, kitPresentAuthFailedAlert, kitPresentLanguageActionSheet, kitRequestReview, kitRequireAuthorizedGuard, kitRequireConfirmingGuard, kitRequiredUnauthorizedGuard, kitRotationImage, objectEqual, provideKitAuth, provideKitHttp, provideKitOverlay, provideKitTheme };
-export type { KitAlertCloseOptions, KitAlertConfirmOptions, KitAuthConfig, KitAuthFailedAlertOptions, KitAuthRedirects, KitAuthState, KitBrotherPrintSettingsParams, KitDomToPngOptions, KitHttpConfig, KitKeyboardAdjust, KitLabels, KitLanguageActionSheetOptions, KitLanguageOption, KitModalPresentOptions, KitOverlayConfig, KitReloadAlertOptions, KitRequestReviewOptions, KitThemeConfig, KitThemeMode };
+export { KIT_AUTH_CONFIG, KIT_HTTP_CONFIG, KIT_OVERLAY_CONFIG, KitAutofillDirective, KitLoadingController, KitOverlayController, KitReloadAlertController, KitStorageService, arrayConcatById, disableHandler, kitAuthInterceptor, kitChangeEventDisabled, kitCreateDidEnter, kitImpact, kitKeyboardInit, kitPresentAuthFailedAlert, kitPresentLanguageActionSheet, kitRequireAuthorizedGuard, kitRequireConfirmingGuard, kitRequiredUnauthorizedGuard, objectEqual, provideKitAuth, provideKitHttp, provideKitOverlay };
+export type { KitAlertCloseOptions, KitAlertConfirmOptions, KitAuthConfig, KitAuthFailedAlertOptions, KitAuthRedirects, KitAuthState, KitHttpConfig, KitKeyboardAdjust, KitLabels, KitLanguageActionSheetOptions, KitLanguageOption, KitModalPresentOptions, KitOverlayConfig, KitReloadAlertOptions, ModalMetadata };