polen 0.11.0-next.14 → 0.11.0-next.16

package/src/template/components/NamedType.tsx

@@ -1,10 +1,16 @@
 import { Api } from '#api/iso'
-import { SchemaLifecycle } from '#lib/schema-lifecycle'
-import { Badge, Box, Heading, Text } from '@radix-ui/themes'
+import { Lifecycles } from '#lib/lifecycles/$'
+import { Schema } from '#lib/schema/$'
+import { Version } from '#lib/version/$'
+import { Badge, Box, Heading, Link, Text } from '@radix-ui/themes'
+import { HashSet, Match } from 'effect'
 import { type GraphQLNamedType } from 'graphql'
 import type { FC } from 'react'
-import { useSchemaLifecycle } from '../contexts/SchemaLifecycleContext.js'
+import { useSchema } from '../contexts/GraphqlLifecycleContext.js'
+import { useExamplesForType } from '../hooks/use-examples.js'
+import { ExampleLink } from './ExampleLink.js'
 import { FieldListSection } from './FieldListSection.js'
+import { TypeLink } from './graphql/graphql.js'
 import { Markdown } from './Markdown.js'
 
 export interface Props {
@@ -12,7 +18,7 @@ export interface Props {
 }
 
 export const NamedType: FC<Props> = ({ data }) => {
-  const { lifecycle, currentVersion } = useSchemaLifecycle()
+  const { schema, lifecycles } = useSchema()
 
   const description = data.description
     ? (
@@ -23,33 +29,68 @@ export const NamedType: FC<Props> = ({ data }) => {
     : null
 
   // Get lifecycle information for this type
-  const typeLifecycle = lifecycle ? SchemaLifecycle.getTypeLifecycle(lifecycle, data.name) : null
-  const addedDate = lifecycle ? SchemaLifecycle.getTypeAddedDate(lifecycle, data.name) : null
-  const removedDate = lifecycle ? SchemaLifecycle.getTypeRemovedDate(lifecycle, data.name) : null
-  const isAvailable = lifecycle ? SchemaLifecycle.isTypeCurrentlyAvailable(lifecycle, data.name) : true
+  const since = Lifecycles.getTypeSince(lifecycles, data.name, schema)
+  const removedDate = Lifecycles.getTypeRemovedDate(lifecycles, data.name, schema)
+
+  // Get examples that use this type
+  const currentVersion = Schema.Versioned.is(schema)
+    ? schema.version
+    : null
+  const examples = useExamplesForType(data.name, currentVersion)
 
   return (
     <Box>
       <Box style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '8px' }}>
-        <Heading size='8'>{data.name}</Heading>
-        {addedDate && (
-          <Badge color='green' variant='soft' size='1'>
-            Added {Api.Schema.dateToVersionString(addedDate)}
-          </Badge>
+        <Heading size='8'>
+          <TypeLink type={data} />
+        </Heading>
+        {since && (
+          since._tag === 'initial'
+            ? (
+              <Badge color='blue' variant='soft' size='1'>
+                Since initial version
+              </Badge>
+            )
+            : (
+              <Link
+                href={Api.Schema.Routing.createChangelogUrl(
+                  since.revision.date,
+                  since.schema,
+                )}
+                style={{ textDecoration: 'none' }}
+              >
+                <Badge color='green' variant='soft' size='1' style={{ cursor: 'pointer' }}>
+                  Added {Match.value(since.schema).pipe(
+                    Match.tagsExhaustive({
+                      SchemaVersioned: (s) => `${Version.encodeSync(s.version)}@${since.revision.date}`,
+                      SchemaUnversioned: () => since.revision.date,
+                    }),
+                  )}
+                </Badge>
+              </Link>
+            )
         )}
         {removedDate && (
           <Badge color='red' variant='soft' size='1'>
             Removed {Api.Schema.dateToVersionString(removedDate)}
           </Badge>
         )}
-        {!isAvailable && (
-          <Badge color='orange' variant='soft' size='1'>
-            Not available in current version
-          </Badge>
-        )}
       </Box>
       {description}
       <FieldListSection data={data} />
+      {HashSet.size(examples) > 0 && (
+        <Box mt='4'>
+          <Heading size='4' mb='2'>Used in Examples</Heading>
+          <Box style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
+            {[...examples].map((exampleRef) => (
+              <ExampleLink
+                key={`${exampleRef.name}-${Version.encodeSync(exampleRef.version)}`}
+                exampleRef={exampleRef}
+              />
+            ))}
+          </Box>
+        </Box>
+      )}
     </Box>
   )
 }

package/src/template/components/SimpleVersionPicker.tsx

@@ -0,0 +1,48 @@
+import { Version } from '#lib/version/$'
+import { Select } from '@radix-ui/themes'
+import type * as React from 'react'
+
+interface Props {
+  versions: readonly Version.Version[]
+  currentVersion: Version.Version
+  onVersionChange: (version: Version.Version) => void
+  label?: string
+}
+
+/**
+ * A generic version picker component that can be used for any versioned content.
+ * This is a controlled component - parent manages the state.
+ */
+export const SimpleVersionPicker: React.FC<Props> = ({
+  versions,
+  currentVersion,
+  onVersionChange,
+  label = '',
+}) => {
+  // Don't show selector if only one version
+  if (versions.length <= 1) {
+    return null
+  }
+
+  return (
+    <Select.Root
+      value={Version.encodeSync(currentVersion)}
+      onValueChange={(versionEncoded) => onVersionChange(Version.fromString(versionEncoded))}
+    >
+      <Select.Trigger style={{ minWidth: '120px' }}>
+        {label}
+        {label ? ' ' : ''}
+        {Version.encodeSync(currentVersion)}
+      </Select.Trigger>
+      <Select.Content position='popper' sideOffset={5}>
+        {versions.map(version => (
+          <Select.Item key={Version.encodeSync(version)} value={Version.encodeSync(version)}>
+            {label}
+            {label ? ' ' : ''}
+            {Version.encodeSync(version)}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  )
+}

package/src/template/components/TypeAnnotation.tsx

@@ -1,8 +1,8 @@
 import type { React } from '#dep/react/index'
 import { Text } from '@radix-ui/themes'
 import type { GraphQLType } from 'graphql'
-import { isInputObjectType, isListType, isNamedType, isNonNullType, isScalarType } from 'graphql'
-import { ReferenceLink } from './ReferenceLink.js'
+import { isListType, isNamedType, isNonNullType } from 'graphql'
+import { TypeLink } from './graphql/graphql.js'
 
 /**
  * Renders a GraphQL type recursively, with links for named types
@@ -29,31 +29,13 @@ export const TypeAnnotation: React.FC<{ type: GraphQLType }> = ({ type }) => {
     )
   }
 
-  // Handle named types
+  // Handle named types - use TypeLink which already has icon support
   if (isNamedType(type)) {
-    const namedType = type
-
-    // Handle input object types
-    if (isInputObjectType(namedType)) {
-      return (
-        <ReferenceLink type={namedType.name}>
-          <Text color='green'>{namedType.name}</Text>
-        </ReferenceLink>
-      )
-    }
-
-    // If it's an expandable type (object or interface), make it a link
-    // if (Grafaid.isExpandableType(namedType)) {
-    return (
-      <ReferenceLink type={namedType.name}>
-        <Text color={isScalarType(namedType) ? `purple` : `blue`}>{namedType.name}</Text>
-      </ReferenceLink>
-    )
-
-    // For scalar and other non-expandable types, just render the name
-    // return <Text color="purple">{namedType.name}</Text>
+    return <TypeLink type={type} />
   }
 
-  // Fallback for any other case (shouldn't happen in standard GraphQL usage)
-  return <Text>{String(type)}</Text>
+  // TypeScript exhaustiveness check - this should be unreachable
+  // as the above three cases cover all possible GraphQLType implementations
+  const _exhaustive: never = type
+  throw new Error(`Unexpected GraphQL type encountered: ${String(_exhaustive)}`)
 }

package/src/template/components/VersionCoveragePicker.tsx

@@ -0,0 +1,57 @@
+import { Catalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { VersionCoverage } from '#lib/version-selection/$'
+import { Select } from '@radix-ui/themes'
+import { HashMap } from 'effect'
+import type { FC } from 'react'
+
+interface Props {
+  document: Document.Document
+  schemaCatalog: Catalog.Catalog
+  current: VersionCoverage.VersionCoverage
+  onChange: (versionCoverage: VersionCoverage.VersionCoverage) => void
+}
+
+/**
+ * Version picker for examples that shows all schema versions.
+ * Groups versions that share the same document into single entries.
+ */
+export const VersionCoveragePicker: FC<Props> = ({
+  document,
+  current,
+  onChange,
+}) => {
+  if (Document.Unversioned.is(document)) return null
+
+  const options = Array.from(HashMap.keys(document.versionDocuments))
+  if (options.length === 0) return null
+
+  return (
+    <Select.Root
+      value={VersionCoverage.toLabel(current)}
+      onValueChange={(label) => {
+        // Find selection by label and pick first version from it
+        const selection = options.find(s => VersionCoverage.toLabel(s) === label)
+        if (selection) {
+          const versions = VersionCoverage.toVersions(selection)
+          const version = versions[0]
+          if (version) onChange(version)
+        }
+      }}
+    >
+      <Select.Trigger>
+        {VersionCoverage.toLabel(current)}
+      </Select.Trigger>
+      <Select.Content position='popper' sideOffset={5}>
+        {options.map(selection => (
+          <Select.Item
+            key={VersionCoverage.toLabel(selection)}
+            value={VersionCoverage.toLabel(selection)}
+          >
+            {VersionCoverage.toLabel(selection)}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  )
+}

package/src/template/components/VersionPicker.tsx

@@ -1,44 +1,58 @@
 import { Api } from '#api/iso'
 import type { React } from '#dep/react/index'
-import { Select } from '@radix-ui/themes'
+import { Version } from '#lib/version/$'
 import { useNavigate } from 'react-router'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
 import { useReferencePath } from '../hooks/useReferencePath.js'
-import { schemaSource } from '../sources/schema-source.js'
 import { Stores } from '../stores/$.js'
 import { tryWithToast } from '../utils/try-with-toast.js'
+import { SimpleVersionPicker } from './SimpleVersionPicker.js'
 
 interface Props {
-  all: string[]
-  current: string
+  data: readonly Version.Version[]
+  current: Version.Version
 }
 
-export const VersionPicker: React.FC<Props> = ({ all, current }) => {
+export const VersionPicker: React.FC<Props> = ({ data, current }) => {
   const navigate = useNavigate()
   const currentPath = useReferencePath()
 
-  // Don't show selector if only one version
-  if (all.length <= 1) {
-    return null
-  }
-
-  const handleVersionChange = async (newVersion: string) => {
+  const handleVersionChange = async (version: Version.Version) => {
+    const newVersion = Version.encodeSync(version)
     const error = await tryWithToast(async () => {
-      // Check if current path exists in target version
-      const targetSchema = await schemaSource.get(newVersion)
+      // 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 targetSchema = catalog.entries.find(schema => Version.encodeSync(schema.version) === newVersion)
+
+      if (!targetSchema) {
+        throw new Error(`Version ${newVersion} not found`)
+      }
+
       // Find fallback path if needed
-      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema, currentPath)
+      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema.definition, currentPath)
       // Get redirect description if path changed
       const redirectDescription = Api.Schema.Validation.getRedirectDescription(
-        targetSchema,
+        targetSchema.definition,
         currentPath,
         fallbackPath,
         newVersion,
       )
-      // Create the new path
+      // Create the new path - parse newVersion string to Version type
       const newPath = Api.Schema.Routing.createReferencePath({
-        version: newVersion,
-        type: fallbackPath.type,
-        field: fallbackPath.field,
+        version: Version.fromString(newVersion),
+        type: fallbackPath.type || '',
+        field: fallbackPath.field || '',
       })
       // Show toast notification if schema location redirect will occur
       if (redirectDescription) {
@@ -69,26 +83,19 @@ export const VersionPicker: React.FC<Props> = ({ all, current }) => {
     if (error) {
       // Fallback to simple navigation if schema loading fails
       const newPath = Api.Schema.Routing.createReferencePath({
-        version: newVersion,
-        type: currentPath.type,
-        field: currentPath.field,
+        version: Version.fromString(newVersion),
+        type: currentPath.type || '',
+        field: currentPath.field || '',
       })
       navigate(newPath)
     }
   }
 
   return (
-    <Select.Root value={current} onValueChange={handleVersionChange}>
-      <Select.Trigger>
-        {current === Api.Schema.VERSION_LATEST ? `Latest` : current}
-      </Select.Trigger>
-      <Select.Content>
-        {all.map(version => (
-          <Select.Item key={version} value={version}>
-            {version === Api.Schema.VERSION_LATEST ? `Latest` : version}
-          </Select.Item>
-        ))}
-      </Select.Content>
-    </Select.Root>
+    <SimpleVersionPicker
+      versions={data}
+      currentVersion={current}
+      onVersionChange={handleVersionChange}
+    />
   )
 }

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

@@ -0,0 +1,49 @@
+import type { Api } from '#api/$'
+import { Catalog } from '#lib/catalog/$'
+import { Box, Heading, Section } from '@radix-ui/themes'
+import * as React from 'react'
+import { Carousel } from '../Carousel.js'
+import { GraphQLDocument } from '../GraphQLDocument.js'
+
+interface ExamplesSectionProps {
+  schemaCatalog?: Catalog.Catalog | undefined
+  title?: string | undefined
+  description?: string | undefined
+  maxExamples?: number | undefined
+  examples: readonly Api.Examples.Example.Example[]
+}
+
+export const ExamplesSection: React.FC<ExamplesSectionProps> = ({
+  examples,
+  schemaCatalog,
+  title = 'API Examples',
+  maxExamples = 3,
+}) => {
+  if (examples.length === 0) {
+    return null
+  }
+
+  // Limit examples to maxExamples
+  const displayExamples = examples.slice(0, maxExamples)
+
+  return (
+    <Section size='3' id='examples' style={{ overflow: 'visible' }}>
+      <Box mb='4' style={{ textAlign: 'center' }}>
+        <Heading size='6' mb='2'>
+          {title}
+        </Heading>
+      </Box>
+
+      <Carousel autoPlay={true}>
+        {displayExamples.map((example) => (
+          <GraphQLDocument
+            style={{ height: '100%' }}
+            key={example.name}
+            document={example.document}
+            schemaCatalog={schemaCatalog}
+          />
+        ))}
+      </Carousel>
+    </Section>
+  )
+}

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

@@ -0,0 +1,135 @@
+import { CatalogStatistics } from '#lib/catalog-statistics/$'
+import { Catalog } from '#lib/catalog/$'
+import { Box, Card, Flex, Grid, Heading, Section, Text } from '@radix-ui/themes'
+import { Link } from 'react-router'
+import { schemasCatalog } from 'virtual:polen/project/schemas'
+
+interface FeaturesGridProps {
+  features?: Feature[]
+}
+
+interface Feature {
+  title: string
+  value: string | number
+  description?: string
+  link?: string
+}
+
+export const FeaturesGridSection: React.FC<FeaturesGridProps> = ({ features }) => {
+  const defaultFeatures = getDefaultFeatures()
+  const displayFeatures = features || defaultFeatures
+
+  return (
+    <Section size='3' pb='8'>
+      <Box style={{ maxWidth: '1200px', margin: '0 auto' }}>
+        <Heading size='7' mb='2' style={{ textAlign: 'center' }}>
+          API at a Glance
+        </Heading>
+        <Text size='3' color='gray' mb='6' style={{ textAlign: 'center', display: 'block' }}>
+          Key metrics and resources
+        </Text>
+
+        <Grid columns={{ initial: '1', sm: '2', md: '4' }} gap='4'>
+          {displayFeatures.map((feature, index) => <FeatureCard key={index} {...feature} />)}
+        </Grid>
+      </Box>
+    </Section>
+  )
+}
+
+const FeatureCard: React.FC<Feature> = ({ title, value, description, link }) => {
+  const content = (
+    <Card size='3' style={{ height: '100%', cursor: link ? 'pointer' : 'default' }}>
+      <Flex direction='column' gap='2'>
+        <Text size='6' weight='bold' style={{ lineHeight: 1 }}>
+          {value}
+        </Text>
+        <Text size='2' weight='medium'>
+          {title}
+        </Text>
+        {description && (
+          <Text size='1' color='gray'>
+            {description}
+          </Text>
+        )}
+      </Flex>
+    </Card>
+  )
+
+  if (link) {
+    if (link.startsWith('http')) {
+      return (
+        <a href={link} target='_blank' rel='noopener noreferrer' style={{ textDecoration: 'none' }}>
+          {content}
+        </a>
+      )
+    }
+    return (
+      <Link to={link} style={{ textDecoration: 'none' }}>
+        {content}
+      </Link>
+    )
+  }
+
+  return content
+}
+
+function getDefaultFeatures(): Feature[] {
+  const features: Feature[] = []
+
+  if (schemasCatalog) {
+    try {
+      // Get the latest schema from the catalog
+      const latestSchema = Catalog.getLatestSchema(schemasCatalog)
+
+      if (latestSchema && latestSchema.definition) {
+        // Build stats from the schema definition
+        const versionStats = CatalogStatistics.analyzeSchema(latestSchema.definition, 'current')
+
+        features.push({
+          title: 'Types',
+          value: versionStats.totalTypes || 0,
+          description: 'GraphQL types',
+          link: '/reference',
+        })
+
+        features.push({
+          title: 'Fields',
+          value: versionStats.totalFields || 0,
+          description: 'Total fields',
+          link: '/reference',
+        })
+
+        features.push({
+          title: 'Changelog',
+          value: '📝',
+          description: 'Recent updates',
+          link: '/changelog',
+        })
+
+        return features
+      }
+    } catch (error) {
+      console.warn('Failed to parse schema for features:', error)
+    }
+  }
+
+  // Add static features only if no schema features were added
+  if (features.length === 0) {
+    features.push({
+      title: 'Documentation',
+      value: '📚',
+      description: 'Guides & tutorials',
+      link: '/guides',
+    })
+
+    features.push({
+      title: 'Changelog',
+      value: '📝',
+      description: 'Recent updates',
+      link: '/changelog',
+    })
+  }
+
+  return features
+}