@jfdevelops/react-layout 0.16.0 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jfdevelops/react-layout",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "A React library for creating layout components.",
   "repository": {
     "type": "git",
@@ -8,7 +8,8 @@
   },
   "type": "module",
   "files": [
-    "dist"
+    "dist",
+    "skills"
   ],
   "sideEffects": false,
   "main": "./dist/index.cjs",

package/skills/build-react-layouts/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: build-react-layouts
+description: Build, extend, refactor, and review typed resource-based React application layouts using @jfdevelops/react-layout. Use when defining shared application shells with defineResourceLayout, generating resource pages with createResourceLayout, creating semantic composables, configuring grouped resource navigation, dispatching route components with createResourceConfig, building create or detail panes, or sharing implementations across multiple resources.
+---
+
+# Build React Layouts
+
+Use `@jfdevelops/react-layout` as a typed application-structure layer.
+
+Model the application around a central resource definition, a shared layout
+contract, small resource-specific page configurations, and router adapters that
+dispatch through the resource configuration. Create additional layout
+definitions for structurally different surfaces such as side panes.
+
+Do not treat the library as a replacement for routing, data fetching, form
+state, or application business logic.
+
+## Follow the workflow
+
+1. Inspect the existing layout definition and resource list.
+2. Identify whether the requested surface belongs to an existing layout family.
+3. Add or reuse the resource in the central definition.
+4. Define shared configuration values with `createProp`.
+5. Expose semantic layout regions through composables.
+6. Generate the narrowest suitable page factory.
+7. Connect navigation and route-state dispatch through the helpers returned by
+   `defineResourceLayout`.
+8. Run the application's typecheck and relevant tests.
+
+Read [references/architecture.md](references/architecture.md) before creating
+or substantially restructuring a layout definition.
+
+Read [references/factory-patterns.md](references/factory-patterns.md) when
+choosing between direct creation, `forResource`, `forResources`,
+`makeComposable`, or `createComponent(...).asHOF()`.
+
+Read
+[references/routing-and-navigation.md](references/routing-and-navigation.md)
+when integrating resource links, route components, pending states, errors, or
+not-found states.
+
+## Apply the core conventions
+
+- Import `defineResourceLayout` and `createProp` from
+  `@jfdevelops/react-layout`.
+- Import optional preset composables from their dedicated packages.
+- Export the helpers returned by the central `defineResourceLayout` call.
+- Keep the authoritative resource list in the central layout definition.
+- Use resource names that match the application's route vocabulary.
+- Define reusable configuration in `options`.
+- Use `layout.props.include` for definition-time values consumed by the shared
+  renderer.
+- Use `layout.props.custom` for props passed when rendering the generated React
+  component.
+- Use `createProp.component({ type: 'ReactNode' })` for React content.
+- Mark genuinely optional values with `.optional()`.
+- Give optional custom values defaults in the shared renderer when appropriate.
+- Name composables by semantic role rather than visual implementation.
+- Connect semantic composables to design-system components with `wrapWith`.
+- Use resource-aware composable names so generated components remain
+  identifiable in React DevTools.
+- Keep page configuration close to the corresponding resource feature.
+- Keep resource routing generic instead of building a separate route component
+  for every resource.
+- Confirm helper signatures against the installed package version and let the
+  current TypeScript types determine which resource-configuration branches are
+  supported.
+- Reuse the consuming application's router and runtime-validation tools. Do not
+  add a schema dependency solely to connect a route parameter to a resource.
+- Create a separate `defineResourceLayout` definition for a surface with a
+  meaningfully different structural contract, such as a create or detail pane.
+- Preserve inferred types. Do not use `any`, broad casts, or duplicated
+  hand-written resource types to work around a layout mismatch.
+
+## Define semantic composables
+
+Prefer names that describe application structure, such as `Layout`, `Header`,
+`Content`, `ResourceLayout`, `ResourceHeader`, `ResourceHeaderActions`, and
+`Breadcrumb`.
+
+Do not expose every wrapper element as a composable. Expose a region when
+consumers may need to replace it, compose it, style it, or address it through a
+generated component.
+
+## Separate definition-time and render-time props
+
+Use `options` for values supplied while creating a resource layout:
+
+```tsx
+options: {
+  title: createProp.component({ type: 'ReactNode' }).optional(),
+}
+```
+
+Make an option available to the shared renderer through `include`:
+
+```tsx
+layout: {
+  props: {
+    include: {
+      title: true,
+    },
+  },
+}
+```
+
+Use `custom` for values supplied when rendering the resulting component:
+
+```tsx
+layout: {
+  props: {
+    custom: {
+      children: createProp.component({ type: 'ReactNode' }),
+      actions: createProp.component({ type: 'ReactNode' }).optional(),
+      showHeader: createProp.boolean().optional(),
+    },
+  },
+}
+```
+
+Keep these categories distinct. Do not turn a definition-time page contract
+into a custom render prop merely because both eventually reach the renderer.
+
+## Verify the result
+
+1. Typecheck the consuming application.
+2. Run relevant component and route tests.
+3. Exercise at least one resource page.
+4. Exercise pending, error, and not-found dispatch if route configuration
+   changed.
+5. Exercise create and detail panes if pane configuration changed.
+6. Confirm grouped navigation generates the intended resource and route.

package/skills/build-react-layouts/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Build React Layouts"
+  short_description: "Build typed resource-driven React layouts"
+  default_prompt: "Use $build-react-layouts to build or refactor a typed resource-based React application layout."

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

@@ -0,0 +1,184 @@
+# Application Architecture
+
+## Contents
+
+- Central layout definition
+- Shared layout contract
+- Semantic composables
+- Preset composables
+- Secondary layout families
+- Feature organization
+
+## Create a central layout definition
+
+Create one central definition for resources that share the same application
+shell. Export the generated helpers from that module:
+
+```tsx
+import {
+  createProp,
+  defineResourceLayout,
+} from '@jfdevelops/react-layout';
+
+export const {
+  createResourceConfig,
+  createResourceLayout,
+  createResourceLinks,
+} = defineResourceLayout({
+  resources: ['appointments', 'locations', 'services', 'settings'],
+  options: {
+    title: createProp.component({ type: 'ReactNode' }).optional(),
+  },
+  layout: {
+    // Define the shared contract here.
+  },
+});
+```
+
+Import these generated helpers in feature modules instead of defining parallel
+resource lists or rebuilding the application shell.
+
+## Define the shared layout contract
+
+Separate definition-time configuration from render-time component props:
+
+```tsx
+layout: {
+  props: {
+    include: {
+      title: true,
+      segments: true,
+    },
+    custom: {
+      children: createProp.component({ type: 'ReactNode' }),
+      actions: createProp.component({ type: 'ReactNode' }).optional(),
+      showHeader: createProp.boolean().optional(),
+    },
+  },
+}
+```
+
+Use included props for values that describe the generated page. Use custom
+props for content supplied when the generated page component is rendered.
+
+Default optional behavioral props in the renderer:
+
+```tsx
+render: (
+  { children, actions, showHeader = true, segments },
+  { composables },
+) => {
+  // Render the shared shell.
+}
+```
+
+## Create semantic composables
+
+Define named layout regions through the scoped `create` function:
+
+```tsx
+composables: (create) => ({
+  Layout: create({
+    name: ({ capitalize, resource }) =>
+      `${capitalize(resource)}Layout`,
+    wrapWith: AppLayout,
+  }),
+  Header: create({
+    name: ({ capitalize, resource }) =>
+      `${capitalize(resource)}Header`,
+    wrapWith: AppHeader,
+  }),
+  Content: create({
+    name: ({ capitalize, resource }) =>
+      `${capitalize(resource)}Content`,
+    wrapWith: AppContent,
+  }),
+  ResourceHeaderActions: create({
+    name: ({ capitalize, resource }) =>
+      `${capitalize(resource)}ResourceHeaderActions`,
+    wrapWith: AppResourceHeaderActions,
+  }),
+}),
+```
+
+Make the composable name communicate the region's role. Use `wrapWith` to
+connect that role to the application's design-system implementation.
+
+## Merge preset composables
+
+Merge optional preset composables into the same semantic map:
+
+```tsx
+import {
+  createBreadcrumbComposable,
+} from '@jfdevelops/react-layout-composable-breadcrumb';
+
+composables: (create) => ({
+  Layout: create({ name: 'Layout', wrapWith: AppLayout }),
+  ...createBreadcrumbComposable(({ segments }) => (
+    <AppBreadcrumb segments={segments} />
+  )),
+})
+```
+
+Include the preset's required values in `layout.props.include`. Keep
+presentation in the preset renderer and segment definitions in resource page
+configuration.
+
+## Create secondary layout families
+
+Create another `defineResourceLayout` when a surface has a distinct structural
+contract. A side pane is not merely a variation of the main page shell:
+
+```tsx
+export const resourcePaneLayout = defineResourceLayout({
+  resources: ['create', 'detail'],
+  options: {
+    title: createProp.component({ type: 'ReactNode' }),
+  },
+  layout: {
+    props: {
+      include: {
+        title: true,
+      },
+      custom: {
+        children: createProp.component({ type: 'ReactNode' }),
+      },
+    },
+    render: function Render({ children, title }) {
+      return (
+        <Panel>
+          <PanelHeader>
+            <PanelTitle>{title}</PanelTitle>
+          </PanelHeader>
+          <PanelContent>{children}</PanelContent>
+        </Panel>
+      );
+    },
+  },
+});
+```
+
+Do not overload the main page layout with pane-specific flags and conditional
+branches.
+
+## Organize by feature
+
+Keep the general layout definition centralized and concrete page definitions
+beside their feature:
+
+```text
+admin/
+├── -utils/
+│   └── layout.tsx
+├── $resource/
+│   ├── -page-config.tsx
+│   ├── -pane/
+│   │   └── layout.tsx
+│   ├── -appointments/
+│   │   └── pages-config.ts
+│   ├── -locations/
+│   │   └── pages-config.ts
+│   └── index.tsx
+└── route.tsx
+```

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