polen 0.11.0-next.25 → 0.11.0-next.26

package/src/template/components/ArgumentListAnnotation.tsx

@@ -1,34 +1,67 @@
+import { Grafaid } from '#lib/grafaid'
 import { GrafaidOld } from '#lib/grafaid-old'
-import { Box, Text } from '@radix-ui/themes'
-import type { GraphQLField } from 'graphql'
+import { Box, Flex } from '@radix-ui/themes'
+import type { GraphQLArgument, GraphQLField } from 'graphql'
 import type { FC } from 'react'
+import { useAlignedColumns } from '../hooks/useAlignedColumns.js'
 import { ArgumentAnnotation } from './ArgumentAnnotation.js'
-import { FieldList } from './FieldList.js'
+import { IAPIndicator } from './IAPIndicator.js'
 
 export interface Props {
   field: GraphQLField<any, any>
+  argumentNameWidth?: number
 }
 
-export const ArgumentListAnnotation: FC<Props> = ({ field }) => {
+export const ArgumentListAnnotation: FC<Props> = ({ field, argumentNameWidth }) => {
   if (field.args.length === 0) return null
 
   const inputObject = GrafaidOld.getIAP(field)
-  const inputObjectFields = inputObject
-    ? (
-      <Box pl='3' style={{ borderLeft: `1px solid var(--gray-6)` }}>
-        <FieldList data={inputObject} />
+
+  // If it's IAP, show indicator and input object's fields directly
+  if (inputObject) {
+    const inputFields = Grafaid.Schema.NodesLike.getFields(inputObject)
+    const nameWidth = argumentNameWidth ?? useAlignedColumns(inputFields, field => field.name)
+
+    return (
+      <Box>
+        <Flex direction='column' gap='2'>
+          {/* Small IAP indicator */}
+          <Box ml='3'>
+            <IAPIndicator inputObject={inputObject} />
+          </Box>
+
+          {/* Show input object fields directly without header */}
+          {inputFields.map(field => (
+            <Box key={field.name} ml='3'>
+              <ArgumentAnnotation
+                data={{
+                  name: field.name,
+                  type: field.type,
+                  description: field.description,
+                  defaultValue: (field as any).defaultValue,
+                  deprecationReason: (field as any).deprecationReason,
+                } as GraphQLArgument}
+                nameWidth={nameWidth}
+              />
+            </Box>
+          ))}
+        </Flex>
       </Box>
     )
-    : null
+  }
+
+  // Regular non-IAP arguments
+  const nameWidth = argumentNameWidth ?? useAlignedColumns([...field.args], arg => arg.name)
 
   return (
-    <>
-      <Text>(</Text>
-      <Box ml='2'>
-        {field.args.map(arg => <ArgumentAnnotation key={arg.name} data={arg} />)}
-        {inputObjectFields}
-      </Box>
-      <Text>)</Text>
-    </>
+    <Box>
+      <Flex direction='column' gap='2'>
+        {field.args.map(arg => (
+          <Box key={arg.name} ml='3'>
+            <ArgumentAnnotation data={arg} nameWidth={nameWidth} />
+          </Box>
+        ))}
+      </Flex>
+    </Box>
   )
 }

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

@@ -1,4 +1,3 @@
-import { Change as GraphqlChange } from '#lib/change/$'
 import { Code } from '@radix-ui/themes'
 import type React from 'react'
 import { ChangeBase } from '../ChangeBase.js'

package/src/template/components/CodeBlock.tsx

@@ -25,6 +25,7 @@ export const CodeBlock: React.FC<CodeBlockProps> = ({ codeblock, schema }) => {
         codeblock={codeblock}
         schema={schema}
         showWarningIfNoSchema={templateConfig.warnings.interactiveWithoutSchema.enabled}
+        referenceEnabled={templateConfig.reference.enabled}
       />
     )
   }

package/src/template/components/Description.tsx

@@ -9,7 +9,7 @@ export const Description: React.FC<{ data: GraphQLNamedType | GrafaidOld.GraphQL
   if (!data.description) return null
 
   return (
-    <Text as='div' color='gray'>
+    <Text as='div' size='2' color='gray' style={{ lineHeight: '1.5' }}>
       <Markdown>{data.description}</Markdown>
     </Text>
   )

package/src/template/components/ExampleLink.tsx

@@ -1,6 +1,7 @@
 import type { ExampleReference } from '#api/examples/schemas/type-usage-index'
 import { Version } from '#lib/version/$'
 import { Badge, Link } from '@radix-ui/themes'
+import { Str } from '@wollybeard/kit'
 import type { FC } from 'react'
 
 export interface Props {
@@ -20,7 +21,7 @@ export const ExampleLink: FC<Props> = ({ exampleRef }) => {
   return (
     <Link href={href} style={{ textDecoration: 'none' }}>
       <Badge variant='soft' size='2' style={{ cursor: 'pointer' }}>
-        {exampleRef.name}
+        {Str.titlizeSlug(exampleRef.name)}
       </Badge>
     </Link>
   )

package/src/template/components/Field.tsx

@@ -3,8 +3,11 @@ 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 { Badge, Box, Text } from '@radix-ui/themes'
+import { Badge, Box, Card, Flex, HoverCard, Link, Text } from '@radix-ui/themes'
+import { isNonNullType } from 'graphql'
 import { useSchema } from '../contexts/GraphqlLifecycleContext.js'
+import { useReferenceConfig } from '../contexts/ReferenceConfigContext.js'
+import { useViewMode } from '../contexts/ViewModeContext.js'
 import { ArgumentListAnnotation } from './ArgumentListAnnotation.js'
 import { DeprecationReason } from './DeprecationReason.js'
 import { Description } from './Description.js'
@@ -15,14 +18,23 @@ export const Field: React.FC<
   BoxProps & {
     data: GrafaidOld.GraphQLField
     parentTypeName?: string
+    fieldNameWidth?: number
+    argumentNameWidth?: number
   }
-> = ({ data, parentTypeName, ...boxProps }) => {
+> = ({ data, parentTypeName, fieldNameWidth, argumentNameWidth, ...boxProps }) => {
   const { schema, lifecycles } = useSchema()
+  const { viewMode } = useViewMode()
+  const referenceConfig = useReferenceConfig()
 
   const argumentList = GrafaidOld.isOutputField(data)
-    ? <ArgumentListAnnotation field={data} />
+    ? argumentNameWidth !== undefined
+      ? <ArgumentListAnnotation field={data} argumentNameWidth={argumentNameWidth} />
+      : <ArgumentListAnnotation field={data} />
     : null
 
+  // Check if the field is nullable (for questionMark mode)
+  const isFieldNullable = !isNonNullType(data.type)
+
   // Get field lifecycle information if available
   const since = parentTypeName
     ? Lifecycles.getFieldSince(lifecycles, parentTypeName, data.name, schema)
@@ -31,24 +43,140 @@ export const Field: React.FC<
     ? Lifecycles.getFieldRemovedDate(lifecycles, parentTypeName, data.name, schema)
     : null
 
+  // Only show since badge if it's NOT the initial version
+  const showSinceBadge = since && since._tag !== 'initial'
+
   return (
-    <Box {...boxProps} id={data.name}>
-      <Description data={data} />
+    <Card
+      {...boxProps}
+      variant='ghost'
+      id={data.name}
+      style={{ overflow: 'visible' }}
+    >
+      {/* Field name and return type with aligned columns */}
+      <style>
+        {`
+        .field-name-anchor {
+          position: absolute;
+          left: 0;
+          top: 50%;
+          transform: translateY(-50%) translateX(0);
+          opacity: 0;
+          transition: all 0.2s ease-in-out;
+          pointer-events: none;
+          z-index: 10;
+        }
+
+        .field-name-wrapper:hover .field-name-anchor {
+          transform: translateY(-50%) translateX(-24px);
+          opacity: 1;
+          pointer-events: auto;
+        }
+      `}
+      </style>
+      <Flex align='baseline' mb='2' gap='2'>
+        <Box
+          className='field-name-wrapper'
+          style={{
+            minWidth: fieldNameWidth ? `${fieldNameWidth}ch` : 'auto',
+            flexShrink: 0,
+            position: 'relative',
+          }}
+        >
+          {/* Anchor icon that slides left on hover */}
+          <Link
+            className='field-name-anchor'
+            href={`#${data.name}`}
+            color='gray'
+            style={{
+              textDecoration: 'none',
+              display: 'inline-flex',
+              alignItems: 'center',
+            }}
+          >
+            <Text size='3' color='gray'>
+              #
+            </Text>
+          </Link>
+          {viewMode === 'compact' && data.description
+            ? (
+              <HoverCard.Root>
+                <HoverCard.Trigger>
+                  <Link
+                    href={`#${data.name}`}
+                    color='gray'
+                    underline='hover'
+                    style={{ textDecoration: 'none', display: 'inline-block' }}
+                  >
+                    <Text size='3' weight='bold'>
+                      {data.name}
+                      {referenceConfig.nullabilityRendering === 'questionMark' && isFieldNullable && '?'}
+                    </Text>
+                  </Link>
+                </HoverCard.Trigger>
+                <HoverCard.Content
+                  size='2'
+                  maxWidth='400px'
+                  side='top'
+                  align='center'
+                >
+                  <Text size='2' color='gray'>
+                    <Description data={data} />
+                  </Text>
+                </HoverCard.Content>
+              </HoverCard.Root>
+            )
+            : (
+              <Link
+                href={`#${data.name}`}
+                color='gray'
+                underline='hover'
+                style={{ textDecoration: 'none', display: 'inline-block' }}
+              >
+                <Text size='3' weight='bold'>
+                  {data.name}
+                  {referenceConfig.nullabilityRendering === 'questionMark' && isFieldNullable && '?'}
+                </Text>
+              </Link>
+            )}
+        </Box>
+        <TypeAnnotation
+          type={data.type}
+          showDescription={true}
+          nullabilityRendering={referenceConfig.nullabilityRendering}
+        />
+      </Flex>
+
+      {/* Badges below the header line */}
+      {(showSinceBadge || removedDate) && (
+        <Flex gap='2' mb='2'>
+          {showSinceBadge && <SinceBadge since={since} />}
+          {removedDate && (
+            <Badge color='red' variant='soft' size='1'>
+              Removed {Api.Schema.dateToVersionString(removedDate)}
+            </Badge>
+          )}
+        </Flex>
+      )}
+
+      {/* Description below title (only in expanded mode) */}
+      {data.description && viewMode === 'expanded' && (
+        <Box mb='2'>
+          <Text size='2' color='gray' style={{ lineHeight: '1.5' }}>
+            <Description data={data} />
+          </Text>
+        </Box>
+      )}
+
+      {/* Deprecation reason if exists */}
       <DeprecationReason data={data} />
-      <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}
-        :{` `}
-        <TypeAnnotation type={data.type} />
-      </Text>
-    </Box>
+
+      {/* Arguments section below, with left border - only show if field has arguments */}
+      {argumentList && GrafaidOld.isOutputField(data) && data.args.length > 0 && (
+        <Box mt='2' ml='3' pl='3' style={{ borderLeft: '2px solid var(--gray-4)' }}>
+          {argumentList}
+        </Box>
+      )}
+    </Card>
   )
 }

package/src/template/components/FieldList.tsx

@@ -1,29 +1,44 @@
 import { Grafaid } from '#lib/grafaid'
-import { Box } from '@radix-ui/themes'
-import type { FC } from 'react'
+import { GrafaidOld } from '#lib/grafaid-old'
+import { Box, Flex } from '@radix-ui/themes'
+import { type FC } from 'react'
+import { useAlignedColumns } from '../hooks/useAlignedColumns.js'
 import { Field } from './Field.js'
 
 export interface Props {
   data: Grafaid.Schema.TypesLike.Named
   parentTypeName?: string
+  argumentNameWidth?: number
 }
 
-export const FieldList: FC<Props> = ({ data, parentTypeName }) => {
+export const FieldList: FC<Props> = ({ data, parentTypeName, argumentNameWidth }) => {
   if (!Grafaid.Schema.TypesLike.isFielded(data)) return null
 
   const fields = Grafaid.Schema.NodesLike.getFields(data)
   if (fields.length === 0) return null
 
+  // Calculate the maximum field name length for alignment using shared hook
+  const fieldNameWidth = useAlignedColumns(fields, field => field.name)
+
   return (
-    <Box>
-      {fields.map(field => (
-        <Field
-          mt='3'
-          key={field.name}
-          data={field}
-          parentTypeName={parentTypeName ?? data.name}
-        />
-      ))}
-    </Box>
+    <Flex direction='column'>
+      {fields.map((field, index) => {
+        // Check if this field has arguments
+        const hasArguments = GrafaidOld.isOutputField(field) && field.args.length > 0
+        // Add extra spacing after fields with arguments
+        const marginBottom = hasArguments ? '5' : '3'
+
+        return (
+          <Box key={field.name} mb={index < fields.length - 1 ? marginBottom : '0'}>
+            <Field
+              data={field}
+              parentTypeName={parentTypeName ?? data.name}
+              fieldNameWidth={fieldNameWidth}
+              {...(argumentNameWidth !== undefined ? { argumentNameWidth } : {})}
+            />
+          </Box>
+        )
+      })}
+    </Flex>
   )
 }

package/src/template/components/FieldListSection.tsx

@@ -1,7 +1,9 @@
 import type { React } from '#dep/react/index'
 import { Grafaid } from '#lib/grafaid'
+import { GrafaidOld } from '#lib/grafaid-old'
 import { Box, Heading } from '@radix-ui/themes'
 import type { GraphQLNamedType } from 'graphql'
+import { useAlignedColumns } from '../hooks/useAlignedColumns.js'
 import { FieldList } from './FieldList.js'
 
 export const FieldListSection: React.FC<{ data: GraphQLNamedType }> = ({ data }) => {
@@ -10,10 +12,18 @@ export const FieldListSection: React.FC<{ data: GraphQLNamedType }> = ({ data })
   const fields = Grafaid.Schema.NodesLike.getFields(data)
   if (fields.length === 0) return null
 
+  // Calculate the maximum argument name width across ALL fields of this type
+  const allArguments = fields.flatMap(field => GrafaidOld.isOutputField(field) ? field.args : [])
+  const argumentNameWidth = useAlignedColumns(allArguments, arg => arg.name)
+
   return (
     <Box>
-      <Heading>Fields</Heading>
-      <FieldList data={data} parentTypeName={data.name} />
+      <Heading size='5' mb='4' weight='medium'>Fields</Heading>
+      <FieldList
+        data={data}
+        parentTypeName={data.name}
+        argumentNameWidth={argumentNameWidth}
+      />
     </Box>
   )
 }

package/src/template/components/GraphQLDocument.tsx

@@ -3,6 +3,7 @@ import { Document } from '#lib/document/$'
 import { VersionCoverage } from '#lib/version-coverage'
 import { Either, Option } from 'effect'
 import * as React from 'react'
+import { templateConfig } from 'virtual:polen/project/config'
 import { useHighlighted } from '../hooks/use-highlighted.js'
 import { GraphQLInteractive } from './GraphQLInteractive/GraphQLInteractive.js'
 import { VersionCoveragePicker } from './VersionCoveragePicker.js'
@@ -72,6 +73,7 @@ export const GraphQLDocument: React.FC<GraphQLDocumentProps> = ({
     <GraphQLInteractive
       codeblock={highlightedCode}
       schema={schema?.definition}
+      referenceEnabled={templateConfig.reference.enabled}
       style={style}
       toolbar={() => (
         showVersionCoveragePicker && selectedVersionCoverage && (

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

@@ -29,6 +29,9 @@ interface GraphQLInteractiveProps {
   /** Whether to show a warning indicator when schema is missing */
   showWarningIfNoSchema?: boolean | undefined
 
+  /** Whether reference documentation is enabled (controls if types link to reference) */
+  referenceEnabled?: boolean | undefined
+
   /** Optional toolbar component to render (e.g., version picker) */
   toolbar?: () => React.ReactNode
 
@@ -53,6 +56,7 @@ const GraphQLInteractiveImpl: React.FC<GraphQLInteractiveProps> = ({
   codeblock,
   schema,
   showWarningIfNoSchema = true,
+  referenceEnabled = true,
   toolbar,
   style,
 }) => {
@@ -86,6 +90,7 @@ const GraphQLInteractiveImpl: React.FC<GraphQLInteractiveProps> = ({
         codeblock.code,
         codeblock.annotations,
         schema, // Pass the schema for semantic analysis
+        referenceEnabled, // Pass reference enabled flag for link generation
       )
 
       setTokens(parsedTokens)
@@ -98,7 +103,7 @@ const GraphQLInteractiveImpl: React.FC<GraphQLInteractiveProps> = ({
     } finally {
       setIsLoading(false)
     }
-  }, [codeblock.code, codeblock.annotations, schema])
+  }, [codeblock.code, codeblock.annotations, schema, referenceEnabled])
 
   // Retry function for users
   const handleRetry = ReactHooks.useCallback(() => {

package/src/template/components/GraphQLInteractive/lib/parser.ts

@@ -109,11 +109,13 @@ class UnifiedToken implements GraphQLToken {
   private _start: number
   private _end: number
   private _nodeType: TreeSitterGraphQLNodeType
+  private _referenceEnabled: boolean
 
   constructor(
     public treeSitterNode: WebTreeSitter.Node,
     public semantic: SemanticNode | undefined,
     annotations: CodeAnnotation[],
+    referenceEnabled = true,
   ) {
     // Cache the values immediately to avoid WASM access issues later
     // This works for both real WebTreeSitter nodes and synthetic nodes
@@ -121,6 +123,7 @@ class UnifiedToken implements GraphQLToken {
     this._start = treeSitterNode.startIndex
     this._end = treeSitterNode.endIndex
     this._nodeType = treeSitterNode.type as TreeSitterGraphQLNodeType
+    this._referenceEnabled = referenceEnabled
 
     this.codeHike = { annotations }
 
@@ -255,6 +258,8 @@ class UnifiedToken implements GraphQLToken {
   }
 
   private _getReferenceUrl(): string | null {
+    // If reference is disabled, don't generate URLs
+    if (!this._referenceEnabled) return null
     if (!this.semantic) return null
 
     // Arguments - use #<field>__<argument> pattern
@@ -536,6 +541,7 @@ export async function parseGraphQLWithTreeSitterEither(
   code: string,
   annotations: CodeAnnotation[] = [],
   schema?: GraphQLSchema,
+  referenceEnabled = true,
 ): Promise<Either.Either<GraphQLToken[], ParseError>> {
   // Validate input
   if (!code || typeof code !== 'string') {
@@ -566,10 +572,10 @@ export async function parseGraphQLWithTreeSitterEither(
 
   try {
     // Step 2: Walk tree and attach semantics
-    const tokens = collectTokensWithSemantics(tree, code, schema, annotations)
+    const tokens = collectTokensWithSemantics(tree, code, schema, annotations, referenceEnabled)
 
     // Step 3: Add error hint tokens after invalid fields
-    const tokensWithHints = addErrorHintTokens(tokens, code, annotations)
+    const tokensWithHints = addErrorHintTokens(tokens, code, annotations, referenceEnabled)
 
     return Either.right(tokensWithHints)
   } catch (error) {
@@ -595,8 +601,9 @@ export async function parseGraphQLWithTreeSitter(
   code: string,
   annotations: CodeAnnotation[] = [],
   schema?: GraphQLSchema,
+  referenceEnabled = true,
 ): Promise<GraphQLToken[]> {
-  const result = await parseGraphQLWithTreeSitterEither(code, annotations, schema)
+  const result = await parseGraphQLWithTreeSitterEither(code, annotations, schema, referenceEnabled)
 
   if (Either.isLeft(result)) {
     const error = result.left
@@ -714,6 +721,7 @@ function addErrorHintTokens(
   tokens: GraphQLToken[],
   code: string,
   annotations: CodeAnnotation[],
+  referenceEnabled = true,
 ): GraphQLToken[] {
   const tokensWithHints: GraphQLToken[] = []
   const processedIndices = new Set<number>()
@@ -792,6 +800,7 @@ function addErrorHintTokens(
         ),
         undefined,
         annotations,
+        referenceEnabled,
       )
       tokensWithHints.push(hintToken)
     }
@@ -808,6 +817,7 @@ function collectTokensWithSemantics(
   code: string,
   schema: GraphQLSchema | undefined,
   annotations: CodeAnnotation[],
+  referenceEnabled = true,
 ): GraphQLToken[] {
   const tokens: GraphQLToken[] = []
   const cursor = tree.walk()
@@ -861,6 +871,7 @@ function collectTokensWithSemantics(
             createWhitespaceNode(whitespace, lastEnd, node.startIndex),
             undefined,
             annotations,
+            referenceEnabled,
           ),
         )
       }
@@ -1009,6 +1020,7 @@ function collectTokensWithSemantics(
         node,
         semantic,
         annotations,
+        referenceEnabled,
       )
 
       tokens.push(token)
@@ -1050,6 +1062,7 @@ function collectTokensWithSemantics(
         createWhitespaceNode(remaining, lastEnd, code.length),
         undefined,
         annotations,
+        referenceEnabled,
       ),
     )
   }

package/src/template/components/IAPIndicator.tsx

@@ -0,0 +1,73 @@
+import { InfoCircledIcon } from '@radix-ui/react-icons'
+import { Box, Flex, HoverCard, Separator, Text } from '@radix-ui/themes'
+import type { GraphQLInputObjectType } from 'graphql'
+import type { FC } from 'react'
+import { TypeLink } from './graphql/type-link.js'
+
+interface Props {
+  inputObject: GraphQLInputObjectType
+}
+
+/**
+ * Indicator for Input Argument Pattern (IAP) - shows when a field
+ * has a single 'input' argument with an Input Object type
+ */
+export const IAPIndicator: FC<Props> = ({ inputObject }) => {
+  return (
+    <HoverCard.Root>
+      <HoverCard.Trigger>
+        <Flex
+          align='center'
+          gap='1'
+          style={{
+            cursor: 'pointer',
+            opacity: 0.7,
+            display: 'inline-flex',
+          }}
+        >
+          <InfoCircledIcon style={{ width: 12, height: 12 }} />
+          <Text size='1' color='gray'>input</Text>
+        </Flex>
+      </HoverCard.Trigger>
+      <HoverCard.Content size='2' maxWidth='400px'>
+        <Flex direction='column' gap='3'>
+          <Flex direction='column' gap='2'>
+            <Box>
+              <TypeLink type={inputObject} />
+            </Box>
+            {inputObject.description && (
+              <Text size='2' color='gray' style={{ lineHeight: '1.5' }}>
+                {inputObject.description}
+              </Text>
+            )}
+          </Flex>
+          {inputObject.description && <Separator size='4' />}
+          <Flex direction='column' gap='2'>
+            <Text size='2' color='gray'>
+              This field uses an input-only argument pattern. The fields shown below belong to the input object, not
+              direct field arguments.
+            </Text>
+            <Box>
+              <Text size='1' color='gray' weight='medium'>
+                Example usage:
+              </Text>
+              <Box
+                mt='1'
+                style={{
+                  padding: '8px',
+                  backgroundColor: 'var(--gray-2)',
+                  borderRadius: '4px',
+                  fontFamily: 'var(--code-font-family)',
+                }}
+              >
+                <Text size='1' style={{ whiteSpace: 'pre' }}>
+                  {`mutation {\n  fieldName(input: { a: 1, b: "value", ... }) {\n    ...\n  }\n}`}
+                </Text>
+              </Box>
+            </Box>
+          </Flex>
+        </Flex>
+      </HoverCard.Content>
+    </HoverCard.Root>
+  )
+}