@m4l/testing 0.0.24 → 1.0.1

package/types/packages/testing/vitest/src/constants.d.ts

@@ -0,0 +1,24 @@
+export declare const DEFAULT_RHF_SUBMIT_REF_GLOBAL_KEY = "__rhfOnSubmitRef";
+export declare const M4L_APP_WINDOW_SIZES: {
+    square: {
+        large: {
+            width: number;
+            height: number;
+        };
+        medium: {
+            width: number;
+            height: number;
+        };
+    };
+};
+export declare const M4L_APP_DATAGRID_SEMANTIC_WIDTHS: {
+    date: number;
+    smallId: number;
+    smallName: number;
+    mediumId: number;
+    mediumName: number;
+    mediumNumber: number;
+    mediumChip: number;
+    mediumDescription: number;
+    smallDescription: number;
+};

package/types/packages/testing/vitest/src/factories/app/index.d.ts

@@ -0,0 +1,5 @@
+export * from './m4lAppBase';
+export * from './m4lAppComponents';
+export * from './m4lAppCore';
+export * from './m4lAppGraphics';
+export * from './m4lAppLayouts';

package/types/packages/testing/vitest/src/factories/app/m4lAppBase.d.ts

@@ -0,0 +1,9 @@
+import type { CreateM4lAppBaseModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/base` mock payload used by M4L app test setups.
+ *
+ * Use this in host or MF `test/setup.ts` files when app tests import base
+ * primitives directly and should share the same neutral placeholder contract
+ * as package tests.
+ */
+export declare function createM4lAppBaseModuleMock({ baseModule, moduleOverrides, }?: CreateM4lAppBaseModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/app/m4lAppComponents.d.ts

@@ -0,0 +1,20 @@
+import type { CreateM4lAppComponentsModuleMockOptions, CreateM4lAppFormComponentsModuleOverridesOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/components` mock payload used by M4L app test
+ * setups.
+ *
+ * Use this in an app root `test/setup.ts` when many tests need the same stable
+ * components baseline. Host and MF apps can keep only app-local overrides or
+ * extra mocks in the local setup file. In repository terminology, Patronus is
+ * only the visual design-system layer applied to these components, not the
+ * functional runtime contract represented by this mock.
+ */
+export declare function createM4lAppComponentsModuleMock({ baseModule, moduleOverrides, submitRefGlobalKey, }?: CreateM4lAppComponentsModuleMockOptions): VitestModuleMockExports;
+/**
+ * Builds reusable `@m4l/components` overrides for app-level form-oriented MFs.
+ *
+ * This helper keeps common setup-time mocks in `@m4l/testing/vitest` so app
+ * test setups can reuse the same baseline without copy/pasting local
+ * `moduleOverrides` payloads.
+ */
+export declare function createM4lAppFormComponentsModuleOverrides({ dynamicMFParameters, }?: CreateM4lAppFormComponentsModuleOverridesOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/app/m4lAppCore.d.ts

@@ -0,0 +1,12 @@
+import type { CreateM4lAppCoreModuleMockOptions, UnknownRecord, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/core` mock payload used by M4L app test setups.
+ *
+ * Use this when host or MF tests need deterministic environment data,
+ * dictionary labels, and host-tools behavior without mounting the real core
+ * runtime. Consumers can also spread `importOriginal` through `baseModule`
+ * when they need to preserve untouched exports. Patronus does not apply here
+ * as a runtime concept; in this repository it refers only to the visual
+ * design-system layer.
+ */
+export declare function createM4lAppCoreModuleMock<TBaseStoreState = UnknownRecord>({ baseModule, baseStoreState, environmentData, hostToolsData, moduleLabel, getLabel, userPreferencesData, moduleOverrides, authState, flagsStoreState, }?: CreateM4lAppCoreModuleMockOptions<TBaseStoreState>): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/app/m4lAppGraphics.d.ts

@@ -0,0 +1,10 @@
+import type { CreateM4lAppGraphicsModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/graphics` mock payload used by M4L app test setups.
+ *
+ * Use this when the test only needs neutral pagination, rows, or responsive
+ * helpers while still supporting host-level graphics providers and stores. If
+ * a test needs to talk about Patronus, it should do so only for the visual
+ * theme/token layer, not for these runtime graphics hooks.
+ */
+export declare function createM4lAppGraphicsModuleMock({ baseModule, moduleOverrides, }?: CreateM4lAppGraphicsModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/app/m4lAppLayouts.d.ts

@@ -0,0 +1,18 @@
+import type { CreateM4lAppFormLayoutsModuleOverridesOptions, CreateM4lAppLayoutsModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/layouts` mock payload used by M4L app test setups.
+ *
+ * Use this when the app test needs the layout shell contract to exist in the
+ * DOM without pulling in the real layouts package behavior. Patronus is not a
+ * layout-runtime concept here; it only names the visual design-system layer in
+ * the broader repository terminology.
+ */
+export declare function createM4lAppLayoutsModuleMock({ baseModule, moduleOverrides, }?: CreateM4lAppLayoutsModuleMockOptions): VitestModuleMockExports;
+/**
+ * Builds reusable `@m4l/layouts` overrides for app-level form-oriented MFs.
+ *
+ * This helper centralizes common setup-time form layout seams so app test
+ * setups can reuse the same baseline without redefining the same local
+ * `moduleOverrides` payload.
+ */
+export declare function createM4lAppFormLayoutsModuleOverrides({ createComponentFieldImplementation, }?: CreateM4lAppFormLayoutsModuleOverridesOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/base/index.d.ts

@@ -0,0 +1 @@
+export * from './m4lBaseComponents';

package/types/packages/testing/vitest/src/factories/base/m4lBaseComponents.d.ts

@@ -0,0 +1,13 @@
+import type { CreateM4lBaseComponentsModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared library-safe `@m4l/components` mock surface used by
+ * package-level suites and reused by app-level factories.
+ *
+ * This intentionally covers reusable M4L component-system primitives, form
+ * helpers, formatters, and utility hooks that are safe for library tests.
+ * Within this repository, Patronus refers only to the visual design-system
+ * layer behind tokens, theme colors, and styling for those components; it does
+ * not name the functional runtime contract mocked here. App-shell and
+ * microfrontend-only collaborators stay in the app factory layer.
+ */
+export declare function createM4lBaseComponentsModuleMock({ baseModule, moduleOverrides, submitRefGlobalKey, }?: CreateM4lBaseComponentsModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/index.d.ts

@@ -0,0 +1,7 @@
+export * from './app';
+export * from './base';
+export * from './leaflet';
+export * from './packages';
+export * from './reactHookForm';
+export * from './reResizable';
+export * from './reactLeaflet';

package/types/packages/testing/vitest/src/factories/leaflet.d.ts

@@ -0,0 +1,10 @@
+import type { CreateLeafletModuleMockOptions, VitestModuleMockExports } from '../types';
+/**
+ * Builds a reusable partial `leaflet` module mock for tests that only need a
+ * stable `DomEvent` seam or `L.control.scale()` behavior.
+ *
+ * Keep plugin-specific state such as `geoJSON()`, `pm`, marker/icon factories,
+ * or highly feature-local Leaflet orchestration inside the owning test when
+ * that behavior is not yet shared across more than one slice.
+ */
+export declare function createLeafletModuleMock({ baseModule, domEventData, moduleOverrides, scaleControlFactory, }?: CreateLeafletModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/packages/index.d.ts

@@ -0,0 +1,7 @@
+export * from './m4lPackageBase';
+export * from './m4lPackageComponents';
+export * from './m4lPackageCore';
+export * from './m4lPackageGclick';
+export * from './m4lPackageGclickRealtime';
+export * from './m4lPackageGraphics';
+export * from './m4lPackageLayouts';

package/types/packages/testing/vitest/src/factories/packages/m4lPackageBase.d.ts

@@ -0,0 +1,11 @@
+import type { CreateM4lPackageBaseModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/base` mock payload used by direct base-package
+ * consumers in package tests.
+ *
+ * Use this when a test imports `ButtonBase`, `Icon`, `Tooltip`, or `Typography`
+ * from `@m4l/base` directly and only needs neutral primitive placeholders.
+ * Keep `baseModule` populated from `importOriginal(...)` when the scenario
+ * still relies on the real constants or helper exports from the package.
+ */
+export declare function createM4lPackageBaseModuleMock({ baseModule, moduleOverrides, }?: CreateM4lPackageBaseModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/packages/m4lPackageComponents.d.ts

@@ -0,0 +1,11 @@
+import type { CreateM4lPackageComponentsModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/components` mock payload used by M4L package
+ * component tests.
+ *
+ * Use this when a package `test/setup.ts` needs lightweight hook and helper
+ * baselines without importing the broader app-shell component surface.
+ * `packages/gclick` is the current pilot consumer, but the helper itself is
+ * intentionally package-generic.
+ */
+export declare function createM4lPackageComponentsModuleMock({ baseModule, dataGridPersistenceData, dynamicFilterAndSortData, modalData, moduleOverrides, popupsStoreData, windowToolsData, }?: CreateM4lPackageComponentsModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/packages/m4lPackageCore.d.ts

@@ -0,0 +1,11 @@
+import type { CreateM4lPackageCoreModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/core` mock payload used by M4L package component
+ * tests.
+ *
+ * Use this when a package `test/setup.ts` needs a deterministic baseline for
+ * environment, dictionary, host-tools, privileges, and network hooks without
+ * pulling in app-shell collaborators. `packages/gclick` is the current pilot
+ * consumer, but the helper itself is intentionally package-generic.
+ */
+export declare function createM4lPackageCoreModuleMock({ baseModule, environmentData, getLabel, hostToolsData, moduleOverrides, moduleLabel, modulePrivilegesData, networkData, }?: CreateM4lPackageCoreModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/packages/m4lPackageGclick.d.ts

@@ -0,0 +1,10 @@
+import type { CreateM4lPackageGclickModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/gclick` mock payload used by tests that depend on
+ * the exact runtime package.
+ *
+ * Use this when the test only needs stable map, indicator, and UI helper
+ * behavior from `@m4l/gclick` while keeping higher-level assertions focused
+ * on orchestration logic.
+ */
+export declare function createM4lPackageGclickModuleMock({ baseModule, mapStoreState, moduleOverrides, }?: CreateM4lPackageGclickModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/packages/m4lPackageGclickRealtime.d.ts

@@ -0,0 +1,6 @@
+import type { CreateM4lPackageGclickRealtimeModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Build the shared `@m4l/gclick-realtime` mock surface for direct package and
+ * subpath consumers.
+ */
+export declare function createM4lPackageGclickRealtimeModuleMock({ baseModule, moduleOverrides, surface, }?: CreateM4lPackageGclickRealtimeModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/packages/m4lPackageGraphics.d.ts

@@ -0,0 +1,9 @@
+import type { CreateM4lPackageGraphicsModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/graphics` mock payload used by M4L package
+ * component tests.
+ *
+ * Use this when a package test needs neutral rows, pagination, or color helper
+ * contracts without adopting the broader app-level graphics surface.
+ */
+export declare function createM4lPackageGraphicsModuleMock({ baseModule, moduleOverrides, }?: CreateM4lPackageGraphicsModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/packages/m4lPackageLayouts.d.ts

@@ -0,0 +1,10 @@
+import type { CreateM4lPackageLayoutsModuleMockOptions, VitestModuleMockExports } from '../../types';
+/**
+ * Builds the shared `@m4l/layouts` mock payload used by M4L package
+ * component tests.
+ *
+ * Use this when a package test needs neutral layout-shell components or hooks
+ * such as `DynamicTabs`, `useModule()`, or `useFormAddEdit()` without pulling
+ * the broader app-shell runtime surface into a library test.
+ */
+export declare function createM4lPackageLayoutsModuleMock({ baseModule, moduleOverrides, }?: CreateM4lPackageLayoutsModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/reResizable.d.ts

@@ -0,0 +1,6 @@
+import type { VitestModuleMockExports } from '../types';
+/**
+ * Builds a minimal `re-resizable` module mock for tests that only need the
+ * resizable container to preserve its children in the DOM.
+ */
+export declare function createReResizableModuleMock(): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/reactHookForm.d.ts

@@ -0,0 +1,10 @@
+import type { CreateReactHookFormModuleMockOptions, VitestModuleMockExports } from '../types';
+/**
+ * Builds a reusable `react-hook-form` module mock for tests that need
+ * `useFormContext()` compatibility without mounting a real RHF tree.
+ *
+ * Use `useFormContextData` when a suite needs to override shared members such
+ * as `setValue`, `reset`, or `formState` while keeping the rest of the module
+ * contract neutral and reusable.
+ */
+export declare function createReactHookFormModuleMock({ baseModule, moduleOverrides, useFormContextData, }?: CreateReactHookFormModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/factories/reactLeaflet.d.ts

@@ -0,0 +1,10 @@
+import type { CreateReactLeafletModuleMockOptions, VitestModuleMockExports } from '../types';
+/**
+ * Builds a reusable `react-leaflet` module mock for tests that need neutral
+ * placeholder output for common shapes plus an overridable `useMap()` result.
+ *
+ * Keep feature-specific map interaction behavior such as Geoman orchestration,
+ * Leaflet `geoJSON()` behavior, or layer-specific event state local when the
+ * test depends on something more precise than these neutral placeholders.
+ */
+export declare function createReactLeafletModuleMock({ baseModule, moduleOverrides, useMapData, useMapImplementation, }?: CreateReactLeafletModuleMockOptions): VitestModuleMockExports;

package/types/packages/testing/vitest/src/fixtures.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Default environment overrides used by the shared GClick app core module
+ * mock.
+ *
+ * Keep this baseline generic enough for host and MF test scaffolds, then
+ * override the few fields that belong to the specific app under test.
+ */
+export declare const defaultM4lAppEnvironmentOverrides: {
+    database: string;
+    domain_token: string;
+    domainToken: string;
+    environment_assets: string;
+    host: string;
+    host_api_local: string;
+    hostApiLocal: string;
+    host_api_remote: string;
+    hostApiRemote: string;
+    hostRemote: string;
+    hostApiIcons: string;
+    host_static_assets: string;
+    isLocalhost: boolean;
+};
+/**
+ * Default environment overrides used by the shared M4L package test
+ * baseline.
+ *
+ * Keep this baseline focused on package-level hooks and icon/url generation,
+ * then let individual suites override only the fields that are scenario
+ * specific.
+ */
+export declare const defaultM4lPackageEnvironmentOverrides: {
+    environment_assets: string;
+    host: string;
+    host_api_local: string;
+    hostApiLocal: string;
+    host_api_remote: string;
+    hostApiRemote: string;
+    hostApiIcons: string;
+    hostRemote: string;
+    host_static_assets: string;
+    database: string;
+    domain_token: string;
+    domainToken: string;
+    isLocalhost: boolean;
+};
+/**
+ * Stable relative-time formatter payload used by app component mocks that read
+ * `useDistanceToNowFormatter()`.
+ */
+export declare const distanceToNowFormatterFixture: {
+    value: string;
+    unit: string;
+};
+/**
+ * Neutral GNSS signal enum fixture for app tests that need predictable signal
+ * values without importing the real runtime enum.
+ */
+export declare const gclickGnssSignalEnumFixture: {
+    noSignal: number;
+    reliable: number;
+    acceptable: number;
+};
+/**
+ * Neutral GNSS motion-status enum fixture for app tests that need predictable
+ * motion values without importing the real runtime enum.
+ */
+export declare const gclickGnssMotionStatusEnumFixture: {
+    off: number;
+    moving: number;
+    maxSpeed: number;
+};

package/types/packages/testing/vitest/src/helpers/columnConfigs.d.ts

@@ -0,0 +1,184 @@
+/**
+ * Minimal structural shape for a DataGrid column used by shared test helpers.
+ *
+ * This intentionally mirrors only the fields that the assertion helpers need to
+ * compare and avoids importing types from workspace component packages.
+ */
+export interface TestingColumnShape {
+    key: string;
+    name: string;
+    type: string;
+    align?: string;
+    width?: number;
+    minWidth?: number;
+    visible?: boolean;
+    fixed?: boolean;
+    formatter?: unknown;
+    customFilter?: unknown;
+    customSort?: unknown;
+    testProps?: Record<string, unknown>;
+}
+/**
+ * Local structural stand-in for a nested-value column formatter hook call.
+ */
+export interface TestingNestedValueHookCall {
+    type: 'nested';
+    fieldValue: string;
+    Component?: unknown;
+    defaultValue?: string;
+}
+/**
+ * Local structural stand-in for a date column formatter hook call.
+ */
+export interface TestingDateHookCall {
+    type: 'date';
+    fieldValue: string;
+    presentationType: string;
+}
+/**
+ * Local structural stand-in for a boolean column formatter hook call.
+ */
+export interface TestingBooleanHookCall {
+    type: 'boolean';
+    fieldValue: string;
+    presentationType: string;
+}
+/**
+ * Local structural stand-in for a price column formatter hook call.
+ */
+export interface TestingPriceHookCall {
+    type: 'price';
+    fieldValue: string;
+}
+/**
+ * Local structural stand-in for a points column formatter hook call.
+ */
+export interface TestingPointsHookCall {
+    type: 'points';
+    fieldValue: string;
+    fieldUnit: string;
+}
+/**
+ * Local structural stand-in for a number column formatter hook call.
+ */
+export interface TestingNumberHookCall {
+    type: 'number';
+    fieldValue: string;
+    fractionDigits?: number;
+}
+/**
+ * Local structural stand-in for an interactive-check column formatter hook call.
+ */
+export interface TestingInteractiveCheckHookCall {
+    type: 'interactiveCheck';
+}
+/**
+ * Local structural stand-in for a set-check column formatter hook call.
+ */
+export interface TestingSetCheckHookCall {
+    type: 'setCheck';
+    field: string;
+    disabledGetter?: (...args: unknown[]) => unknown;
+    rowKeyGetter: (...args: unknown[]) => unknown;
+    useHook: (...args: unknown[]) => unknown;
+}
+/**
+ * Local structural stand-in for an uncertainty column formatter hook call.
+ */
+export interface TestingUncertaintyHookCall {
+    type: 'uncertainty';
+    fieldValue: string;
+    fieldUnit: string;
+    fieldSymbol: string;
+}
+/**
+ * Local structural stand-in for a concatenated-values column formatter hook call.
+ */
+export interface TestingConcatenatedHookCall {
+    type: 'concatenated';
+    fieldValue: string[];
+    fieldSeparator: string;
+}
+/**
+ * Local structural stand-in for a chip-status column formatter hook call.
+ */
+export interface TestingChipStatusHookCall {
+    type: 'chipStatus';
+    fieldStatus: string;
+    fieldLabel: string | ((row: unknown, status: string) => string);
+    statusesColors?: Record<string, unknown>;
+    fallbackColor?: string;
+}
+/**
+ * Local structural stand-in for a tags column formatter hook call.
+ */
+export interface TestingTagsHookCall {
+    type: 'tags';
+    fieldValue: string;
+}
+/**
+ * Local structural stand-in for an icon column formatter hook call.
+ */
+export interface TestingIconHookCall {
+    type: 'icon';
+    getIconProps: (...args: unknown[]) => unknown;
+}
+/**
+ * Local structural stand-in for a color column formatter hook call.
+ */
+export interface TestingColorHookCall {
+    type: 'color';
+    fieldValue: string;
+    size?: string | number;
+    className?: string;
+}
+/**
+ * Local structural stand-in for an image column formatter hook call.
+ */
+export interface TestingImageHookCall {
+    type: 'image';
+    fieldValue: string;
+    fieldText?: string;
+    cover?: boolean;
+    width?: number;
+    height?: number;
+}
+/**
+ * Union of every supported structural hook-call shape used by the assertion
+ * helper.
+ */
+export type TestingHookCall = TestingNestedValueHookCall | TestingDateHookCall | TestingBooleanHookCall | TestingPriceHookCall | TestingPointsHookCall | TestingNumberHookCall | TestingInteractiveCheckHookCall | TestingSetCheckHookCall | TestingUncertaintyHookCall | TestingConcatenatedHookCall | TestingChipStatusHookCall | TestingTagsHookCall | TestingIconHookCall | TestingColorHookCall | TestingImageHookCall;
+/**
+ * Structural expected column config used by `assertColumnConfigs(...)`.
+ */
+export interface TestingColumnConfig<T = unknown> extends Omit<TestingColumnShape, 'formatter' | 'customFilter' | 'customSort' | 'testProps'> {
+    hookCall?: TestingHookCall;
+    /**
+     * Reserved generic marker so consumers can keep their existing
+     * `TestingColumnConfig<Row>` usage without pulling real package types into
+     * this helper library.
+     */
+    __rowType?: T;
+}
+/**
+ * Structural actual column used by `assertColumnConfigs(...)`.
+ */
+export type TestingColumn = TestingColumnShape;
+/**
+ * Asserts that each column in `columns` matches the expected shape in `configs`.
+ *
+ * Returns an array of human-readable violation strings. An empty array means
+ * the columns fully satisfy the config contract. Pass the result to
+ * `expect(violations).toEqual([])` in the test body.
+ *
+ * Use this when a hook or helper builds a DataGrid column array and the test
+ * needs to verify basic properties (`key`, `name`, `type`, `align`, `width`,
+ * `visible`, `fixed`) plus the structural `testProps` passed through hook-based
+ * column builders. Keep the `describe` / `it` structure in the test file and
+ * call this helper inside a single `it` block.
+ *
+ * @param columns - The actual column array produced by the component or hook.
+ * @param configs - The expected column config specs, one entry per column.
+ * @returns Array of violation strings; empty when all columns satisfy the contract.
+ */
+export declare function assertColumnConfigs<T>(columns: Array<TestingColumn>, configs: readonly TestingColumnConfig<T>[]): string[];