@rdlabo/ionic-angular-kit 0.0.3 → 0.0.4

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

@@ -1,53 +0,0 @@
-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

@@ -1,127 +0,0 @@
-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

@@ -1,91 +0,0 @@
-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

@@ -1,33 +0,0 @@
-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

@@ -1,82 +0,0 @@
-/**
- * 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

@@ -1,32 +0,0 @@
-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

@@ -1,24 +0,0 @@
-/*
- * 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

@@ -1,14 +0,0 @@
-/* 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

@@ -1,11 +0,0 @@
-/* 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

@@ -1,10 +0,0 @@
-/* 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"]
-}