polen 0.11.0-next.2 → 0.11.0-next.21

package/src/template/routes/examples/name.tsx

@@ -0,0 +1,71 @@
+import { Example } from '#api/examples/schemas/example/example'
+import { route } from '#lib/react-router-effect/route'
+import { useLoaderData } from '#lib/react-router-effect/use-loader-data'
+import { Version } from '#lib/version/$'
+import { Heading } from '@radix-ui/themes'
+import { Str } from '@wollybeard/kit'
+import { Array, Option } from 'effect'
+import { useSearchParams } from 'react-router'
+import { examplesCatalog } from 'virtual:polen/project/examples'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
+import { GraphQLDocument } from '../../components/GraphQLDocument.js'
+
+export const NameSchema = Example
+
+// ============================================================================
+// Loader
+// ============================================================================
+
+export const nameLoader = async ({ params }: any) => {
+  const { name } = params
+
+  if (!name) {
+    throw new Response('Not Found', { status: 404 })
+  }
+
+  // Check if the example exists
+  const exampleOption = Array.findFirst(examplesCatalog.examples, (e) => e.name === name)
+  if (Option.isNone(exampleOption)) {
+    throw new Response('Not Found', { status: 404 })
+  }
+  const example = exampleOption.value
+
+  return example
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+const Component = () => {
+  const example = useLoaderData(NameSchema)
+  const [searchParams] = useSearchParams()
+
+  // Parse version from query parameter if present
+  const versionParam = searchParams.get('version')
+  const selectedVersion = versionParam
+    ? Version.decodeSync(versionParam)
+    : undefined
+
+  return (
+    <>
+      <Heading size='6' mb='4'>{Str.Case.title(example.name)}</Heading>
+      <GraphQLDocument
+        document={example.document}
+        schemaCatalog={schemasCatalog ?? undefined}
+        selectedVersionCoverage={selectedVersion}
+      />
+    </>
+  )
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export const nameRoute = route({
+  path: ':name',
+  schema: NameSchema,
+  loader: nameLoader,
+  Component,
+})

package/src/template/routes/index.tsx

@@ -1,10 +1,56 @@
-import { createRouteIndex } from '#lib/react-router-aid/react-router-aid'
-import { Box } from '@radix-ui/themes'
+import { DirectedFilter } from '#lib/directed-filter'
+import { routeIndex } from '#lib/react-router-effect/react-router-effect'
+import { Swiss } from '#lib/swiss'
+import { redirect } from 'react-router'
+import { templateConfig } from 'virtual:polen/project/config'
+import { examplesCatalog } from 'virtual:polen/project/examples'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
+import { ExamplesSection } from '../components/home/ExamplesSection.js'
+import { Hero } from '../components/home/HeroSection.js'
+
+const loader = () => {
+  // If home is disabled, redirect to reference page
+  if (!templateConfig.home.enabled) {
+    return redirect('/reference')
+  }
+
+  return null
+}
 
 const Component = () => {
-  return <Box>home todo</Box>
+  const filteredExamples = DirectedFilter.filterByProperty(templateConfig.home.examples.filter)('name')(
+    examplesCatalog.examples,
+  )
+
+  return (
+    <>
+      {templateConfig.home.hero.enabled && (
+        <Hero
+          {...Object.fromEntries(
+            Object.entries(templateConfig.home.hero).filter(([k, v]) => k !== 'enabled' && v !== undefined),
+          )}
+        />
+      )}
+      <Swiss.Body>
+        {templateConfig.home.examples.enabled && filteredExamples.length > 0 && (
+          <ExamplesSection
+            examples={filteredExamples}
+            schemaCatalog={schemasCatalog ?? undefined}
+            {...Object.fromEntries(
+              Object.entries({
+                title: templateConfig.home.examples.title,
+                description: templateConfig.home.examples.description,
+                maxExamples: templateConfig.home.examples.maxExamples,
+              }).filter(([_, v]) => v !== undefined),
+            )}
+          />
+        )}
+      </Swiss.Body>
+    </>
+  )
 }
 
-export const index = createRouteIndex({
+export const index = routeIndex({
+  loader,
   Component,
 })

package/src/template/routes/pages.tsx

@@ -1,45 +1,11 @@
-import { createRoute } from '#lib/react-router-aid/react-router-aid'
-import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
+import { route } from '#lib/react-router-effect/route'
 import { SidebarLayout } from '#template/layouts/index'
-import { MDXProvider } from '@mdx-js/react'
-import {
-  Badge,
-  Box,
-  Button,
-  Callout,
-  Card,
-  Code,
-  DataList,
-  Em,
-  Heading,
-  Link,
-  Quote,
-  Separator,
-  Strong,
-  Table,
-  Tabs,
-  Text,
-  Tooltip,
-} from '@radix-ui/themes'
 import { Outlet, useLocation } from 'react-router'
-import PROJECT_DATA_PAGES_CATALOG from 'virtual:polen/project/data/pages-catalog.jsonsuper'
+import { pagesCatalog } from 'virtual:polen/project/pages'
 import { routes } from 'virtual:polen/project/routes.jsx'
-import { CodeBlock } from '../components/CodeBlock.js'
-import { schemaSource } from '../sources/schema-source.js'
-
-const loader = createLoader(async () => {
-  // Check if schema exists first
-  if (schemaSource.isEmpty) {
-    return { schema: null }
-  }
-
-  // Fetch the latest schema for MDX pages
-  const schema = await schemaSource.get('latest')
-  return { schema }
-})
+import { MdxProvider } from '../providers/mdx.js'
 
 const Component = () => {
-  const { schema } = useLoaderData<typeof loader>()
   const location = useLocation()
 
   // Build sidebar from pages catalog
@@ -48,62 +14,19 @@ const Component = () => {
   const topLevelPath = pathSegments[0] ? `/${pathSegments[0]}` : '/'
 
   // Get the sidebar for this section
-  const sidebar = PROJECT_DATA_PAGES_CATALOG.sidebarIndex[topLevelPath]?.items || []
+  const sidebar = pagesCatalog.sidebarIndex[topLevelPath]?.items || []
 
   return (
-    <MDXProvider
-      components={{
-        // Map markdown elements to Radix with spacing
-        p: (props) => <Text as='p' mb='4' {...props} />,
-        h1: (props) => <Heading size='8' mt='6' mb='4' {...props} />,
-        h2: (props) => <Heading size='7' mt='6' mb='3' {...props} />,
-        h3: (props) => <Heading size='6' mt='5' mb='3' {...props} />,
-        h4: (props) => <Heading size='5' mt='5' mb='2' {...props} />,
-        h5: (props) => <Heading size='4' mt='4' mb='2' {...props} />,
-        h6: (props) => <Heading size='3' mt='4' mb='2' {...props} />,
-        strong: Strong,
-        em: Em,
-        code: Code,
-        blockquote: (props) => <Quote my='4' {...props} />,
-        a: Link,
-        hr: (props) => <Separator my='6' {...props} />,
-        table: Table.Root,
-        thead: Table.Header,
-        tbody: Table.Body,
-        tr: Table.Row,
-        th: Table.ColumnHeaderCell,
-        td: Table.Cell,
-        // Lists need spacing too
-        ul: (props) => <Box as='ul' mb='4' style={{ paddingLeft: '1.5rem' }} {...props} />,
-        ol: (props) => <Box as='ol' mb='4' style={{ paddingLeft: '1.5rem' }} {...props} />,
-        li: (props) => <Box as='li' mb='2' {...props} />,
-
-        // Direct Radix components for MDX
-        Badge,
-        Button,
-        // @ts-expect-error
-        Callout,
-        Card,
-        // @ts-expect-error
-        DataList,
-        // @ts-expect-error
-        Tabs,
-        Tooltip,
-
-        // Code Hike component with schema injected
-        CodeBlock: (props: any) => <CodeBlock {...props} schema={schema} />,
-      }}
-    >
+    <MdxProvider>
       <SidebarLayout sidebar={sidebar}>
         <Outlet />
       </SidebarLayout>
-    </MDXProvider>
+    </MdxProvider>
   )
 }
 
-export const pages = createRoute({
+export const pages = route({
   // Pathless layout route - doesn't affect URL paths
-  loader,
   Component,
   children: [...routes], // All MDX page routes go here
 })

package/src/template/routes/reference.tsx

@@ -1,89 +1,224 @@
-import type { Content } from '#api/content/$'
-import { GrafaidOld } from '#lib/grafaid-old/index'
-import { createRoute } from '#lib/react-router-aid/react-router-aid'
-import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
-import { Box } from '@radix-ui/themes'
-import { Outlet } from 'react-router'
+import { Api } from '#api/iso'
+import { Catalog } from '#lib/catalog/$'
+import { GrafaidOld } from '#lib/grafaid-old'
+import { Grafaid } from '#lib/grafaid/$'
+import { S } from '#lib/kit-temp/effect'
+import { Lifecycles } from '#lib/lifecycles/$'
+import { route, useLoaderData } from '#lib/react-router-effect/react-router-effect'
+import { Schema } from '#lib/schema/$'
+import { Version } from '#lib/version/$'
+import { Flex } from '@radix-ui/themes'
+import { neverCase } from '@wollybeard/kit/language'
+import { HashMap, Option } from 'effect'
+import { Effect, Match } from 'effect'
+import React from 'react'
+import { useParams } from 'react-router'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
+import { Field } from '../components/Field.js'
+import { TypeKindIcon } from '../components/graphql/graphql.js'
 import { MissingSchema } from '../components/MissingSchema.js'
-import { VersionSelector } from '../components/VersionSelector.js'
-import { useVersionPath } from '../hooks/useVersionPath.js'
+import { NamedType } from '../components/NamedType.js'
+import { ReferenceVersionPicker } from '../components/ReferenceVersionPicker.js'
+import { GraphqlLifecycleProvider } from '../contexts/GraphqlLifecycleContext.js'
 import { SidebarLayout } from '../layouts/index.js'
-import { VERSION_LATEST } from '../lib/schema-utils/constants.js'
-import { schemaSource } from '../sources/schema-source.js'
-import { reference$type } from './reference.$type.js'
-import { referenceVersion$version$type } from './reference.version.$version.$type.js'
-
-const loader = createLoader(async ({ params }) => {
-  // Handle both versioned and unversioned routes:
-  // - Versioned: /reference/version/:version/:type → params.version exists
-  // - Unversioned: /reference/:type → params.version is undefined, defaults to latest
-  const currentVersion = params.version ?? VERSION_LATEST
-
-  const schema = await schemaSource.get(currentVersion)
-  const availableVersions = schemaSource.versions
-
-  return {
-    schema,
-    currentVersion,
-    availableVersions,
-  }
+
+const routeSchema = S.Struct({
+  catalog: Catalog.Catalog,
+  schema: Schema.Schema,
 })
 
-const Component = () => {
-  const data = useLoaderData<typeof loader>()
+const referenceLoader = ({ params }: any) => {
+  // This should never be called when schemasCatalog is null
+  // because the route won't be added to the router
+  // But we return an Effect.fail for safety
+  if (!schemasCatalog) {
+    return Effect.fail(
+      new Error(
+        'No schema catalog available. This page requires a GraphQL schema to be configured. '
+          + 'Please ensure your Polen configuration includes a valid schema source.',
+      ),
+    )
+  }
+  return Effect.succeed(schemasCatalog).pipe(
+    Effect.map(catalog => {
+      // Resolve the actual schema based on catalog type and params
+      const schema = Match.value(catalog).pipe(
+        Match.tagsExhaustive({
+          CatalogUnversioned: (c) => c.schema,
+          CatalogVersioned: (c) => {
+            // If version param provided, find that specific version
+            if (params.version) {
+              const requestedVersion = Version.decodeSync(params.version)
+              const foundOption = HashMap.get(c.entries, requestedVersion)
+              if (Option.isNone(foundOption)) {
+                // TODO: Return 404 error
+                throw new Error(`Version ${params.version} not found`)
+              }
+              return Option.getOrThrow(foundOption)
+            }
+            // No version param means "latest" - use the last entry
+            const latest = Catalog.Versioned.getLatestOrThrow(c)
+            if (!latest) {
+              throw new Error('No schemas available in versioned catalog')
+            }
+            return latest
+          },
+        }),
+      )
 
-  if (!data.schema) {
+      return {
+        catalog,
+        schema,
+      }
+    }),
+  )
+}
+
+// Single component that handles all reference route variations
+const ReferenceView = () => {
+  const params = useParams() as { version?: string; type?: string; field?: string }
+  const loaderData = useLoaderData(routeSchema)
+  const { catalog, schema } = loaderData
+
+  // Create lifecycles from schema
+  const lifecycle = Lifecycles.createFromSchema(schema)
+
+  if (!schema) {
+    // this would be some sort of internal error, make issue more clear.
     return <MissingSchema />
   }
 
   // Build reference sidebar from schema types
-  const kindMap = GrafaidOld.getKindMap(data.schema)
+  const kindMap = GrafaidOld.getKindMap(schema.definition)
 
-  const sidebarItems: Content.Item[] = []
+  const sidebarItems: any[] = [] // Will be cast to template types in SidebarLayout
   const kindEntries = Object.entries(kindMap.list).filter(([_, types]) => types.length > 0)
 
-  // Build path prefix based on current version using new route structure
-  const versionPath = useVersionPath()
-
   for (const [title, types] of kindEntries) {
     sidebarItems.push({
       type: `ItemSection` as const,
       title,
       pathExp: `reference-${title.toLowerCase()}`,
       isLinkToo: false,
-      links: types.map(type => ({
-        type: `ItemLink` as const,
-        title: type.name,
-        pathExp: `reference/${versionPath}${type.name}`,
-      })),
+      links: types.map(type => {
+        const kind = Grafaid.Schema.typeKindFromClass(type)
+        return {
+          type: `ItemLink` as const,
+          title: (
+            <Flex align='center' gap='1' display='inline-flex'>
+              <TypeKindIcon kind={kind} />
+              {type.name}
+            </Flex>
+          ),
+          pathExp: type.name, // Just the type name, basePath will be prepended
+        }
+      }),
     })
   }
 
-  return (
-    <SidebarLayout sidebar={sidebarItems}>
-      <Box mb={`4`}>
-        <VersionSelector
-          availableVersions={data.availableVersions}
-          currentVersion={data.currentVersion}
+  // Calculate basePath based on schema version
+  const basePath = Api.Schema.Routing.createReferenceBasePath(
+    Schema.getVersion(schema),
+  )
+
+  // Determine view type and render appropriate content
+  const viewType = Api.Schema.Routing.getReferenceViewType({
+    schema: schema,
+    type: params.type || '',
+    field: params.field || '',
+  })
+
+  const content: React.ReactNode = (() => {
+    if (viewType === 'index') {
+      return <div>Select a type from the sidebar to view its documentation.</div>
+    } else if (viewType === 'type-missing' || viewType === 'field-missing') {
+      return <MissingSchema />
+    } else if (viewType === 'type') {
+      const type = schema.definition.getType(params.type!)!
+      return <NamedType data={type} />
+    } else if (viewType === 'field') {
+      const type = schema.definition.getType(params.type!)!
+      const fields = (type as any).getFields()
+      const field = fields[params.field!]
+      return (
+        <Field
+          data={field}
+          parentTypeName={params.type!}
         />
-      </Box>
-      <Outlet />
-    </SidebarLayout>
+      )
+    } else {
+      neverCase(viewType)
+    }
+  })()
+
+  return (
+    <GraphqlLifecycleProvider lifecycle={lifecycle} schema={schema}>
+      <SidebarLayout
+        sidebar={sidebarItems}
+        basePath={basePath}
+        topContent={(() => {
+          const version = Schema.getVersion(schema)
+          return catalog._tag === 'CatalogVersioned' && version
+            ? (
+              <ReferenceVersionPicker
+                data={Catalog.Versioned.getVersions(catalog)}
+                current={version}
+              />
+            )
+            : null
+        })()}
+      >
+        {content}
+      </SidebarLayout>
+    </GraphqlLifecycleProvider>
   )
 }
 
-// Create the versioned reference route with explicit version prefix
-const referenceVersioned = createRoute({
-  path: `version/:version`,
-  loader,
-  Component,
-  children: [referenceVersion$version$type],
-})
+// Define routes that handle type and field params
+const typeAndFieldRoutes = [
+  route({
+    index: true,
+    Component: ReferenceView,
+    loader: referenceLoader,
+    schema: routeSchema,
+  }),
+  route({
+    path: `:type`,
+    Component: ReferenceView,
+    errorElement: <MissingSchema />,
+    loader: referenceLoader,
+    schema: routeSchema,
+    children: [
+      route({
+        path: `:field`,
+        Component: ReferenceView,
+        errorElement: <MissingSchema />,
+        loader: referenceLoader,
+        schema: routeSchema,
+      }),
+    ],
+  }),
+]
 
-// Create the main reference route with explicit version path and fallback type path
-export const reference = createRoute({
-  path: `reference`,
-  loader,
-  Component,
-  children: [referenceVersioned, reference$type],
-})
+/**
+ * Reference documentation routes using proper React Router patterns
+ * - Parent routes have no components (automatically render Outlet)
+ * - Leaf routes have components and loaders that always run fresh
+ * - Single ReferenceView component handles all variations
+ */
+
+export const reference = !schemasCatalog
+  ? null
+  : route({
+    path: `reference`,
+    children: [
+      ...typeAndFieldRoutes,
+      // Only add version routes if versioned
+      ...(Catalog.Versioned.is(schemasCatalog)
+        ? [route({
+          path: `version/:version`,
+          children: typeAndFieldRoutes,
+        })]
+        : []),
+    ],
+  })