@mittwald/flow-react-components 1.2.0-next.55 → 1.2.0-next.56

package/AGENTS.md

@@ -319,11 +319,19 @@ Run: `pnpm nx test:unit components`,
 | `.` (default)                                                   | Everything listed **manually** in `src/components/public.ts` — new public components must be added there.                                                                                                                                           |
 | `./internal`                                                    | Advanced internals (`flowComponent`, prop helper types, …).                                                                                                                                                                                         |
 | `./flr-universal`                                               | Curated subset that works local _and_ remote. Adding to `public.ts` does **not** add here.                                                                                                                                                          |
+| `./tunnel`                                                      | `@mittwald/react-tunnel` re-exported (`src/index/tunnel.ts`) plus `getTunnelProviderId`, so a consumer's own tunnels share Flow's module instance instead of creating a second React context.                                                       |
 | `./nextjs`, `./react-hook-form`, `./mittwald-password-tools-js` | Integrations (`src/integrations/`): wrappers around third-party dependencies that not every consumer should pay for — they get their own export entry instead of entering the core surface.                                                         |
 | `./all.css`, `./all-layered.css`                                | Bundled stylesheet, plain and `@layer`-wrapped.                                                                                                                                                                                                     |
 | `./component-index`                                             | Generated consumer-facing index: every public component with its status and its own props (`dev/component-index/`). What the docs site's prop tables read, and the one prop dataset a consumer's agent should use.                                  |
 | `./doc-properties`                                              | `react-docgen-typescript` output in its raw `ComponentDoc[]` shape, filtered to the props a consumer can act on. Prefer `./component-index`. The unfiltered dump the generators above read is `.cache/doc-properties.json`, which is not published. |
 
+**Adding any new export entry?** Add the subpath to `keptSubpaths` in
+`packages/codemods/src/migrations/imports-to-package-root/transform.ts`. That
+codemod collapses subpath imports onto the package root with a catch-all `else`,
+so a subpath that is not listed gets flattened onto a root that does not export
+its names. The guard beside the transform fails the codemods unit tests when you
+forget.
+
 **Adding a new integration export entry?** Also register it in the component
 status registry so it is covered: add the entry to `STATUS_EXPORT_ENTRIES`
 (`dev/status-registry/exportEntries.ts`) — the `FlowExportEntry` union and the

package/USAGE.md

@@ -70,6 +70,7 @@ overrides), `RouterProvider` (so `Link` and navigation use your router),
 | `@mittwald/flow-react-components/nextjs`                     | Next.js integration                             |
 | `@mittwald/flow-react-components/react-hook-form`            | react-hook-form integration                     |
 | `@mittwald/flow-react-components/mittwald-password-tools-js` | password-strength integration                   |
+| `@mittwald/flow-react-components/tunnel`                     | Tunnels — see below                             |
 | `@mittwald/flow-react-components/all.css`                    | Stylesheet                                      |
 | `@mittwald/flow-react-components/component-index`            | Machine-readable component + prop index (below) |
 
@@ -77,6 +78,34 @@ overrides), `RouterProvider` (so `Link` and navigation use your router),
 (`flowComponent`, prop helper types, the status registry) and is not a consumer
 API.
 
+### Tunnels
+
+`@mittwald/flow-react-components/tunnel` re-exports `TunnelProvider`,
+`TunnelEntry` and `TunnelExit`. Import them from there — **never add
+`@mittwald/react-tunnel` to your own dependencies.** Its React context lives in
+a module-level `createContext`, so a second copy of the package is a second,
+unrelated context: your `TunnelEntry` stops finding any provider and
+`useTunnelState` throws at runtime. Nothing in `tsc` or ESLint warns first.
+
+The same entry point exports `getTunnelProviderId`, which names the tunnel Flow
+opens around every ui/layout component. That is how you render into a Flow
+component's own exits — a `Heading`'s `headingContent`, for example, the slot
+`Badge` and `AlertBadge` use:
+
+```tsx
+import {
+  TunnelEntry,
+  getTunnelProviderId,
+} from "@mittwald/flow-react-components/tunnel";
+
+<Heading>
+  <ModelTitle model={model} />
+  <TunnelEntry id="headingContent" providerId={getTunnelProviderId("Heading")}>
+    {titleSuffix}
+  </TunnelEntry>
+</Heading>;
+```
+
 ## Finding the right component
 
 `@mittwald/flow-react-components/component-index` is a JSON index of every