polen 0.11.0-next.17 → 0.11.0-next.19

package/src/template/components/ReferenceVersionPicker.tsx

@@ -0,0 +1,107 @@
+import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
+import { Version } from '#lib/version/$'
+import { HashMap, Option } from 'effect'
+import { useNavigate } from 'react-router'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
+import { useReferencePath } from '../hooks/useReferencePath.js'
+import { Stores } from '../stores/$.js'
+import { tryWithToast } from '../utils/try-with-toast.js'
+import { VersionPicker } from './VersionPicker.js'
+
+interface Props {
+  data: readonly Version.Version[]
+  current: Version.Version
+}
+
+export const ReferenceVersionPicker: React.FC<Props> = ({ data, current }) => {
+  const navigate = useNavigate()
+  const currentPath = useReferencePath()
+
+  const handleVersionChange = async (version: Version.Version) => {
+    const newVersion = Version.encodeSync(version)
+    const error = await tryWithToast(async () => {
+      // Get the full catalog to find the target schema
+      if (!schemasCatalog) {
+        throw new Error('No catalog available')
+      }
+      const catalog = schemasCatalog
+
+      // This component is only used for versioned catalogs
+      if (catalog._tag !== 'CatalogVersioned') {
+        throw new Error('VersionPicker used with non-versioned catalog')
+      }
+
+      // Find the schema for the target version
+      // Note: newVersion is a string that we need to parse
+      const targetSchemaOption = Option.map(
+        HashMap.findFirst(catalog.entries, (_, key) => Version.encodeSync(key) === newVersion),
+        ([, value]) => value,
+      )
+
+      if (Option.isNone(targetSchemaOption)) {
+        throw new Error(`Version ${newVersion} not found`)
+      }
+
+      const targetSchema = Option.getOrThrow(targetSchemaOption)
+
+      // Find fallback path if needed
+      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema.definition, currentPath)
+      // Get redirect description if path changed
+      const redirectDescription = Api.Schema.Validation.getRedirectDescription(
+        targetSchema.definition,
+        currentPath,
+        fallbackPath,
+        newVersion,
+      )
+      // Create the new path - parse newVersion string to Version type
+      const newPath = Api.Schema.Routing.createReferencePath({
+        version: Version.fromString(newVersion),
+        type: fallbackPath.type || '',
+        field: fallbackPath.field || '',
+      })
+      // Show toast notification if schema location redirect will occur
+      if (redirectDescription) {
+        Stores.Toast.store.info(redirectDescription, {
+          duration: 160_000,
+          actions: [
+            {
+              label: 'Go back',
+              onClick() {
+                navigate(-1)
+              },
+            },
+            {
+              label: 'View changelog',
+              onClick() {
+                // Navigate to changelog page
+                navigate('/changelog')
+              },
+            },
+          ],
+        })
+      }
+
+      navigate(newPath)
+    }, 'Failed to switch version')
+
+    // Fallback logic if error occurred
+    if (error) {
+      // Fallback to simple navigation if schema loading fails
+      const newPath = Api.Schema.Routing.createReferencePath({
+        version: Version.fromString(newVersion),
+        type: currentPath.type || '',
+        field: currentPath.field || '',
+      })
+      navigate(newPath)
+    }
+  }
+
+  return (
+    <VersionPicker
+      versions={data}
+      currentVersion={current}
+      onVersionChange={handleVersionChange}
+    />
+  )
+}

package/src/template/components/VersionCoveragePicker.tsx

@@ -1,6 +1,6 @@
 import { Catalog } from '#lib/catalog/$'
 import { Document } from '#lib/document/$'
-import { VersionCoverage } from '#lib/version-selection/$'
+import { VersionCoverage } from '#lib/version-coverage'
 import { Select } from '@radix-ui/themes'
 import { HashMap } from 'effect'
 import type { FC } from 'react'
@@ -30,12 +30,11 @@ export const VersionCoveragePicker: FC<Props> = ({
     <Select.Root
       value={VersionCoverage.toLabel(current)}
       onValueChange={(label) => {
-        // Find selection by label and pick first version from it
+        // Find the full version coverage by label and pass it entirely
         const selection = options.find(s => VersionCoverage.toLabel(s) === label)
         if (selection) {
-          const versions = VersionCoverage.toVersions(selection)
-          const version = versions[0]
-          if (version) onChange(version)
+          // Pass the entire VersionCoverage, not just the first version
+          onChange(selection)
         }
       }}
     >

package/src/template/components/VersionPicker.tsx

@@ -1,108 +1,42 @@
-import { Api } from '#api/iso'
-import type { React } from '#dep/react/index'
-import { Catalog } from '#lib/catalog/$'
 import { Version } from '#lib/version/$'
-import { HashMap, Option } from 'effect'
-import { useNavigate } from 'react-router'
-import { schemasCatalog } from 'virtual:polen/project/schemas'
-import { useReferencePath } from '../hooks/useReferencePath.js'
-import { Stores } from '../stores/$.js'
-import { tryWithToast } from '../utils/try-with-toast.js'
-import { SimpleVersionPicker } from './SimpleVersionPicker.js'
+import { Select } from '@radix-ui/themes'
+import type * as React from 'react'
 
 interface Props {
-  data: readonly Version.Version[]
-  current: Version.Version
+  versions: readonly Version.Version[]
+  currentVersion: Version.Version
+  onVersionChange: (version: Version.Version) => void
 }
 
-export const VersionPicker: React.FC<Props> = ({ data, current }) => {
-  const navigate = useNavigate()
-  const currentPath = useReferencePath()
-
-  const handleVersionChange = async (version: Version.Version) => {
-    const newVersion = Version.encodeSync(version)
-    const error = await tryWithToast(async () => {
-      // Get the full catalog to find the target schema
-      if (!schemasCatalog) {
-        throw new Error('No catalog available')
-      }
-      const catalog = schemasCatalog
-
-      // This component is only used for versioned catalogs
-      if (catalog._tag !== 'CatalogVersioned') {
-        throw new Error('VersionPicker used with non-versioned catalog')
-      }
-
-      // Find the schema for the target version
-      // Note: newVersion is a string that we need to parse
-      const targetSchemaOption = Option.map(
-        HashMap.findFirst(catalog.entries, (_, key) => Version.encodeSync(key) === newVersion),
-        ([, value]) => value,
-      )
-
-      if (Option.isNone(targetSchemaOption)) {
-        throw new Error(`Version ${newVersion} not found`)
-      }
-
-      const targetSchema = Option.getOrThrow(targetSchemaOption)
-
-      // Find fallback path if needed
-      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema.definition, currentPath)
-      // Get redirect description if path changed
-      const redirectDescription = Api.Schema.Validation.getRedirectDescription(
-        targetSchema.definition,
-        currentPath,
-        fallbackPath,
-        newVersion,
-      )
-      // Create the new path - parse newVersion string to Version type
-      const newPath = Api.Schema.Routing.createReferencePath({
-        version: Version.fromString(newVersion),
-        type: fallbackPath.type || '',
-        field: fallbackPath.field || '',
-      })
-      // Show toast notification if schema location redirect will occur
-      if (redirectDescription) {
-        Stores.Toast.store.info(redirectDescription, {
-          duration: 160_000,
-          actions: [
-            {
-              label: 'Go back',
-              onClick() {
-                navigate(-1)
-              },
-            },
-            {
-              label: 'View changelog',
-              onClick() {
-                // Navigate to changelog page
-                navigate('/changelog')
-              },
-            },
-          ],
-        })
-      }
-
-      navigate(newPath)
-    }, 'Failed to switch version')
-
-    // Fallback logic if error occurred
-    if (error) {
-      // Fallback to simple navigation if schema loading fails
-      const newPath = Api.Schema.Routing.createReferencePath({
-        version: Version.fromString(newVersion),
-        type: currentPath.type || '',
-        field: currentPath.field || '',
-      })
-      navigate(newPath)
-    }
+/**
+ * A generic version picker component that can be used for any versioned content.
+ * This is a controlled component - parent manages the state.
+ */
+export const VersionPicker: React.FC<Props> = ({
+  versions,
+  currentVersion,
+  onVersionChange,
+}) => {
+  // Don't show selector if only one version
+  if (versions.length <= 1) {
+    return null
   }
 
   return (
-    <SimpleVersionPicker
-      versions={data}
-      currentVersion={current}
-      onVersionChange={handleVersionChange}
-    />
+    <Select.Root
+      value={Version.encodeSync(currentVersion)}
+      onValueChange={(versionEncoded) => onVersionChange(Version.fromString(versionEncoded))}
+    >
+      <Select.Trigger style={{ minWidth: '120px' }}>
+        Version {Version.encodeSync(currentVersion)}
+      </Select.Trigger>
+      <Select.Content position='popper' sideOffset={5}>
+        {versions.map(version => (
+          <Select.Item key={Version.encodeSync(version)} value={Version.encodeSync(version)}>
+            Version {Version.encodeSync(version)}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
   )
 }

package/src/template/components/home/QuickStart.tsx

@@ -1,5 +1,6 @@
 import { Box, Card, Heading, Section, Tabs, Text } from '@radix-ui/themes'
 import { highlight } from 'codehike/code'
+import { Effect } from 'effect'
 import * as React from 'react'
 import { CodeBlock } from '../CodeBlock.js'
 
@@ -73,14 +74,22 @@ export const QuickStartSection: React.FC<Props> = ({ examples = defaultExamples
 
   React.useEffect(() => {
     const highlightExamples = async () => {
-      const highlighted = await Promise.all(
-        examples.map(async (example) => ({
-          label: example.label,
-          codeblock: await highlight(
-            { value: example.code, lang: example.language, meta: '' },
-            { theme: 'github-light' },
+      const highlighted = await Effect.runPromise(
+        Effect.all(
+          examples.map((example) =>
+            Effect.tryPromise({
+              try: async () => ({
+                label: example.label,
+                codeblock: await highlight(
+                  { value: example.code, lang: example.language, meta: '' },
+                  { theme: 'github-light' },
+                ),
+              }),
+              catch: (error) => new Error(`Failed to highlight ${example.label}: ${error}`),
+            })
           ),
-        })),
+          { concurrency: 'unbounded' },
+        ),
       )
       setHighlightedExamples(highlighted)
     }

package/src/template/hooks/use-highlighted.ts

@@ -1,5 +1,6 @@
 import type { HighlightedCode } from 'codehike/code'
 import { highlight } from 'codehike/code'
+import { Duration, Effect } from 'effect'
 import * as React from 'react'
 
 /**
@@ -29,26 +30,37 @@ export const useHighlighted = (
   const [highlightedCode, setHighlightedCode] = React.useState<HighlightedCode | null>(null)
 
   React.useEffect(() => {
-    const highlightContent = async () => {
-      // Add a timeout to detect if highlight is hanging
-      const timeoutPromise = new Promise((_, reject) => {
-        setTimeout(() => reject(new Error('Highlight timeout after 5 seconds')), 5000)
-      })
-
-      const highlightPromise = highlight(
-        {
-          value: content,
-          lang: config.lang,
-          meta: metaString,
-        },
-        {
-          theme: 'github-light',
-        },
-      )
+    const HIGHLIGHT_TIMEOUT = Duration.seconds(5)
 
-      const highlighted = await Promise.race([highlightPromise, timeoutPromise])
-
-      setHighlightedCode(highlighted as any)
+    const highlightContent = async () => {
+      try {
+        const highlighted = await Effect.runPromise(
+          Effect.tryPromise({
+            try: () =>
+              highlight(
+                {
+                  value: content,
+                  lang: config.lang,
+                  meta: metaString,
+                },
+                {
+                  theme: 'github-light',
+                },
+              ),
+            catch: (error) => new Error(`Highlight failed: ${error}`),
+          }).pipe(
+            Effect.timeout(HIGHLIGHT_TIMEOUT),
+            Effect.catchTag(
+              'TimeoutException',
+              () => Effect.fail(new Error(`Highlight timeout after ${Duration.toSeconds(HIGHLIGHT_TIMEOUT)} seconds`)),
+            ),
+          ),
+        )
+        setHighlightedCode(highlighted)
+      } catch (error) {
+        console.error('Failed to highlight code:', error)
+        setHighlightedCode(null)
+      }
     }
     highlightContent()
   }, [content, config.lang, config.interactive])

package/src/template/lib/fetch-text.ts

@@ -1,13 +1,54 @@
+import { Either } from 'effect'
+
+/**
+ * Error type for fetch failures
+ */
+export interface FetchError {
+  readonly _tag: 'FetchError'
+  readonly url: string
+  readonly status: number
+  readonly statusText: string
+  readonly message: string
+}
+
+const makeFetchError = (url: string, status: number, statusText: string): FetchError => ({
+  _tag: 'FetchError',
+  url,
+  status,
+  statusText,
+  message: `Failed to fetch: ${url} (${status} ${statusText})`,
+})
+
 /**
  * Fetch text content from a URL
  * @param url - The URL to fetch from
+ * @returns Either with text content on right or FetchError on left
+ */
+export const fetchTextEither = async (url: string): Promise<Either.Either<string, FetchError>> => {
+  try {
+    const response = await fetch(url)
+    if (!response.ok) {
+      return Either.left(makeFetchError(url, response.status, response.statusText))
+    }
+    const text = await response.text()
+    return Either.right(text)
+  } catch (error) {
+    // Network errors or other exceptions
+    return Either.left(makeFetchError(url, 0, 'Network Error'))
+  }
+}
+
+/**
+ * Fetch text content from a URL (legacy throwing version)
+ * @param url - The URL to fetch from
  * @returns Promise that resolves to the text content
  * @throws Error if the request fails
+ * @deprecated Use fetchTextEither for better error handling
  */
 export const fetchText = async (url: string): Promise<string> => {
-  const response = await fetch(url)
-  if (!response.ok) {
-    throw new Error(`Failed to fetch: ${url} (${response.status} ${response.statusText})`)
+  const result = await fetchTextEither(url)
+  if (Either.isLeft(result)) {
+    throw new Error(result.left.message)
   }
-  return response.text()
+  return result.right
 }

package/src/template/{components/Changelog/Changelog.tsx → routes/changelog/ChangelogBody.tsx}

@@ -1,75 +1,18 @@
 import { Catalog } from '#lib/catalog/$'
 import { Change } from '#lib/change/$'
-import { DateOnly } from '#lib/date-only/$'
 import { Revision } from '#lib/revision/$'
 import { Schema } from '#lib/schema/$'
-import { Version } from '#lib/version/$'
-import { HashMap, Option } from 'effect'
 const CRITICALITY_LEVELS = ['BREAKING', 'DANGEROUS', 'NON_BREAKING'] as const
 import type { CriticalityLevel } from '@graphql-inspector/core'
 import { Box, Heading } from '@radix-ui/themes'
-import React, { useEffect } from 'react'
+import React from 'react'
 import { useMemo } from 'react'
-import { useNavigate, useParams } from 'react-router'
-import { ComponentDispatch } from '../ComponentDispatch.js'
-import { CriticalitySection } from './CriticalitySection.js'
-import * as Group from './groups/index.js'
-
-export const renderDate = (dateOnly: DateOnly.DateOnly) => {
-  const date = DateOnly.toDate(dateOnly)
-  const year = date.getUTCFullYear()
-  return `${year} ${
-    date.toLocaleString('default', {
-      month: 'long',
-      day: 'numeric',
-      timeZone: 'UTC',
-    })
-  }`
-}
-
-export const Changelog: React.FC<{ catalog: Catalog.Catalog }> = ({ catalog }) => {
-  const params = useParams()
-  const navigate = useNavigate()
-  const urlVersion = params['version']
-
-  // Redirect to latest version if versioned catalog and no version specified
-  useEffect(() => {
-    if (urlVersion) return
-    if (Catalog.Unversioned.is(catalog)) return
-    const latestSchema = Catalog.Versioned.getLatestOrThrow(catalog)
-    const latestVersion = Version.encodeSync(latestSchema.version)
-    navigate(`/changelog/version/${latestVersion}`, { replace: true })
-  }, [catalog, urlVersion, navigate])
-
-  // Get revisions and corresponding schema based on catalog type and URL params
-  const { revisions, schema } = useMemo(() => {
-    if (Catalog.Unversioned.is(catalog)) {
-      return {
-        revisions: catalog.schema.revisions,
-        schema: catalog.schema,
-      }
-    } else {
-      // For versioned catalogs, always show specific version (never all)
-      if (urlVersion) {
-        const entryOption = Option.map(
-          HashMap.findFirst(catalog.entries, (_, key) => Version.encodeSync(key) === urlVersion),
-          ([, value]) => value,
-        )
-        return Option.match(entryOption, {
-          onNone: () => ({ revisions: [], schema: null }),
-          onSome: (entry) => ({ revisions: entry.revisions, schema: entry }),
-        })
-      }
-      // This shouldn't happen due to redirect above, but return empty as fallback
-      return { revisions: [], schema: null }
-    }
-  }, [catalog, urlVersion])
-
-  // Don't render anything while redirecting
-  if (Catalog.Versioned.is(catalog) && !urlVersion) {
-    return null
-  }
+import { CriticalitySection } from '../../components/Changelog/CriticalitySection.js'
+import * as Group from '../../components/Changelog/groups/index.js'
+import { ComponentDispatch } from '../../components/ComponentDispatch.js'
+import { renderDate } from './utils.js'
 
+export const ChangelogBody: React.FC<{ schema: Schema.Schema }> = ({ schema }) => {
   return (
     <Box>
       {/* Title bar - always shown */}
@@ -77,7 +20,7 @@ export const Changelog: React.FC<{ catalog: Catalog.Catalog }> = ({ catalog }) =
         Changelog
       </Heading>
 
-      {revisions.map(revision => <Changeset key={revision.date} revision={revision} schema={schema} />)}
+      {schema.revisions.map(revision => <Changeset key={revision.date} revision={revision} schema={schema} />)}
     </Box>
   )
 }

package/src/template/routes/changelog/ChangelogSidebar.tsx

@@ -0,0 +1,80 @@
+import { Catalog } from '#lib/catalog/$'
+import { Schema } from '#lib/schema/$'
+import { Swiss } from '#lib/swiss/$'
+import { Version } from '#lib/version'
+import { Box, Text } from '@radix-ui/themes'
+import { useEffect, useState } from 'react'
+import { useNavigate, useParams } from 'react-router'
+import { VersionPicker } from '../../components/VersionPicker.js'
+import { ChangelogSidebarItem } from './ChangelogSidebarItem.js'
+
+export const ChangelogSidebar: React.FC<{
+  catalog: Catalog.Catalog
+  schema: Schema.Schema
+}> = ({ catalog, schema }) => {
+  {
+    const navigate = useNavigate()
+
+    // Get revisions for the current version (for sidebar)
+    const revisions = schema.revisions
+
+    const [activeRevision, setActiveRevision] = useState<string | null>(null)
+    // 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 (
+      <Swiss.Item
+        cols={3}
+        style={{
+          position: 'sticky',
+          top: '2rem',
+          height: 'fit-content',
+          minWidth: '250px',
+          maxHeight: 'calc(100vh - 4rem)',
+          overflowY: 'auto',
+        }}
+      >
+        {Catalog.Versioned.is(catalog) && Schema.Versioned.is(schema) && (
+          <Box mb='3'>
+            <VersionPicker
+              versions={Catalog.Versioned.getVersions(catalog)}
+              currentVersion={schema.version}
+              onVersionChange={(newVersion) => {
+                navigate(`/changelog/version/${Version.encodeSync(newVersion)}`)
+              }}
+            />
+          </Box>
+        )}
+        <Text size='2' weight='medium' mb='3' style={{ display: 'block' }}>
+          Revisions
+        </Text>
+        {revisions.map((revision) => (
+          <ChangelogSidebarItem
+            key={revision.date}
+            revision={revision}
+            isActive={activeRevision === revision.date}
+          />
+        ))}
+      </Swiss.Item>
+    )
+  }
+}

package/src/template/routes/changelog/ChangelogSidebarItem.tsx

@@ -0,0 +1,68 @@
+import { Change } from '#lib/change'
+import { Revision } from '#lib/revision'
+import { Box, Flex, Text } from '@radix-ui/themes'
+import { renderDate } from './utils.js'
+
+export const ChangelogSidebarItem: React.FC<{
+  revision: Revision.Revision
+  isActive: boolean
+}> = ({ revision, isActive }) => {
+  const counts = calculateCounts(revision)
+
+  return (
+    <Box mb='2'>
+      <a
+        href={`#${revision.date}`}
+        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, '', `#${revision.date}`)
+          // Dispatch custom event for pushState
+          window.dispatchEvent(new Event('pushstate'))
+          // Smooth scroll to element
+          document.getElementById(revision.date)?.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>
+  )
+}
+
+export const calculateCounts = (revision: Revision.Revision) => {
+  return {
+    breaking: revision.changes.filter(Change.isBreaking).length,
+    dangerous: revision.changes.filter(Change.isDangerous).length,
+    safe: revision.changes.filter(Change.isSafe).length,
+  }
+}