@grasp-labs/ds-microfrontends-integration 0.24.0 → 0.24.1

package/README.md

@@ -106,9 +106,48 @@ 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
+
+**Build-time** (`@grasp-labs/ds-microfrontends-integration/mf-common`):
+
+- `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
+- `COMMON_SHARED_DEPS` — shared dependency definitions (React, React Router, this package) configured as singletons
+- Types: `MicrofrontendExposes`
+
+**Client-side** (`@grasp-labs/ds-microfrontends-integration`):
+
+- `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
+- Types: `RouteConfig`, `CategoryConfig`, `NavigationItem`, `ComposableNavigationConfig`
+
+#### Vite Setup
 
 ```typescript
 // vite.config.ts
@@ -128,14 +167,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 +191,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";
 
-export const navigationConfig = {
-  INDEX: {
+const { navigationConfig, pageRoutes: PageRoutes } = defineNavigation({
+  HOME: {
     label: "Home",
     path: "/",
     icon: "database",
@@ -181,21 +217,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 +235,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.
 
@@ -267,7 +299,7 @@ src/
 ├── lib/               # JSON schema utilities and shared logic
 ├── types/             # TypeScript type definitions
 ├── utils/             # Shared helper functions
-├── mf-common.ts       # Microfrontend configuration utilities
+├── mf-common.ts       # Build-time microfrontend configuration (Vite plugin, Module Federation)
 └── index.ts           # Main entry point
 ```