@jfdevelops/react-layout 0.16.0 → 0.17.1

package/skills/build-react-layouts/references/factory-patterns.md

@@ -0,0 +1,156 @@
+# Factory Patterns
+
+## Contents
+
+- Direct creation
+- Resource-scoped factories
+- Composable detail pages
+- Multi-resource subsets
+- Higher-order multi-resource components
+- Selection guide
+
+## Create one page directly
+
+Use direct creation for one isolated page:
+
+```tsx
+export const WaitlistPage = createResourceLayout({
+  resource: 'waitlist',
+  name: 'WaitlistPage',
+  segments: {
+    title: 'Waitlist',
+  },
+});
+```
+
+Provide an explicit `name` when the surrounding factory does not establish one.
+
+## Scope a factory to one resource
+
+Use `forResource` when multiple page definitions share one resource:
+
+```tsx
+const createLocationsPage = createResourceLayout.forResource({
+  resource: 'locations',
+});
+
+export const LocationsPage = createLocationsPage({
+  segments: {
+    title: 'Locations',
+  },
+});
+```
+
+Keep the scoped factory private unless several modules genuinely need it.
+
+## Make a generated page composable
+
+Use `makeComposable` when a page needs to retain the resource layout contract
+while allowing consumers to address or rearrange semantic regions:
+
+```tsx
+export const LocationsDetailPage = LocationsPage.makeComposable({
+  name: 'LocationsDetailPage',
+});
+```
+
+Prefer this over copying the parent layout or manually reproducing its header
+and content structure. Do not call `makeComposable` when consumers only need to
+pass `children` or other declared custom props.
+
+## Narrow a factory to several resources
+
+Use `forResources` when a shared implementation applies to a known subset:
+
+```tsx
+const createCalendarPane =
+  resourcePaneLayout.createResourceLayout.forResources('create', 'detail');
+
+export const createCalendarDetailPane = createCalendarPane.forResource({
+  resource: 'detail',
+});
+
+export const createCalendarCreatePane = createCalendarPane.forResource({
+  resource: 'create',
+});
+```
+
+Narrow the resource set before creating the final resource-specific factory.
+
+## Create a higher-order multi-resource component
+
+Use the advanced component factory when several resources share behavior but
+need distinct render implementations:
+
+```tsx
+const createCalendarPage = createResourceLayout
+  .forResources('appointments', 'availability')
+  .createComponent({
+    resources: {
+      appointments: {
+        segments: {
+          title: 'Appointments',
+        },
+        render: function AppointmentsRender() {
+          return <AppointmentsView />;
+        },
+      },
+      availability: {
+        segments: {
+          title: 'Availability',
+        },
+        render: function AvailabilityRender() {
+          return <AvailabilityView />;
+        },
+      },
+    },
+    render: function Render({ resource, children }, context) {
+      return (
+        <context.Root>
+          {children ??
+            (resource === 'appointments' ? (
+              <context.Appointments />
+            ) : (
+              <context.Availability />
+            ))}
+        </context.Root>
+      );
+    },
+  })
+  .asHOF();
+
+export const AppointmentsPage = createCalendarPage('appointments');
+export const AvailabilityPage = createCalendarPage('availability');
+```
+
+Use this pattern only when the resources share meaningful behavior, controls,
+or state transitions. The outer renderer should own behavior shared by the
+resource subset. Each resource renderer should own resource-specific data and
+content.
+
+Attach closely related states when that creates a useful page namespace:
+
+```tsx
+export const AppointmentsPage = Object.assign(
+  createCalendarPage('appointments'),
+  {
+    Loading: AppointmentsLoading,
+    Error: AppointmentsError,
+    NotFound: AppointmentsNotFound,
+  },
+);
+```
+
+Use this for components that are semantically part of the generated page
+surface. Avoid turning the page component into an unrelated utility namespace.
+
+## Choose the narrowest factory
+
+- For one page, call `createResourceLayout`.
+- For several pages belonging to one resource, use `forResource`.
+- For several resources with the same configuration shape, use `forResources`.
+- When consumers need semantic subcomponents, use `makeComposable`.
+- When several resources share an outer behavior but need distinct
+  implementations, use `createComponent(...).asHOF()`.
+- When the surface has a different structural contract, create another
+  `defineResourceLayout`.

package/skills/build-react-layouts/references/routing-and-navigation.md

@@ -0,0 +1,174 @@
+# Routing and Navigation
+
+## Contents
+
+- Grouped resource links
+- Resource configuration
+- Route dispatch
+- Runtime route validation
+- Async route states
+- Separation of concerns
+
+## Generate grouped resource links
+
+Generate navigation from the layout's resource vocabulary:
+
+```tsx
+const navigation = createResourceLinks.withGroups([
+  {
+    links: {
+      dashboard: {
+        label: 'Dashboard',
+        icon: <DashboardIcon />,
+        href: '/admin',
+      },
+      appointments: {
+        label: 'Appointments',
+        icon: <AppointmentsIcon />,
+      },
+    },
+  },
+  {
+    label: 'Configuration',
+    links: {
+      settings: {
+        label: 'Settings',
+        icon: <SettingsIcon />,
+      },
+    },
+  },
+]);
+```
+
+Use groups to express information architecture. Let normal resources use the
+shared resource route. Provide `href` only for special destinations whose route
+does not follow the general pattern.
+
+Render links using the generated `resource` value instead of reconstructing it
+from labels.
+
+## Create the resource configuration
+
+Create a typed configuration that maps each routeable resource to its normal
+and asynchronous states:
+
+```tsx
+export const resourcePageConfig = createResourceConfig({
+  appointments: {
+    component: <AppointmentsPage />,
+    pendingComponent: (
+      <AppointmentsPage>
+        <AppointmentsPage.Loading />
+      </AppointmentsPage>
+    ),
+    errorComponent: (
+      <AppointmentsPage>
+        <AppointmentsPage.Error />
+      </AppointmentsPage>
+    ),
+    notFoundComponent: (
+      <AppointmentsPage>
+        <AppointmentsPage.NotFound />
+      </AppointmentsPage>
+    ),
+  },
+  locations: {
+    component: <Locations />,
+    pendingComponent: <LocationsLoading />,
+    errorComponent: <LocationsError />,
+    notFoundComponent: <LocationsNotFound />,
+    detail: {
+      component: <LocationDetail />,
+      pendingComponent: <LocationDetailLoading />,
+      errorComponent: <LocationDetailError />,
+      notFoundComponent: <LocationDetailNotFound />,
+    },
+  },
+});
+```
+
+Keep this mapping declarative. Keep data fetching and mutation logic inside the
+corresponding feature components or router loaders.
+
+## Dispatch route components generically
+
+Use one generic route adapter to select the configured component:
+
+```tsx
+type ResourceComponentKey =
+  | 'component'
+  | 'pendingComponent'
+  | 'errorComponent'
+  | 'notFoundComponent';
+
+function getResourceComponent(component: ResourceComponentKey) {
+  const resource = Route.useParams({
+    select: ({ resource }) => resource,
+  });
+
+  return resourcePageConfig.getComponent.forResource({
+    resource,
+  })({
+    component,
+  });
+}
+
+function RouteComponent() {
+  return getResourceComponent('component');
+}
+
+function PendingComponent() {
+  return getResourceComponent('pendingComponent');
+}
+```
+
+Use the same mechanism for error and not-found states. Do not create resource
+condition chains in the generic route component when the information belongs
+in `createResourceConfig`.
+
+## Validate route parameters at runtime
+
+The layout provides compile-time resource constraints. The router must still
+validate untrusted URL parameters at runtime.
+
+Parse or validate the route parameter before passing it to generated resource
+helpers. Reject invalid resources through the router's normal not-found
+mechanism. Keep routing validation in the router layer instead of embedding it
+in the shared layout renderer.
+
+## Preserve the layout during async states
+
+Wrap pending, error, and not-found content in the same generated page shell
+when the shell should remain visible during those states.
+
+Use a separate route-state surface when a detail view cannot render its normal
+page structure without loaded data. Keep the mapping explicit so one resource's
+state cannot appear inside another resource's layout.
+
+## Keep ownership clear
+
+Let the layout layer own:
+
+- Valid resource vocabulary
+- Shared application structure
+- Page configuration contracts
+- Semantic composition points
+- Navigation metadata
+- Resource-to-component dispatch
+
+Let the router own:
+
+- URL parsing
+- Search parameter validation
+- Redirects
+- Loaders
+- Route lifecycle selection
+- Runtime not-found behavior
+
+Let feature components own:
+
+- Queries and mutations
+- Feature-level loading details
+- Tables and calendars
+- Forms
+- Resource-specific interactions