polen 0.11.0-next.25 → 0.11.0-next.27

package/src/template/components/Link.tsx

@@ -1,4 +1,4 @@
-import type { FC } from 'react'
+import { forwardRef } from 'react'
 import type { LinkProps as LinkPropsReactRouter } from 'react-router'
 import { Link as LinkReactRouter, useLocation } from 'react-router'
 // todo: #lib/kit-temp does not work as import
@@ -20,7 +20,10 @@ const reactRouterPropKeys = [
   `children`,
 ] as const
 
-export const Link: FC<LinkPropsReactRouter & Omit<LinkPropsRadix, `asChild`>> = props => {
+export const Link = forwardRef<
+  HTMLAnchorElement,
+  LinkPropsReactRouter & Omit<LinkPropsRadix, `asChild`>
+>((props, ref) => {
   const location = useLocation()
   const toPathExp = typeof props.to === `string` ? props.to : props.to.pathname || ``
 
@@ -34,6 +37,7 @@ export const Link: FC<LinkPropsReactRouter & Omit<LinkPropsRadix, `asChild`>> =
   // Only add data attributes if they're true
   const linkRadixProps = {
     ...radixProps,
+    ref,
     asChild: true,
     ...(active.is && { 'data-active': true }),
     ...(active.isDirect && { 'data-active-direct': true }),
@@ -45,7 +49,9 @@ export const Link: FC<LinkPropsReactRouter & Omit<LinkPropsRadix, `asChild`>> =
       <LinkReactRouter {...reactRouterProps} />
     </LinkRadix>
   )
-}
+})
+
+Link.displayName = 'Link'
 
 export interface PathActiveReport {
   is: boolean

package/src/template/components/NamedType.tsx

@@ -2,11 +2,12 @@ import { Api } from '#api/iso'
 import { Lifecycles } from '#lib/lifecycles/$'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
-import { Badge, Box, Heading, Text } from '@radix-ui/themes'
+import { Badge, Box, Card, Heading, Section, Separator, Text } from '@radix-ui/themes'
 import { HashSet } from 'effect'
 import { type GraphQLNamedType } from 'graphql'
 import type { FC } from 'react'
 import { useSchema } from '../contexts/GraphqlLifecycleContext.js'
+import { useViewMode } from '../contexts/ViewModeContext.js'
 import { useExamplesForType } from '../hooks/use-examples.js'
 import { ExampleLink } from './ExampleLink.js'
 import { FieldListSection } from './FieldListSection.js'
@@ -20,10 +21,11 @@ export interface Props {
 
 export const NamedType: FC<Props> = ({ data }) => {
   const { schema, lifecycles } = useSchema()
+  const { viewMode } = useViewMode()
 
-  const description = data.description
+  const description = data.description && viewMode === 'expanded'
     ? (
-      <Text as='div' color='gray'>
+      <Text as='div' size='2' color='gray'>
         <Markdown>{data.description}</Markdown>
       </Text>
     )
@@ -33,6 +35,9 @@ export const NamedType: FC<Props> = ({ data }) => {
   const since = Lifecycles.getTypeSince(lifecycles, data.name, schema)
   const removedDate = Lifecycles.getTypeRemovedDate(lifecycles, data.name, schema)
 
+  // Only show since badge if it's NOT the initial version
+  const showSinceBadge = since && since._tag !== 'initial'
+
   // Get examples that use this type
   const currentVersion = Schema.Versioned.is(schema)
     ? schema.version
@@ -41,34 +46,55 @@ export const NamedType: FC<Props> = ({ data }) => {
 
   return (
     <Box>
-      <Box style={{ display: 'flex', alignItems: 'center', gap: '8px', marginBottom: '8px' }}>
-        <Heading size='8'>
-          <TypeLink type={data} />
-        </Heading>
-        {since && <SinceBadge since={since} />}
-        {removedDate && (
-          <Badge color='red' variant='soft' size='1'>
-            Removed {Api.Schema.dateToVersionString(removedDate)}
-          </Badge>
+      {/* Type header section */}
+      <Section size='1'>
+        <Box style={{ display: 'flex', alignItems: 'center', gap: '8px' }}>
+          <Heading size='7' weight='bold'>
+            <TypeLink type={data} />
+          </Heading>
+          {showSinceBadge && <SinceBadge since={since} />}
+          {removedDate && (
+            <Badge color='red' variant='soft' size='1'>
+              Removed {Api.Schema.dateToVersionString(removedDate)}
+            </Badge>
+          )}
+        </Box>
+
+        {/* Description section */}
+        {description && (
+          <Box mt='3'>
+            {description}
+          </Box>
         )}
-      </Box>
-      {description}
+      </Section>
+
+      {/* Examples section with separator */}
       {HashSet.size(examples) > 0 && (
-        <Box mt='4' mb='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}-${
-                  exampleRef.version ? Version.encodeSync(exampleRef.version) : 'unversioned'
-                }`}
-                exampleRef={exampleRef}
-              />
-            ))}
-          </Box>
-        </Box>
+        <>
+          <Separator size='4' my='4' />
+          <Section size='1'>
+            <Heading size='5' mb='3' weight='medium'>Used in Examples</Heading>
+            <Card variant='surface'>
+              <Box style={{ display: 'flex', flexWrap: 'wrap', gap: '8px' }}>
+                {[...examples].map((exampleRef) => (
+                  <ExampleLink
+                    key={`${exampleRef.name}-${
+                      exampleRef.version ? Version.encodeSync(exampleRef.version) : 'unversioned'
+                    }`}
+                    exampleRef={exampleRef}
+                  />
+                ))}
+              </Box>
+            </Card>
+          </Section>
+        </>
       )}
-      <FieldListSection data={data} />
+
+      {/* Fields section with separator */}
+      <Separator size='4' my='4' />
+      <Section size='1'>
+        <FieldListSection data={data} />
+      </Section>
     </Box>
   )
 }

package/src/template/components/ReferenceLink.tsx

@@ -1,5 +1,6 @@
 import { Api } from '#api/iso'
 import type { React } from '#dep/react/index'
+import { forwardRef } from 'react'
 import { useVersionPath } from '../hooks/useVersionPath.js'
 import { Link } from './Link.js'
 
@@ -10,14 +11,18 @@ import { Link } from './Link.js'
  * <ReferenceLink type="User">User</ReferenceLink>
  * <ReferenceLink type="User" field="name">User.name</ReferenceLink>
  */
-export const ReferenceLink: React.FC<{
-  /** The GraphQL type name */
-  type: string
-  /** Optional field name for field-specific links */
-  field?: string
-  /** Link content */
-  children: React.ReactNode
-}> = ({ type, field, children }) => {
+export const ReferenceLink = forwardRef<
+  HTMLAnchorElement,
+  {
+    className?: string
+    /** The GraphQL type name */
+    type: string
+    /** Optional field name for field-specific links */
+    field?: string
+    /** Link content */
+    children: React.ReactNode
+  }
+>(({ type, field, children, ...props }, ref) => {
   const versionPath = useVersionPath()
 
   const path = Api.Schema.Routing.joinSegmentsAndPaths(
@@ -28,8 +33,10 @@ export const ReferenceLink: React.FC<{
   )
 
   return (
-    <Link to={path}>
+    <Link to={path} ref={ref} {...props}>
       {children}
     </Link>
   )
-}
+})
+
+ReferenceLink.displayName = 'ReferenceLink'

package/src/template/components/TypeAnnotation.tsx

@@ -7,13 +7,21 @@ import { TypeLink } from './graphql/graphql.js'
 /**
  * Renders a GraphQL type recursively, with links for named types
  */
-export const TypeAnnotation: React.FC<{ type: GraphQLType }> = ({ type }) => {
+export const TypeAnnotation: React.FC<{
+  type: GraphQLType
+  showDescription?: boolean
+  nullabilityRendering?: 'questionMark' | 'bangMark'
+}> = ({ type, showDescription = false, nullabilityRendering = 'bangMark' }) => {
   // Handle NonNull type wrapper
   if (isNonNullType(type)) {
     return (
       <>
-        <TypeAnnotation type={type.ofType} />
-        <Text color='gray'>!</Text>
+        <TypeAnnotation
+          type={type.ofType}
+          showDescription={showDescription}
+          nullabilityRendering={nullabilityRendering}
+        />
+        {nullabilityRendering === 'bangMark' && <Text color='gray'>!</Text>}
       </>
     )
   }
@@ -23,7 +31,11 @@ export const TypeAnnotation: React.FC<{ type: GraphQLType }> = ({ type }) => {
     return (
       <>
         <Text color='gray'>[</Text>
-        <TypeAnnotation type={type.ofType} />
+        <TypeAnnotation
+          type={type.ofType}
+          showDescription={showDescription}
+          nullabilityRendering={nullabilityRendering}
+        />
         <Text color='gray'>]</Text>
       </>
     )
@@ -31,7 +43,7 @@ export const TypeAnnotation: React.FC<{ type: GraphQLType }> = ({ type }) => {
 
   // Handle named types - use TypeLink which already has icon support
   if (isNamedType(type)) {
-    return <TypeLink type={type} />
+    return <TypeLink type={type} showDescription={showDescription} />
   }
 
   // TypeScript exhaustiveness check - this should be unreachable

package/src/template/components/ViewModeToggle.tsx

@@ -0,0 +1,27 @@
+import type { React } from '#dep/react/index'
+import { ReaderIcon, RowsIcon } from '@radix-ui/react-icons'
+import { Flex, SegmentedControl } from '@radix-ui/themes'
+import { useViewMode } from '../contexts/ViewModeContext.js'
+
+export const ViewModeToggle: React.FC = () => {
+  const { viewMode, setViewMode } = useViewMode()
+
+  return (
+    <SegmentedControl.Root
+      value={viewMode}
+      onValueChange={(value) => setViewMode(value as 'compact' | 'expanded')}
+      size='1'
+    >
+      <SegmentedControl.Item value='expanded'>
+        <Flex align='center' gap='2'>
+          <ReaderIcon />
+        </Flex>
+      </SegmentedControl.Item>
+      <SegmentedControl.Item value='compact'>
+        <Flex align='center' gap='2'>
+          <RowsIcon />
+        </Flex>
+      </SegmentedControl.Item>
+    </SegmentedControl.Root>
+  )
+}

package/src/template/components/graphql/type-link.tsx

@@ -1,19 +1,62 @@
 import { Grafaid } from '#lib/grafaid'
-import { Code, Flex } from '@radix-ui/themes'
+import { Code, Flex, HoverCard, Text } from '@radix-ui/themes'
+import React from 'react'
+import { Description } from '../Description.js'
 import { ReferenceLink } from '../ReferenceLink.js'
 import { TypeKindIcon } from './graphql.js'
 import { typeKindTokensIndex } from './type-kind-tokens.js'
 
-export const TypeLink: React.FC<{ type: Grafaid.Schema.TypesLike.Named }> = ({ type }) => {
+export const TypeLink: React.FC<{
+  type: Grafaid.Schema.TypesLike.Named
+  showDescription?: boolean
+}> = ({ type, showDescription = false }) => {
   const kind = Grafaid.Schema.typeKindFromClass(type)
+  const hasDescription = type.description && type.description.trim() !== ''
+
+  const linkContent = (
+    <>
+      <style>
+        {`
+          .type-link-content:hover code:not(:first-child) {
+            text-decoration: underline;
+            text-underline-offset: 2px;
+          }
+        `}
+      </style>
+      <ReferenceLink type={type.name} className='type-link-content'>
+        <Flex
+          align='center'
+          gap='1'
+          display='inline-flex'
+        >
+          <TypeKindIcon kind={kind} />
+          {` `}
+          <Code color={typeKindTokensIndex[kind].color} variant='ghost'>{type.name}</Code>
+        </Flex>
+      </ReferenceLink>
+    </>
+  )
+
+  // Only show HoverCard if showDescription is true AND description exists
+  if (!showDescription || !hasDescription) {
+    return linkContent
+  }
 
   return (
-    <ReferenceLink type={type.name}>
-      <Flex align='center' gap='1' display='inline-flex'>
-        <TypeKindIcon kind={kind} />
-        {` `}
-        <Code color={typeKindTokensIndex[kind].color} variant='ghost'>{type.name}</Code>
-      </Flex>
-    </ReferenceLink>
+    <HoverCard.Root>
+      <HoverCard.Trigger>
+        {linkContent}
+      </HoverCard.Trigger>
+      <HoverCard.Content
+        size='2'
+        maxWidth='400px'
+        side='top'
+        align='center'
+      >
+        <Text size='2' color='gray'>
+          <Description data={type} />
+        </Text>
+      </HoverCard.Content>
+    </HoverCard.Root>
   )
 }

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

@@ -3,6 +3,7 @@ import { highlight } from 'codehike/code'
 import type { GraphQLSchema } from 'graphql'
 import * as React from 'react'
 import { Link } from 'react-router'
+import { templateConfig } from 'virtual:polen/project/config'
 import { GraphQLInteractive } from '../GraphQLInteractive/GraphQLInteractive.js'
 
 interface PlaygroundPreviewProps {
@@ -68,12 +69,14 @@ export const PlaygroundPreviewSection: React.FC<PlaygroundPreviewProps> = ({
                       codeblock={highlightedCode}
                       schema={schema}
                       showWarningIfNoSchema={false}
+                      referenceEnabled={templateConfig.reference.enabled}
                     />
                   )
                   : (
                     <GraphQLInteractive
                       codeblock={highlightedCode}
                       showWarningIfNoSchema={false}
+                      referenceEnabled={templateConfig.reference.enabled}
                     />
                   )}
               </Box>

package/src/template/components/sidebar/SidebarItem.tsx

@@ -3,6 +3,7 @@ import { Api } from '#api/iso'
 import type { React } from '#dep/react/index'
 import { Texts } from '#template/components/Texts/index'
 import { Box, Flex } from '@radix-ui/themes'
+import { Str } from '@wollybeard/kit'
 import { useContext } from 'react'
 import { useLocation } from 'react-router'
 import { getPathActiveReport, Link } from '../Link.js'
@@ -70,6 +71,11 @@ const SBLink: React.FC<{
   const href = Api.Schema.Routing.joinSegmentsAndPaths(basePath, link.pathExp)
   const active = getPathActiveReport(href, currentPathExp)
 
+  // Apply title case transformation to string titles for better readability
+  const displayTitle = typeof link.title === 'string'
+    ? Str.Case.title(link.title)
+    : link.title
+
   return (
     <Link
       role='Sidebar Link'
@@ -80,11 +86,11 @@ const SBLink: React.FC<{
         display: `block`,
         textDecoration: `none`,
         color: active.is ? `var(--accent-12)` : undefined,
-        backgroundColor: active.isDirect ? `var(--accent-2)` : active.isDescendant ? `var(--accent-1)` : `transparent`,
+        backgroundColor: active.isDirect ? `var(--accent-3)` : active.isDescendant ? `var(--gray-2)` : `transparent`,
         borderRadius: `var(--radius-2)`,
       }}
     >
-      <Box py='2' px='4'>{link.title}</Box>
+      <Box py='2' px='4'>{displayTitle}</Box>
     </Link>
   )
 }
@@ -100,11 +106,16 @@ const SBLink: React.FC<{
 const Section: React.FC<{
   section: TemplateItemSection
 }> = ({ section }) => {
+  // Apply title case transformation to string titles for better readability
+  const displayTitle = typeof section.title === 'string'
+    ? Str.Case.title(section.title)
+    : section.title
+
   return (
     <Box mt='8'>
       <Box ml='4' mb='2'>
         <Texts.MinorHeading color='gray'>
-          {section.title}
+          {displayTitle}
         </Texts.MinorHeading>
       </Box>
       <Items items={section.links} />
@@ -156,6 +167,11 @@ const SectionLink: React.FC<{ link: TemplateItemLink }> = ({ link }) => {
   const href = Api.Schema.Routing.joinSegmentsAndPaths(basePath, link.pathExp)
   const active = getPathActiveReport(href, location.pathname)
 
+  // Apply title case transformation to string titles for better readability
+  const displayTitle = typeof link.title === 'string'
+    ? Str.Case.title(link.title)
+    : link.title
+
   return (
     <Link
       role='Sidebar Link'
@@ -164,12 +180,12 @@ const SectionLink: React.FC<{ link: TemplateItemLink }> = ({ link }) => {
       style={{
         textDecoration: `none`,
         color: active.is ? `var(--accent-12)` : undefined,
-        backgroundColor: active.isDirect ? `var(--accent-2)` : active.isDescendant ? `var(--accent-1)` : `transparent`,
+        backgroundColor: active.isDirect ? `var(--accent-3)` : active.isDescendant ? `var(--gray-2)` : `transparent`,
         borderBottomRightRadius: `var(--radius-2)`,
         borderTopRightRadius: `var(--radius-2)`,
       }}
     >
-      <Box py='2' px='4'>{link.title}</Box>
+      <Box py='2' px='4'>{displayTitle}</Box>
     </Link>
   )
 }

package/src/template/contexts/ReferenceConfigContext.tsx

@@ -0,0 +1,37 @@
+import type { React } from '#dep/react/index'
+import { createContext, useContext } from 'react'
+
+export interface ReferenceConfig {
+  descriptionsView: {
+    defaultMode: 'compact' | 'expanded'
+    showControl: boolean
+  }
+  nullabilityRendering: 'questionMark' | 'bangMark'
+}
+
+interface ReferenceConfigContextValue {
+  config: ReferenceConfig
+}
+
+const ReferenceConfigContext = createContext<ReferenceConfigContextValue | undefined>(undefined)
+
+interface ReferenceConfigProviderProps {
+  children: React.ReactNode
+  config: ReferenceConfig
+}
+
+export const ReferenceConfigProvider: React.FC<ReferenceConfigProviderProps> = ({ children, config }) => {
+  return (
+    <ReferenceConfigContext.Provider value={{ config }}>
+      {children}
+    </ReferenceConfigContext.Provider>
+  )
+}
+
+export const useReferenceConfig = () => {
+  const context = useContext(ReferenceConfigContext)
+  if (!context) {
+    throw new Error('useReferenceConfig must be used within ReferenceConfigProvider')
+  }
+  return context.config
+}

package/src/template/contexts/ViewModeContext.tsx

@@ -0,0 +1,64 @@
+import type { React } from '#dep/react/index'
+import { createContext, useContext, useEffect, useState } from 'react'
+
+export type ViewMode = 'compact' | 'expanded'
+
+interface ViewModeContextValue {
+  viewMode: ViewMode
+  setViewMode: (mode: ViewMode) => void
+}
+
+const ViewModeContext = createContext<ViewModeContextValue | undefined>(undefined)
+
+const STORAGE_KEY = 'polen-view-mode'
+
+interface ViewModeProviderProps {
+  children: React.ReactNode
+  defaultMode?: ViewMode
+}
+
+export const ViewModeProvider: React.FC<ViewModeProviderProps> = ({ children, defaultMode = 'expanded' }) => {
+  const [viewMode, setViewModeState] = useState<ViewMode>(defaultMode)
+
+  // Load from localStorage after mount to avoid hydration mismatch
+  useEffect(() => {
+    const saved = localStorage.getItem(STORAGE_KEY)
+    if (saved === 'compact' || saved === 'expanded') {
+      setViewModeState(saved)
+    }
+  }, [])
+
+  const setViewMode = (mode: ViewMode) => {
+    setViewModeState(mode)
+    // Save to localStorage
+    if (typeof window !== 'undefined') {
+      localStorage.setItem(STORAGE_KEY, mode)
+    }
+  }
+
+  useEffect(() => {
+    // Sync with localStorage changes from other tabs
+    const handleStorageChange = (e: StorageEvent) => {
+      if (e.key === STORAGE_KEY && (e.newValue === 'compact' || e.newValue === 'expanded')) {
+        setViewModeState(e.newValue as ViewMode)
+      }
+    }
+
+    window.addEventListener('storage', handleStorageChange)
+    return () => window.removeEventListener('storage', handleStorageChange)
+  }, [])
+
+  return (
+    <ViewModeContext.Provider value={{ viewMode, setViewMode }}>
+      {children}
+    </ViewModeContext.Provider>
+  )
+}
+
+export const useViewMode = () => {
+  const context = useContext(ViewModeContext)
+  if (!context) {
+    throw new Error('useViewMode must be used within ViewModeProvider')
+  }
+  return context
+}

package/src/template/hooks/useAlignedColumns.ts

@@ -0,0 +1,19 @@
+import { useMemo } from 'react'
+
+/**
+ * Generic hook for calculating the maximum character width of names in a list.
+ * Used to align columns in lists like fields, arguments, etc.
+ *
+ * @param items - Array of items to measure
+ * @param getName - Function to extract the name from each item
+ * @returns Maximum character width across all names
+ */
+export const useAlignedColumns = <T>(
+  items: T[],
+  getName: (item: T) => string,
+): number => {
+  return useMemo(() => {
+    if (items.length === 0) return 0
+    return Math.max(...items.map(item => getName(item).length))
+  }, [items])
+}

package/src/template/routes/examples/name.tsx

@@ -1,14 +1,17 @@
 import { Example } from '#api/examples/schemas/example/example'
+import { Catalog } from '#lib/catalog/$'
 import { route } from '#lib/react-router-effect/route'
 import { useLoaderData } from '#lib/react-router-effect/use-loader-data'
 import { Version } from '#lib/version/$'
-import { Heading } from '@radix-ui/themes'
+import { Box, Heading } from '@radix-ui/themes'
 import { Str } from '@wollybeard/kit'
 import { Array, Option } from 'effect'
 import { useSearchParams } from 'react-router'
+import * as ExamplesModule from 'virtual:polen/project/examples'
 import { examplesCatalog } from 'virtual:polen/project/examples'
 import { schemasCatalog } from 'virtual:polen/project/schemas'
 import { GraphQLDocument } from '../../components/GraphQLDocument.js'
+import { MdxProvider } from '../../providers/mdx.js'
 
 export const NameSchema = Example
 
@@ -47,9 +50,18 @@ const Component = () => {
     ? Version.decodeSync(versionParam)
     : undefined
 
+  const DescriptionComponent = (ExamplesModule as any)[`DescriptionComponent_${example.name.replace(/-/g, '_')}`]
+
   return (
     <>
       <Heading size='6' mb='4'>{Str.Case.title(example.name)}</Heading>
+      {DescriptionComponent && (
+        <Box mb='4'>
+          <MdxProvider schema={schemasCatalog && Catalog.getLatest(schemasCatalog).definition}>
+            <DescriptionComponent />
+          </MdxProvider>
+        </Box>
+      )}
       <GraphQLDocument
         document={example.document}
         schemaCatalog={schemasCatalog ?? undefined}