polen 0.11.0-next.11 → 0.11.0-next.12

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/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,17 +1,8 @@
 import { Api } from '#api/iso'
-import type { ReactNode } from 'react'
+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
  *
@@ -19,7 +10,14 @@ 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()
 
   const path = Api.Schema.Routing.joinSegmentsAndPaths(

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 (

package/src/template/components/VersionPicker.tsx

@@ -0,0 +1,94 @@
+import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
+import { Select } from '@radix-ui/themes'
+import { useNavigate } from 'react-router'
+import { useReferencePath } from '../hooks/useReferencePath.js'
+import { schemaSource } from '../sources/schema-source.js'
+import { Stores } from '../stores/$.js'
+import { tryWithToast } from '../utils/try-with-toast.js'
+
+interface Props {
+  all: string[]
+  current: string
+}
+
+export const VersionPicker: React.FC<Props> = ({ all, current }) => {
+  const navigate = useNavigate()
+  const currentPath = useReferencePath()
+
+  // Don't show selector if only one version
+  if (all.length <= 1) {
+    return null
+  }
+
+  const handleVersionChange = async (newVersion: string) => {
+    const error = await tryWithToast(async () => {
+      // Check if current path exists in target version
+      const targetSchema = await schemaSource.get(newVersion)
+      // Find fallback path if needed
+      const fallbackPath = Api.Schema.Validation.findFallbackPath(targetSchema, currentPath)
+      // Get redirect description if path changed
+      const redirectDescription = Api.Schema.Validation.getRedirectDescription(
+        targetSchema,
+        currentPath,
+        fallbackPath,
+        newVersion,
+      )
+      // Create the new path
+      const newPath = Api.Schema.Routing.createReferencePath({
+        version: newVersion,
+        type: fallbackPath.type,
+        field: fallbackPath.field,
+      })
+      // Show toast notification if schema location redirect will occur
+      if (redirectDescription) {
+        Stores.Toast.store.info(redirectDescription, {
+          duration: 160_000,
+          actions: [
+            {
+              label: 'Go back',
+              onClick() {
+                navigate(-1)
+              },
+            },
+            {
+              label: 'View changelog',
+              onClick() {
+                // Navigate to changelog page
+                navigate('/changelog')
+              },
+            },
+          ],
+        })
+      }
+
+      navigate(newPath)
+    }, 'Failed to switch version')
+
+    // Fallback logic if error occurred
+    if (error) {
+      // Fallback to simple navigation if schema loading fails
+      const newPath = Api.Schema.Routing.createReferencePath({
+        version: newVersion,
+        type: currentPath.type,
+        field: currentPath.field,
+      })
+      navigate(newPath)
+    }
+  }
+
+  return (
+    <Select.Root value={current} onValueChange={handleVersionChange}>
+      <Select.Trigger>
+        {current === Api.Schema.VERSION_LATEST ? `Latest` : current}
+      </Select.Trigger>
+      <Select.Content>
+        {all.map(version => (
+          <Select.Item key={version} value={version}>
+            {version === Api.Schema.VERSION_LATEST ? `Latest` : version}
+          </Select.Item>
+        ))}
+      </Select.Content>
+    </Select.Root>
+  )
+}

package/src/template/hooks/useReferencePath.ts

@@ -0,0 +1,20 @@
+import { Api } from '#api/iso'
+import { useLocation, useParams } from 'react-router'
+
+/**
+ * Hook that returns parsed reference path parameters
+ *
+ * @throws {Error} If not currently on a reference route
+ * @returns Parsed reference path object
+ */
+export const useReferencePath = (): Api.Schema.Validation.PathValidation => {
+  const params = useParams()
+  const location = useLocation()
+
+  Api.Schema.Routing.assertReferenceRoute({
+    pathname: location.pathname,
+    params,
+  })
+
+  return params
+}

package/src/template/routes/reference.tsx

@@ -1,15 +1,16 @@
 import type { Content } from '#api/content/$'
 import { Api } from '#api/iso'
+import type { React } from '#dep/react/index'
 import { GrafaidOld } from '#lib/grafaid-old/index'
-import { Grafaid } from '#lib/grafaid/index'
 import { route, routeIndex } from '#lib/react-router-aid/react-router-aid'
 import { createLoader, useLoaderData } from '#lib/react-router-loader/react-router-loader'
 import { Box } from '@radix-ui/themes'
-import { Outlet, useParams } from 'react-router'
+import { neverCase } from '@wollybeard/kit/language'
+import { useParams } from 'react-router'
 import { Field } from '../components/Field.js'
 import { MissingSchema } from '../components/MissingSchema.js'
 import { NamedType } from '../components/NamedType.js'
-import { VersionSelector } from '../components/VersionSelector.js'
+import { VersionPicker } from '../components/VersionPicker.js'
 import { SidebarLayout } from '../layouts/index.js'
 import { schemaSource } from '../sources/schema-source.js'
 
@@ -29,7 +30,9 @@ export const loader = createLoader(async ({ params }) => {
   }
 })
 
-const RouteReferenceComponent = () => {
+// Single component that handles all reference route variations
+const ReferenceView = () => {
+  const params = useParams() as { version?: string; type?: string; field?: string }
   const data = useLoaderData<typeof loader>()
 
   if (!data.schema) {
@@ -59,91 +62,74 @@ const RouteReferenceComponent = () => {
   // Calculate basePath based on current version
   const basePath = Api.Schema.Routing.createReferenceBasePath(data.currentVersion)
 
+  // Determine view type and render appropriate content
+  const viewType = Api.Schema.Routing.getReferenceViewType({
+    schema: data.schema,
+    type: params.type,
+    field: params.field,
+  })
+
+  const content: React.ReactNode = (() => {
+    if (viewType === 'index') {
+      return <div>Select a type from the sidebar to view its documentation.</div>
+    } else if (viewType === 'type-missing' || viewType === 'field-missing') {
+      return <MissingSchema />
+    } else if (viewType === 'type') {
+      const type = data.schema.getType(params.type!)!
+      return <NamedType data={type} />
+    } else if (viewType === 'field') {
+      const type = data.schema.getType(params.type!)!
+      const fields = (type as any).getFields()
+      const field = fields[params.field!]
+      return <Field data={field} />
+    } else {
+      neverCase(viewType)
+    }
+  })()
+
   return (
     <SidebarLayout sidebar={sidebarItems} basePath={basePath}>
       <Box mb={`4`}>
-        <VersionSelector
-          availableVersions={data.availableVersions}
-          currentVersion={data.currentVersion}
+        <VersionPicker
+          all={[...data.availableVersions]} // Convert readonly to mutable
+          current={data.currentVersion}
         />
       </Box>
-      <Outlet />
+      {content}
     </SidebarLayout>
   )
 }
 
-// Shared hooks for schema data validation and retrieval
-const useReferenceSchema = () => {
-  const data = useLoaderData<typeof loader>('reference')
-  if (!data?.schema) {
-    throw new Error('Schema not found')
-  }
-  return data
-}
-
-const useSchemaType = (typeName: string) => {
-  const { schema } = useReferenceSchema()
-  const type = schema.getType(typeName)
-  if (!type) {
-    throw new Error(`Could not find type ${typeName}`)
-  }
-  return type
-}
-
-const useSchemaField = (typeName: string, fieldName: string) => {
-  const type = useSchemaType(typeName)
-  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
-    throw new Error(`Type ${typeName} does not have fields`)
-  }
-
-  const fields = type.getFields()
-  const field = fields[fieldName]
-  if (!field) {
-    throw new Error(`Could not find field ${fieldName} on type ${typeName}`)
-  }
-  return field
-}
-
-const RouteComponentIndex = () => {
-  return <div>Select a type from the sidebar to view its documentation.</div>
-}
-
-const RouteComponentType = () => {
-  const params = useParams() as { type: string }
-  const type = useSchemaType(params.type)
-  return <NamedType data={type} />
-}
-
-const RouteComponentTypeField = () => {
-  const params = useParams() as { type: string; field: string }
-  const field = useSchemaField(params.type, params.field)
-  return <Field data={field} />
-}
-
+// Define routes that handle type and field params
 const typeAndFieldRoutes = [
-  routeIndex(RouteComponentIndex),
+  routeIndex({
+    Component: ReferenceView,
+    loader,
+  }),
   route({
     path: `:type`,
-    Component: RouteComponentType,
+    Component: ReferenceView,
     errorElement: <MissingSchema />,
+    loader,
     children: [
       route({
         path: `:field`,
-        Component: RouteComponentTypeField,
+        Component: ReferenceView,
         errorElement: <MissingSchema />,
+        loader,
       }),
     ],
   }),
 ]
 
 /**
- * Reference documentation with proper nested structure - all routes in one file
+ * Reference documentation routes using proper React Router patterns
+ * - Parent routes have no components (automatically render Outlet)
+ * - Leaf routes have components and loaders that always run fresh
+ * - Single ReferenceView component handles all variations
  */
 export const reference = route({
-  id: 'reference',
   path: `reference`,
-  loader,
-  Component: RouteReferenceComponent,
   children: [
     ...typeAndFieldRoutes,
     route({

package/src/template/routes/root.tsx

@@ -1,5 +1,7 @@
 import type { ReactRouter } from '#dep/react-router/index'
 import { route } from '#lib/react-router-aid/react-router-aid'
+import { createLoader } from '#lib/react-router-loader/react-router-loader'
+import type { Stores } from '#template/stores/$'
 import { Box, Flex, Theme } from '@radix-ui/themes'
 import { Link as LinkReactRouter } from 'react-router'
 import { Outlet, ScrollRestoration } from 'react-router'
@@ -11,6 +13,7 @@ import { Link as PolenLink } from '../components/Link.js'
 import { Logo } from '../components/Logo.js'
 import { NotFound } from '../components/NotFound.js'
 import { ThemeToggle } from '../components/ThemeToggle.js'
+import { ToastContainer } from '../components/ToastContainer.js'
 import { ThemeProvider, useTheme } from '../contexts/ThemeContext.js'
 import { changelog } from './changelog.js'
 import { index } from './index.js'
@@ -46,7 +49,12 @@ const Layout = () => {
         style={{ color: `inherit`, textDecoration: `none` }}
       >
         <Box display={{ initial: `block`, md: `block` }}>
-          <Logo src={logoSrc} title={templateVariables.title} height={30} showTitle={true} />
+          <Logo
+            src={logoSrc}
+            title={templateVariables.title}
+            height={30}
+            showTitle={true}
+          />
         </Box>
       </LinkReactRouter>
       <Flex direction='row' gap='4' style={{ flex: 1 }}>
@@ -61,7 +69,7 @@ const Layout = () => {
   )
 
   return (
-    <Theme asChild appearance={appearance}>
+    <Theme asChild appearance={appearance} radius='none'>
       <Box
         width={{ initial: `100%`, sm: `100%`, md: `var(--container-4)` }}
         maxWidth='100vw'
@@ -72,15 +80,13 @@ const Layout = () => {
       >
         {header}
         <Outlet />
+        <ToastContainer />
       </Box>
     </Theme>
   )
 }
 
-const children: ReactRouter.RouteObject[] = [
-  index,
-  pages,
-]
+const children: ReactRouter.RouteObject[] = [index, pages]
 
 //
 //
@@ -122,8 +128,25 @@ children.push(notFoundRoute)
 //
 //
 
+const storeModules = import.meta.glob('../stores/!($.*)*.ts', { eager: true }) as Record<
+  string,
+  Stores.StoreModule
+>
+
 export const root = route({
   path: `/`,
   Component,
+  loader: createLoader(async () => {
+    // Reset all stores on SSR to prevent cross-request pollution
+    if (import.meta.env.SSR) {
+      for (const module of Object.values(storeModules)) {
+        if (module.store?.reset) {
+          module.store.reset()
+        }
+      }
+    }
+
+    return {}
+  }),
   children,
 })

package/src/template/stores/$$.ts

@@ -0,0 +1,15 @@
+export * as Schema from './schema.js'
+export { store as schema } from './schema.js'
+
+export * as Toast from './toast.js'
+export { store as toast } from './toast.js'
+
+export interface Store {
+  reset: () => void
+  set: (data?: unknown) => void
+}
+
+export interface StoreModule {
+  store: Store
+  initialState: unknown
+}

package/src/template/stores/$.ts

@@ -0,0 +1 @@
+export * as Stores from './$$.js'