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

package/src/template/components/Changelog/groups/SchemaRootType.tsx

@@ -1,30 +1,28 @@
-import type { GraphqlChange } from '#lib/graphql-change/index'
+import { Change as GraphqlChange } from '#lib/change/$'
 import { Code } from '@radix-ui/themes'
 import type React from 'react'
 import { ChangeBase } from '../ChangeBase.js'
 
-export const SchemaRootType: React.FC<{ change: GraphqlChange.Group.SchemaRootType }> = ({ change }) => {
-  switch (change.type) {
+export const SchemaRootType: React.FC<{ change: any }> = ({ change }) => {
+  switch (change._tag) {
     case `SCHEMA_QUERY_TYPE_CHANGED`:
       return (
         <ChangeBase change={change}>
-          Schema query root type changed from <Code>{change.meta.oldQueryTypeName}</Code> to{' '}
-          <Code>{change.meta.newQueryTypeName}</Code>
+          Schema query root type changed from <Code>{change.oldType}</Code> to <Code>{change.newType}</Code>
         </ChangeBase>
       )
     case `SCHEMA_MUTATION_TYPE_CHANGED`:
       return (
         <ChangeBase change={change}>
-          Schema mutation root type changed from <Code>{change.meta.oldMutationTypeName || `null`}</Code> to{' '}
-          <Code>{change.meta.newMutationTypeName || `null`}</Code>
+          Schema mutation root type changed from <Code>{change.oldType || `null`}</Code> to{' '}
+          <Code>{change.newType || `null`}</Code>
         </ChangeBase>
       )
     case `SCHEMA_SUBSCRIPTION_TYPE_CHANGED`:
       return (
         <ChangeBase change={change}>
-          Schema subscription root type changed from <Code>{change.meta.oldSubscriptionTypeName || `null`}</Code> to
-          {' '}
-          <Code>{change.meta.newSubscriptionTypeName || `null`}</Code>
+          Schema subscription root type changed from <Code>{change.oldType || `null`}</Code> to{' '}
+          <Code>{change.newType || `null`}</Code>
         </ChangeBase>
       )
   }

package/src/template/components/Changelog/groups/TypeDescription.tsx

@@ -1,26 +1,26 @@
-import type { GraphqlChange } from '#lib/graphql-change/index'
+import { Change as GraphqlChange } from '#lib/change/$'
 import { Code } from '@radix-ui/themes'
 import type React from 'react'
 import { ChangeBase } from '../ChangeBase.js'
 
-export const TypeDescription: React.FC<{ change: GraphqlChange.Group.TypeDescription }> = ({ change }) => {
-  switch (change.type) {
+export const TypeDescription: React.FC<{ change: any }> = ({ change }) => {
+  switch (change._tag) {
     case `TYPE_DESCRIPTION_ADDED`:
       return (
         <ChangeBase change={change}>
-          Added description to type <Code>{change.meta.typeName}</Code>
+          Added description to type <Code>{change.name}</Code>
         </ChangeBase>
       )
     case `TYPE_DESCRIPTION_REMOVED`:
       return (
         <ChangeBase change={change}>
-          Removed description from type <Code>{change.meta.typeName}</Code>
+          Removed description from type <Code>{change.name}</Code>
         </ChangeBase>
       )
     case `TYPE_DESCRIPTION_CHANGED`:
       return (
         <ChangeBase change={change}>
-          Changed description for type <Code>{change.meta.typeName}</Code>
+          Changed description for type <Code>{change.name}</Code>
         </ChangeBase>
       )
   }

package/src/template/components/Changelog/groups/TypeOperation.tsx

@@ -1,26 +1,74 @@
-import type { GraphqlChange } from '#lib/graphql-change/index'
-import { Code } from '@radix-ui/themes'
+import { Change as GraphqlChange } from '#lib/change/$'
+import { Grafaid } from '#lib/grafaid'
+import { Schema } from '#lib/schema/$'
+import { Code, Flex } from '@radix-ui/themes'
+import { isNamedType } from 'graphql'
 import type React from 'react'
+import { TypeKindIcon } from '../../graphql/graphql.js'
+import { typeKindTokensIndex } from '../../graphql/type-kind-tokens.js'
+import { ReferenceLink } from '../../ReferenceLink.js'
 import { ChangeBase } from '../ChangeBase.js'
 
-export const TypeOperation: React.FC<{ change: GraphqlChange.Group.TypeOperation }> = ({ change }) => {
-  switch (change.type) {
+export const TypeOperation: React.FC<{ change: any; schema?: Schema.Schema }> = ({ change, schema }) => {
+  // Helper to render a type name with icon if we have the schema
+  const renderTypeName = (name: string, kind?: string) => {
+    if (!schema) {
+      return <Code>{name}</Code>
+    }
+
+    const type = schema.definition.getType(name)
+
+    if (type && isNamedType(type)) {
+      // Use the actual type kind from the schema if available
+      const actualKind = kind || Grafaid.Schema.typeKindFromClass(type)
+
+      // Only render if we have a valid kind
+      if (actualKind in typeKindTokensIndex) {
+        return (
+          <ReferenceLink type={name}>
+            <Flex align='center' gap='1' display='inline-flex'>
+              <TypeKindIcon kind={actualKind as Grafaid.Schema.TypeKindName} />
+              {` `}
+              <Code color={typeKindTokensIndex[actualKind as Grafaid.Schema.TypeKindName].color} variant='ghost'>
+                {name}
+              </Code>
+            </Flex>
+          </ReferenceLink>
+        )
+      }
+    }
+
+    // Fallback if type not found or no schema - just show with kind if provided
+    if (kind && kind in typeKindTokensIndex) {
+      return (
+        <Flex align='center' gap='1' display='inline-flex'>
+          <TypeKindIcon kind={kind as Grafaid.Schema.TypeKindName} />
+          {` `}
+          <Code color={typeKindTokensIndex[kind as Grafaid.Schema.TypeKindName].color} variant='ghost'>{name}</Code>
+        </Flex>
+      )
+    }
+
+    return <Code>{name}</Code>
+  }
+
+  switch (change._tag) {
     case `TYPE_ADDED`:
       return (
         <ChangeBase change={change}>
-          Added type <Code>{change.meta.addedTypeName}</Code>
+          Added type {renderTypeName(change.name)}
         </ChangeBase>
       )
     case `TYPE_REMOVED`:
       return (
         <ChangeBase change={change}>
-          Removed type <Code>{change.meta.removedTypeName}</Code>
+          Removed type {renderTypeName(change.name)}
         </ChangeBase>
       )
     case `TYPE_KIND_CHANGED`:
       return (
         <ChangeBase change={change}>
-          Changed type <Code>{change.meta.typeName}</Code> from {change.meta.oldTypeKind} to {change.meta.newTypeKind}
+          Changed type {renderTypeName(change.name, change.newKind)} from {change.oldKind} to {change.newKind}
         </ChangeBase>
       )
   }

package/src/template/components/Changelog/groups/UnionMemberOperation.tsx

@@ -1,20 +1,20 @@
-import type { GraphqlChange } from '#lib/graphql-change/index'
+import { Change as GraphqlChange } from '#lib/change/$'
 import { Code } from '@radix-ui/themes'
 import type React from 'react'
 import { ChangeBase } from '../ChangeBase.js'
 
-export const UnionMemberOperation: React.FC<{ change: GraphqlChange.Group.UnionMemberOperation }> = ({ change }) => {
-  switch (change.type) {
+export const UnionMemberOperation: React.FC<{ change: any }> = ({ change }) => {
+  switch (change._tag) {
     case `UNION_MEMBER_ADDED`:
       return (
         <ChangeBase change={change}>
-          Added <Code>{change.meta.addedUnionMemberTypeName}</Code> to union <Code>{change.meta.unionName}</Code>
+          Added <Code>{change.memberName}</Code> to union <Code>{change.unionName}</Code>
         </ChangeBase>
       )
     case `UNION_MEMBER_REMOVED`:
       return (
         <ChangeBase change={change}>
-          Removed <Code>{change.meta.removedUnionMemberTypeName}</Code> from union <Code>{change.meta.unionName}</Code>
+          Removed <Code>{change.memberName}</Code> from union <Code>{change.unionName}</Code>
         </ChangeBase>
       )
   }

package/src/template/components/Changelog/groups/index.ts

@@ -4,7 +4,7 @@ export { DirectiveArgumentOperation } from './DirectiveArgumentOperation.js'
 export { DirectiveDescription } from './DirectiveDescription.js'
 export { DirectiveLocationOperation } from './DirectiveLocationOperation.js'
 export { DirectiveOperation } from './DirectiveOperation.js'
-export { DirectiveUsage } from './DirectiveUsage.js'
+// export { DirectiveUsage } from './DirectiveUsage.js' // TODO: Add directive usage change types
 export { EnumValueDeprecationReason } from './EnumValueDeprecationReason.js'
 export { EnumValueDescription } from './EnumValueDescription.js'
 export { EnumValueOperation } from './EnumValueOperation.js'

package/src/template/components/CodeBlock.tsx

@@ -1,7 +1,7 @@
 import { type HighlightedCode, Pre } from 'codehike/code'
 import type { GraphQLSchema } from 'graphql'
 import React from 'react'
-import PROJECT_DATA from 'virtual:polen/project/data.jsonsuper'
+import { templateConfig } from 'virtual:polen/project/config'
 import { GraphQLInteractive } from './GraphQLInteractive/index.js'
 
 interface CodeBlockProps {
@@ -16,11 +16,15 @@ interface CodeBlockProps {
 export const CodeBlock: React.FC<CodeBlockProps> = ({ codeblock, schema }) => {
   // Check if this is an interactive GraphQL block
   if (codeblock.lang === 'graphql' && codeblock.meta?.includes('interactive')) {
+    // Only render interactive if we have a schema
+    if (!schema) {
+      return <Pre code={codeblock} />
+    }
     return (
       <GraphQLInteractive
         codeblock={codeblock}
         schema={schema}
-        showWarningIfNoSchema={PROJECT_DATA.warnings.interactiveWithoutSchema.enabled}
+        showWarningIfNoSchema={templateConfig.warnings.interactiveWithoutSchema.enabled}
       />
     )
   }

package/src/template/components/DeprecationReason.tsx

@@ -1,9 +1,9 @@
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { React } from '#dep/react/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import { Text } from '@radix-ui/themes'
-import type { FC } from 'react'
 import { Markdown } from './Markdown.js'
 
-export const DeprecationReason: FC<{ data: GrafaidOld.GraphQLField }> = ({ data }) => {
+export const DeprecationReason: React.FC<{ data: GrafaidOld.GraphQLField }> = ({ data }) => {
   if (!data.deprecationReason) return null
 
   return (

package/src/template/components/Description.tsx

@@ -1,11 +1,11 @@
+import type { React } from '#dep/react/index'
 import { Text } from '@radix-ui/themes'
-import type { FC } from 'react'
 import { Markdown } from './Markdown.js'
 // import type { Grafaid } from '#lib/grafaid'
-import type { GrafaidOld } from '#lib/grafaid-old/index'
+import type { GrafaidOld } from '#lib/grafaid-old'
 import type { GraphQLNamedType } from 'graphql'
 
-export const Description: FC<{ data: GraphQLNamedType | GrafaidOld.GraphQLField }> = ({ data }) => {
+export const Description: React.FC<{ data: GraphQLNamedType | GrafaidOld.GraphQLField }> = ({ data }) => {
   if (!data.description) return null
 
   return (

package/src/template/components/DevelopmentTip.tsx

@@ -0,0 +1,43 @@
+import type { React } from '#dep/react/index'
+import { InfoCircledIcon } from '@radix-ui/react-icons'
+import { Badge, Box, Callout, Flex, Text } from '@radix-ui/themes'
+
+interface Props {
+  title?: string
+  children: React.ReactNode
+  variant?: 'info' | 'warning'
+}
+
+/**
+ * A component for showing development tips and guidance that is only visible in development mode.
+ * Automatically hidden in production builds.
+ */
+export const DevelopmentTip: React.FC<Props> = ({
+  title = 'Development Tip',
+  variant = 'info',
+  children,
+}) => {
+  // Only show in development mode
+  if (__BUILDING__) {
+    return null
+  }
+
+  const color = variant === 'warning' ? 'amber' : 'blue'
+
+  return (
+    <Callout.Root color={color} variant='surface' style={{ marginBottom: 'var(--space-4)' }}>
+      <Callout.Icon>
+        <InfoCircledIcon />
+      </Callout.Icon>
+      <Callout.Text>
+        <Flex direction='column' gap='2'>
+          <Flex align='center' gap='2'>
+            <Text weight='bold'>{title}</Text>
+            <Badge color={color} variant='soft' size='1'>Dev Only</Badge>
+          </Flex>
+          <Box>{children}</Box>
+        </Flex>
+      </Callout.Text>
+    </Callout.Root>
+  )
+}

package/src/template/components/ExampleLink.tsx

@@ -0,0 +1,25 @@
+import type { ExampleReference } from '#api/examples/schemas/type-usage-index'
+import { Version } from '#lib/version/$'
+import { Badge, Link } from '@radix-ui/themes'
+import type { FC } from 'react'
+
+export interface Props {
+  exampleRef: ExampleReference
+}
+
+/**
+ * Component for rendering a link to an example at a specific version.
+ * Always includes the version query parameter for consistent behavior.
+ */
+export const ExampleLink: FC<Props> = ({ exampleRef }) => {
+  // Always include version parameter for consistency
+  const href = `/examples/${exampleRef.name}?version=${Version.encodeSync(exampleRef.version)}`
+
+  return (
+    <Link href={href} style={{ textDecoration: 'none' }}>
+      <Badge variant='soft' size='2' style={{ cursor: 'pointer' }}>
+        {exampleRef.name}
+      </Badge>
+    </Link>
+  )
+}

package/src/template/components/Field.tsx

@@ -1,26 +1,49 @@
-import { GrafaidOld } from '#lib/grafaid-old/index'
+import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
+import { GrafaidOld } from '#lib/grafaid-old'
+import { Lifecycles } from '#lib/lifecycles/$'
 import type { BoxProps } from '@radix-ui/themes'
-import { Box, Text } from '@radix-ui/themes'
-import type { FC } from 'react'
+import { Badge, Box, Text } from '@radix-ui/themes'
+import { useSchema } from '../contexts/GraphqlLifecycleContext.js'
 import { ArgumentListAnnotation } from './ArgumentListAnnotation.js'
 import { DeprecationReason } from './DeprecationReason.js'
 import { Description } from './Description.js'
+import { SinceBadge } from './SinceBadge.js'
 import { TypeAnnotation } from './TypeAnnotation.js'
 
-export type Props = BoxProps & {
-  data: GrafaidOld.GraphQLField
-}
+export const Field: React.FC<
+  BoxProps & {
+    data: GrafaidOld.GraphQLField
+    parentTypeName?: string
+  }
+> = ({ data, parentTypeName, ...boxProps }) => {
+  const { schema, lifecycles } = useSchema()
 
-export const Field: FC<Props> = ({ data, ...boxProps }) => {
   const argumentList = GrafaidOld.isOutputField(data)
     ? <ArgumentListAnnotation field={data} />
     : null
 
+  // Get field lifecycle information if available
+  const since = parentTypeName
+    ? Lifecycles.getFieldSince(lifecycles, parentTypeName, data.name, schema)
+    : null
+  const removedDate = parentTypeName
+    ? Lifecycles.getFieldRemovedDate(lifecycles, parentTypeName, data.name, schema)
+    : null
+
   return (
     <Box {...boxProps} id={data.name}>
       <Description data={data} />
       <DeprecationReason data={data} />
-      <Text weight='medium'>{data.name}</Text>
+      <Box style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+        <Text weight='medium'>{data.name}</Text>
+        {since && <SinceBadge since={since} />}
+        {removedDate && (
+          <Badge color='red' variant='soft' size='1'>
+            Removed {Api.Schema.dateToVersionString(removedDate)}
+          </Badge>
+        )}
+      </Box>
       <Text>
         {argumentList}
         :{` `}

package/src/template/components/FieldList.tsx

@@ -1,13 +1,14 @@
-import { Grafaid } from '#lib/grafaid/index'
+import { Grafaid } from '#lib/grafaid'
 import { Box } from '@radix-ui/themes'
 import type { FC } from 'react'
 import { Field } from './Field.js'
 
 export interface Props {
   data: Grafaid.Schema.TypesLike.Named
+  parentTypeName?: string
 }
 
-export const FieldList: FC<Props> = ({ data }) => {
+export const FieldList: FC<Props> = ({ data, parentTypeName }) => {
   if (!Grafaid.Schema.TypesLike.isFielded(data)) return null
 
   const fields = Grafaid.Schema.NodesLike.getFields(data)
@@ -20,6 +21,7 @@ export const FieldList: FC<Props> = ({ data }) => {
           mt='3'
           key={field.name}
           data={field}
+          parentTypeName={parentTypeName ?? data.name}
         />
       ))}
     </Box>

package/src/template/components/FieldListSection.tsx

@@ -1,14 +1,10 @@
-import { Grafaid } from '#lib/grafaid/index'
+import type { React } from '#dep/react/index'
+import { Grafaid } from '#lib/grafaid'
 import { Box, Heading } from '@radix-ui/themes'
 import type { GraphQLNamedType } from 'graphql'
-import type { FC } from 'react'
 import { FieldList } from './FieldList.js'
 
-export interface Props {
-  data: GraphQLNamedType
-}
-
-export const FieldListSection: FC<Props> = ({ data }) => {
+export const FieldListSection: React.FC<{ data: GraphQLNamedType }> = ({ data }) => {
   if (!Grafaid.Schema.TypesLike.isFielded(data)) return null
 
   const fields = Grafaid.Schema.NodesLike.getFields(data)
@@ -17,7 +13,7 @@ export const FieldListSection: FC<Props> = ({ data }) => {
   return (
     <Box>
       <Heading>Fields</Heading>
-      <FieldList data={data} />
+      <FieldList data={data} parentTypeName={data.name} />
     </Box>
   )
 }

package/src/template/components/GraphQLDocument.tsx

@@ -0,0 +1,88 @@
+import { Catalog } from '#lib/catalog/$'
+import { Document } from '#lib/document/$'
+import { VersionCoverage } from '#lib/version-coverage'
+import { Either, Option } from 'effect'
+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>(
+    Option.getOrNull(Catalog.getLatestVersion(schemaCatalog)),
+  )
+  const selectedVersionCoverage = isControlled ? controlledVersionCoverage : internalVersionCoverage
+  const internalOnVersionChange = (version: VersionCoverage.VersionCoverage) => {
+    if (!isControlled) {
+      setInternalVersionCoverage(version)
+    }
+    onVersionCoverageChange?.(version)
+  }
+
+  /// ━ DATA RESOLUTION
+  const result = Document.resolveDocumentAndSchema(document, schemaCatalog, selectedVersionCoverage)
+
+  // Handle resolution errors gracefully
+  if (Either.isLeft(result)) {
+    console.error('Failed to resolve document and schema:', result.left.message)
+    return null
+  }
+
+  const { schema, content } = result.right
+  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}
+          />
+        )
+      )}
+    />
+  )
+}

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 */}
@@ -241,13 +250,26 @@ const GraphQLInteractiveImpl: React.FC<GraphQLInteractiveProps> = ({
                 token={token}
                 tokenId={tokenId}
                 popoverState={popoverState}
-                schema={schema}
+                {...(schema !== undefined && { schema })}
               />
             )
           })}
         </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/GraphQLInteractive/components/GraphQLTokenPopover.tsx

@@ -58,14 +58,14 @@ function getPopoverContent(
   token: GraphQLToken,
 ): {
   title: string
-  path?: Array<{ name: string; url: string | null }>
-  description?: string
-  type?: string
-  invalid?: boolean
-  availableFields?: string[]
-  typeName?: string
-  typeUrl?: string
-  fieldName?: string
+  path?: Array<{ name: string; url: string | null }> | undefined
+  description?: string | undefined
+  type?: string | undefined
+  invalid?: boolean | undefined
+  availableFields?: string[] | undefined
+  typeName?: string | undefined
+  typeUrl?: string | undefined
+  fieldName?: string | undefined
 } | null {
   const semantic = token.semantic