@jfdevelops/react-layout 0.20.0 → 0.22.0

package/skills/build-react-layouts/references/architecture.md

@@ -6,6 +6,7 @@
 - Shared layout contract
 - Semantic composables
 - Preset composables
+- Persistent application shell
 - Secondary layout families
 - Feature organization
 
@@ -125,6 +126,97 @@ Include the preset's required values in `layout.props.include`. Keep
 presentation in the preset renderer and segment definitions in resource page
 configuration.
 
+## Persist the application shell across navigation
+
+Plain `defineResourceLayout` wraps every page in its own `createResourceLayout`
+component. Navigating between resources unmounts one page component and mounts
+another, so the chrome that `render` produces — a sidebar, a header,
+subscriptions, observers — is rebuilt on every navigation.
+
+Use `defineResourceLayout.withLayout` when that rebuild is a problem. It returns
+a `Shell` component in addition to the usual helpers:
+
+```tsx
+export const {
+  createResourceConfig,
+  createResourceLayout,
+  createResourceLinks,
+  Shell,
+} = defineResourceLayout.withLayout({
+  resources: ['appointments', 'locations', 'services', 'settings'],
+  options: {
+    title: createProp.component({ type: 'ReactNode' }).optional(),
+  },
+  shell: {
+    composables: (create) => ({
+      Layout: create({
+        name: ({ capitalize, resource }) =>
+          resource ? `${capitalize(resource)}Shell` : 'Shell',
+        wrapWith: AppLayout,
+      }),
+    }),
+    render: (_props, { composables, children }) => (
+      <composables.Layout>
+        <AppSidebar />
+        <main>{children}</main>
+      </composables.Layout>
+    ),
+  },
+  layout: {
+    // Optional under `withLayout`. Give a resource its own header or actions
+    // here, or omit `render` entirely and the page renders its children into
+    // the shell's outlet.
+    props: {
+      custom: {
+        children: createProp.component({ type: 'ReactNode' }),
+        actions: createProp.component({ type: 'ReactNode' }).optional(),
+      },
+    },
+    render: ({ children, actions }, { composables }) => (
+      <composables.ResourceLayout>
+        {actions && (
+          <composables.ResourceHeaderActions>
+            {actions}
+          </composables.ResourceHeaderActions>
+        )}
+        {children}
+      </composables.ResourceLayout>
+    ),
+  },
+});
+```
+
+Mount `Shell` once, in the parent route, wrapping the router outlet:
+
+```tsx
+function AdminRoute() {
+  return (
+    <Shell>
+      <Outlet />
+    </Shell>
+  );
+}
+```
+
+The shell's `render` context matches a per-resource `render` context
+(`composables`, `resources`, `name`) plus `children` — the outlet subtree, which
+you place where page content belongs. `resource` and `resources.current` are
+possibly `undefined`: the shell outlives any single page, so the current
+resource is whatever the mounted page reports.
+
+A page created by `createResourceLayout` reports its resource to the shell
+automatically, so resource-scoped composable names still resolve. Pass the
+always-optional `resource` prop to `<Shell>` for routes that render non-library
+content, or in tests and stories:
+
+```tsx
+<Shell resource="appointments">{children}</Shell>
+```
+
+Keep genuinely shared, stateful chrome (sidebar, header, breadcrumb container)
+in `shell`. Keep anything that varies per resource in `layout.render`. Anything
+placed in `shell` cannot read per-page render props.
+
 ## Create secondary layout families
 
 Create another `defineResourceLayout` when a surface has a distinct structural