@lenne.tech/ng-base 18.1.3 → 22.0.0

package/types/lenne.tech-ng-base-testing.d.ts

@@ -0,0 +1,327 @@
+import { APIRequestContext, APIResponse, Page } from "@playwright/test";
+/**
+ * Default timeout for hydration waiting (in milliseconds)
+ */
+export declare const DEFAULT_HYDRATION_TIMEOUT = 15000;
+/**
+ * Wait for Angular hydration to complete
+ *
+ * `provideLtNgBase()` sets `window.__ltNgBaseHydrated = true` once the app is stable in the browser
+ * (`ApplicationRef.whenStable()`), which is after hydration finished. Event replay (`withEventReplay()`) keeps
+ * input made before that moment, but assertions on component state are only reliable afterwards.
+ *
+ * @param page - Playwright page object
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait (default: 15000ms)
+ *
+ * @example
+ * ```typescript
+ * await waitForHydration(page);
+ * await page.click('button'); // Now safe to interact
+ * ```
+ */
+export declare function waitForHydration(page: Page, options?: {
+  timeout?: number;
+}): Promise<void>;
+/**
+ * Navigate to URL and wait for Angular hydration to complete
+ *
+ * Combines page.goto() with hydration waiting. Use this instead of
+ * page.goto() when you need to interact with Vue components immediately.
+ *
+ * @param page - Playwright page object
+ * @param url - URL to navigate to (relative or absolute)
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait for hydration (default: 15000ms)
+ *
+ * @example
+ * ```typescript
+ * await gotoAndWaitForHydration(page, '/auth/login');
+ * // Page is now hydrated and ready for interaction
+ * ```
+ */
+export declare function gotoAndWaitForHydration(page: Page, url: string, options?: {
+  timeout?: number;
+}): Promise<void>;
+/**
+ * Wait for URL navigation and then Angular hydration
+ *
+ * Use after form submissions or actions that trigger navigation.
+ * Ensures both the navigation completes AND the new page is hydrated.
+ *
+ * @param page - Playwright page object
+ * @param url - URL pattern to wait for (string or RegExp)
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait for URL (default: 30000ms)
+ * @param options.hydrationTimeout - Maximum time to wait for hydration (default: 15000ms)
+ *
+ * @example
+ * ```typescript
+ * await page.click('button[type="submit"]');
+ * await waitForURLAndHydration(page, /\/dashboard/);
+ * ```
+ */
+export declare function waitForURLAndHydration(page: Page, url: string | RegExp, options?: {
+  timeout?: number;
+  hydrationTimeout?: number;
+}): Promise<void>;
+/**
+ * Fill an input field with proper Vue 3 reactivity support
+ *
+ * Uses keyboard typing instead of Playwright's fill() to properly
+ * trigger Vue's v-model updates. This is necessary because fill()
+ * sets the value directly without firing input events in some cases.
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the input element
+ * @param value - Value to type into the input
+ * @param options - Configuration options
+ * @param options.delay - Delay between keystrokes in ms (default: 5)
+ * @param options.clear - Whether to clear existing content (default: true)
+ *
+ * @example
+ * ```typescript
+ * await fillInput(page, 'input[name="email"]', 'test@example.com');
+ * await fillInput(page, '#password', 'secret', { delay: 10 });
+ * ```
+ */
+export declare function fillInput(page: Page, selector: string, value: string, options?: {
+  delay?: number;
+  clear?: boolean;
+}): Promise<void>;
+/**
+ * Fill multiple input fields at once
+ *
+ * Convenience function for filling multiple form fields.
+ *
+ * @param page - Playwright page object
+ * @param fields - Object mapping selectors to values
+ * @param options - Configuration options passed to fillInput
+ *
+ * @example
+ * ```typescript
+ * await fillInputs(page, {
+ *   'input[name="email"]': 'test@example.com',
+ *   'input[name="password"]': 'secret123',
+ * });
+ * ```
+ */
+export declare function fillInputs(page: Page, fields: Record<string, string>, options?: {
+  delay?: number;
+  clear?: boolean;
+}): Promise<void>;
+/**
+ * Test user credentials interface
+ */
+interface TestUser {
+  email: string;
+  password: string;
+  name: string;
+}
+/**
+ * Generate unique test user credentials
+ *
+ * Creates unique email, password, and name for test isolation.
+ * Each call generates different credentials to avoid test conflicts.
+ *
+ * @param prefix - Prefix for the email address (default: 'e2e')
+ * @returns Object with email, password, and name
+ *
+ * @example
+ * ```typescript
+ * const user = generateTestUser('auth-test');
+ * // { email: 'auth-test-abc123@test.com', password: 'TestPassabc123!', name: 'E2E Test User auth-test' }
+ * ```
+ */
+export declare function generateTestUser(prefix?: string): TestUser;
+/**
+ * Generate a random string for test data
+ *
+ * @param length - Length of the string (default: 8)
+ * @param charset - Characters to use (default: alphanumeric)
+ *
+ * @example
+ * ```typescript
+ * const id = generateRandomString(12);
+ * const code = generateRandomString(6, '0123456789');
+ * ```
+ */
+export declare function generateRandomString(length?: number, charset?: string): string;
+/**
+ * Generate a TOTP code from a secret (RFC 6238)
+ *
+ * Implements the Time-based One-Time Password algorithm for testing
+ * 2FA functionality. Compatible with Google Authenticator and similar apps.
+ *
+ * @param secret - Base32-encoded TOTP secret
+ * @param options - Configuration options
+ * @param options.digits - Number of digits in the code (default: 6)
+ * @param options.period - Time period in seconds (default: 30)
+ * @param options.algorithm - Hash algorithm (default: 'sha1')
+ * @returns 6-digit TOTP code as string
+ *
+ * @example
+ * ```typescript
+ * const secret = 'JBSWY3DPEHPK3PXP';
+ * const code = generateTOTP(secret);
+ * await page.fill('input[name="code"]', code);
+ * ```
+ */
+export declare function generateTOTP(secret: string, options?: {
+  digits?: number;
+  period?: number;
+  algorithm?: 'sha1' | 'sha256' | 'sha512';
+}): string;
+/**
+ * Extract TOTP secret from otpauth:// URL
+ *
+ * Parses the secret parameter from a TOTP QR code URL.
+ *
+ * @param otpauthUrl - The otpauth:// URL (or data URL containing it)
+ * @returns The extracted secret, or null if not found
+ *
+ * @example
+ * ```typescript
+ * const qrSrc = await page.locator('img[alt="QR Code"]').getAttribute('src');
+ * const secret = extractTOTPSecret(qrSrc);
+ * const code = generateTOTP(secret);
+ * ```
+ */
+export declare function extractTOTPSecret(otpauthUrl: string): string | null;
+/**
+ * Extract all parameters from otpauth:// URL
+ *
+ * @param otpauthUrl - The otpauth:// URL
+ * @returns Object with issuer, account, secret, algorithm, digits, period
+ *
+ * @example
+ * ```typescript
+ * const params = parseTOTPUrl(otpauthUrl);
+ * console.log(params.issuer, params.secret);
+ * ```
+ */
+export declare function parseTOTPUrl(otpauthUrl: string): {
+  issuer: string | null;
+  account: string | null;
+  secret: string | null;
+  algorithm: string;
+  digits: number;
+  period: number;
+};
+/**
+ * Wait for an element to be visible and stable
+ *
+ * Useful for waiting for animations to complete or elements to settle.
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the element
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait (default: 10000ms)
+ * @param options.stable - Wait for element to be stable (default: true)
+ *
+ * @example
+ * ```typescript
+ * await waitForElement(page, '.modal-content');
+ * ```
+ */
+export declare function waitForElement(page: Page, selector: string, options?: {
+  timeout?: number;
+  stable?: boolean;
+}): Promise<void>;
+/**
+ * Wait for network to be idle
+ *
+ * Useful for waiting for all API calls to complete.
+ *
+ * @param page - Playwright page object
+ * @param options - Configuration options
+ * @param options.timeout - Maximum time to wait (default: 30000ms)
+ *
+ * @example
+ * ```typescript
+ * await page.click('button[type="submit"]');
+ * await waitForNetworkIdle(page);
+ * ```
+ */
+export declare function waitForNetworkIdle(page: Page, options?: {
+  timeout?: number;
+}): Promise<void>;
+/**
+ * Check if an element contains specific text
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the element
+ * @param text - Text to search for
+ * @returns true if text is found
+ *
+ * @example
+ * ```typescript
+ * const hasError = await hasText(page, '.error', 'Invalid email');
+ * ```
+ */
+export declare function hasText(page: Page, selector: string, text: string): Promise<boolean>;
+/**
+ * Get all text content from matching elements
+ *
+ * @param page - Playwright page object
+ * @param selector - CSS selector for the elements
+ * @returns Array of text content
+ *
+ * @example
+ * ```typescript
+ * const errors = await getAllText(page, '.error-message');
+ * ```
+ */
+export declare function getAllText(page: Page, selector: string): Promise<string[]>;
+/** SHA-256 hex of a password, as the browser sends it (nest-server expects hashed passwords). */
+export declare function hashTestPassword(password: string): string;
+/** Options of {@link createTestUser}. */
+interface CreateTestUserOptions {
+  /** API base URL, e.g. `http://localhost:3000` (default `NG_API_URL` / `NG_PUBLIC_API_URL`, else `http://localhost:3000`). */
+  apiUrl?: string;
+  /** Better Auth base path (default `/iam`). */
+  basePath?: string;
+  /** Extra sign-up fields (e.g. `termsAndPrivacyAccepted: true` when the backend's `signUpChecks` require it). */
+  extra?: Record<string, unknown>;
+  /** Prefix for the generated email (default `e2e`). */
+  prefix?: string;
+  /** Use this user instead of a generated one. */
+  user?: TestUser;
+}
+/** Result of {@link createTestUser}. */
+interface CreatedTestUser {
+  response: APIResponse;
+  /** Response body (`{ token?, user }`). */
+  body: Record<string, unknown> | null;
+  user: TestUser;
+}
+/**
+ * Create a user through the API (`POST <api>/iam/sign-up/email`, password hashed like the browser does). Fails the
+ * test with the response text when sign-up does not answer 2xx.
+ *
+ * @example
+ * const { user } = await createTestUser(request, { extra: { termsAndPrivacyAccepted: true } });
+ * await loginTestUser(page, user);
+ */
+export declare function createTestUser(request: APIRequestContext, options?: CreateTestUserOptions): Promise<CreatedTestUser>;
+/** Options of {@link loginTestUser}. */
+interface LoginTestUserOptions {
+  /** Selector of the email input (default: an input with `autocomplete="email"`/`"username"`, `type="email"` or `name="email"`). */
+  emailSelector?: string;
+  /** URL (or pattern) expected after the login (default `/app`). Pass `null` to skip the wait. */
+  expectUrl?: RegExp | string | null;
+  /** Login page (default `/auth/login`). */
+  loginPath?: string;
+  /** Selector of the password input (default: `autocomplete="current-password"`, else the first `type="password"`). */
+  passwordSelector?: string;
+  /** Selector of the submit button (default `button[type="submit"]`). */
+  submitSelector?: string;
+}
+/** Sign in through the login form (waits for hydration first) and wait for the target page. */
+export declare function loginTestUser(page: Page, user: Pick<TestUser, 'email' | 'password'>, options?: LoginTestUserOptions): Promise<void>;
+/**
+ * Sign in through the API (`POST <api>/iam/sign-in/email`); the request context keeps the session cookie for later
+ * API calls. Returns the response body (`{ token?, user }`).
+ */
+export declare function loginTestUserViaApi(request: APIRequestContext, user: Pick<TestUser, 'email' | 'password'>, options?: Pick<CreateTestUserOptions, 'apiUrl' | 'basePath'>): Promise<Record<string, unknown>>;
+export type { CreateTestUserOptions, CreatedTestUser, LoginTestUserOptions, TestUser };

package/types/lenne.tech-ng-base-ui-provide.d.ts

@@ -0,0 +1,65 @@
+import * as i0 from "@angular/core";
+import { EnvironmentProviders } from "@angular/core";
+import { LtToastAdapter } from "@lenne.tech/ng-base";
+/** Options of {@link provideLtUi}. */
+interface LtUiOptions {
+  /** Start `LtColorModeService` at bootstrap, so the `.dark` class is right from the SSR render on (default `true`). */
+  colorMode?: boolean;
+  /** Bind `LtToastService` / error toasts to Spartan Sonner (`<hlm-toaster />` in the app shell). Default `true`. */
+  sonnerToasts?: boolean;
+}
+/** Sonner toast adapter: maps the lt colors onto Sonner's variants; loads Sonner lazily on the first toast. */
+export declare const ltSonnerToastAdapter: LtToastAdapter;
+/**
+ * UI providers for `app.config.ts`: the color mode (started at bootstrap) and the toast bridge to Spartan Sonner (loaded
+ * on the first toast). Put `<hlm-toaster />` (from `@lenne.tech/ng-base/ui`, ideally in a `@defer` block) into the
+ * app shell. Lives in its own entry point and imports neither the component layer nor the CDK, so it adds almost
+ * nothing to the initial bundle. Overlay defaults (toasts above dialogs): `provideLtUiOverlayDefaults()` from
+ * `@lenne.tech/ng-base/ui` in the providers of the (lazy) routes that open overlays.
+ */
+export declare function provideLtUi(options?: LtUiOptions): EnvironmentProviders;
+/** Color mode preference. */
+type LtColorMode = 'dark' | 'light' | 'system';
+/** Cookie holding the preference (read during SSR so the first paint has the right theme). */
+export declare const LT_COLOR_MODE_COOKIE = "lt-color-mode";
+/**
+ * Inline script for `<head>` (before any stylesheet) that sets `.dark` on `<html>` from the cookie or
+ * `prefers-color-scheme` before the first paint, so dark mode never flashes light.
+ */
+export declare const LT_COLOR_MODE_SCRIPT = "(function(){try{var m=(document.cookie.match(/(?:^|; )lt-color-mode=([^;]*)/)||[])[1]||'system';var d=m==='dark'||(m==='system'&&matchMedia('(prefers-color-scheme: dark)').matches);document.documentElement.classList.toggle('dark',d);document.documentElement.style.colorScheme=d?'dark':'light';}catch(e){}})();";
+/**
+ * Light / dark / system color mode: toggles `.dark` on `<html>` (Tailwind `dark:` variant and the theme tokens),
+ * persists the preference in a cookie (SSR reads it), follows `prefers-color-scheme` in `system` mode.
+ *
+ * - Server: reads the preference from the request cookie and sets or clears `.dark` on the rendered document, so the
+ *   HTML arrives with the right theme. In `system` mode the server only knows the scheme when the browser sends the
+ *   `Sec-CH-Prefers-Color-Scheme` client hint (the app opts in with `Accept-CH`); otherwise `LT_COLOR_MODE_SCRIPT`
+ *   fixes it before the first paint.
+ * - Browser: toggles the class and `color-scheme` on `<html>` and listens to `prefers-color-scheme` changes.
+ *
+ * The class is applied as soon as the service exists (an `lt-color-mode-button` creates it). When the app renders no
+ * button, create it at startup: `provideAppInitializer(() => void inject(LtColorModeService))`.
+ */
+export declare class LtColorModeService {
+  private readonly document;
+  private readonly cookies;
+  private readonly request;
+  private readonly isBrowser;
+  private readonly modeState;
+  private readonly systemDark;
+  /** The preference. */
+  readonly mode: import("@angular/core").Signal<LtColorMode>;
+  /** The effective mode. */
+  readonly resolved: import("@angular/core").Signal<"dark" | "light">;
+  constructor();
+  /** Set the preference (persisted for one year in the `lt-color-mode` cookie). */
+  setMode(mode: LtColorMode): void;
+  /** Switch between light and dark (leaves `system`). */
+  toggle(): void;
+  private listenToSystemScheme;
+  /** Write the resolved mode to `<html>` (server: the SSR document; browser: the live document). */
+  private apply;
+  static ɵfac: i0.ɵɵFactoryDeclaration<LtColorModeService, never>;
+  static ɵprov: i0.ɵɵInjectableDeclaration<any>;
+}
+export type { LtColorMode, LtUiOptions };