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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.11.0-next.25",
+  "version": "0.11.0-next.26",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {

package/src/api/config/input.ts

@@ -1,4 +1,5 @@
 import { ExamplesConfig } from '#api/examples/config'
+import { ReferenceConfig } from '#api/reference/config'
 import { ConfigSchema } from '#api/schema/config-schema'
 import { Vite } from '#dep/vite/index'
 import { spreadShallow } from '#lib/kit-temp'
@@ -306,6 +307,7 @@ export const ConfigInput = S.Struct({
    */
   description: S.optional(S.String),
   schema: S.optional(ConfigSchema),
+  reference: S.optional(ReferenceConfig),
   examples: S.optional(ExamplesConfig),
   templateVariables: S.optional(TemplateVariables),
   home: S.optional(HomeConfig),

package/src/api/config/normalized.ts

@@ -1,4 +1,5 @@
 import { ExamplesConfig } from '#api/examples/config'
+import { DescriptionsView, ReferenceConfigObject } from '#api/reference/config'
 import { ConfigSchema } from '#api/schema/config-schema'
 import { Typings } from '#api/typings/$'
 import { DirectedFilter } from '#lib/directed-filter/$'
@@ -11,6 +12,24 @@ import { Effect } from 'effect'
 import type { WritableDeep } from 'type-fest'
 import { BuildArchitecture, ConfigInput } from './input.js'
 
+// ============================================================================
+// Normalized Reference Config
+// ============================================================================
+
+/**
+ * Normalized reference configuration where all optional fields have defaults applied.
+ */
+const NormalizedReferenceConfig = S.extend(
+  ReferenceConfigObject.pipe(S.omit('descriptionsView', 'nullabilityRendering')),
+  S.Struct({
+    descriptionsView: S.Struct({
+      defaultMode: S.Literal('compact', 'expanded'),
+      showControl: S.Boolean,
+    }),
+    nullabilityRendering: S.Literal('questionMark', 'bangMark'),
+  }),
+)
+
 // ============================================================================
 // DirectedFilter for Strings
 // ============================================================================
@@ -320,6 +339,11 @@ export const Config = S.Struct({
    */
   schema: ConfigSchema,
 
+  /**
+   * Reference documentation configuration with resolved defaults.
+   */
+  reference: NormalizedReferenceConfig,
+
   /**
    * Examples configuration with resolved defaults.
    */
@@ -487,6 +511,13 @@ const getConfigInputDefaults = (baseRootDirPath: string): Config => ({
     },
   },
   schema: {},
+  reference: {
+    descriptionsView: {
+      defaultMode: 'expanded',
+      showControl: true,
+    },
+    nullabilityRendering: 'bangMark',
+  },
   examples: {
     display: 'all',
   },
@@ -658,6 +689,29 @@ export const normalizeInput = (
         configInput_as_writeable.warnings.interactiveWithoutSchema.enabled
     }
 
+    // Process reference configuration
+    if (configInput_as_writeable?.reference) {
+      const referenceInput = configInput_as_writeable.reference
+      // The schema transform handles boolean shorthand, so we always get an object here
+      if (referenceInput.enabled !== undefined) {
+        config.reference.enabled = referenceInput.enabled
+      }
+      if (referenceInput.descriptionsView) {
+        if (referenceInput.descriptionsView.defaultMode !== undefined) {
+          config.reference.descriptionsView.defaultMode = referenceInput.descriptionsView.defaultMode
+        }
+        if (referenceInput.descriptionsView.showControl !== undefined) {
+          config.reference.descriptionsView.showControl = referenceInput.descriptionsView.showControl
+        }
+      }
+      if (referenceInput.nullabilityRendering !== undefined) {
+        config.reference.nullabilityRendering = referenceInput.nullabilityRendering
+      }
+      if (referenceInput.diagnostics) {
+        config.reference.diagnostics = referenceInput.diagnostics
+      }
+    }
+
     // Process examples configuration
     if (configInput_as_writeable?.examples) {
       const examplesInput = configInput_as_writeable.examples

package/src/api/config-template/template.ts

@@ -1,5 +1,6 @@
 import type { Api } from '#api/$'
 import { ExamplesConfigObject } from '#api/examples/config'
+import { ReferenceConfigObject } from '#api/reference/config'
 import { ConfigSchema } from '#api/schema/config-schema'
 import type { Catalog } from '#lib/catalog/$'
 import { S } from '#lib/kit-temp/effect'
@@ -16,6 +17,13 @@ export const resolve = (config: Config, data: {
       ...config.schema,
       enabled: Boolean(config.schema.enabled ?? data.schemas),
     },
+    reference: {
+      ...config.reference,
+      // Reference is enabled if explicitly enabled OR if schemas exist (unless explicitly disabled)
+      enabled: Boolean(config.reference.enabled ?? data.schemas),
+      descriptionsView: config.reference.descriptionsView,
+      nullabilityRendering: config.reference.nullabilityRendering,
+    },
     examples: {
       ...config.examples,
       enabled: Boolean(config.examples.enabled ?? (data.examples && data.examples.examples.length > 0)),
@@ -33,7 +41,7 @@ export const resolve = (config: Config, data: {
  * that control feature enablement have been resolved to concrete values.
  */
 export const TemplateConfig = S.extend(
-  Config.pipe(S.omit('_input', 'schema', 'examples')),
+  Config.pipe(S.omit('_input', 'schema', 'reference', 'examples')),
   S.Struct({
     schema: S.extend(
       ConfigSchema.pipe(S.omit('enabled')),
@@ -41,6 +49,15 @@ export const TemplateConfig = S.extend(
         enabled: S.Boolean,
       }),
     ),
+    reference: S.Struct({
+      enabled: S.Boolean,
+      descriptionsView: S.Struct({
+        defaultMode: S.Literal('compact', 'expanded'),
+        showControl: S.Boolean,
+      }),
+      nullabilityRendering: S.Literal('questionMark', 'bangMark'),
+      diagnostics: S.optional(S.Unknown), // From ReferenceConfigObject
+    }),
     examples: S.extend(
       ExamplesConfigObject.pipe(S.omit('enabled')),
       S.Struct({

package/src/api/examples/scanner.ts

@@ -330,6 +330,20 @@ export const scan = (
       }
 
       if (example) {
+        // Check for description.md or description.mdx file
+        const descriptionMdPath = Path.join(options.dir, `${name}.md`)
+        const descriptionMdxPath = Path.join(options.dir, `${name}.mdx`)
+
+        const descriptionPath = (yield* fs.exists(descriptionMdPath))
+          ? descriptionMdPath
+          : (yield* fs.exists(descriptionMdxPath))
+          ? descriptionMdxPath
+          : null
+
+        if (descriptionPath) {
+          example = { ...example, description: { path: descriptionPath } }
+        }
+
         examples.push(example)
         // Generate diagnostics for this example
         diagnostics.push(...lintFileLayout(example, options.schemaCatalog))

package/src/api/examples/schemas/example/example.ts

@@ -26,6 +26,12 @@ export const Example = S.Struct({
    * The document content, which can be unversioned, versioned, or partially versioned.
    */
   document: Document.Document,
+
+  /**
+   * Optional description file for this example.
+   * Points to a markdown/MDX file that describes the example.
+   */
+  description: S.optional(S.Struct({ path: S.String })),
 }).annotations({
   identifier: 'Example',
   description: 'A GraphQL example that contains a document with optional versioning support',

package/src/api/reference/$.ts

@@ -0,0 +1,3 @@
+export * as Catalog from './catalog.js'
+export * as Config from './config.js'
+export * from './scanner.js'

package/src/api/reference/catalog.ts

@@ -0,0 +1,55 @@
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema and Type
+// ============================================================================
+
+export const Catalog = S.Struct({
+  /**
+   * Optional index file metadata for custom reference landing page.
+   * If not provided, the app will redirect to the Query type.
+   */
+  index: S.optional(S.Struct({
+    /**
+     * Path to the index.md or index.mdx file
+     */
+    path: S.String,
+  })),
+}).annotations({
+  identifier: 'ReferenceCatalog',
+  description: 'A catalog of reference documentation metadata',
+})
+
+export type Catalog = S.Schema.Type<typeof Catalog>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = Catalog.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(Catalog)
+
+// ============================================================================
+// State Predicates
+// ============================================================================
+
+/**
+ * Check if the catalog has a custom index page
+ */
+export const hasIndex = (catalog: Catalog): boolean => {
+  return catalog.index !== undefined
+}
+
+// ============================================================================
+// Codec
+// ============================================================================
+
+export const decode = S.decode(Catalog)
+export const decodeSync = S.decodeSync(Catalog)
+export const encode = S.encode(Catalog)
+export const encodeSync = S.encodeSync(Catalog)

package/src/api/reference/config.ts

@@ -0,0 +1,193 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { S } from '#lib/kit-temp/effect'
+
+// ============================================================================
+// Schema - Reference Diagnostics
+// ============================================================================
+
+/**
+ * Diagnostic controls for reference documentation.
+ */
+export const ReferenceDiagnostics = S.Struct({
+  /**
+   * Control diagnostics for missing or invalid reference content.
+   *
+   * @default true (info in dev, warning in build)
+   */
+  validation: S.optional(S.Union(S.Boolean, Diagnostic.Control)),
+}).annotations({
+  identifier: 'ReferenceDiagnostics',
+  description: 'Diagnostic controls for reference documentation',
+})
+
+export type ReferenceDiagnostics = S.Schema.Type<typeof ReferenceDiagnostics>
+
+// ============================================================================
+// Schema - Descriptions View
+// ============================================================================
+
+/**
+ * Configuration for how descriptions are displayed in reference documentation.
+ */
+export const DescriptionsView = S.Struct({
+  /**
+   * Default view mode for descriptions.
+   * - 'expanded': Show full descriptions (default)
+   * - 'compact': Show condensed view
+   *
+   * @default 'expanded'
+   */
+  defaultMode: S.optional(S.Literal('compact', 'expanded')),
+
+  /**
+   * Whether to show the view mode toggle control.
+   * Allows users to switch between compact and expanded views.
+   *
+   * @default true
+   */
+  showControl: S.optional(S.Boolean),
+}).annotations({
+  identifier: 'DescriptionsView',
+  description: 'Configuration for descriptions display in reference documentation',
+})
+
+export type DescriptionsView = S.Schema.Type<typeof DescriptionsView>
+
+// ============================================================================
+// Schema - Reference Config
+// ============================================================================
+
+export const ReferenceConfigObject = S.Struct({
+  /**
+   * Control whether the reference documentation is enabled.
+   * - true: Always enabled (show in nav even if no schema exists)
+   * - false: Always disabled (hide even if schema exists)
+   * - undefined: Auto-detect based on schema presence (default behavior)
+   *
+   * @default undefined (auto-detect based on schema presence)
+   * @example
+   * // Always show reference section
+   * reference: { enabled: true }
+   *
+   * @example
+   * // Never show reference
+   * reference: { enabled: false }
+   *
+   * @example
+   * // Auto-detect based on schema (default)
+   * reference: { }
+   */
+  enabled: S.optional(S.Boolean),
+
+  /**
+   * Configuration for how descriptions are displayed.
+   *
+   * @example
+   * // Use compact mode by default
+   * descriptionsView: {
+   *   defaultMode: 'compact'
+   * }
+   *
+   * @example
+   * // Hide the view mode toggle
+   * descriptionsView: {
+   *   showControl: false
+   * }
+   */
+  descriptionsView: S.optional(DescriptionsView),
+
+  /**
+   * Configuration for how field nullability is rendered.
+   * - 'bangMark': Show '!' after non-nullable types (GraphQL style)
+   * - 'questionMark': Show '?' after nullable field names (TypeScript style)
+   *
+   * @default 'bangMark'
+   * @example
+   * // Use TypeScript-style nullability rendering
+   * nullabilityRendering: 'questionMark'
+   */
+  nullabilityRendering: S.optional(S.Literal('questionMark', 'bangMark')),
+
+  /**
+   * Diagnostic controls for reference documentation.
+   *
+   * @example
+   * // Enable all diagnostics with defaults
+   * diagnostics: {
+   *   validation: true
+   * }
+   *
+   * @example
+   * // Fine-grained control
+   * diagnostics: {
+   *   validation: {
+   *     enabled: true,
+   *     dev: { severity: 'error' },
+   *     build: { severity: 'warning' }
+   *   }
+   * }
+   */
+  diagnostics: S.optional(ReferenceDiagnostics),
+}).annotations({
+  identifier: 'ReferenceConfigObject',
+  title: 'Reference Configuration',
+  description: 'Configuration for reference documentation feature',
+})
+
+export type ReferenceConfigObject = S.Schema.Type<typeof ReferenceConfigObject>
+
+/**
+ * Reference configuration with boolean shorthand support.
+ * - true: Enable with defaults
+ * - false: Disable completely
+ * - object: Fine-grained control
+ */
+export const ReferenceConfig = S.transform(
+  S.Union(
+    S.Boolean,
+    ReferenceConfigObject,
+  ),
+  ReferenceConfigObject,
+  {
+    strict: false,
+    decode: (input) => {
+      if (typeof input === 'boolean') {
+        return {
+          enabled: input,
+          descriptionsView: {},
+          nullabilityRendering: undefined,
+          diagnostics: {},
+        }
+      }
+      return input
+    },
+    encode: (config) => config,
+  },
+).annotations({
+  identifier: 'ReferenceConfig',
+  title: 'Reference Configuration',
+  description: 'Reference documentation configuration with boolean shortcuts',
+})
+
+export type ReferenceConfig = S.Schema.Type<typeof ReferenceConfig>
+
+// ============================================================================
+// Constructors
+// ============================================================================
+
+export const make = ReferenceConfigObject.make
+
+// ============================================================================
+// Type Guards
+// ============================================================================
+
+export const is = S.is(ReferenceConfig)
+
+// ============================================================================
+// Codecs
+// ============================================================================
+
+export const decode = S.decode(ReferenceConfig)
+export const decodeSync = S.decodeSync(ReferenceConfig)
+export const encode = S.encode(ReferenceConfig)
+export const encodeSync = S.encodeSync(ReferenceConfig)

package/src/api/reference/scanner.ts

@@ -0,0 +1,53 @@
+import { Diagnostic } from '#lib/diagnostic/$'
+import { FileSystem } from '@effect/platform'
+import { Effect } from 'effect'
+import * as Path from 'node:path'
+import * as Catalog from './catalog.js'
+
+export interface ScanOptions {
+  /**
+   * The directory to scan for reference content
+   */
+  dir: string
+}
+
+export interface ScanResult {
+  /**
+   * The reference catalog with index metadata
+   */
+  catalog: Catalog.Catalog
+  /**
+   * Any diagnostics generated during scanning
+   */
+  diagnostics: Diagnostic.Diagnostic[]
+}
+
+/**
+ * Scan for reference documentation content.
+ * Currently looks for index.md or index.mdx files for custom landing pages.
+ */
+export const scan = (
+  options: ScanOptions,
+): Effect.Effect<ScanResult, Error, FileSystem.FileSystem> =>
+  Effect.gen(function*() {
+    const fs = yield* FileSystem.FileSystem
+
+    const diagnostics: Diagnostic.Diagnostic[] = []
+
+    // Check for index.md or index.mdx file
+    const indexMdPath = Path.join(options.dir, 'reference', 'index.md')
+    const indexMdxPath = Path.join(options.dir, 'reference', 'index.mdx')
+
+    // Try index.md first, then index.mdx
+    const indexPath = (yield* fs.exists(indexMdPath))
+      ? indexMdPath
+      : (yield* fs.exists(indexMdxPath))
+      ? indexMdxPath
+      : null
+
+    const catalog = Catalog.make({
+      index: indexPath ? { path: indexPath } : undefined,
+    })
+
+    return { catalog, diagnostics }
+  })

package/src/lib/grafaid/schema/format-default-value.ts

@@ -0,0 +1,22 @@
+import { astFromValue, print } from 'graphql'
+import type { GraphQLInputType } from 'graphql'
+
+/**
+ * Formats a GraphQL default value into a string representation.
+ * Returns just the value part (e.g., "20", "true", '"hello"')
+ *
+ * @param value - The default value from a GraphQL argument or input field
+ * @param type - The GraphQL input type of the field
+ * @returns The formatted value string, or null if value is undefined
+ */
+export const formatDefaultValue = (value: unknown, type: GraphQLInputType): string | null => {
+  if (value === undefined) return null
+
+  const ast = astFromValue(value, type)
+  if (!ast) {
+    // Fallback for edge cases where astFromValue fails
+    return JSON.stringify(value)
+  }
+
+  return print(ast)
+}

package/src/lib/grafaid/schema/schema.ts

@@ -51,6 +51,8 @@ export * as NodesLike from './nodes-like.js'
 
 export * from './read.js'
 
+export * from './format-default-value.js'
+
 import * as AST from './ast.js'
 
 export const empty: GraphQLSchema = buildASTSchema(AST.empty)

package/src/template/components/ArgumentAnnotation.tsx

@@ -1,24 +1,73 @@
-import { Box, Flex, Text } from '@radix-ui/themes'
+import { Grafaid } from '#lib/grafaid'
+import { Box, Flex, HoverCard, Text } from '@radix-ui/themes'
 import type { GraphQLArgument } from 'graphql'
 import type { FC } from 'react'
+import { useViewMode } from '../contexts/ViewModeContext.js'
+import { Description } from './Description.js'
 import { TypeAnnotation } from './TypeAnnotation.js'
 
 export interface Props {
   data: GraphQLArgument
+  nameWidth?: number
 }
 
 /**
- * Renders a single GraphQL argument in SDL syntax
+ * Renders a single GraphQL argument with aligned columns
  */
-export const ArgumentAnnotation: FC<Props> = ({ data }) => {
-  return (
-    <Box as='div'>
-      <Flex>
-        <Text>{data.name}</Text>
-        <Text>:&nbsp;</Text>
+export const ArgumentAnnotation: FC<Props> = ({ data, nameWidth }) => {
+  const { viewMode } = useViewMode()
+
+  const nameElement = (
+    <Text size='2' weight='bold' color='gray'>
+      {data.name}
+    </Text>
+  )
 
-        <TypeAnnotation type={data.type} />
+  return (
+    <Box>
+      <Flex align='baseline' gap='2'>
+        <Box
+          style={{
+            minWidth: nameWidth ? `${nameWidth}ch` : 'auto',
+            flexShrink: 0,
+          }}
+        >
+          {viewMode === 'compact' && data.description
+            ? (
+              <HoverCard.Root>
+                <HoverCard.Trigger>
+                  {nameElement}
+                </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>
+            )
+            : nameElement}
+        </Box>
+        <TypeAnnotation type={data.type} showDescription={true} />
+        {data.defaultValue !== undefined && (
+          <Text size='2' color='gray'>
+            {' = '}
+            {Grafaid.Schema.formatDefaultValue(data.defaultValue, data.type)}
+          </Text>
+        )}
       </Flex>
+      {/* Argument description below name/type (only in expanded mode) */}
+      {data.description && viewMode === 'expanded' && (
+        <Box mt='2'>
+          <Text size='2' color='gray' style={{ lineHeight: '1.5' }}>
+            <Description data={data} />
+          </Text>
+        </Box>
+      )}
     </Box>
   )
 }