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

package/src/template/components/Carousel.tsx

@@ -0,0 +1,224 @@
+import { Box, Flex } from '@radix-ui/themes'
+import useEmblaCarousel from 'embla-carousel-react'
+import * as React from 'react'
+import { useCallback, useEffect, useRef, useState } from 'react'
+import { CarouselPill } from './CarouselPill.js'
+
+export interface CarouselProps {
+  /** Items to display in the carousel */
+  children: React.ReactNode[]
+  /** Whether to enable auto-play */
+  autoPlay?: boolean
+  /** Duration in ms between slides when auto-playing */
+  slideDuration?: number
+  /** Whether to loop back to start */
+  loop?: boolean
+  /** Alignment of slides */
+  align?: 'start' | 'center' | 'end'
+  /** Number of slides to scroll at once */
+  slidesToScroll?: number
+  /** Whether to show navigation dots */
+  showDots?: boolean
+  /** Callback when slide changes */
+  onSlideChange?: (index: number) => void
+  /** Custom class name for carousel container */
+  className?: string
+  /** Width of each slide as percentage (e.g., '80%' to show partial next slide) */
+  slideWidth?: string
+}
+
+export const Carousel: React.FC<CarouselProps> = ({
+  children,
+  autoPlay = false,
+  slideDuration = 10_000,
+  loop = true,
+  align = 'center',
+  slidesToScroll = 1,
+  showDots = true,
+  onSlideChange,
+  className,
+  slideWidth = children.length > 1 ? '80%' : '100%',
+}) => {
+  // Carousel setup
+  const [emblaRef, emblaApi] = useEmblaCarousel({
+    loop,
+    align,
+    slidesToScroll,
+    containScroll: false,
+  })
+
+  const [selectedIndex, setSelectedIndex] = useState(0)
+
+  // Auto-play state
+  const [isHovering, setIsHovering] = useState(false)
+  const [progress, setProgress] = useState(0)
+  const progressIntervalRef = useRef<NodeJS.Timeout | null>(null)
+  const elapsedRef = useRef<number>(0)
+  const PROGRESS_UPDATE_INTERVAL = 50
+
+  // No need for height tracking - flexbox handles it naturally
+
+  // Track selected slide
+  useEffect(() => {
+    if (!emblaApi) return
+
+    const onSelect = () => {
+      const index = emblaApi.selectedScrollSnap()
+      setSelectedIndex(index)
+      onSlideChange?.(index)
+      // Reset progress on slide change
+      elapsedRef.current = 0
+      setProgress(0)
+    }
+
+    emblaApi.on('select', onSelect)
+    onSelect()
+
+    return () => {
+      emblaApi.off('select', onSelect)
+    }
+  }, [emblaApi, onSlideChange])
+
+  // Auto-play functionality
+  const startAutoPlay = useCallback((resumeFromProgress = false) => {
+    if (progressIntervalRef.current) clearInterval(progressIntervalRef.current)
+
+    if (!resumeFromProgress) {
+      elapsedRef.current = 0
+      setProgress(0)
+    }
+
+    progressIntervalRef.current = setInterval(() => {
+      if (!isHovering) {
+        elapsedRef.current += PROGRESS_UPDATE_INTERVAL
+        const newProgress = (elapsedRef.current / slideDuration) * 100
+
+        if (newProgress >= 100) {
+          elapsedRef.current = 0
+          if (emblaApi && children.length > 1) {
+            emblaApi.scrollNext()
+          }
+        }
+
+        setProgress(Math.min(newProgress, 100))
+      }
+    }, PROGRESS_UPDATE_INTERVAL)
+  }, [emblaApi, autoPlay, isHovering, children.length, slideDuration])
+
+  const stopAutoPlay = useCallback((preserveProgress = false) => {
+    if (progressIntervalRef.current) {
+      clearInterval(progressIntervalRef.current)
+      progressIntervalRef.current = null
+    }
+    if (!preserveProgress) {
+      elapsedRef.current = 0
+      setProgress(0)
+    }
+  }, [])
+
+  // Handle auto-play start/stop
+  useEffect(() => {
+    if (autoPlay && !isHovering && children.length > 1) {
+      startAutoPlay(true)
+    } else {
+      stopAutoPlay(true)
+    }
+
+    return () => {
+      stopAutoPlay(false)
+    }
+  }, [autoPlay, isHovering, startAutoPlay, stopAutoPlay, children.length])
+
+  // Keyboard navigation
+  useEffect(() => {
+    if (!emblaApi) return
+
+    const handleKeyDown = (event: KeyboardEvent) => {
+      if (event.key === 'ArrowLeft') {
+        event.preventDefault()
+        emblaApi.scrollPrev()
+      } else if (event.key === 'ArrowRight') {
+        event.preventDefault()
+        emblaApi.scrollNext()
+      }
+    }
+
+    window.addEventListener('keydown', handleKeyDown)
+    return () => {
+      window.removeEventListener('keydown', handleKeyDown)
+    }
+  }, [emblaApi])
+
+  if (children.length === 0) return null
+
+  return (
+    <Box
+      position='relative'
+      className={className}
+      onMouseEnter={() => setIsHovering(true)}
+      onMouseLeave={() => setIsHovering(false)}
+    >
+      {/* Carousel viewport */}
+      <Box
+        ref={emblaRef}
+        style={{
+          overflow: 'hidden',
+          // Break out of container for full-width effect
+          marginLeft: 'calc(-50vw + 50%)',
+          marginRight: 'calc(-50vw + 50%)',
+          paddingLeft: 'calc(50vw - 50%)',
+          paddingRight: 'calc(50vw - 50%)',
+        }}
+      >
+        <Flex
+          style={{
+            display: 'flex',
+            // Don't override align-items - let it default to 'stretch'
+            // This makes all items equal height based on tallest content
+            gap: children.length > 1 ? '2rem' : 0,
+          }}
+        >
+          {React.Children.map(children, (child, index) => (
+            <Box
+              style={{
+                // Control width but let height be determined by content
+                flex: `0 0 ${slideWidth}`,
+                minWidth: 0,
+                // Opacity for focus effect
+                opacity: index === selectedIndex ? 1 : 0.5,
+                transition: 'opacity 0.3s ease-in-out',
+                // Let flexbox stretch items to equal height (default behavior)
+                // alignSelf defaults to 'auto' which inherits align-items: stretch
+                // Add overflow for tall content
+                overflow: 'auto',
+                // Make this a flex container to allow children to stretch
+                display: 'flex',
+                flexDirection: 'column',
+              }}
+            >
+              {child}
+            </Box>
+          ))}
+        </Flex>
+      </Box>
+
+      {/* Navigation pills with integrated timer */}
+      {children.length > 1 && showDots && (
+        <Flex justify='center' align='center' gap='2' mt='3'>
+          {React.Children.map(children, (_, index) => (
+            <CarouselPill
+              key={index}
+              isActive={index === selectedIndex}
+              progress={progress}
+              autoPlay={autoPlay}
+              isPaused={false}
+              isHovering={isHovering}
+              onClick={() => emblaApi?.scrollTo(index)}
+              index={index}
+            />
+          ))}
+        </Flex>
+      )}
+    </Box>
+  )
+}

package/src/template/components/CarouselPill.tsx

@@ -0,0 +1,101 @@
+import { Box } from '@radix-ui/themes'
+import * as React from 'react'
+
+export interface CarouselPillProps {
+  /** Whether this pill represents the active slide */
+  isActive: boolean
+  /** Progress percentage (0-100) for the active pill */
+  progress: number
+  /** Whether autoplay is enabled */
+  autoPlay: boolean
+  /** Whether the carousel is paused */
+  isPaused: boolean
+  /** Whether the carousel is being hovered */
+  isHovering: boolean
+  /** Click handler to navigate to this slide */
+  onClick: () => void
+  /** Slide index for accessibility */
+  index: number
+}
+
+export const CarouselPill: React.FC<CarouselPillProps> = ({
+  isActive,
+  progress,
+  autoPlay,
+  isPaused,
+  isHovering,
+  onClick,
+  index,
+}) => {
+  const pillWidth = 24
+  const pillHeight = 4
+  const borderRadius = 2
+  const gap = 2 // Gap between pill and progress stroke
+  const strokeWidth = 1.5
+
+  // SVG canvas needs to fit both pill and surrounding progress ring
+  const svgWidth = pillWidth + (gap * 2) + (strokeWidth * 2)
+  const svgHeight = pillHeight + (gap * 2) + (strokeWidth * 2)
+
+  // Progress ring dimensions (surrounds the pill with gap)
+  const progressWidth = pillWidth + (gap * 2) + 1
+  const progressHeight = pillHeight + (gap * 2) + 1
+  const progressRadius = borderRadius + gap
+
+  // Calculate perimeter for progress animation
+  const perimeter = 2 * (progressWidth + progressHeight - 2 * progressRadius) + 2 * Math.PI * progressRadius
+
+  return (
+    <Box
+      onClick={onClick}
+      style={{
+        cursor: 'pointer',
+        opacity: isActive ? 1 : 0.6,
+        transition: 'opacity 0.3s ease',
+      }}
+      aria-label={`Go to slide ${index + 1}`}
+    >
+      <svg
+        width={svgWidth}
+        height={svgHeight}
+        viewBox={`0 0 ${svgWidth} ${svgHeight}`}
+      >
+        {/* Background pill - centered in the SVG */}
+        <rect
+          x={gap + strokeWidth}
+          y={gap + strokeWidth}
+          width={pillWidth}
+          height={pillHeight}
+          rx={borderRadius}
+          ry={borderRadius}
+          fill={isActive ? 'var(--accent-9)' : 'var(--gray-5)'}
+          style={{
+            transition: 'fill 0.3s ease',
+          }}
+        />
+
+        {/* Progress ring - only for active slide with autoplay */}
+        {isActive && autoPlay && (
+          <rect
+            x={strokeWidth / 2}
+            y={strokeWidth / 2}
+            width={progressWidth}
+            height={progressHeight}
+            rx={progressRadius}
+            ry={progressRadius}
+            fill='none'
+            stroke='var(--accent-11)'
+            strokeWidth={strokeWidth}
+            strokeDasharray={perimeter}
+            strokeDashoffset={perimeter * (1 - progress / 100)}
+            style={{
+              transition: isPaused || isHovering ? 'none' : 'stroke-dashoffset 0.05s linear',
+              opacity: '0.5',
+              transformOrigin: 'center',
+            }}
+          />
+        )}
+      </svg>
+    </Box>
+  )
+}

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

@@ -2,6 +2,7 @@ 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/$'
 const CRITICALITY_LEVELS = ['BREAKING', 'DANGEROUS', 'NON_BREAKING'] as const
 import type { CriticalityLevel } from '@graphql-inspector/core'
@@ -36,22 +37,27 @@ export const Changelog: React.FC<{ catalog: Catalog.Catalog }> = ({ catalog }) =
     if (Catalog.Unversioned.is(catalog)) return
     const latestSchema = catalog.entries[0]
     if (!latestSchema) return
-    const latestVersion = Version.toString(latestSchema.version)
+    const latestVersion = Version.encodeSync(latestSchema.version)
     navigate(`/changelog/version/${latestVersion}`, { replace: true })
   }, [catalog, urlVersion, navigate])
 
-  // Get revisions based on catalog type and URL params
-  const revisions = useMemo(() => {
+  // Get revisions and corresponding schema based on catalog type and URL params
+  const { revisions, schema } = useMemo(() => {
     if (Catalog.Unversioned.is(catalog)) {
-      return catalog.schema.revisions
+      return {
+        revisions: catalog.schema.revisions,
+        schema: catalog.schema,
+      }
     } else {
       // For versioned catalogs, always show specific version (never all)
       if (urlVersion) {
-        const entry = catalog.entries.find(e => Version.toString(e.version) === urlVersion)
-        return entry ? entry.revisions : []
+        const entry = catalog.entries.find(e => Version.encodeSync(e.version) === urlVersion)
+        return entry
+          ? { revisions: entry.revisions, schema: entry }
+          : { revisions: [], schema: null }
       }
       // This shouldn't happen due to redirect above, but return empty as fallback
-      return []
+      return { revisions: [], schema: null }
     }
   }, [catalog, urlVersion])
 
@@ -67,12 +73,12 @@ export const Changelog: React.FC<{ catalog: Catalog.Catalog }> = ({ catalog }) =
         Changelog
       </Heading>
 
-      {revisions.map(revision => <Changeset key={revision.date} revision={revision} />)}
+      {revisions.map(revision => <Changeset key={revision.date} revision={revision} schema={schema} />)}
     </Box>
   )
 }
 
-const Changeset: React.FC<{ revision: Revision.Revision }> = ({ revision }) => {
+const Changeset: React.FC<{ revision: Revision.Revision; schema: Schema.Schema | null }> = ({ revision, schema }) => {
   // Group changes by criticality level
   const groupedChanges = useMemo(() => {
     const groups = {} as Record<CriticalityLevel, Change.Change[]>
@@ -137,7 +143,7 @@ const Changeset: React.FC<{ revision: Revision.Revision }> = ({ revision }) => {
                 key={`${change._tag}-${change.path || change.message}-${index}`}
                 components={Group}
                 name={type}
-                props={{ change }}
+                props={{ change, schema }}
               />
             )
           })}

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

@@ -1,26 +1,74 @@
 import { Change as GraphqlChange } from '#lib/change/$'
-import { Code } from '@radix-ui/themes'
+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: any }> = ({ change }) => {
+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.name}</Code>
+          Added type {renderTypeName(change.name)}
         </ChangeBase>
       )
     case `TYPE_REMOVED`:
       return (
         <ChangeBase change={change}>
-          Removed type <Code>{change.name}</Code>
+          Removed type {renderTypeName(change.name)}
         </ChangeBase>
       )
     case `TYPE_KIND_CHANGED`:
       return (
         <ChangeBase change={change}>
-          Changed type <Code>{change.name}</Code> from {change.oldKind} to {change.newKind}
+          Changed type {renderTypeName(change.name, change.newKind)} from {change.oldKind} to {change.newKind}
         </ChangeBase>
       )
   }

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.json'
+import { templateConfig } from 'virtual:polen/project/config'
 import { GraphQLInteractive } from './GraphQLInteractive/index.js'
 
 interface CodeBlockProps {
@@ -24,7 +24,7 @@ export const CodeBlock: React.FC<CodeBlockProps> = ({ codeblock, schema }) => {
       <GraphQLInteractive
         codeblock={codeblock}
         schema={schema}
-        showWarningIfNoSchema={PROJECT_DATA?.warnings?.interactiveWithoutSchema?.enabled ?? false}
+        showWarningIfNoSchema={templateConfig.warnings.interactiveWithoutSchema.enabled}
       />
     )
   }

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

@@ -57,7 +57,7 @@ export const Field: React.FC<
                 <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,
                     }),
                   )}