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

package/src/template/routes/reference.tsx

@@ -7,20 +7,28 @@ import { Lifecycles } from '#lib/lifecycles/$'
 import { route, useLoaderData } from '#lib/react-router-effect/react-router-effect'
 import { Schema } from '#lib/schema/$'
 import { Version } from '#lib/version/$'
+import { SegmentedControl, Text } from '@radix-ui/themes'
 import { Flex } from '@radix-ui/themes'
+import { Str } from '@wollybeard/kit'
 import { neverCase } from '@wollybeard/kit/language'
 import { HashMap, Option } from 'effect'
 import { Effect, Match } from 'effect'
 import React from 'react'
-import { useParams } from 'react-router'
+import { redirect, useParams } from 'react-router'
+import { templateConfig } from 'virtual:polen/project/config'
+import { IndexComponent } from 'virtual:polen/project/reference'
 import { schemasCatalog } from 'virtual:polen/project/schemas'
 import { Field } from '../components/Field.js'
 import { TypeKindIcon } from '../components/graphql/graphql.js'
 import { MissingSchema } from '../components/MissingSchema.js'
 import { NamedType } from '../components/NamedType.js'
 import { ReferenceVersionPicker } from '../components/ReferenceVersionPicker.js'
+import { ViewModeToggle } from '../components/ViewModeToggle.js'
 import { GraphqlLifecycleProvider } from '../contexts/GraphqlLifecycleContext.js'
+import { ReferenceConfigProvider } from '../contexts/ReferenceConfigContext.js'
+import { ViewModeProvider } from '../contexts/ViewModeContext.js'
 import { SidebarLayout } from '../layouts/index.js'
+import { MdxProvider } from '../providers/mdx.js'
 
 const routeSchema = S.Struct({
   catalog: Catalog.Catalog,
@@ -28,6 +36,17 @@ const routeSchema = S.Struct({
 })
 
 const referenceLoader = ({ params }: any) => {
+  // Check if reference is enabled
+  if (!templateConfig.reference.enabled) {
+    throw new Response('Reference documentation is disabled', { status: 404 })
+  }
+
+  // Check if no type is selected (index route) and no custom index exists
+  if (!params.type && !params.version && !IndexComponent) {
+    // Redirect to Query type which is guaranteed to exist
+    throw redirect('/reference/Query')
+  }
+
   // This should never be called when schemasCatalog is null
   // because the route won't be added to the router
   // But we return an Effect.fail for safety
@@ -97,7 +116,7 @@ const ReferenceView = () => {
   for (const [title, types] of kindEntries) {
     sidebarItems.push({
       type: `ItemSection` as const,
-      title,
+      title: Str.Case.title(Str.Case.snake(title)),
       pathExp: `reference-${title.toLowerCase()}`,
       isLinkToo: false,
       links: types.map(type => {
@@ -130,7 +149,16 @@ const ReferenceView = () => {
 
   const content: React.ReactNode = (() => {
     if (viewType === 'index') {
-      return <div>Select a type from the sidebar to view its documentation.</div>
+      // Render custom index component if available
+      if (IndexComponent) {
+        return (
+          <MdxProvider schema={schema.definition}>
+            <IndexComponent />
+          </MdxProvider>
+        )
+      }
+      // Fallback message (shouldn't reach here due to redirect)
+      return <Text>Select a type from the sidebar to view its documentation.</Text>
     } else if (viewType === 'type-missing' || viewType === 'field-missing') {
       return <MissingSchema />
     } else if (viewType === 'type') {
@@ -151,26 +179,42 @@ const ReferenceView = () => {
     }
   })()
 
+  const referenceConfig = {
+    descriptionsView: templateConfig.reference.descriptionsView,
+    nullabilityRendering: templateConfig.reference.nullabilityRendering,
+  }
+
   return (
-    <GraphqlLifecycleProvider lifecycle={lifecycle} schema={schema}>
-      <SidebarLayout
-        sidebar={sidebarItems}
-        basePath={basePath}
-        topContent={(() => {
-          const version = Schema.getVersion(schema)
-          return catalog._tag === 'CatalogVersioned' && version
-            ? (
-              <ReferenceVersionPicker
-                data={Catalog.Versioned.getVersions(catalog)}
-                current={version}
-              />
-            )
-            : null
-        })()}
-      >
-        {content}
-      </SidebarLayout>
-    </GraphqlLifecycleProvider>
+    <ReferenceConfigProvider config={referenceConfig}>
+      <ViewModeProvider defaultMode={referenceConfig.descriptionsView.defaultMode}>
+        <GraphqlLifecycleProvider lifecycle={lifecycle} schema={schema}>
+          <SidebarLayout
+            sidebar={sidebarItems}
+            basePath={basePath}
+            topContent={(() => {
+              const version = Schema.getVersion(schema)
+              const versionPicker = catalog._tag === 'CatalogVersioned' && version
+                ? (
+                  <ReferenceVersionPicker
+                    data={Catalog.Versioned.getVersions(catalog)}
+                    current={version}
+                  />
+                )
+                : null
+
+              return (
+                <Flex gap='3' align='center'>
+                  {versionPicker}
+                  {referenceConfig.descriptionsView.showControl && <ViewModeToggle />}
+                </Flex>
+              )
+            })()}
+          >
+            {content}
+          </SidebarLayout>
+        </GraphqlLifecycleProvider>
+      </ViewModeProvider>
+    </ReferenceConfigProvider>
   )
 }
 
@@ -207,7 +251,7 @@ const typeAndFieldRoutes = [
  * - Single ReferenceView component handles all variations
  */
 
-export const reference = !schemasCatalog
+export const reference = !schemasCatalog || !templateConfig.reference.enabled
   ? null
   : route({
     path: `reference`,

package/src/types/virtual-modules.d.ts

@@ -35,6 +35,11 @@ declare module 'virtual:polen/project/examples' {
   export const IndexComponent: React.ComponentType | null
 }
 
+declare module 'virtual:polen/project/reference' {
+  export const referenceCatalog: import('#api/reference/catalog').Catalog
+  export const IndexComponent: React.ComponentType | null
+}
+
 declare module 'virtual:polen/project/config' {
   export const templateConfig: import('#api/config-template/template').TemplateConfig
 }

package/src/vite/plugins/core.ts

@@ -10,6 +10,7 @@ import { Examples } from './examples.js'
 import { Hooks, viProjectHooks } from './hooks.js'
 import { Navbar, viProjectNavbar } from './navbar.js'
 import { Pages, viProjectRoutes } from './pages.js'
+import { Reference, viProjectReference } from './reference.js'
 import { Schemas, viProjectSchema } from './schemas.js'
 
 export interface ProjectRoutesModule {
@@ -44,6 +45,10 @@ export const Core = (config: Api.Config.Config): Vite.PluginOption[] => {
     schemaReader: schemasArea.reader,
     dependentVirtualModules: [viProjectConfig, viProjectNavbar],
   })
+  const referenceArea = Reference({
+    config,
+    dependentVirtualModules: [viProjectConfig, viProjectNavbar],
+  })
   const configPlugin = ConfigPlugin({
     config,
     schemaReader: schemasArea.reader,
@@ -62,6 +67,7 @@ export const Core = (config: Api.Config.Config): Vite.PluginOption[] => {
     ...conditionalPlugins,
     ...examplesArea.plugins,
     ...schemasArea.plugins,
+    ...referenceArea.plugins,
     ...pagesArea.plugins,
     configPlugin,
     navbarPlugin,

package/src/vite/plugins/examples.ts

@@ -121,6 +121,8 @@ export const Examples = ({
             || file.endsWith('.gql')
             || file.endsWith('index.md')
             || file.endsWith('index.mdx')
+            || (file.endsWith('.md') && !file.endsWith('index.md'))
+            || (file.endsWith('.mdx') && !file.endsWith('index.mdx'))
           )
         },
       },
@@ -179,6 +181,16 @@ export const Examples = ({
               s`export const IndexComponent = null`
             }
 
+            // Export description components for each example
+            for (const example of scanExamplesResult.catalog.examples) {
+              if (example.description?.path) {
+                s``
+                s`export { default as DescriptionComponent_${
+                  example.name.replace(/-/g, '_')
+                } } from '${example.description.path}'`
+              }
+            }
+
             // Encode the catalog to ensure HashMap and other Effect types are properly serialized
             const encodedCatalog = Catalog.encodeSync(catalogWithIndex)
 

package/src/vite/plugins/index.ts

@@ -4,5 +4,6 @@ export { Core } from './core.js'
 export { Examples } from './examples.js'
 export { Main } from './main.js'
 export { Pages } from './pages.js'
+export { Reference } from './reference.js'
 export { Schemas } from './schemas.js'
 export { Serve } from './serve.js'

package/src/vite/plugins/navbar.ts

@@ -46,7 +46,10 @@ export const Navbar = ({
             >,
           )
 
-          if (loadedSchemaCatalog?.data) {
+          // Check if reference is enabled (explicitly or auto-detected via schema presence)
+          const referenceEnabled = config.reference.enabled ?? Boolean(loadedSchemaCatalog?.data)
+
+          if (referenceEnabled && loadedSchemaCatalog?.data) {
             // IMPORTANT: Always ensure paths start with '/' for React Router compatibility.
             // Without the leading slash, React Router treats paths as relative, which causes
             // hydration mismatches between SSR (where base path is prepended) and client

package/src/vite/plugins/reference.ts

@@ -0,0 +1,130 @@
+import type { Api } from '#api/$'
+import * as ReferenceModule from '#api/reference/$'
+import * as Catalog from '#api/reference/catalog'
+import { Diagnostic } from '#lib/diagnostic/$'
+import { ViteReactive } from '#lib/vite-reactive/$'
+import { type AssetReader, createAssetReader } from '#lib/vite-reactive/reactive-asset-plugin'
+import { ViteVirtual } from '#lib/vite-virtual'
+import { debugPolen } from '#singletons/debug'
+import { FileSystem } from '@effect/platform'
+import * as NodeFileSystem from '@effect/platform-node/NodeFileSystem'
+import { Str } from '@wollybeard/kit'
+import { Effect } from 'effect'
+import type * as Vite from 'vite'
+import { polenVirtual } from '../vi.js'
+
+// Virtual modules provided by this plugin
+export const viProjectReference = polenVirtual([`project`, `reference`])
+
+export interface Options {
+  config: Api.Config.Config
+  dependentVirtualModules?: ViteVirtual.Identifier.Identifier[]
+}
+
+/**
+ * Reference plugin for handling reference documentation
+ */
+export const Reference = ({
+  config,
+  dependentVirtualModules = [],
+}: Options): {
+  plugins: Vite.Plugin[]
+  reader: AssetReader<ReferenceModule.ScanResult, Error, FileSystem.FileSystem>
+} => {
+  const debug = debugPolen.sub(`vite-reference`)
+
+  const reader = createAssetReader<ReferenceModule.ScanResult, Error, FileSystem.FileSystem>(() => {
+    return ReferenceModule.scan({
+      dir: config.paths.project.rootDir,
+    })
+  })
+
+  const scanReference = async () => {
+    return await Effect.runPromise(
+      reader.read().pipe(Effect.provide(NodeFileSystem.layer)),
+    )
+  }
+
+  // Map diagnostic to its control configuration
+  const getControlForDiagnostic = (diagnostic: any) => {
+    return config.reference.diagnostics?.validation
+  }
+
+  // Report diagnostics
+  const reportDiagnostics = (
+    diagnostics: any[],
+    phase: 'dev' | 'build' = 'dev',
+  ) => {
+    Diagnostic.filterAndReport(diagnostics, getControlForDiagnostic, phase)
+  }
+
+  // Check if a file is the reference index file
+  const isReferenceIndexFile = (file: string): boolean => {
+    return file.endsWith('/reference/index.md') || file.endsWith('/reference/index.mdx')
+  }
+
+  const plugins: Vite.Plugin[] = [
+    ViteReactive.ReactiveAssetPlugin<ReferenceModule.ScanResult, Error, FileSystem.FileSystem>({
+      name: 'polen:reference-reactive',
+      reader,
+      filePatterns: {
+        watch: ['reference'],
+        isRelevant: (file: string) => {
+          return isReferenceIndexFile(file)
+        },
+      },
+      dependentVirtualModules: [viProjectReference, ...dependentVirtualModules],
+      hooks: {
+        async shouldFullReload() {
+          // Trigger full reload for reference changes
+          return true
+        },
+        async onDiagnostics(data: any) {
+          // Report diagnostics with DiagnosticControl filtering
+          reportDiagnostics(data.diagnostics, 'dev')
+        },
+      },
+    }),
+    {
+      name: 'polen:reference-virtual',
+      ...ViteVirtual.IdentifiedLoader.toHooks(
+        {
+          identifier: viProjectReference,
+          async loader() {
+            debug(`Loading viProjectReference virtual module`)
+
+            const scanReferenceResult = await scanReference()
+
+            reportDiagnostics(scanReferenceResult.diagnostics, 'dev')
+
+            // Generate the module code with both catalog and component exports
+            const s = Str.Builder()
+            s`import { Effect } from 'effect'`
+            s`import * as Catalog from '#api/reference/catalog'`
+
+            const indexFilePath = scanReferenceResult.catalog.index?.path
+            if (indexFilePath) {
+              s``
+              s`export { default as IndexComponent } from '${indexFilePath}'`
+            } else {
+              s``
+              s`export const IndexComponent = null`
+            }
+
+            // Encode the catalog to ensure proper serialization
+            const encodedCatalog = Catalog.encodeSync(scanReferenceResult.catalog)
+
+            s``
+            s`const catalogData = ${JSON.stringify(encodedCatalog)}`
+            s``
+            s`export const referenceCatalog = Catalog.decodeSync(catalogData)`
+
+            return s.render()
+          },
+        },
+      ),
+    },
+  ]
+
+  return { plugins, reader }
+}

package/build/template/components/ArgumentList.d.ts

@@ -1,6 +0,0 @@
-import type { React } from '#dep/react/index';
-import type { GraphQLArgument } from 'graphql';
-export declare const ArgumentsList: React.FC<{
-    args: readonly GraphQLArgument[];
-}>;
-//# sourceMappingURL=ArgumentList.d.ts.map

package/build/template/components/ArgumentList.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"ArgumentList.d.ts","sourceRoot":"","sources":["../../../src/template/components/ArgumentList.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,SAAS,CAAA;AAG9C,eAAO,MAAM,aAAa,EAAE,KAAK,CAAC,EAAE,CAAC;IAAE,IAAI,EAAE,SAAS,eAAe,EAAE,CAAA;CAAE,CAgBxE,CAAA"}

package/build/template/components/ArgumentList.js

@@ -1,9 +0,0 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Box, Flex, Heading, Text } from '@radix-ui/themes';
-import { TypeAnnotation } from './TypeAnnotation.js';
-export const ArgumentsList = ({ args }) => {
-    if (args.length === 0)
-        return null;
-    return (_jsxs(Flex, { direction: 'column', children: [_jsx(Heading, { size: '1', weight: 'bold', children: "Arguments" }), args.map(arg => (_jsxs(Box, { children: [_jsx(Text, { children: arg.name }), _jsx(Text, { children: ":" }), _jsx(TypeAnnotation, { type: arg.type }), arg.description && _jsx(Text, { as: 'p', size: '2', color: 'gray', children: arg.description })] }, arg.name)))] }));
-};
-//# sourceMappingURL=ArgumentList.js.map

package/build/template/components/ArgumentList.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"ArgumentList.js","sourceRoot":"","sources":["../../../src/template/components/ArgumentList.tsx"],"names":[],"mappings":";AACA,OAAO,EAAE,GAAG,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,kBAAkB,CAAA;AAE3D,OAAO,EAAE,cAAc,EAAE,MAAM,qBAAqB,CAAA;AAEpD,MAAM,CAAC,MAAM,aAAa,GAAmD,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE;IACxF,IAAI,IAAI,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO,IAAI,CAAA;IAElC,OAAO,CACL,MAAC,IAAI,IAAC,SAAS,EAAC,QAAQ,aACtB,KAAC,OAAO,IAAC,IAAI,EAAC,GAAG,EAAC,MAAM,EAAC,MAAM,0BAAoB,EAClD,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,CACf,MAAC,GAAG,eACF,KAAC,IAAI,cAAE,GAAG,CAAC,IAAI,GAAQ,EACvB,KAAC,IAAI,oBAAS,EACd,KAAC,cAAc,IAAC,IAAI,EAAE,GAAG,CAAC,IAAI,GAAI,EACjC,GAAG,CAAC,WAAW,IAAI,KAAC,IAAI,IAAC,EAAE,EAAC,GAAG,EAAC,IAAI,EAAC,GAAG,EAAC,KAAK,EAAC,MAAM,YAAE,GAAG,CAAC,WAAW,GAAQ,KAJvE,GAAG,CAAC,IAAI,CAKZ,CACP,CAAC,IACG,CACR,CAAA;AACH,CAAC,CAAA"}

package/src/template/components/ArgumentList.tsx

@@ -1,22 +0,0 @@
-import type { React } from '#dep/react/index'
-import { Box, Flex, Heading, Text } from '@radix-ui/themes'
-import type { GraphQLArgument } from 'graphql'
-import { TypeAnnotation } from './TypeAnnotation.js'
-
-export const ArgumentsList: React.FC<{ args: readonly GraphQLArgument[] }> = ({ args }) => {
-  if (args.length === 0) return null
-
-  return (
-    <Flex direction='column'>
-      <Heading size='1' weight='bold'>Arguments</Heading>
-      {args.map(arg => (
-        <Box key={arg.name}>
-          <Text>{arg.name}</Text>
-          <Text>:</Text>
-          <TypeAnnotation type={arg.type} />
-          {arg.description && <Text as='p' size='2' color='gray'>{arg.description}</Text>}
-        </Box>
-      ))}
-    </Flex>
-  )
-}