@grasp-labs/ds-microfrontends-integration 0.23.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/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/lib/schema/defaults.d.ts

@@ -1,3 +1,3 @@
 import { Schema } from 'src/types/Schema';
 export declare function getDefaultValue(fieldSchema: Schema, rootSchema?: Schema, initialValue?: unknown): unknown;
-export declare function buildDefaultValues(schema: Schema | null, rootSchema?: Schema, initialValues?: Record<string, unknown>): Record<string, unknown> | undefined;
+export declare function buildDefaultValues<T extends Record<string, unknown>>(schema: Schema | null, rootSchema?: Schema, initialValues?: T): T | undefined;

package/dist/lib/schema/descriptor.d.ts

@@ -3,8 +3,8 @@ import { FieldDescriptor } from './types';
 /**
  * Create a field descriptor from a schema
  */
-export declare function createFieldDescriptor(key: string, schema: Schema, prefix?: string, rootSchema?: Schema, requiredFields?: string[]): FieldDescriptor;
+export declare function createFieldDescriptor<TFieldName extends string = string>(key: string, schema: Schema, prefix?: string, rootSchema?: Schema, requiredFields?: string[]): FieldDescriptor<TFieldName>;
 /**
  * Parse schema fields into field descriptors
  */
-export declare function parseSchemaFields(schema: Schema | null, prefix?: string, rootSchema?: Schema): FieldDescriptor[];
+export declare function parseSchemaFields<TFieldName extends string = string>(schema: Schema | null, prefix?: string, rootSchema?: Schema): FieldDescriptor<TFieldName>[];

package/dist/lib/schema/schemaResolver/schemaResolver.d.ts

@@ -1,4 +1,4 @@
 import { FieldValues, Resolver } from 'react-hook-form';
-import { z } from 'zod';
 import { CustomErrorHandler } from 'src/types';
-export declare const getSchemaResolver: (schema?: z.core.JSONSchema.JSONSchema, errorHandler?: CustomErrorHandler) => Resolver<FieldValues> | undefined;
+import { z } from 'zod';
+export declare const getSchemaResolver: <T extends FieldValues = FieldValues>(schema?: z.core.JSONSchema.JSONSchema, errorHandler?: CustomErrorHandler) => Resolver<T> | undefined;

package/dist/lib/schema/types.d.ts

@@ -15,9 +15,9 @@ export type Constraints = {
     maxDate?: Date;
     locale?: unknown;
 };
-export type FieldDescriptor = {
+export type FieldDescriptor<TFieldName extends string = string> = {
     key: string;
-    fieldName: string;
+    fieldName: TFieldName;
     schema: Schema;
     type: FieldType;
     label: string;

package/dist/mf-common.d.ts

@@ -1,5 +1,6 @@
 import { IconName } from '@grasp-labs/ds-react-components';
 import { ModuleFederationOptions } from '@module-federation/vite/lib/utils/normalizeModuleFederationOptions';
+import { ExtractPaths } from './types/Navigation';
 export type BaseItem = {
     /**
      * Display label used as fallback when translation is not available
@@ -18,16 +19,46 @@ export type RouteConfig = BaseItem & {
 };
 export type CategoryConfig = BaseItem & {
     type: "category";
-    children: Record<string, RouteConfig | CategoryConfig>;
+    children: Record<string, NavigationItem>;
 };
 export type NavigationItem = RouteConfig | CategoryConfig;
 /**
  * INDEX is a mandatory route representing the root of the microfrontend, used as the parent navigation item in the sidebar
+ * @deprecated Use ComposableNavigationConfig for new microfrontends
  */
 export type IndexNavigationConfig = {
     INDEX: RouteConfig;
 };
+/**
+ * @deprecated Use ComposableNavigationConfig for new microfrontends
+ */
 export type NavigationConfig<TKeys extends string = string> = IndexNavigationConfig & Record<TKeys, NavigationItem>;
+/**
+ * Composable navigation configuration where each entry is a standalone NavigationItem.
+ */
+export type ComposableNavigationConfig = Record<string, NavigationItem>;
+/**
+ * Extracts a flat `{ KEY: path }` map from a valid navigation config.
+ *
+ * @example
+ * const PageRoutes = extractPaths(navigationConfig);
+ * // PageRoutes.DASHBOARD === "/dashboard"
+ */
+export declare const extractPaths: <const T extends ComposableNavigationConfig>(config: T) => ExtractPaths<T>;
+/**
+ * Defines a navigation config and extracts its page routes in one step.
+ *
+ * @example
+ * const { navigationConfig, pageRoutes } = defineNavigation({
+ *   INDEX: { label: "Home", labelKey: "home", path: "/", icon: "home" },
+ * });
+ * export const PageRoutes = pageRoutes;
+ * export default navigationConfig;
+ */
+export declare const defineNavigation: <const T extends ComposableNavigationConfig>(config: T) => {
+    navigationConfig: T;
+    pageRoutes: ExtractPaths<T>;
+};
 export type MicrofrontendExposes = {
     ".": string;
     "./navigationConfig": string;

package/dist/mf-common.js

@@ -1,45 +1,56 @@
-import { federation as o } from "@module-federation/vite";
-const i = { react: "19.2.3", "react-dom": "19.2.3", "react-router": "7.12.0" }, n = {
-  peerDependencies: i
-}, s = (e, r = {}) => {
-  const t = a(e);
+import { federation as s } from "@module-federation/vite";
+const c = { react: "19.2.3", "react-dom": "19.2.3", "react-router": "7.12.0" }, o = {
+  peerDependencies: c
+}, i = (e) => Object.entries(e).reduce((r, [n, t]) => t.type === "category" ? {
+  ...r,
+  ...i(t.children)
+} : {
+  ...r,
+  [n]: t.path
+}, {}), p = (e) => ({
+  navigationConfig: e,
+  pageRoutes: i(e)
+}), a = (e, r = {}) => {
+  const n = u(e);
   return {
     name: e,
     manifest: !0,
     filename: "remoteEntry.js",
-    getPublicPath: `function() {return "${t}"}`,
+    getPublicPath: `function() {return "${n}"}`,
     exposes: {
       ".": "./src/App",
       "./navigationConfig": "./src/navigationConfig"
     },
     shared: {
-      ...c
+      ...d
     },
     ...r
   };
-}, c = {
+}, d = {
   react: {
     singleton: !0,
-    requiredVersion: n.peerDependencies.react
+    requiredVersion: o.peerDependencies.react
   },
   "react-dom": {
     singleton: !0,
-    requiredVersion: n.peerDependencies["react-dom"]
+    requiredVersion: o.peerDependencies["react-dom"]
   },
   "react-router": {
     singleton: !0,
-    requiredVersion: n.peerDependencies["react-router"]
+    requiredVersion: o.peerDependencies["react-router"]
   },
   "@grasp-labs/ds-microfrontends-integration": {
     singleton: !0,
     requiredVersion: ">=0.17.0 <1.0.0"
   }
-}, a = (e) => `microfrontends/${e}/`, u = (e, r = {}) => o({
-  ...s(e, r)
+}, u = (e) => `microfrontends/${e}/`, f = (e, r = {}) => s({
+  ...a(e, r)
 });
 export {
-  c as COMMON_SHARED_DEPS,
-  a as createMicrofrontendsBase,
-  s as createModuleFederationConfig,
-  u as dsFederation
+  d as COMMON_SHARED_DEPS,
+  u as createMicrofrontendsBase,
+  a as createModuleFederationConfig,
+  p as defineNavigation,
+  f as dsFederation,
+  i as extractPaths
 };

package/dist/types/Navigation.d.ts

@@ -0,0 +1,11 @@
+import { CategoryConfig, NavigationItem, RouteConfig } from '../mf-common';
+export type UnionToIntersection<U> = (U extends unknown ? (x: U) => void : never) extends (x: infer I) => void ? I : never;
+/**
+ * Recursively extracts a flat path map from a navigation config.
+ * For route items, extracts `{ KEY: path }`. For categories, recurses into children.
+ */
+export type ExtractPaths<T extends Record<string, NavigationItem>> = {
+    [K in keyof T as T[K] extends CategoryConfig ? never : K]: T[K] extends RouteConfig ? T[K]["path"] : never;
+} & UnionToIntersection<{
+    [K in keyof T]: T[K] extends CategoryConfig ? ExtractPaths<T[K]["children"]> : unknown;
+}[keyof T]>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@grasp-labs/ds-microfrontends-integration",
-  "version": "0.23.0",
+  "version": "0.24.0-beta.20260225075929.9b4e423",
   "private": false,
   "license": "Apache-2.0",
   "type": "module",