@rdlabo/ionic-angular-kit 0.0.13 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rdlabo/ionic-angular-kit",
-  "version": "0.0.13",
+  "version": "0.0.15",
   "peerDependencies": {
     "@angular/common": "^21.0.0",
     "@angular/core": "^21.0.0",
@@ -18,6 +18,23 @@
     "dom-to-image-more": "^3.0.0",
     "rxjs": "^7.8.0"
   },
+  "peerDependenciesMeta": {
+    "@capacitor/preferences": {
+      "optional": true
+    },
+    "@capacitor/status-bar": {
+      "optional": true
+    },
+    "@capacitor-community/in-app-review": {
+      "optional": true
+    },
+    "@rdlabo/capacitor-brotherprint": {
+      "optional": true
+    },
+    "dom-to-image-more": {
+      "optional": true
+    }
+  },
   "dependencies": {
     "tslib": "^2.3.0"
   },
@@ -31,6 +48,18 @@
     ".": {
       "types": "./types/rdlabo-ionic-angular-kit.d.ts",
       "default": "./fesm2022/rdlabo-ionic-angular-kit.mjs"
+    },
+    "./printer": {
+      "types": "./types/rdlabo-ionic-angular-kit-printer.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-printer.mjs"
+    },
+    "./review": {
+      "types": "./types/rdlabo-ionic-angular-kit-review.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-review.mjs"
+    },
+    "./theme": {
+      "types": "./types/rdlabo-ionic-angular-kit-theme.d.ts",
+      "default": "./fesm2022/rdlabo-ionic-angular-kit-theme.mjs"
     }
   },
   "type": "module"

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

@@ -0,0 +1,81 @@
+import { BRLMPrinterModelName, BRLMPrinterLabelName, BRLMPrintOptions } from '@rdlabo/capacitor-brotherprint';
+
+/**
+ * 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;
+
+export { kitBuildBrotherPrintSettings, kitDomToPng, kitRotationImage };
+export type { KitBrotherPrintSettingsParams, KitDomToPngOptions };

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

@@ -0,0 +1,45 @@
+/**
+ * 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>;
+
+export { kitRequestReview };
+export type { KitRequestReviewOptions };

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

@@ -0,0 +1,116 @@
+import * as i0 from '@angular/core';
+import { InjectionToken, EnvironmentProviders } from '@angular/core';
+import { BehaviorSubject } from 'rxjs';
+
+/**
+ * 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>;
+}
+
+export { KIT_THEME_CONFIG, KitThemeController, provideKitTheme };
+export type { KitThemeConfig, KitThemeMode };