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

package/src/template/components/GraphQLDocument.tsx

@@ -0,0 +1,145 @@
+import { Catalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { S } from '#lib/kit-temp/$'
+import type { Schema } from '#lib/schema/$'
+import { VersionCoverage } from '#lib/version-selection/$'
+import { VersionCoverageSet } from '#lib/version-selection/version-selection'
+import { Version } from '#lib/version/$'
+import { Array, HashMap, Match } from 'effect'
+import type { GraphQLSchema } from 'graphql'
+import * as React from 'react'
+import { useHighlighted } from '../hooks/use-highlighted.js'
+import { GraphQLInteractive } from './GraphQLInteractive/GraphQLInteractive.js'
+import { VersionCoveragePicker } from './VersionCoveragePicker.js'
+
+interface GraphQLDocumentProps {
+  /** The document containing the GraphQL content */
+  document: Document.Document
+
+  /** Optional GraphQL schema catalog for validation and interactivity */
+  schemaCatalog?: Catalog.Catalog | undefined
+
+  /** Whether to show version picker for versioned examples */
+  showVersionCoveragePicker?: boolean | undefined
+
+  /** Callback when version changes */
+  onVersionCoverageChange?: (versionCoverage: VersionCoverage.VersionCoverage) => void
+
+  /** Override the initial/selected version */
+  selectedVersionCoverage?: VersionCoverage.VersionCoverage | undefined
+
+  /** Optional custom styles */
+  style?: React.CSSProperties | undefined
+}
+
+/**
+ * Unified component for displaying GraphQL documents with optional version selection.
+ * Handles all document types: Unversioned, Versioned, and PartiallyVersioned.
+ */
+export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
+  document,
+  schemaCatalog,
+  showVersionCoveragePicker = true,
+  onVersionCoverageChange,
+  selectedVersionCoverage: controlledVersionCoverage,
+  style,
+}) => {
+  /// ━ VERSION MANAGEMENT
+  const isControlled = controlledVersionCoverage !== undefined
+  const [internalVersionCoverage, setInternalVersionCoverage] = React.useState<VersionCoverage.VersionCoverage | null>(
+    Catalog.getLatestVersionIdentifier(schemaCatalog),
+  )
+  const selectedVersionCoverage = isControlled ? controlledVersionCoverage : internalVersionCoverage
+  const internalOnVersionChange = (version: VersionCoverage.VersionCoverage) => {
+    if (!isControlled) {
+      setInternalVersionCoverage(version)
+    }
+    onVersionCoverageChange?.(version)
+  }
+
+  /// ━ DATA RESOLUTION
+  const {
+    schema,
+    content,
+  } = resolveSelectedVerCov(document, selectedVersionCoverage, schemaCatalog)
+
+  const highlightedCode = useHighlighted(content, { interactive: true })
+
+  if (!highlightedCode) {
+    return null
+  }
+
+  return (
+    <GraphQLInteractive
+      codeblock={highlightedCode}
+      schema={schema?.definition}
+      style={style}
+      toolbar={() => (
+        showVersionCoveragePicker && selectedVersionCoverage && (
+          <VersionCoveragePicker
+            document={document}
+            schemaCatalog={schemaCatalog!}
+            current={selectedVersionCoverage}
+            onChange={internalOnVersionChange}
+          />
+        )
+      )}
+    />
+  )
+}
+
+/**
+ * Matches a document with an optional schema catalog, returning the document content,
+ * corresponding schema, and available versions for the selected version.
+ *
+ * @param document - The document to retrieve content from (required)
+ * @param selectedVersionCoverage - The version to select (optional, defaults to latest)
+ * @param schemaCatalog - The schema catalog to match against (optional)
+ * @returns Object with document content, optional schema, and available versions
+ * @throws {Error} If versions in catalog don't match versions in document
+ */
+type Result = { content: string; schema?: Schema.Schema }
+const resolveSelectedVerCov = (
+  document: Document.Document,
+  selectedVersionCoverage?: VersionCoverage.VersionCoverage | null,
+  schemaCatalog?: Catalog.Catalog,
+): Result => {
+  if (Document.Unversioned.is(document)) {
+    return {
+      content: document.document,
+      schema: Match.value(schemaCatalog).pipe(
+        Match.tagsExhaustive({
+          CatalogUnversioned: (catalog) => catalog.schema,
+          CatalogVersioned: (catalog) => Catalog.Versioned.getLatest(catalog),
+        }),
+      ),
+    }
+  }
+
+  return Match.value(selectedVersionCoverage).pipe(
+    Match.whenOr(null, undefined, _ => {
+      const content = Document.Versioned.getContentForLatestVersionOrThrow(document)
+      return { content }
+    }),
+    Match.orElse(_ => {
+      const version = VersionCoverage.getLatest(_)
+
+      const content = Document.Versioned.getContentForVersion(document, version)
+      if (!content) {
+        throw new Error(`Version ${Version.encodeSync(version)} not covered by document`)
+      }
+
+      if (!schemaCatalog) return { version, content }
+
+      if (Catalog.Unversioned.is(schemaCatalog)) {
+        throw new Error('Cannot use a set of versions with an unversioned catalog')
+      }
+      const schema = schemaCatalog.entries.find(e => Version.equivalence(e.version, version))
+      if (!schema) {
+        throw new Error(`Version ${Version.encodeSync(version)} not found in catalog`)
+      }
+
+      return { content, schema: schema }
+    }),
+  )
+}

package/src/template/components/GraphQLInteractive/GraphQLInteractive.tsx

@@ -24,10 +24,16 @@ interface GraphQLInteractiveProps {
   codeblock: HighlightedCode
 
   /** The GraphQL schema for providing type information and validation */
-  schema?: GraphQLSchema
+  schema?: GraphQLSchema | undefined
 
   /** Whether to show a warning indicator when schema is missing */
-  showWarningIfNoSchema?: boolean
+  showWarningIfNoSchema?: boolean | undefined
+
+  /** Optional toolbar component to render (e.g., version picker) */
+  toolbar?: () => React.ReactNode
+
+  /** Optional custom styles */
+  style?: React.CSSProperties | undefined
 }
 
 /**
@@ -47,6 +53,8 @@ const GraphQLInteractiveImpl: React.FC<GraphQLInteractiveProps> = ({
   codeblock,
   schema,
   showWarningIfNoSchema = true,
+  toolbar,
+  style,
 }) => {
   // State to hold the parsed tokens
   const [tokens, setTokens] = ReactHooks.useState<GraphQLToken[] | null>(null)
@@ -228,6 +236,7 @@ const GraphQLInteractiveImpl: React.FC<GraphQLInteractiveProps> = ({
         backgroundColor: 'var(--gray-2)',
         overflowX: 'auto',
         maxWidth: '100%',
+        ...style,
       }}
     >
       {/* Render each token as a separate span with appropriate styling */}
@@ -247,7 +256,20 @@ const GraphQLInteractiveImpl: React.FC<GraphQLInteractiveProps> = ({
           })}
         </code>
       </pre>
-      {!schema && showWarningIfNoSchema && (
+      {/* Toolbar (e.g., version picker) */}
+      {toolbar && (
+        <div
+          style={{
+            position: 'absolute',
+            top: '8px',
+            right: '8px',
+            zIndex: 10,
+          }}
+        >
+          {toolbar()}
+        </div>
+      )}
+      {!schema && showWarningIfNoSchema && !toolbar && (
         <div
           style={{
             position: 'absolute',

package/src/template/components/HamburgerMenu.tsx

@@ -1,14 +1,27 @@
 import type { Content } from '#api/content/$'
+import type { React } from '#dep/react/index'
 import { Cross2Icon, HamburgerMenuIcon } from '@radix-ui/react-icons'
 import { Box, Flex, IconButton, Text } from '@radix-ui/themes'
 import { useEffect } from 'react'
 import { Sidebar } from '../components/sidebar/Sidebar.js'
 
+// Template layer extension: Allow React elements in title
+interface TemplateItemLink extends Omit<Content.ItemLink, 'title'> {
+  title: string | React.ReactNode
+}
+
+interface TemplateItemSection extends Omit<Content.ItemSection, 'title' | 'links'> {
+  title: string | React.ReactNode
+  links: TemplateItemLink[]
+}
+
+type TemplateItem = TemplateItemLink | TemplateItemSection
+
 export interface HamburgerMenuProps {
   isOpen: boolean
   onToggle: () => void
   onClose: () => void
-  sidebarData: Content.Item[]
+  sidebarData: TemplateItem[]
   basePath?: string
   topContent?: React.ReactNode
 }

package/src/template/components/Logo.tsx

@@ -1,18 +1,50 @@
 import { Box, Flex, Text } from '@radix-ui/themes'
+import * as React from 'react'
+import { useTheme } from '../contexts/ThemeContext.js'
+
+interface LogoConfig {
+  light: string
+  dark: string
+  mode: 'single' | 'dual'
+  designedFor: 'light' | 'dark'
+}
 
 interface Props {
-  src: string
+  src: string | LogoConfig
   title?: string
   height?: number
   showTitle?: boolean
 }
 
 export const Logo: React.FC<Props> = ({ src, title, height = 30, showTitle = true }) => {
+  const { appearance } = useTheme()
+
+  // Handle both legacy string src and new LogoConfig
+  let logoSrc: string
+  let needsInvert = false
+
+  if (typeof src === 'string') {
+    // Legacy mode - just use the string as-is
+    logoSrc = src
+  } else {
+    // New mode with logo configuration
+    if (src.mode === 'dual') {
+      // Use theme-specific logo directly
+      logoSrc = appearance === 'dark' ? src.dark : src.light
+    } else {
+      // Single logo - check if invert needed
+      logoSrc = src.light // Same file for both in single mode
+      // Invert when: logo designed for light mode but we're in dark mode, or vice versa
+      needsInvert = (src.designedFor === 'light' && appearance === 'dark')
+        || (src.designedFor === 'dark' && appearance === 'light')
+    }
+  }
+
   return (
     <Flex align='center' gap='2'>
       <Box style={{ height, display: `flex`, alignItems: `center` }}>
         <img
-          src={src}
+          src={logoSrc}
           alt={title}
           height={height}
           className='polen-logo'
@@ -20,6 +52,7 @@ export const Logo: React.FC<Props> = ({ src, title, height = 30, showTitle = tru
             height: `100%`,
             width: `auto`,
             transition: `filter 0.2s ease-in-out`,
+            filter: needsInvert ? 'invert(1)' : undefined,
           }}
         />
       </Box>
@@ -28,19 +61,6 @@ export const Logo: React.FC<Props> = ({ src, title, height = 30, showTitle = tru
           {title}
         </Text>
       )}
-      <style>
-        {`
-          .polen-logo {
-            filter: none;
-          }
-          
-          @media (prefers-color-scheme: dark) {
-            .polen-logo {
-              filter: invert(1);
-            }
-          }
-        `}
-      </style>
     </Flex>
   )
 }

package/src/template/components/NamedType.tsx

@@ -3,11 +3,14 @@ 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 { Match } from 'effect'
+import { HashSet, Match } from 'effect'
 import { type GraphQLNamedType } from 'graphql'
 import type { FC } from 'react'
 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 {
@@ -29,10 +32,18 @@ export const NamedType: FC<Props> = ({ data }) => {
   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>
+        <Heading size='8'>
+          <TypeLink type={data} />
+        </Heading>
         {since && (
           since._tag === 'initial'
             ? (
@@ -51,7 +62,7 @@ export const NamedType: FC<Props> = ({ data }) => {
                 <Badge color='green' variant='soft' size='1' style={{ cursor: 'pointer' }}>
                   Added {Match.value(since.schema).pipe(
                     Match.tagsExhaustive({
-                      SchemaVersioned: (s) => `${Version.toString(s.version)}@${since.revision.date}`,
+                      SchemaVersioned: (s) => `${Version.encodeSync(s.version)}@${since.revision.date}`,
                       SchemaUnversioned: () => since.revision.date,
                     }),
                   )}
@@ -67,6 +78,19 @@ export const NamedType: FC<Props> = ({ data }) => {
       </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,13 +1,12 @@
 import { Api } from '#api/iso'
 import type { React } from '#dep/react/index'
 import { Version } from '#lib/version/$'
-import { Select } from '@radix-ui/themes'
-import { Effect } from 'effect'
 import { useNavigate } from 'react-router'
-import { catalogBridge } from '../catalog-bridge.js'
+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'
 
 interface Props {
   data: readonly Version.Version[]
@@ -18,19 +17,14 @@ export const VersionPicker: React.FC<Props> = ({ data, current }) => {
   const navigate = useNavigate()
   const currentPath = useReferencePath()
 
-  // Don't show selector if only one version
-  if (data.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 () => {
       // Get the full catalog to find the target schema
-      const catalog = await Effect.runPromise(catalogBridge.view())
-
-      if (!catalog) {
+      if (!schemasCatalog) {
         throw new Error('No catalog available')
       }
+      const catalog = schemasCatalog
 
       // This component is only used for versioned catalogs
       if (catalog._tag !== 'CatalogVersioned') {
@@ -39,7 +33,7 @@ export const VersionPicker: React.FC<Props> = ({ data, current }) => {
 
       // Find the schema for the target version
       // Note: newVersion is a string that we need to parse
-      const targetSchema = catalog.entries.find(schema => Version.toString(schema.version) === newVersion)
+      const targetSchema = catalog.entries.find(schema => Version.encodeSync(schema.version) === newVersion)
 
       if (!targetSchema) {
         throw new Error(`Version ${newVersion} not found`)
@@ -97,23 +91,11 @@ export const VersionPicker: React.FC<Props> = ({ data, current }) => {
     }
   }
 
-  const currentStr = Version.toString(current)
-
   return (
-    <Select.Root value={currentStr} onValueChange={handleVersionChange}>
-      <Select.Trigger>
-        {currentStr}
-      </Select.Trigger>
-      <Select.Content>
-        {data.map(version => {
-          const versionStr = Version.toString(version)
-          return (
-            <Select.Item key={versionStr} value={versionStr}>
-              {versionStr}
-            </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>
+  )
+}