@rdlabo/ionic-angular-kit 0.0.12 → 0.0.13

package/README.md

@@ -26,10 +26,18 @@ npm install @rdlabo/ionic-angular-kit
 | `@ionic/angular` | `^8.0.0` |
 | `@ionic/storage-angular` | `^4.0.0` |
 | `@capacitor/core` | `>=6.0.0 <9.0.0` |
+| `@capacitor/haptics` | `>=6.0.0 <9.0.0` |
 | `@capacitor/keyboard` | `>=6.0.0 <9.0.0` |
 | `@capacitor/network` | `>=6.0.0 <9.0.0` |
+| `@capacitor/preferences` | `>=6.0.0 <9.0.0` |
+| `@capacitor/status-bar` | `>=6.0.0 <9.0.0` |
+| `@capacitor-community/in-app-review` | `>=6.0.0 <9.0.0` |
+| `@rdlabo/capacitor-brotherprint` | `>=6.0.0 <9.0.0` |
+| `dom-to-image-more` | `^3.0.0` |
 | `rxjs` | `^7.8.0` |
 
+Feature-scoped peers are only needed by the features that use them (`status-bar` → `KitThemeController`; `preferences` + `in-app-review` → `kitRequestReview`; `capacitor-brotherprint` + `dom-to-image-more` → the printer helpers); an app that doesn't use a feature can ignore its unmet-peer warning.
+
 ---
 
 ## Features
@@ -409,6 +417,43 @@ export class ComposePage {
 
 ---
 
+### KitThemeController + provideKitTheme
+
+Light/dark theme controller that unifies the theme logic that had drifted across the fleet: it persists the user's choice, follows the OS `prefers-color-scheme` until the user overrides it, toggles the configured palette classes, and syncs the native Android status bar. It also fixes a latent leak in one variant where the system-theme listener stayed registered after a manual toggle — `changeTheme()` always detaches the listener first, so a later OS change can't silently flip an app the user pinned.
+
+Per-app CSS differences are absorbed by config: `darkClasses` are toggled on when dark, `lightClasses` on when light. The kit ships no class names of its own. Subscribe to `themeSubject` (a `BehaviorSubject`) to reflect the current mode in the UI. It is a controller (not a plain function) because the subject and OS-listener are shared state across the app lifetime.
+
+```typescript
+// app.config.ts
+provideKitTheme({
+  storageKey: StorageKeyEnum.theme,
+  darkClasses: ['ion-palette-dark', 'a2ui-dark'],
+  lightClasses: ['a2ui-light'],
+});
+
+// app.component.ts — apply on boot
+inject(KitThemeController).setDefaultThemeMode();
+
+// settings page — bind a toggle
+const theme = inject(KitThemeController);
+theme.themeSubject.subscribe((mode) => this.isDark.set(mode === 'dark'));
+theme.changeTheme(true); // force dark, stop following the OS
+```
+
+---
+
+### kitRequestReview
+
+A plain function (no DI — `@capacitor/preferences`, `@capacitor-community/in-app-review` and `Capacitor` are all static) that requests the native in-app review dialog, throttled so the user is prompted at most once per window. A no-op on web. The wait/throttle/record sequence was previously copy-pasted verbatim across the fleet; centralizing it means a single place to tune the prompt cadence. The storage key and throttle window are passed as arguments, so the kit ships no config of its own.
+
+```typescript
+import { kitRequestReview } from '@rdlabo/ionic-angular-kit';
+
+await kitRequestReview({ storageKey: StorageEnum.lastRequestRate, throttleMonths: 3 });
+```
+
+---
+
 ### Utilities
 
 Framework-agnostic helpers (no DI required unless noted):
@@ -432,6 +477,61 @@ async onSubmit(event: Event) {
 }
 ```
 
+Ionic-event / lifecycle helpers:
+
+```typescript
+import { kitChangeEventDisabled, kitCreateDidEnter } from '@rdlabo/ionic-angular-kit';
+
+// Toggle a signal-held ion-infinite-scroll / ion-refresher's `disabled` (no-op when empty).
+kitChangeEventDisabled(infiniteScrollSignal, true);
+
+// Observe an Ionic page's "is entered" state from its lifecycle DOM events (true on didEnter).
+readonly isEntered = toSignal(kitCreateDidEnter(inject(ElementRef)), { initialValue: false });
+```
+
+---
+
+### kitPresentLanguageActionSheet
+
+A plain function (the `ActionSheetController` is passed in — nothing injected) that presents a language picker and, on a new selection, reloads the app at that locale's entry point. Unifies the language-switch flow duplicated across apps: it stashes the current path in `sessionStorage` (to restore after reload), records the chosen locale in `localStorage`, and calls `window.location.replace()` with the app-provided URL. Being a navigation helper, it stays standalone rather than part of a controller. All text, the locale list, and the per-locale URL mapping are injected, so the kit stays free of i18n strings.
+
+```typescript
+import { kitPresentLanguageActionSheet } from '@rdlabo/ionic-angular-kit';
+
+await kitPresentLanguageActionSheet(inject(ActionSheetController), {
+  header: $localize`言語設定`,
+  locales: [{ text: 'English', data: 'en-US' }, { text: '日本語', data: 'ja' }],
+  cancelText: $localize`キャンセル`,
+  currentLocale: normalizedLocale,
+  currentPath: this.#router.url,
+  pathnameStorageKey: StorageKeyEnum.pathnameBeforeRedirect,
+  buildRedirectUrl: (locale) => location.origin + (localePath[locale.toLowerCase()] ?? '/index.html'),
+  enabled: environment.production,
+});
+```
+
+---
+
+### Printer (Brother label plumbing)
+
+Three pure functions (no DI) that extract the i18n-free core of the fleet's Brother label printing, so a device-quirk or print-setting fix lands in every app at once. The UI orchestration — search/channel-selection alerts, loading overlays, and the app-specific paper list — stays in each app, since those diverge (labels, paper options, copies policy).
+
+- `kitDomToPng(element, { rotate?, scale? })` — render a DOM element to a base64 PNG with the fleet's device fixes (iOS +2px to avoid bottom clipping, none on Android to avoid a black line; retries up to 10×). The caller presents its own loading UI.
+- `kitRotationImage(base64)` — rotate a base64 image 90° via canvas.
+- `kitBuildBrotherPrintSettings({ modelName, printBase64, label, numberOfCopies, halftoneThreshold })` — assemble the canonical `BRLMPrintOptions` (fit-page, centered, best quality, threshold halftone, standard margins, tape size parsed from the label's `W<w>H<h>` code). Merge `{ port, channelInfo }` from the selected channel before calling `BrotherPrint.printImage()`.
+
+```typescript
+import { kitDomToPng, kitBuildBrotherPrintSettings } from '@rdlabo/ionic-angular-kit';
+
+const png = await kitDomToPng(this.preview().nativeElement, { rotate: true });
+const settings = kitBuildBrotherPrintSettings({
+  modelName, printBase64: png, label,
+  numberOfCopies: printOptions.printNum,
+  halftoneThreshold: printOptions.halftoneThreshold,
+});
+await BrotherPrint.printImage({ ...settings, port: channel.port, channelInfo: channel.channelInfo });
+```
+
 ---
 
 ## Consumer Vitest setup notes

package/fesm2022/rdlabo-ionic-angular-kit.mjs

@@ -1,15 +1,20 @@
 import * as i0 from '@angular/core';
-import { inject, Injectable, InjectionToken, makeEnvironmentProviders, ElementRef, Directive } from '@angular/core';
+import { inject, Injectable, InjectionToken, makeEnvironmentProviders, ElementRef, Directive, DOCUMENT } from '@angular/core';
 import { Storage } from '@ionic/storage-angular';
 import { ModalController, PopoverController, ToastController, AlertController, NavController } from '@ionic/angular/standalone';
 import { Capacitor } from '@capacitor/core';
 import { Keyboard } from '@capacitor/keyboard';
 import { ImpactStyle, Haptics } from '@capacitor/haptics';
+import { StatusBar, Style } from '@capacitor/status-bar';
+import { BehaviorSubject, from, throwError, retry, timer, Observable, startWith } from 'rxjs';
+import { Preferences } from '@capacitor/preferences';
+import { InAppReview } from '@capacitor-community/in-app-review';
+import { BRLMPrinterHalftone, BRLMPrinterCustomPaperUnit, BRLMPrinterCustomPaperType, BRLMPrinterPrintQuality, BRLMPrinterHorizontalAlignment, BRLMPrinterVerticalAlignment, BRLMPrinterImageRotation, BRLMPrinterScaleMode } from '@rdlabo/capacitor-brotherprint';
+import domtoimage from 'dom-to-image-more';
 import { Router } from '@angular/router';
 import { map, mergeMap, catchError, timeout, tap } from 'rxjs/operators';
 import { HttpErrorResponse, HttpResponse } from '@angular/common/http';
 import { Network } from '@capacitor/network';
-import { from, throwError, retry, timer } from 'rxjs';
 
 /**
  * Thin, typed wrapper around `@ionic/storage-angular`.
@@ -517,6 +522,52 @@ const kitPresentAuthFailedAlert = async (alertCtrl, options) => {
     await alert.present();
 };
 
+/**
+ * Present a language picker and, on a new selection, reload the app at that locale's entry point.
+ *
+ * @remarks
+ * A plain function (the `ActionSheetController` is passed in, so nothing is injected) that unifies the
+ * language-switch flow duplicated across apps. On a changed selection while {@link enabled} it stashes
+ * the current path in `sessionStorage` (so the app can return the user to where they were), records the
+ * chosen locale in `localStorage` under `'locale'`, and calls `window.location.replace()` with the
+ * app-provided URL. Because it performs navigation, it is a standalone helper rather than part of a
+ * controller (mirroring `kitPresentReloadAlert` / `kitPresentAuthFailedAlert`). Centralizing it means a
+ * future improvement to the switch flow lands in every app at once.
+ *
+ * @param actionSheetCtrl - the Ionic `ActionSheetController`
+ * @param options - labels, locale list, and redirect configuration; see {@link KitLanguageActionSheetOptions}
+ * @returns a Promise that resolves once presented (and, on a new selection, after the reload is triggered)
+ * @example
+ * ```ts
+ * await kitPresentLanguageActionSheet(inject(ActionSheetController), {
+ *   header: $localize`言語設定`,
+ *   locales: [{ text: 'English', data: 'en-US' }, { text: '日本語', data: 'ja' }],
+ *   cancelText: $localize`キャンセル`,
+ *   currentLocale: normalizedLocale,
+ *   currentPath: this.#router.url,
+ *   pathnameStorageKey: StorageKeyEnum.pathnameBeforeRedirect,
+ *   buildRedirectUrl: (locale) => location.origin + (localePath[locale.toLowerCase()] ?? '/index.html'),
+ *   enabled: environment.production,
+ * });
+ * ```
+ */
+const kitPresentLanguageActionSheet = async (actionSheetCtrl, options) => {
+    const actionSheet = await actionSheetCtrl.create({
+        header: options.header,
+        buttons: [
+            ...options.locales.map((locale) => ({ text: locale.text, data: locale.data })),
+            { text: options.cancelText, role: 'cancel' },
+        ],
+    });
+    await actionSheet.present();
+    const { data } = await actionSheet.onDidDismiss();
+    if (options.enabled && data && data !== options.currentLocale) {
+        sessionStorage.setItem(options.pathnameStorageKey, options.currentPath);
+        localStorage.setItem('locale', data);
+        window.location.replace(options.buildRedirectUrl(data));
+    }
+};
+
 /**
  * Work around iOS `ion-input` autofill values not propagating to the Angular form model.
  *
@@ -687,6 +738,323 @@ const kitKeyboardInit = async (elementRef, type) => {
     ];
 };
 
+/**
+ * Injection token carrying the {@link KitThemeConfig} for `KitThemeController`.
+ *
+ * @remarks
+ * Provide it through {@link provideKitTheme} rather than registering it directly.
+ */
+const KIT_THEME_CONFIG = new InjectionToken('@rdlabo/ionic-angular-kit:theme');
+/**
+ * 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'],
+ *     }),
+ *   ],
+ * });
+ * ```
+ */
+const provideKitTheme = (config) => makeEnvironmentProviders([{ provide: KIT_THEME_CONFIG, useValue: config }]);
+
+/**
+ * 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);
+ * ```
+ */
+class KitThemeController {
+    constructor() {
+        this.#storage = inject(KitStorageService);
+        this.#document = inject(DOCUMENT);
+        this.#config = inject(KIT_THEME_CONFIG);
+        /**
+         * 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.
+         */
+        this.themeSubject = new BehaviorSubject('light');
+    }
+    #storage;
+    #document;
+    #config;
+    #prefersDark;
+    #onSystemThemeChange;
+    /**
+     * 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
+     */
+    async setDefaultThemeMode() {
+        const stored = await this.#storage.get(this.#config.storageKey);
+        if (stored) {
+            // 保存済みの選択を強制し、OS 追従は解除する。
+            this.#unwatchSystemTheme();
+            return this.#applyTheme(stored === 'dark');
+        }
+        // 未保存 → OS の設定に追従する。
+        this.#watchSystemTheme();
+    }
+    /**
+     * 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
+     */
+    async changeTheme(isDark) {
+        this.#unwatchSystemTheme();
+        await this.#storage.set(this.#config.storageKey, isDark ? 'dark' : 'light');
+        await this.#applyTheme(isDark);
+    }
+    #watchSystemTheme() {
+        if (this.#prefersDark) {
+            // 既に監視中なら二重登録しない（冪等）。
+            return;
+        }
+        this.#prefersDark = window.matchMedia('(prefers-color-scheme: dark)');
+        this.#onSystemThemeChange = (e) => void this.#applyTheme(e.matches);
+        this.#prefersDark.addEventListener('change', this.#onSystemThemeChange, { passive: true });
+        void this.#applyTheme(this.#prefersDark.matches);
+    }
+    #unwatchSystemTheme() {
+        if (this.#prefersDark && this.#onSystemThemeChange) {
+            this.#prefersDark.removeEventListener('change', this.#onSystemThemeChange);
+        }
+        this.#prefersDark = undefined;
+        this.#onSystemThemeChange = undefined;
+    }
+    async #applyTheme(isDark) {
+        if (Capacitor.isNativePlatform() && Capacitor.getPlatform() === 'android') {
+            await StatusBar.setStyle({ style: isDark ? Style.Dark : Style.Light });
+        }
+        const root = this.#document.documentElement;
+        for (const cls of this.#config.darkClasses) {
+            root.classList.toggle(cls, isDark);
+        }
+        for (const cls of this.#config.lightClasses) {
+            root.classList.toggle(cls, !isDark);
+        }
+        this.themeSubject.next(isDark ? 'dark' : 'light');
+    }
+    static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitThemeController, deps: [], target: i0.ɵɵFactoryTarget.Injectable }); }
+    static { this.ɵprov = i0.ɵɵngDeclareInjectable({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitThemeController, providedIn: 'root' }); }
+}
+i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "21.2.17", ngImport: i0, type: KitThemeController, decorators: [{
+            type: Injectable,
+            args: [{
+                    providedIn: 'root',
+                }]
+        }] });
+
+/**
+ * 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 });
+ * ```
+ */
+const kitRequestReview = async (options) => {
+    if (!Capacitor.isNativePlatform()) {
+        return;
+    }
+    await new Promise((resolve) => setTimeout(() => resolve(), 1000));
+    const threshold = new Date();
+    threshold.setMonth(threshold.getMonth() - options.throttleMonths);
+    const { value } = await Preferences.get({ key: options.storageKey });
+    if (!value || new Date(Number(value)).getTime() < threshold.getTime()) {
+        await InAppReview.requestReview();
+        await Preferences.set({ key: options.storageKey, value: new Date().getTime().toString() });
+    }
+};
+
+/**
+ * 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
+ */
+const kitRotationImage = async (imageData) => {
+    const imgType = imageData.substring(5, imageData.indexOf(';'));
+    const image = new Image();
+    const loaded = () => new Promise((resolve) => {
+        image.onload = () => resolve();
+    });
+    setTimeout(() => (image.src = imageData));
+    await loaded();
+    const canvas = document.createElement('canvas');
+    const ctx = canvas.getContext('2d');
+    canvas.width = image.height;
+    canvas.height = image.width;
+    ctx.rotate((90 * Math.PI) / 180);
+    ctx.translate(0, -image.height);
+    ctx.drawImage(image, 0, 0, image.width, image.height);
+    return canvas.toDataURL(imgType);
+};
+/**
+ * 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();
+ * ```
+ */
+const kitDomToPng = async (element, options) => {
+    await new Promise((resolve) => requestAnimationFrame(resolve));
+    const { clientHeight, clientWidth } = element;
+    // デバイス毎の問題解決のため、px 調整。
+    // iOS: ないと下が途切れる。Android: あると黒線が入る。
+    const addClient = Capacitor.getPlatform() === 'ios' ? 2 : 0;
+    const dataUrl = await new Promise((resolve) => {
+        void (async () => {
+            for (let i = 0; i < 10; i++) {
+                const url = await domtoimage.toPng(element, {
+                    width: clientWidth + addClient,
+                    height: clientHeight + addClient,
+                    scale: options?.scale ?? 3,
+                    copyDefaultStyles: false,
+                });
+                if (url) {
+                    resolve(url);
+                    return;
+                }
+            }
+            resolve('');
+        })();
+    });
+    return options?.rotate ? kitRotationImage(dataUrl) : dataUrl;
+};
+/**
+ * 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 });
+ * ```
+ */
+const kitBuildBrotherPrintSettings = (params) => {
+    const startPoint = params.printBase64.indexOf(',');
+    const tapeSize = params.label.match(/W(\d+)H(\d+)/);
+    const tapeWidth = tapeSize && tapeSize.length >= 2 ? parseInt(tapeSize[1], 10) : 0;
+    const tapeLength = tapeSize && tapeSize.length >= 3 ? parseInt(tapeSize[2], 10) : 0;
+    // `BRLMPrintOptions` is a `QL | TD` union; a die-cut label legitimately carries fields from both
+    // groups, so the object is composed via spreads to bypass the union's excess-property checks — the
+    // same technique the source printer services used.
+    return {
+        ...{
+            modelName: params.modelName,
+            encodedImage: params.printBase64.slice(startPoint + 1),
+            numberOfCopies: params.numberOfCopies,
+            autoCut: true,
+            scaleMode: BRLMPrinterScaleMode.FitPageAspect,
+            imageRotation: BRLMPrinterImageRotation.Rotate0,
+            verticalAlignment: BRLMPrinterVerticalAlignment.Center,
+            horizontalAlignment: BRLMPrinterHorizontalAlignment.Center,
+            printQuality: BRLMPrinterPrintQuality.Best,
+        },
+        ...{
+            labelName: params.label,
+        },
+        ...{
+            paperType: BRLMPrinterCustomPaperType.dieCutPaper,
+            paperUnit: BRLMPrinterCustomPaperUnit.mm,
+            halftone: BRLMPrinterHalftone.Threshold,
+            halftoneThreshold: params.halftoneThreshold,
+            tapeWidth: Number(tapeWidth.toFixed(1)),
+            tapeLength: Number(tapeLength.toFixed(1)),
+            gapLength: 2.0,
+            marginTop: 1.0,
+            marginRight: 2.0,
+            marginBottom: 1.0,
+            marginLeft: 2.0,
+            paperMarkPosition: 0,
+            paperMarkLength: 0,
+        },
+    };
+};
+
 /**
  * Injection token that carries the {@link KitAuthConfig} to the authentication guards.
  */
@@ -1175,6 +1543,67 @@ const disableHandler = async (event, work) => {
     target.disabled = false;
 };
 
+/**
+ * Toggle the `disabled` flag of a signal-held `ion-infinite-scroll` / `ion-refresher` element.
+ *
+ * @remarks
+ * A tiny pure helper for the common pattern of stashing the completing scroll/refresher element in a
+ * signal (e.g. captured from the event) and later enabling/disabling it — for instance disabling
+ * infinite scroll once the last page has loaded. A no-op when the signal holds no element.
+ *
+ * @param completeEvent - a writable signal holding the infinite-scroll / refresher element (or nullish)
+ * @param disabled - the value to set on the element's `disabled` property
+ * @example
+ * ```ts
+ * const infinite = signal<HTMLIonInfiniteScrollElement | null>(null);
+ * // ...on ionInfinite: infinite.set(ev.target); ...when no more pages:
+ * kitChangeEventDisabled(infinite, true);
+ * ```
+ */
+const kitChangeEventDisabled = (completeEvent, disabled) => {
+    completeEvent.update((event) => {
+        if (event) {
+            event.disabled = disabled;
+        }
+        return event;
+    });
+};
+
+/**
+ * Observe an Ionic page's "is currently entered" state from its lifecycle DOM events.
+ *
+ * @remarks
+ * Emits `true` on `ionViewDidEnter` and `false` on `ionViewWillEnter` / `ionViewWillLeave`, seeded
+ * with `false` via `startWith`. Useful to pause/resume work (timers, video, expensive rendering)
+ * while a page is off-screen in Ionic's stack navigation, without wiring the four lifecycle hooks by
+ * hand. The listeners are removed when the Observable is unsubscribed.
+ *
+ * @param el - an `ElementRef` for the page host element (the `ion-page`)
+ * @returns an Observable that emits whether the page is currently entered
+ * @example
+ * ```ts
+ * export class FeedPage {
+ *   readonly #host = inject(ElementRef);
+ *   readonly isEntered = toSignal(kitCreateDidEnter(this.#host), { initialValue: false });
+ * }
+ * ```
+ */
+const kitCreateDidEnter = (el) => {
+    return new Observable((observer) => {
+        const willEnter = () => observer.next(false);
+        const didEnter = () => observer.next(true);
+        const willLeave = () => observer.next(false);
+        el.nativeElement.addEventListener('ionViewWillEnter', willEnter);
+        el.nativeElement.addEventListener('ionViewDidEnter', didEnter);
+        el.nativeElement.addEventListener('ionViewWillLeave', willLeave);
+        return () => {
+            el.nativeElement.removeEventListener('ionViewWillEnter', willEnter);
+            el.nativeElement.removeEventListener('ionViewDidEnter', didEnter);
+            el.nativeElement.removeEventListener('ionViewWillLeave', willLeave);
+        };
+    }).pipe(startWith(false));
+};
+
 /*
  * Public API Surface of @rdlabo/ionic-angular-kit
  */
@@ -1184,5 +1613,5 @@ const disableHandler = async (event, work) => {
  * Generated bundle index. Do not edit.
  */
 
-export { KIT_AUTH_CONFIG, KIT_HTTP_CONFIG, KIT_OVERLAY_CONFIG, KitAutofillDirective, KitOverlayController, KitReloadAlertController, KitStorageService, arrayConcatById, disableHandler, kitAuthInterceptor, kitImpact, kitKeyboardInit, kitPresentAuthFailedAlert, kitRequireAuthorizedGuard, kitRequireConfirmingGuard, kitRequiredUnauthorizedGuard, objectEqual, provideKitAuth, provideKitHttp, provideKitOverlay };
+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 };
 //# sourceMappingURL=rdlabo-ionic-angular-kit.mjs.map