polen 0.11.0-next.15 → 0.11.0-next.16

package/src/template/routes/changelog.tsx

@@ -1,42 +1,261 @@
-import { Catalog } from '#lib/catalog/$'
+import { Catalog } from '#lib/catalog'
+import { Change } from '#lib/change'
 import { route } from '#lib/react-router-effect/route'
 import { useLoaderData } from '#lib/react-router-effect/use-loader-data'
-import { catalogBridge } from '../catalog-bridge.js'
-
-import { ChangelogLayout } from '#template/layouts/index'
+import { Revision } from '#lib/revision'
+import { Swiss } from '#lib/swiss'
+import { Version } from '#lib/version'
+import { Box, Flex, Text } from '@radix-ui/themes'
+import { Effect } from 'effect'
+import React, { useEffect, useMemo, useState } from 'react'
+import { useParams } from 'react-router'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
 import { Changelog } from '../components/Changelog/Changelog.js'
+import { renderDate } from '../components/Changelog/Changelog.js'
+import { ChangelogVersionPicker } from '../components/Changelog/ChangelogVersionPicker.js'
+
+interface VersionCounts {
+  breaking: number
+  dangerous: number
+  safe: number
+}
+
+const calculateCounts = (revision: Revision.Revision): VersionCounts => {
+  return {
+    breaking: revision.changes.filter(Change.isBreaking).length,
+    dangerous: revision.changes.filter(Change.isDangerous).length,
+    safe: revision.changes.filter(Change.isSafe).length,
+  }
+}
+
+const SidebarEntry: React.FC<{
+  revision: Revision.Revision
+  counts: VersionCounts
+  isActive: boolean
+}> = ({ revision, counts, isActive }) => {
+  const dateId = revision.date
+
+  return (
+    <Box mb='2'>
+      <a
+        href={`#${dateId}`}
+        style={{
+          textDecoration: 'none',
+          display: 'flex',
+          alignItems: 'center',
+          justifyContent: 'space-between',
+          padding: '0.5rem 0.75rem',
+          borderRadius: '4px',
+          backgroundColor: isActive ? 'var(--gray-a3)' : 'transparent',
+          color: 'inherit',
+          transition: 'background-color 0.2s',
+        }}
+        onClick={(e) => {
+          e.preventDefault()
+          // Update URL hash
+          window.history.pushState(null, '', `#${dateId}`)
+          // Dispatch custom event for pushState
+          window.dispatchEvent(new Event('pushstate'))
+          // Smooth scroll to element
+          document.getElementById(dateId)?.scrollIntoView({ behavior: 'smooth' })
+        }}
+      >
+        <Text size='2' weight={isActive ? 'medium' : 'regular'}>
+          {renderDate(revision.date)}
+        </Text>
+        <Flex gap='2' align='center'>
+          {counts.breaking > 0 && (
+            <Text size='1' weight='medium' style={{ color: '#ef4444' }}>
+              {counts.breaking}
+            </Text>
+          )}
+          {counts.dangerous > 0 && (
+            <Text size='1' weight='medium' style={{ color: '#f59e0b' }}>
+              {counts.dangerous}
+            </Text>
+          )}
+          {counts.safe > 0 && (
+            <Text size='1' weight='medium' style={{ color: '#10b981' }}>
+              {counts.safe}
+            </Text>
+          )}
+        </Flex>
+      </a>
+    </Box>
+  )
+}
+
+//
+//
+//
+//
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Schema
+//
+//
 
 const schema = Catalog.Catalog
 
-const changelogLoader = () => catalogBridge.view()
+//
+//
+//
+//
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Loader
+//
+//
+
+const changelogLoader = () => {
+  // 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)
+}
+
+//
+//
+//
+//
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Component
+//
+//
 
 const Component = () => {
   const catalog = useLoaderData(schema)
 
+  const [activeRevision, setActiveRevision] = useState<string | null>(null)
+  const params = useParams()
+  const urlVersion = params['version']
+
+  // Get available versions if catalog is versioned
+  const availableVersions = useMemo(() => {
+    if (Catalog.Versioned.is(catalog)) {
+      return catalog.entries.map(entry => Version.encodeSync(entry.version))
+    }
+    return []
+  }, [catalog])
+
+  // Get revisions for the current version (for sidebar)
+  const revisions = useMemo(() => {
+    if (Catalog.Unversioned.is(catalog)) {
+      return catalog.schema.revisions
+    } else {
+      // For versioned catalogs, show only current version's revisions
+      if (urlVersion) {
+        const entry = catalog.entries.find(e => Version.encodeSync(e.version) === urlVersion)
+        return entry ? entry.revisions : []
+      }
+      // No revisions if no version selected (will redirect)
+      return []
+    }
+  }, [catalog, urlVersion])
+
+  // Calculate counts for all revisions (SSR-safe)
+  const revisionsWithCounts = revisions.map(revision => ({
+    revision,
+    counts: calculateCounts(revision),
+  }))
+
+  // Track active revision based on URL hash
+  useEffect(() => {
+    const handleHashChange = () => {
+      const hash = window.location.hash.slice(1)
+      setActiveRevision(hash || null)
+    }
+
+    // Set initial active revision
+    handleHashChange()
+
+    // Listen for hash changes
+    window.addEventListener('hashchange', handleHashChange)
+
+    // Listen for pushState/replaceState (custom event we'll dispatch)
+    window.addEventListener('pushstate', handleHashChange)
+
+    return () => {
+      window.removeEventListener('hashchange', handleHashChange)
+      window.removeEventListener('pushstate', handleHashChange)
+    }
+  }, [])
+
   return (
-    <ChangelogLayout catalog={catalog}>
-      <Changelog catalog={catalog} />
-    </ChangelogLayout>
+    <Swiss.Body subgrid>
+      {/* Sidebar */}
+      <Swiss.Item
+        cols={4}
+        style={{
+          position: 'sticky',
+          top: '2rem',
+          height: 'fit-content',
+          minWidth: '250px',
+          maxHeight: 'calc(100vh - 4rem)',
+          overflowY: 'auto',
+        }}
+      >
+        {/* Version picker for versioned catalogs */}
+        {Catalog.Versioned.is(catalog) && availableVersions.length > 1 && urlVersion && (
+          <Box mb='3'>
+            <ChangelogVersionPicker
+              versions={availableVersions}
+              currentVersion={urlVersion}
+            />
+          </Box>
+        )}
+
+        <Text size='2' weight='medium' mb='3' style={{ display: 'block' }}>
+          Revisions
+        </Text>
+        {revisionsWithCounts.map(({ revision, counts }) => (
+          <SidebarEntry
+            key={revision.date}
+            revision={revision}
+            counts={counts}
+            isActive={activeRevision === revision.date}
+          />
+        ))}
+      </Swiss.Item>
+
+      {/* Main content */}
+      <Swiss.Item start={6} cols={7}>
+        <Changelog catalog={catalog} />
+      </Swiss.Item>
+    </Swiss.Body>
   )
 }
 
-export const changelog = route({
-  schema,
-  path: `changelog`,
-  loader: changelogLoader,
-  Component,
-  children: [
-    // Support deep linking to specific version
-    route({
-      path: `version/:version`,
-      loader: changelogLoader,
-      Component,
-    }),
-    // Support deep linking to specific version/revision
-    route({
-      path: `version/:version/revision/:revision`,
-      loader: changelogLoader,
-      Component,
-    }),
-  ],
-})
+//
+//
+//
+//
+// ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ • Routes
+//
+//
+
+export const changelog = !schemasCatalog
+  ? null
+  : route({
+    schema,
+    path: `changelog`,
+    loader: changelogLoader,
+    Component,
+    children: [
+      // Support deep linking to specific version
+      route({
+        path: `version/:version`,
+        loader: changelogLoader,
+        Component,
+      }),
+      // Support deep linking to specific version/revision
+      route({
+        path: `version/:version/revision/:revision`,
+        loader: changelogLoader,
+        Component,
+      }),
+    ],
+  })

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

@@ -0,0 +1,90 @@
+import { Catalog } from '#api/examples/schemas/catalog'
+import { route } from '#lib/react-router-effect/route'
+import { useLoaderData } from '#lib/react-router-effect/use-loader-data'
+import { Swiss } from '#lib/swiss'
+import { Heading } from '@radix-ui/themes'
+import { Str } from '@wollybeard/kit'
+import { Outlet } from 'react-router'
+import { examplesCatalog } from 'virtual:polen/project/examples'
+import { Sidebar } from '../../components/sidebar/Sidebar.js'
+import { examplesIndexRoute } from './_index.js'
+import { nameRoute } from './name.js'
+
+// ============================================================================
+// Global Type Augmentation
+// ============================================================================
+
+declare global {
+  interface RouteSchemaRegistry {
+    'examples': typeof LayoutSchema
+  }
+}
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+const LayoutSchema = Catalog
+
+// ============================================================================
+// Loader
+// ============================================================================
+
+export const layoutLoader = async () => {
+  return examplesCatalog
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+export const LayoutComponent = () => {
+  const examplesCatalog = useLoaderData(Catalog)
+
+  const sidebarData = examplesCatalog.examples.map((example) => ({
+    type: 'ItemLink',
+    title: Str.Case.title(example.name),
+    pathExp: example.name,
+  })) ?? []
+
+  return (
+    <Swiss.Body subgrid>
+      {/* Sidebar */}
+      <Swiss.Item
+        cols={4}
+        style={{
+          // width: '250px',
+          // borderRight: '1px solid var(--gray-a5)',
+          // padding: '1rem',
+          overflowY: 'auto',
+          position: 'sticky',
+          top: 0,
+          // height: '100vh',
+        }}
+      >
+        <Heading size='4' mb='4' style={{ paddingLeft: '1rem' }}>Examples</Heading>
+        <Sidebar data={sidebarData as any} basePath='/examples' />
+      </Swiss.Item>
+
+      {/* Main content */}
+      <Swiss.Item cols={8}>
+        <Outlet />
+      </Swiss.Item>
+    </Swiss.Body>
+  )
+}
+
+// ============================================================================
+// Export
+// ============================================================================
+
+export const examplesRoute = route({
+  path: 'examples',
+  schema: LayoutSchema,
+  loader: layoutLoader,
+  Component: LayoutComponent,
+  children: [
+    examplesIndexRoute,
+    nameRoute,
+  ],
+})

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

@@ -0,0 +1,93 @@
+import { Catalog as ExamplesCatalog } from '#api/examples/schemas/catalog'
+import { Catalog } from '#lib/catalog/$'
+import { routeIndex } from '#lib/react-router-effect/react-router-effect'
+import { useLoaderData } from '#lib/react-router-effect/use-loader-data'
+import { Box, Code, Text } from '@radix-ui/themes'
+import { redirect } from 'react-router'
+import { examplesCatalog, IndexComponent } from 'virtual:polen/project/examples'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
+import { DevelopmentTip } from '../../components/DevelopmentTip.js'
+import { MdxProvider } from '../../providers/mdx.js'
+
+// ============================================================================
+// Schema
+// ============================================================================
+
+const IndexSchema = ExamplesCatalog
+
+// ============================================================================
+// Loader
+// ============================================================================
+
+const isHasExamplesIndexPage = !!IndexComponent
+
+export const loader = async () => {
+  const firstExample = examplesCatalog.examples[0]
+  if (!isHasExamplesIndexPage && firstExample) {
+    throw redirect(`/examples/${firstExample.name}`)
+  }
+
+  return examplesCatalog
+}
+
+// ============================================================================
+// Component
+// ============================================================================
+
+const Component = () => {
+  const examplesCatalog = useLoaderData(IndexSchema)
+  const schema = schemasCatalog && Catalog.getLatestSchema(schemasCatalog).definition
+  const hasExamples = examplesCatalog && examplesCatalog.examples.length > 0
+
+  // TODO: This should become a proper diagnostic viewer component that displays
+  // diagnostics from the Polen diagnostic system, ensuring symmetry between
+  // terminal and UI communication. The component would consume the same diagnostic
+  // data that gets logged to the terminal during build/dev processes.
+  const insituDiagnostic = !hasExamples && (
+    <DevelopmentTip title='Examples Setup' variant='warning'>
+      <Text>
+        The examples section is enabled but no example files were found. To get started:
+      </Text>
+      <Box mt='2'>
+        <Text>
+          <strong>Option 1:</strong> Add <Code>.graphql</Code> or <Code>.gql</Code> files to your <Code>examples/</Code>
+          {' '}
+          directory
+        </Text>
+      </Box>
+      <Box mt='1'>
+        <Text>
+          <strong>Option 2:</strong> If you don't need examples, disable this section in your config by setting{' '}
+          <Code>examples.enabled: false</Code>
+        </Text>
+      </Box>
+    </DevelopmentTip>
+  )
+
+  // Render index component if available
+  if (IndexComponent) {
+    return (
+      <>
+        {insituDiagnostic}
+        {IndexComponent && (
+          <MdxProvider schema={schema}>
+            <IndexComponent />
+          </MdxProvider>
+        )}
+      </>
+    )
+  }
+
+  // Has examples but no index - shouldn't reach here due to redirect
+  return null
+}
+
+// ============================================================================
+// Route
+// ============================================================================
+
+export const examplesIndexRoute = routeIndex({
+  schema: IndexSchema,
+  loader,
+  Component,
+})

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

@@ -0,0 +1,69 @@
+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 { 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 example = examplesCatalog.examples.find((e: any) => e.name === name)
+  if (!example) {
+    throw new Response('Not Found', { status: 404 })
+  }
+
+  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 { DirectedFilter } from '#lib/directed-filter'
 import { routeIndex } from '#lib/react-router-effect/react-router-effect'
-import { Box } from '@radix-ui/themes'
+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 = routeIndex({
+  loader,
   Component,
 })

package/src/template/routes/pages.tsx

@@ -1,29 +1,9 @@
 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.json'
+import { pagesCatalog } from 'virtual:polen/project/pages'
 import { routes } from 'virtual:polen/project/routes.jsx'
-import { CodeBlock } from '../components/CodeBlock.js'
+import { MdxProvider } from '../providers/mdx.js'
 
 const Component = () => {
   const location = useLocation()
@@ -34,56 +14,14 @@ 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 - schema will be loaded client-side if needed
-        CodeBlock: (props: any) => <CodeBlock {...props} schema={null} />,
-      }}
-    >
+    <MdxProvider>
       <SidebarLayout sidebar={sidebar}>
         <Outlet />
       </SidebarLayout>
-    </MDXProvider>
+    </MdxProvider>
   )
 }