@rdlabo/ionic-angular-kit 0.0.2 → 0.0.3

package/src/lib/overlay/overlay-config.ts

@@ -0,0 +1,53 @@
+import type { EnvironmentProviders } from '@angular/core';
+import { InjectionToken, makeEnvironmentProviders } from '@angular/core';
+
+/**
+ * User-visible button labels consumed by `KitOverlayController`.
+ *
+ * @remarks
+ * The kit deliberately ships no i18n strings of its own and has no hard dependency on
+ * `@angular/localize`. The consuming application always provides these labels: multilingual apps
+ * pass `$localize`-resolved strings, single-language apps pass plain literals.
+ */
+export interface KitLabels {
+  /** Text for the "close" button used by alerts and toasts. */
+  readonly close: string;
+  /** Text for the "cancel" button used by confirmation alerts. */
+  readonly cancel: string;
+}
+
+/**
+ * Overlay configuration injected via `provideKitOverlay()`.
+ *
+ * @remarks
+ * All fields are required; the consuming application must supply a complete configuration.
+ */
+export interface KitOverlayConfig {
+  /** Button labels used across the overlays presented by `KitOverlayController`. */
+  readonly labels: KitLabels;
+}
+
+/**
+ * Injection token carrying the {@link KitOverlayConfig} for `KitOverlayController`.
+ *
+ * @remarks
+ * Provide it through {@link provideKitOverlay} rather than registering it directly.
+ */
+export const KIT_OVERLAY_CONFIG = new InjectionToken<KitOverlayConfig>('@rdlabo/ionic-angular-kit:overlay');
+
+/**
+ * Wire `KitOverlayController` into the application by providing its button labels.
+ *
+ * @param config - overlay configuration, including the button labels to inject
+ * @returns environment providers to add to the application's provider list
+ * @example
+ * ```ts
+ * bootstrapApplication(AppComponent, {
+ *   providers: [
+ *     provideKitOverlay({ labels: { close: $localize`Close`, cancel: $localize`Cancel` } }),
+ *   ],
+ * });
+ * ```
+ */
+export const provideKitOverlay = (config: KitOverlayConfig): EnvironmentProviders =>
+  makeEnvironmentProviders([{ provide: KIT_OVERLAY_CONFIG, useValue: config }]);

package/src/lib/storage/kit-storage.service.spec.ts

@@ -0,0 +1,127 @@
+import { provideZonelessChangeDetection } from '@angular/core';
+import { TestBed } from '@angular/core/testing';
+
+import { KitStorageService } from './kit-storage.service';
+
+// ---------------------------------------------------------------------------
+// Fake storage engine (in-memory Map)
+// ---------------------------------------------------------------------------
+class FakeStorageEngine {
+  private readonly store = new Map<string, unknown>();
+  async set(key: string, value: unknown): Promise<void> {
+    this.store.set(key, value);
+  }
+  async get(key: string): Promise<unknown | null> {
+    return this.store.has(key) ? this.store.get(key) : null;
+  }
+  async remove(key: string): Promise<void> {
+    this.store.delete(key);
+  }
+  async clear(): Promise<void> {
+    this.store.clear();
+  }
+  async keys(): Promise<string[]> {
+    return [...this.store.keys()];
+  }
+}
+
+// Fake @ionic/storage-angular Storage class — create() resolves to FakeStorageEngine.
+// We do NOT vi.mock the module; instead we provide this value directly as the DI token
+// to avoid ESM/transform issues with the real package.
+class FakeStorage {
+  create() {
+    return Promise.resolve(new FakeStorageEngine());
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+describe('KitStorageService', () => {
+  let service: KitStorageService;
+
+  // We need the real Storage class as the DI token.  Import it lazily to
+  // avoid hard-wiring an ESM import at module-top level where Vitest might
+  // not have transformed it yet.  Using vi.mock avoids the issue entirely.
+  beforeEach(async () => {
+    // Dynamically import so the vi.mock below (hoisted) takes effect first.
+    const { Storage } = await import('@ionic/storage-angular');
+
+    TestBed.configureTestingModule({
+      providers: [provideZonelessChangeDetection(), KitStorageService, { provide: Storage, useValue: new FakeStorage() }],
+    });
+    service = TestBed.inject(KitStorageService);
+  });
+
+  it('set → get round-trip for string', async () => {
+    await service.set<string>('key', 'hello');
+    const result = await service.get<string>('key');
+    expect(result).toBe('hello');
+  });
+
+  it('set → get round-trip for object', async () => {
+    const obj = { a: 1, b: true };
+    await service.set('obj', obj);
+    const result = await service.get<typeof obj>('obj');
+    expect(result).toEqual(obj);
+  });
+
+  it('get returns null for a missing key', async () => {
+    const result = await service.get<string>('does-not-exist');
+    expect(result).toBeNull();
+  });
+
+  it('remove deletes the key so get returns null', async () => {
+    await service.set('x', 42);
+    await service.remove('x');
+    const result = await service.get<number>('x');
+    expect(result).toBeNull();
+  });
+
+  it('clear removes all keys', async () => {
+    await service.set('a', 1);
+    await service.set('b', 2);
+    await service.clear();
+    expect(await service.get('a')).toBeNull();
+    expect(await service.get('b')).toBeNull();
+    expect(await service.keys()).toEqual([]);
+  });
+
+  it('keys returns every stored key', async () => {
+    await service.set('p', 1);
+    await service.set('q', 2);
+    const result = await service.keys();
+    expect(result).toContain('p');
+    expect(result).toContain('q');
+    expect(result).toHaveLength(2);
+  });
+
+  it('set called without separate init is not lost (readiness guarantee)', async () => {
+    // Create a fresh service in a fresh TestBed for this isolation test.
+    // The key contract: the service never requires the caller to separately
+    // "await storage.create()" before using it — #ready handles that internally.
+    const { Storage } = await import('@ionic/storage-angular');
+    let resolveCreate!: (engine: FakeStorageEngine) => void;
+    const engine = new FakeStorageEngine();
+    const delayedStorage = {
+      // create() returns a promise that we control manually
+      create: () => new Promise<FakeStorageEngine>((r) => (resolveCreate = r)),
+    };
+
+    TestBed.resetTestingModule();
+    TestBed.configureTestingModule({
+      providers: [provideZonelessChangeDetection(), KitStorageService, { provide: Storage, useValue: delayedStorage }],
+    });
+    const svc = TestBed.inject(KitStorageService);
+
+    // Issue a set before storage is ready
+    const setPromise = svc.set('early', 'value');
+    // Now resolve the storage creation
+    resolveCreate(engine);
+    await setPromise;
+
+    // Verify the set was not lost
+    const result = await svc.get<string>('early');
+    expect(result).toBe('value');
+  });
+});

package/src/lib/storage/kit-storage.service.ts

@@ -0,0 +1,91 @@
+import { inject, Injectable } from '@angular/core';
+import { Storage } from '@ionic/storage-angular';
+
+/**
+ * Thin, typed wrapper around `@ionic/storage-angular`.
+ *
+ * Starts `create()` exactly once and stores the resulting ready Promise. Every operation awaits
+ * that Promise before touching the underlying store, so calls made before initialization completes
+ * are queued rather than dropped.
+ *
+ * @remarks
+ * A naive wrapper that reads the store synchronously would silently no-op (or throw) when invoked
+ * before `create()` resolves, losing early writes. Awaiting the one-time ready Promise on every
+ * operation removes that race without forcing callers to coordinate initialization themselves.
+ *
+ * @example
+ * ```ts
+ * constructor(private readonly storage: KitStorageService) {}
+ *
+ * async ngOnInit(): Promise<void> {
+ *   await this.storage.set('token', 'abc123');
+ *   const token = await this.storage.get<string>('token');
+ * }
+ * ```
+ */
+@Injectable({
+  providedIn: 'root',
+})
+export class KitStorageService {
+  /** One-time `create()` ready Promise; awaited before every operation so early calls are not lost. */
+  readonly #ready: Promise<Storage> = inject(Storage).create();
+
+  /**
+   * Persist a value under the given key.
+   *
+   * @typeParam T - type of the value being stored
+   * @param key - key to store the value under
+   * @param value - value to persist; overwrites any existing value for the key
+   * @returns a Promise that resolves once the value has been written
+   * @example
+   * ```ts
+   * await storage.set('user', { id: 1, name: 'Ada' });
+   * ```
+   */
+  async set<T>(key: string, value: T): Promise<void> {
+    await (await this.#ready).set(key, value);
+  }
+
+  /**
+   * Read the value stored under the given key.
+   *
+   * @typeParam T - expected type of the stored value
+   * @param key - key to read
+   * @returns the stored value, or `null` when the key is absent
+   * @example
+   * ```ts
+   * const user = await storage.get<{ id: number }>('user');
+   * ```
+   */
+  async get<T>(key: string): Promise<T | null> {
+    return (await (await this.#ready).get(key)) ?? null;
+  }
+
+  /**
+   * Remove the value stored under the given key.
+   *
+   * @param key - key to remove; a no-op when the key is absent
+   * @returns a Promise that resolves once the key has been removed
+   */
+  async remove(key: string): Promise<void> {
+    await (await this.#ready).remove(key);
+  }
+
+  /**
+   * Remove every key/value pair from the store.
+   *
+   * @returns a Promise that resolves once the store has been emptied
+   */
+  async clear(): Promise<void> {
+    await (await this.#ready).clear();
+  }
+
+  /**
+   * List every key currently present in the store.
+   *
+   * @returns an array of all stored keys
+   */
+  async keys(): Promise<string[]> {
+    return (await this.#ready).keys();
+  }
+}

package/src/lib/utils/array.spec.ts

@@ -0,0 +1,33 @@
+import { arrayConcatById } from './array';
+
+interface Row {
+  id: number;
+  label: string;
+}
+
+describe('arrayConcatById', () => {
+  it('returns [] when both inputs are empty', () => {
+    expect(arrayConcatById<Row>([], [], 'id')).toEqual([]);
+  });
+
+  it('merges new rows over old by key and sorts DESC by default', () => {
+    const old: Row[] = [
+      { id: 3, label: 'old-3' },
+      { id: 2, label: 'old-2' },
+      { id: 1, label: 'old-1' },
+    ];
+    const fresh: Row[] = [
+      { id: 3, label: 'new-3' },
+      { id: 2, label: 'new-2' },
+    ];
+    const result = arrayConcatById<Row>(old, fresh, 'id');
+    expect(result.map((r) => r.id)).toEqual([3, 2, 1]);
+    expect(result.find((r) => r.id === 3)?.label).toBe('new-3');
+    expect(result.find((r) => r.id === 1)?.label).toBe('old-1');
+  });
+
+  it('sorts ASC when requested', () => {
+    const result = arrayConcatById<Row>([{ id: 1, label: 'a' }], [{ id: 2, label: 'b' }], 'id', 'ASC');
+    expect(result.map((r) => r.id)).toEqual([1, 2]);
+  });
+});

package/src/lib/utils/array.ts

@@ -0,0 +1,82 @@
+/**
+ * Merge a newly fetched page of items into an existing list by id, keeping the result sorted.
+ *
+ * Items are merged by the numeric `key` field. On a duplicate `key` the item from `arrayNew` wins
+ * and replaces the one in `arrayOld`. Old items whose `key` falls *inside* the window spanned by
+ * `arrayNew` (between its first and last `key`) are dropped, since the freshly fetched page is the
+ * authoritative copy of that window; old items *outside* the window are kept. The merged items are
+ * finally sorted by `key`, ascending or descending according to `order`.
+ *
+ * The algorithm is:
+ * 1. If both inputs are empty, return an empty array.
+ * 2. Read the first (`lead`) and last (`last`) `key` values of `arrayNew` as the bounds of the
+ *    page's window. Keep the old items whose `key` lies *outside* that window (at or beyond the
+ *    extremes) and drop those strictly inside it, handling both a high-to-low page (`lead > last`)
+ *    and a low-to-high page (`lead < last`). A single-value page (`lead === last`) keeps all old items.
+ * 3. Remove old items whose `key` already exists in `arrayNew` (new wins on duplicates).
+ * 4. Concatenate `arrayNew` with the surviving old items and sort by `key` in the requested
+ *    direction.
+ *
+ * @remarks
+ * Designed for infinite-scroll / paginated list merging, where each fetched page may overlap the
+ * previously held items and the server returns a contiguous, ordered window of records. The `key`
+ * field is treated as a number for range comparison and sorting.
+ *
+ * @typeParam T - Element type of both arrays. Its `key` property must be a numeric value.
+ * @param arrayOld - The previously accumulated list. May be empty or nullish-safe (empty when falsy).
+ * @param arrayNew - The newly fetched page of items; its `key` range defines the window that its own
+ *   items replace, and its items take precedence on duplicates.
+ * @param key - The property of `T` used as the unique, numeric id for matching, range filtering, and sorting.
+ * @param order - Sort direction by `key`: `'ASC'` for ascending or `'DESC'` for descending. Defaults to `'DESC'`.
+ * @returns A new array containing `arrayNew` merged with the out-of-window, non-duplicate old items, sorted by `key`.
+ * @example
+ * ```ts
+ * interface Post {
+ *   id: number;
+ *   title: string;
+ * }
+ *
+ * const loaded: Post[] = [
+ *   { id: 30, title: 'c' },
+ *   { id: 20, title: 'b' },
+ *   { id: 10, title: 'a' },
+ * ];
+ * const nextPage: Post[] = [
+ *   { id: 20, title: 'b (updated)' },
+ *   { id: 15, title: 'a.5' },
+ * ];
+ *
+ * // Descending merge: id 30 lies above the new page's [15, 20] window so it is kept; id 20 is
+ * // inside the window and is replaced by the new value; id 10 lies below the window and is kept.
+ * const merged = arrayConcatById(loaded, nextPage, 'id', 'DESC');
+ * // => [{ id: 30, title: 'c' }, { id: 20, title: 'b (updated)' }, { id: 15, title: 'a.5' }, { id: 10, title: 'a' }]
+ * ```
+ */
+export const arrayConcatById = <T>(arrayOld: T[], arrayNew: T[], key: keyof T, order: 'ASC' | 'DESC' = 'DESC'): T[] => {
+  if (!arrayNew.length && !arrayOld.length) {
+    return [];
+  }
+  const lead = arrayNew[0][key] as number;
+  const last = arrayNew[arrayNew.length - 1][key] as number;
+
+  const filteredOld = (arrayOld || []).filter((vol) => {
+    const value = vol[key] as number;
+    return (lead > last && (value >= lead || value <= last)) || (lead < last && (value <= lead || value >= last)) || lead === last;
+  });
+
+  const oldData = filteredOld.filter((vol) => !arrayNew.some((element) => element[key] === vol[key]));
+  const data = arrayNew.concat(oldData);
+
+  const direction = order === 'ASC' ? 1 : -1;
+  return data.sort((a, b) => {
+    const x = a[key] as number;
+    const y = b[key] as number;
+    if (x > y) {
+      return direction;
+    }
+    if (x < y) {
+      return direction * -1;
+    }
+    return 0;
+  });
+};

package/src/lib/utils/haptics.ts

@@ -0,0 +1,32 @@
+import { Capacitor } from '@capacitor/core';
+import { Haptics, ImpactStyle } from '@capacitor/haptics';
+
+/**
+ * Trigger native haptic impact feedback.
+ *
+ * Delegates to `@capacitor/haptics` `Haptics.impact()` when running on a native platform. On the
+ * web (or any non-native platform) it is a no-op and resolves without doing anything.
+ *
+ * @remarks
+ * This haptic side effect was previously bundled implicitly into toast/modal presentation. It has
+ * been decoupled into this explicit function so callers opt in to the feedback deliberately, rather
+ * than receiving it as a hidden side effect of presenting UI.
+ *
+ * @param style - The impact intensity to play. Defaults to {@link ImpactStyle.Light}.
+ * @returns A promise that resolves once the feedback has been requested (immediately on the web).
+ * @example
+ * ```ts
+ * import { ImpactStyle } from '@capacitor/haptics';
+ *
+ * // Light tap (default)
+ * await kitImpact();
+ *
+ * // Stronger feedback, e.g. on a confirming action
+ * await kitImpact(ImpactStyle.Heavy);
+ * ```
+ */
+export const kitImpact = async (style: ImpactStyle = ImpactStyle.Light): Promise<void> => {
+  if (Capacitor.isNativePlatform()) {
+    await Haptics.impact({ style });
+  }
+};

package/src/public-api.ts

@@ -0,0 +1,24 @@
+/*
+ * Public API Surface of @rdlabo/ionic-angular-kit
+ */
+
+// Storage: typed wrapper around the platform key/value store.
+export * from './lib/storage/kit-storage.service';
+
+// Overlay: wrapper around the Ionic Modal / Toast / Alert controllers.
+export * from './lib/overlay/overlay-config';
+export * from './lib/overlay/kit-overlay.controller';
+export * from './lib/overlay/kit-reload-alert.controller';
+
+// Directives.
+export * from './lib/directives/autofill.directive';
+
+// Auth: functional route guards.
+export * from './lib/auth/auth-guards';
+
+// HTTP: functional interceptor.
+export * from './lib/http/kit-http.interceptor';
+
+// Utils: framework-agnostic pure helpers.
+export * from './lib/utils/haptics';
+export * from './lib/utils/array';

package/tsconfig.lib.json

@@ -0,0 +1,14 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/lib",
+    "declaration": true,
+    "declarationMap": true,
+    "inlineSources": true,
+    "types": []
+  },
+  "include": ["src/**/*.ts"],
+  "exclude": ["**/*.spec.ts"]
+}

package/tsconfig.lib.prod.json

@@ -0,0 +1,11 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "./tsconfig.lib.json",
+  "compilerOptions": {
+    "declarationMap": false
+  },
+  "angularCompilerOptions": {
+    "compilationMode": "partial"
+  }
+}

package/tsconfig.spec.json

@@ -0,0 +1,10 @@
+/* To learn more about Typescript configuration file: https://www.typescriptlang.org/docs/handbook/tsconfig-json.html. */
+/* To learn more about Angular compiler options: https://angular.dev/reference/configs/angular-compiler-options. */
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "../../out-tsc/spec",
+    "types": ["vitest/globals"]
+  },
+  "include": ["src/**/*.d.ts", "src/**/*.spec.ts"]
+}