@grasp-labs/ds-microfrontends-integration 0.22.0 → 0.24.0-beta.20260225075929.9b4e423

package/README.md

@@ -106,9 +106,42 @@ import "@grasp-labs/ds-microfrontends-integration/styles.css";
 
 ### Microfrontend Configuration (`/mf-common`)
 
-Standardized Module Federation configuration for remote microfrontend applications.
+The platform uses a **host / remote** architecture powered by [Module Federation](https://module-federation.io/). A central host application dynamically discovers and mounts independent microfrontend remotes at runtime. For this to work, every remote must follow a shared contract — exposing the same entry points, using compatible shared dependencies, and providing a navigation config so the host can build its sidebar and routing.
 
-#### Basic Setup
+`mf-common` enforces this contract. It provides a pre-configured Vite plugin, shared dependency definitions, and type-safe navigation primitives so that each remote is wired up correctly with minimal boilerplate.
+
+#### The Contract
+
+Every microfrontend must expose two modules:
+
+| Expose key             | Default path               | What the host expects                                                                                   |
+| ---------------------- | -------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `"."`                  | `"./src/App"`              | A **React component** (not a full app with `ReactDOM.render`). The host mounts it inside its own router |
+| `"./navigationConfig"` | `"./src/navigationConfig"` | A `ComposableNavigationConfig` object. The host reads it to build sidebar entries and route definitions |
+
+#### Navigation Item Types
+
+Each entry in the navigation config is a `NavigationItem` — either a **route** or a **category**:
+
+| Type       | Description                                                                |
+| ---------- | -------------------------------------------------------------------------- |
+| `visible`  | A route that appears in the sidebar (default when `type` is omitted)       |
+| `hidden`   | A route that is routable but does not appear in the sidebar                |
+| `category` | A non-routable group with `children` — used to create nested sidebar menus |
+
+Every item has a `label` (display fallback), an optional `labelKey` (i18n key in the `navigation` namespace), and an `icon`.
+
+#### Available Utilities
+
+- `dsFederation(name, overrides?)` — Vite plugin that wraps Module Federation with the standard config
+- `createModuleFederationConfig(name, overrides?)` — generates the raw Module Federation options if you need more control
+- `createMicrofrontendsBase(name)` — returns the deployment base path (`microfrontends/<name>/`), used to set Vite's `base` in production
+- `defineNavigation(config)` — defines a navigation config and extracts its page routes in one step, returning `{ navigationConfig, pageRoutes }`
+- `extractPaths(config)` — recursively flattens a navigation config into a type-safe `{ KEY: path }` map
+- `COMMON_SHARED_DEPS` — shared dependency definitions (React, React Router, this package) configured as singletons
+- Types: `RouteConfig`, `CategoryConfig`, `NavigationItem`, `ComposableNavigationConfig`, `MicrofrontendExposes`
+
+#### Vite Setup
 
 ```typescript
 // vite.config.ts
@@ -128,14 +161,9 @@ export default defineConfig(({ mode }) => ({
 }));
 ```
 
-**Default exposes:**
-
-- `"."` → `"./src/App"` - Your main React component (not a full app with ReactDOM.render, just a component)
-- `"./navigationConfig"` → `"./src/navigationConfig"` - Navigation configuration object of type `NavigationConfig`
-
-#### App Component Example
+#### App Component
 
-Your `src/App.tsx` should export a React component with Routes, not render it:
+Your `src/App.tsx` should export a React component with `<Routes>`, not render it — the host handles mounting:
 
 ```tsx
 // src/App.tsx
@@ -157,14 +185,16 @@ function App() {
 export default App;
 ```
 
-#### Navigation Configuration Example
+#### Navigation Configuration
+
+Use `defineNavigation` to define your navigation config and extract route paths in one step:
 
 ```typescript
 // src/navigationConfig.ts
-import type { NavigationConfig } from "@grasp-labs/ds-microfrontends-integration/mf-common";
+import { defineNavigation } from "@grasp-labs/ds-microfrontends-integration/mf-common";
 
-export const navigationConfig = {
-  INDEX: {
+const { navigationConfig, pageRoutes: PageRoutes } = defineNavigation({
+  HOME: {
     label: "Home",
     path: "/",
     icon: "database",
@@ -181,21 +211,17 @@ export const navigationConfig = {
     path: "/internal",
     type: "hidden",
   },
-} satisfies NavigationConfig;
-```
+});
 
-**What it provides:**
+export { PageRoutes };
+// PageRoutes.HOME === "/"
+// PageRoutes.SETTINGS === "/settings"
+// PageRoutes.INTERNAL === "/internal"
 
-- Pre-configured Module Federation settings with standard shared dependencies (React, React Router, etc.)
-- Automatic public path configuration for microfrontend deployment
-- Type-safe navigation and route configuration helpers
-
-**Available utilities:**
+export default navigationConfig;
+```
 
-- `dsFederation(name, overrides?)` - Vite plugin for Module Federation
-- `createModuleFederationConfig(name, overrides?)` - Generate config object
-- `COMMON_SHARED_DEPS` - Shared dependency configuration
-- Types: `RouteConfig`, `NavigationConfig`, `MicrofrontendExposes`
+For nested configs with categories, route paths are recursively flattened into a single map.
 
 #### Shared Dependencies
 
@@ -203,10 +229,10 @@ Your microfrontend project must install compatible versions of these shared depe
 
 | Dependency                                  | Purpose                                                                              |
 | ------------------------------------------- | ------------------------------------------------------------------------------------ |
-| `react`                                     | UI library - singleton ensures one React instance across all microfrontends          |
-| `react-dom`                                 | React DOM renderer - must match React version                                        |
-| `react-router`                              | Routing library - singleton required for React context to work across microfrontends |
-| `@grasp-labs/ds-microfrontends-integration` | This package - singleton required for React context to work across microfrontends    |
+| `react`                                     | UI library — singleton ensures one React instance across all microfrontends          |
+| `react-dom`                                 | React DOM renderer — must match React version                                        |
+| `react-router`                              | Routing library — singleton required for React context to work across microfrontends |
+| `@grasp-labs/ds-microfrontends-integration` | This package — singleton required for React context to work across microfrontends    |
 
 These dependencies are configured as singletons to prevent multiple instances and ensure compatibility across the microfrontend architecture.
 

package/dist/components/schemaFields/ArrayField.d.ts

@@ -1,8 +1,8 @@
-import { Control } from 'react-hook-form';
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-type ArrayFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type ArrayFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function ArrayField({ descriptor, control }: ArrayFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function ArrayField<T extends FieldValues = FieldValues>({ descriptor, control, }: ArrayFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/BooleanField.d.ts

@@ -1,8 +1,8 @@
-import { Control } from 'react-hook-form';
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-type BooleanFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type BooleanFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function BooleanField({ descriptor, control }: BooleanFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function BooleanField<T extends FieldValues = FieldValues>({ descriptor, control, }: BooleanFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/DateField.d.ts

@@ -1,8 +1,8 @@
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-import { Control } from 'react-hook-form';
-type DateFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type DateFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function DateField({ descriptor, control }: DateFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function DateField<T extends FieldValues = FieldValues>({ descriptor, control, }: DateFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/EnumField.d.ts

@@ -1,8 +1,8 @@
-import { Control } from 'react-hook-form';
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-type EnumFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type EnumFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function EnumField({ descriptor, control }: EnumFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function EnumField<T extends FieldValues = FieldValues>({ descriptor, control, }: EnumFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/JsonField.d.ts

@@ -1,8 +1,8 @@
-import { Control } from 'react-hook-form';
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-type JsonFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type JsonFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function JsonField({ descriptor, control }: JsonFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function JsonField<T extends FieldValues = FieldValues>({ descriptor, control, }: JsonFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/NumberField.d.ts

@@ -1,8 +1,8 @@
-import { Control } from 'react-hook-form';
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-type NumberFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type NumberFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function NumberField({ descriptor, control }: NumberFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function NumberField<T extends FieldValues = FieldValues>({ descriptor, control, }: NumberFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/SchemaFields.d.ts

@@ -1,11 +1,11 @@
-import { Control, FieldErrors } from 'react-hook-form';
+import { Control, FieldErrors, FieldValues } from 'react-hook-form';
 import { Schema } from 'src/types/Schema';
-type SchemaFieldsProps = {
-    control: Control;
-    errors: FieldErrors;
+type SchemaFieldsProps<T extends FieldValues = FieldValues> = {
+    control: Control<T>;
+    errors: FieldErrors<T>;
     schema: Schema | null;
     prefix?: string;
     fieldDirection?: "horizontal" | "vertical";
 };
-export declare function SchemaFields({ control, errors, schema, prefix, fieldDirection, }: SchemaFieldsProps): import("react/jsx-runtime").JSX.Element;
+export declare function SchemaFields<T extends FieldValues = FieldValues>({ control, errors, schema, prefix, fieldDirection, }: SchemaFieldsProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/SchemaFields.stories.d.ts

@@ -1,13 +1,15 @@
 import { StoryObj } from '@storybook/react-vite';
+import { Resolver } from 'react-hook-form';
 import { Schema } from 'src/types';
 type SchemaFieldsExampleProps = {
     schema: Schema;
     defaultValues: Record<string, unknown>;
     fieldDirection?: "horizontal" | "vertical";
+    resolver?: Resolver;
 };
 declare const meta: {
     title: string;
-    component: ({ schema, defaultValues, fieldDirection, }: SchemaFieldsExampleProps) => import("react/jsx-runtime").JSX.Element;
+    component: ({ schema, defaultValues, fieldDirection, resolver, }: SchemaFieldsExampleProps) => import("react/jsx-runtime").JSX.Element;
     parameters: {
         layout: string;
     };
@@ -16,15 +18,18 @@ declare const meta: {
         schema: Schema;
         defaultValues: Record<string, unknown>;
         fieldDirection?: "horizontal" | "vertical" | undefined;
+        resolver?: Resolver | undefined;
     }>, context: import('storybook/internal/csf').StoryContext<import('@storybook/react').ReactRenderer, {
         schema: Schema;
         defaultValues: Record<string, unknown>;
         fieldDirection?: "horizontal" | "vertical" | undefined;
+        resolver?: Resolver | undefined;
     }>) => import("react/jsx-runtime").JSX.Element)[];
 };
 export default meta;
 type Story = StoryObj<typeof meta>;
 export declare const BasicForm: Story;
+export declare const BasicFormWithCustomValidation: Story;
 export declare const BasicFormWithVerticalAlignment: Story;
 export declare const NestedWithVault: Story;
 export declare const PasswordFields: Story;

package/dist/components/schemaFields/TextField.d.ts

@@ -1,8 +1,8 @@
-import { Control } from 'react-hook-form';
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-type TextFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type TextFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function TextField({ descriptor, control }: TextFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function TextField<T extends FieldValues = FieldValues>({ descriptor, control, }: TextFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/VaultField.d.ts

@@ -1,8 +1,8 @@
-import { Control } from 'react-hook-form';
+import { Control, FieldValues, Path } from 'react-hook-form';
 import { FieldDescriptor } from 'src/lib/schema';
-type VaultFieldProps = {
-    descriptor: FieldDescriptor;
-    control: Control;
+type VaultFieldProps<T extends FieldValues = FieldValues> = {
+    descriptor: FieldDescriptor<Path<T>>;
+    control: Control<T>;
 };
-export declare function VaultField({ descriptor, control }: VaultFieldProps): import("react/jsx-runtime").JSX.Element;
+export declare function VaultField<T extends FieldValues = FieldValues>({ descriptor, control, }: VaultFieldProps<T>): import("react/jsx-runtime").JSX.Element;
 export {};

package/dist/components/schemaFields/consts/index.d.ts

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

package/dist/components/schemaFields/consts/schemas.d.ts

@@ -0,0 +1,5 @@
+import { Schema } from 'src/types';
+export declare const SIMPLE_SCHEMA: Schema;
+export declare const NESTED_SCHEMA: Schema;
+export declare const SECRET_FORM_SCHEMA: Schema;
+export declare const PASSWORD_SCHEMA: Schema;