polen 0.11.0-next.10 → 0.11.0-next.12

package/src/api/schema/schema.ts

@@ -1,10 +1,13 @@
 import type { GraphqlChangeset } from '#lib/graphql-changeset/index'
 
-export * as DataSources from './data-sources/data-sources.js'
-
-export * from './read.js'
+// Re-export everything from isomorphic layer
+export * from '../iso/schema/constants.js'
+export * as Routing from '../iso/schema/routing.js'
 
+// Server-only exports
+export * as DataSources from './data-sources/data-sources.js'
 export * from './metadata.js'
+export * from './read.js'
 
 export type ChangeSets = GraphqlChangeset.ChangeSet[]
 
@@ -17,53 +20,3 @@ export interface ChangelogData {
   changes: GraphqlChangeset.ChangeSet['changes']
   date: string
 }
-
-/**
- * Constants for schema versioning
- */
-
-/**
- * The version identifier for the latest schema
- */
-export const VERSION_LATEST = `latest`
-
-/**
- * Fallback version name when date parsing fails
- */
-export const VERSION_UNKNOWN_FALLBACK = `unknown`
-
-/**
- * Convert a date to a version string in YYYY-MM-DD format
- */
-export const dateToVersionString = (date: Date): string => {
-  return date.toLocaleDateString('en-CA')
-}
-
-/**
- * Determine if a version at the given index should have a changelog file.
- * Only non-oldest versions get changelog files.
- */
-export const shouldVersionHaveChangelog = (versionIndex: number, totalVersions: number): boolean => {
-  return versionIndex < totalVersions - 1
-}
-
-/**
- * Convert a version string back to a Date
- */
-export const versionStringToDate = (version: string): Date => {
-  if (version === VERSION_LATEST) {
-    return new Date()
-  }
-
-  // Use modern date parsing - the version string should be in YYYY-MM-DD format
-  // which is ISO 8601 compatible
-  const parsedDate = new Date(version + 'T00:00:00Z')
-
-  // Check if the date is valid
-  if (!isNaN(parsedDate.getTime())) {
-    return parsedDate
-  }
-
-  // Throw error for invalid dates instead of silently defaulting
-  throw new Error(`Invalid version string: ${version}`)
-}

package/src/api/vite/plugins/core.ts

@@ -1,22 +1,18 @@
 import type { Config } from '#api/config/index'
 import { Content } from '#api/content/$'
 import { createNavbar } from '#api/content/navbar'
+import { Api } from '#api/index'
 import { VitePluginSelfContainedMode } from '#cli/_/self-contained-mode'
-import { Hono } from '#dep/hono/index'
 import type { ReactRouter } from '#dep/react-router/index'
 import type { Vite } from '#dep/vite/index'
 import { VitePluginJson } from '#lib/vite-plugin-json/index'
 import { ViteVirtual } from '#lib/vite-virtual/index'
 import { debugPolen } from '#singletons/debug'
 import { superjson } from '#singletons/superjson'
-import * as HonoNodeServer from '@hono/node-server'
-import { serveStatic } from '@hono/node-server/serve-static'
 import { Json, Str } from '@wollybeard/kit'
-import * as NodePath from 'node:path'
 import type { ProjectData } from '../../../project-data.js'
 import { SchemaAugmentation } from '../../schema-augmentation/index.js'
 import { Schema } from '../../schema/index.js'
-import { createLogger } from '../logger.js'
 import { polenVirtual } from '../vi.js'
 import { Pages } from './pages.js'
 import { SchemaAssets } from './schema-assets.js'
@@ -201,7 +197,8 @@ export const Core = (config: Config.Config): Vite.PluginOption[] => {
               // Without the leading slash, React Router treats paths as relative, which causes
               // hydration mismatches between SSR (where base path is prepended) and client
               // (where basename is configured). This ensures consistent behavior.
-              navbar.push({ pathExp: `/reference`, title: `Reference` })
+              const referencePath = Api.Schema.Routing.createReferenceBasePath()
+              navbar.push({ pathExp: referencePath, title: `Reference` })
               if (schemaResult.data.length > 1) {
                 navbar.push({ pathExp: `/changelog`, title: `Changelog` })
               }

package/src/template/components/ArgumentList.tsx

@@ -1,13 +1,9 @@
+import type { React } from '#dep/react/index'
 import { Box, Flex, Heading, Text } from '@radix-ui/themes'
 import type { GraphQLArgument } from 'graphql'
-import type { FC } from 'react'
 import { TypeAnnotation } from './TypeAnnotation.js'
 
-export interface Props {
-  args: readonly GraphQLArgument[]
-}
-
-export const ArgumentsList: FC<Props> = ({ args }) => {
+export const ArgumentsList: React.FC<{ args: readonly GraphQLArgument[] }> = ({ args }) => {
   if (args.length === 0) return null
 
   return (

package/src/template/components/Changelog.tsx

@@ -61,11 +61,11 @@ const Changeset: React.FC<{ changeset: GraphqlChangeset.ChangeSet }> = ({ change
       </h1>
       {groupedChanges.map(group => (
         <CriticalitySection key={group.level} level={group.level} changes={group.changes}>
-          {group.changes.map(change => {
+          {group.changes.map((change, index) => {
             const type = GraphqlChange.Group.getType(change)
             return (
               <ComponentDispatch
-                key={`${change.type}-${change.path || change.message}`}
+                key={`${change.type}-${change.path || change.message}-${index}`}
                 components={Group}
                 name={type}
                 props={{ change }}

package/src/template/components/DeprecationReason.tsx

@@ -1,9 +1,9 @@
+import type { React } from '#dep/react/index'
 import type { GrafaidOld } from '#lib/grafaid-old/index'
 import { Text } from '@radix-ui/themes'
-import type { FC } from 'react'
 import { Markdown } from './Markdown.js'
 
-export const DeprecationReason: FC<{ data: GrafaidOld.GraphQLField }> = ({ data }) => {
+export const DeprecationReason: React.FC<{ data: GrafaidOld.GraphQLField }> = ({ data }) => {
   if (!data.deprecationReason) return null
 
   return (

package/src/template/components/Description.tsx

@@ -1,11 +1,11 @@
+import type { React } from '#dep/react/index'
 import { Text } from '@radix-ui/themes'
-import type { FC } from 'react'
 import { Markdown } from './Markdown.js'
 // import type { Grafaid } from '#lib/grafaid'
 import type { GrafaidOld } from '#lib/grafaid-old/index'
 import type { GraphQLNamedType } from 'graphql'
 
-export const Description: FC<{ data: GraphQLNamedType | GrafaidOld.GraphQLField }> = ({ data }) => {
+export const Description: React.FC<{ data: GraphQLNamedType | GrafaidOld.GraphQLField }> = ({ data }) => {
   if (!data.description) return null
 
   return (

package/src/template/components/Field.tsx

@@ -1,17 +1,13 @@
+import type { React } from '#dep/react/index'
 import { GrafaidOld } from '#lib/grafaid-old/index'
 import type { BoxProps } from '@radix-ui/themes'
 import { Box, Text } from '@radix-ui/themes'
-import type { FC } from 'react'
 import { ArgumentListAnnotation } from './ArgumentListAnnotation.js'
 import { DeprecationReason } from './DeprecationReason.js'
 import { Description } from './Description.js'
 import { TypeAnnotation } from './TypeAnnotation.js'
 
-export type Props = BoxProps & {
-  data: GrafaidOld.GraphQLField
-}
-
-export const Field: FC<Props> = ({ data, ...boxProps }) => {
+export const Field: React.FC<BoxProps & { data: GrafaidOld.GraphQLField }> = ({ data, ...boxProps }) => {
   const argumentList = GrafaidOld.isOutputField(data)
     ? <ArgumentListAnnotation field={data} />
     : null

package/src/template/components/FieldListSection.tsx

@@ -1,14 +1,10 @@
+import type { React } from '#dep/react/index'
 import { Grafaid } from '#lib/grafaid/index'
 import { Box, Heading } from '@radix-ui/themes'
 import type { GraphQLNamedType } from 'graphql'
-import type { FC } from 'react'
 import { FieldList } from './FieldList.js'
 
-export interface Props {
-  data: GraphQLNamedType
-}
-
-export const FieldListSection: FC<Props> = ({ data }) => {
+export const FieldListSection: React.FC<{ data: GraphQLNamedType }> = ({ data }) => {
   if (!Grafaid.Schema.TypesLike.isFielded(data)) return null
 
   const fields = Grafaid.Schema.NodesLike.getFields(data)

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

@@ -5,6 +5,7 @@
  * analysis to create unified tokens for interactive code blocks.
  */
 
+import { Api } from '#api/iso'
 import type { CodeAnnotation } from 'codehike/code'
 import {
   getNamedType,
@@ -14,7 +15,6 @@ import {
   GraphQLInputObjectType,
   GraphQLInterfaceType,
   GraphQLObjectType,
-  type GraphQLOutputType,
   GraphQLScalarType,
   type GraphQLSchema,
   GraphQLUnionType,
@@ -24,12 +24,7 @@ import {
 import graphqlWasmUrl from 'tree-sitter-graphql-grammar-wasm/grammar.wasm?url'
 import * as WebTreeSitter from 'web-tree-sitter'
 import treeSitterWasmUrl from 'web-tree-sitter/tree-sitter.wasm?url'
-import {
-  isKeywordNodeType,
-  isLiteralNodeType,
-  isPunctuationNodeType,
-  type TreeSitterGraphQLNodeType,
-} from './graphql-node-types.js'
+import { isKeywordNodeType, isPunctuationNodeType, type TreeSitterGraphQLNodeType } from './graphql-node-types.js'
 import type { SemanticNode } from './semantic-nodes.js'
 import {
   isArgument,
@@ -263,42 +258,63 @@ class UnifiedToken implements GraphQLToken {
 
     // Arguments - use #<field>__<argument> pattern
     if (isArgument(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.parentField.name}__${this.semantic.argumentDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.parentField.name}__${this.semantic.argumentDef.name}`
     }
 
     // Output fields - use hash links since field routes aren't connected yet
     if (isOutputField(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.fieldDef.name}`
     }
 
     // Input fields - use hash links since field routes aren't connected yet
     if (isInputField(this.semantic)) {
-      return `/reference/${this.semantic.parentType.name}#${this.semantic.fieldDef.name}`
+      const basePath = Api.Schema.Routing.createReferencePath({
+        type: this.semantic.parentType.name,
+      })
+      return `${basePath}#${this.semantic.fieldDef.name}`
     }
 
     // Type references - use :type pattern
     if (this.semantic instanceof GraphQLObjectType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLScalarType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLInterfaceType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLUnionType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLEnumType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     if (this.semantic instanceof GraphQLInputObjectType) {
-      return `/reference/${this.semantic.name}`
+      return Api.Schema.Routing.createReferencePath({
+        type: this.semantic.name,
+      })
     }
 
     return null

package/src/template/components/HamburgerMenu.tsx

@@ -9,6 +9,7 @@ export interface HamburgerMenuProps {
   onToggle: () => void
   onClose: () => void
   sidebarData: Content.Item[]
+  basePath?: string
 }
 
 export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
@@ -16,6 +17,7 @@ export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
   onToggle,
   onClose,
   sidebarData,
+  basePath,
 }) => {
   // Prevent body scroll when mobile menu is open
   useEffect(() => {
@@ -87,7 +89,7 @@ export const HamburgerMenu: React.FC<HamburgerMenuProps> = ({
                 <Cross2Icon width='18' height='18' />
               </IconButton>
             </Flex>
-            <Sidebar data={sidebarData} />
+            <Sidebar data={sidebarData} basePath={basePath} />
           </Box>
         </>
       )}

package/src/template/components/MissingSchema.tsx

@@ -1,3 +1,5 @@
-export const MissingSchema = () => {
+import type { React } from '#dep/react/index'
+
+export const MissingSchema: React.FC = () => {
   return <div>No content to show. There is no schema to work with.</div>
 }

package/src/template/components/ReferenceLink.tsx

@@ -1,16 +1,8 @@
-import type { ReactNode } from 'react'
+import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
 import { useVersionPath } from '../hooks/useVersionPath.js'
 import { Link } from './Link.js'
 
-interface Props {
-  /** The GraphQL type name */
-  type: string
-  /** Optional field name for field-specific links */
-  field?: string
-  /** Link content */
-  children: ReactNode
-}
-
 /**
  * Link component for GraphQL schema references that preserves version context
  *
@@ -18,13 +10,22 @@ interface Props {
  * <ReferenceLink type="User">User</ReferenceLink>
  * <ReferenceLink type="User" field="name">User.name</ReferenceLink>
  */
-export const ReferenceLink = ({ type, field, children }: Props) => {
+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 }) => {
   const versionPath = useVersionPath()
 
-  let path = `/reference/${versionPath}${type}`
-  if (field) {
-    path += `/${field}`
-  }
+  const path = Api.Schema.Routing.joinSegmentsAndPaths(
+    Api.Schema.Routing.segmentLiterals.reference,
+    versionPath,
+    type,
+    field,
+  )
 
   return (
     <Link to={path}>

package/src/template/components/ToastContainer.tsx

@@ -0,0 +1,67 @@
+import type { React } from '#dep/react/index'
+import { Box, Flex } from '@radix-ui/themes'
+import { useSnapshot } from 'valtio'
+import { Stores } from '../stores/$.js'
+import { ToastItem } from './ToastItem.js'
+
+export const ToastContainer: React.FC = () => {
+  const snap = useSnapshot(Stores.Toast.store)
+
+  return (
+    <>
+      <style>
+        {`
+          @keyframes slideIn {
+            from {
+              transform: translateX(100%);
+              opacity: 0;
+            }
+            to {
+              transform: translateX(0);
+              opacity: 1;
+            }
+          }
+
+          @keyframes slideOut {
+            from {
+              transform: translateX(0);
+              opacity: 1;
+            }
+            to {
+              transform: translateX(100%);
+              opacity: 0;
+            }
+          }
+
+          @keyframes timerCountdown {
+            from {
+              width: 100%;
+            }
+            to {
+              width: 0%;
+            }
+          }
+        `}
+      </style>
+      <Box
+        position='fixed'
+        bottom='0'
+        right='0'
+        p='4'
+        style={{
+          zIndex: 9999,
+          pointerEvents: 'none',
+        }}
+      >
+        <Flex
+          direction='column'
+          gap='2'
+          align='end'
+          style={{ pointerEvents: 'auto' }}
+        >
+          {snap.toasts.map(toast => <ToastItem key={toast.id} toast={toast} />)}
+        </Flex>
+      </Box>
+    </>
+  )
+}

package/src/template/components/ToastItem.tsx

@@ -0,0 +1,119 @@
+import type { React } from '#dep/react/index'
+import {
+  CheckCircledIcon,
+  Cross2Icon,
+  CrossCircledIcon,
+  ExclamationTriangleIcon,
+  InfoCircledIcon,
+} from '@radix-ui/react-icons'
+import { Box, Button, Card, Flex, IconButton, Text } from '@radix-ui/themes'
+import type { TextProps } from '@radix-ui/themes'
+import type { ReadonlyDeep } from 'type-fest'
+import { Stores } from '../stores/$.js'
+
+const toastVariants = {
+  info: {
+    icon: <InfoCircledIcon />,
+    color: 'blue',
+  },
+  success: {
+    icon: <CheckCircledIcon />,
+    color: 'green',
+  },
+  warning: {
+    icon: <ExclamationTriangleIcon />,
+    color: 'amber',
+  },
+  error: {
+    icon: <CrossCircledIcon />,
+    color: 'red',
+  },
+} satisfies Record<Stores.Toast.Type, {
+  icon: React.ReactElement
+  color: NonNullable<TextProps['color']>
+}>
+
+export const ToastItem: React.FC<{ toast: ReadonlyDeep<Stores.Toast.Toast> }> = ({ toast }) => {
+  const handleClose = () => Stores.toast.remove(toast.id)
+  const duration = toast.duration ?? 5000
+  const showTimer = duration > 0
+  const type: Stores.Toast.Type = toast.type || 'info'
+
+  return (
+    <Card
+      size={'2'}
+      style={{
+        animation: 'slideIn 0.2s ease-out',
+        position: 'relative',
+      }}
+    >
+      <Flex gap='3' align='start' maxWidth={'400px'}>
+        <Text
+          as='div'
+          size='4'
+          color={toastVariants[type].color}
+        >
+          {toastVariants[type].icon}
+        </Text>
+        <Box style={{ flex: 1 }}>
+          <Flex align='baseline' gap='2' wrap='wrap'>
+            <Text weight='medium' size='2'>
+              {toast.message}
+            </Text>
+            {toast.actions.map((action) => (
+              <Button
+                id={action.label}
+                size='1'
+                variant='soft'
+                onClick={() => {
+                  action.onClick()
+                  handleClose()
+                }}
+              >
+                {action.label}
+              </Button>
+            ))}
+          </Flex>
+
+          {toast.description && (
+            <Text size='1' color='gray' mt='1' style={{ display: 'block' }}>
+              {toast.description}
+            </Text>
+          )}
+        </Box>
+
+        <IconButton
+          size='1'
+          variant='ghost'
+          color='gray'
+          onClick={handleClose}
+          style={{ flexShrink: 0 }}
+        >
+          <Cross2Icon />
+        </IconButton>
+      </Flex>
+
+      {showTimer && (
+        <Box
+          style={{
+            position: 'absolute',
+            bottom: 0,
+            left: 0,
+            right: 0,
+            height: '2px',
+            backgroundColor: `var(--${toastVariants[toast.type || 'info'].color}-a3)`,
+            overflow: 'hidden',
+          }}
+        >
+          <Box
+            style={{
+              height: '100%',
+              backgroundColor: `var(--${toastVariants[toast.type || 'info'].color}-a6)`,
+              animation: `timerCountdown ${duration}ms linear forwards`,
+            }}
+          />
+        </Box>
+      )}
+    </Card>
+  )
+}

package/src/template/components/TypeAnnotation.tsx

@@ -1,17 +1,13 @@
+import type { React } from '#dep/react/index'
 import { Text } from '@radix-ui/themes'
 import type { GraphQLType } from 'graphql'
 import { isInputObjectType, isListType, isNamedType, isNonNullType, isScalarType } from 'graphql'
-import type { FC } from 'react'
 import { ReferenceLink } from './ReferenceLink.js'
 
-export interface Props {
-  type: GraphQLType // Can be either GraphQLInputType or GraphQLOutputType
-}
-
 /**
  * Renders a GraphQL type recursively, with links for named types
  */
-export const TypeAnnotation: FC<Props> = ({ type }) => {
+export const TypeAnnotation: React.FC<{ type: GraphQLType }> = ({ type }) => {
   // Handle NonNull type wrapper
   if (isNonNullType(type)) {
     return (