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

package/build/template/stores/schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.d.ts","sourceRoot":"","sources":["../../../src/template/stores/schema.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,SAAS,CAAA;AAG5C;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,wCAAwC;IACxC,cAAc,EAAE,MAAM,CAAA;IACtB,oCAAoC;IACpC,iBAAiB,EAAE,MAAM,EAAE,CAAA;IAC3B,+CAA+C;IAC/C,aAAa,EAAE,aAAa,GAAG,IAAI,CAAA;CACpC;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,KAI1B,CAAA;AAED;;;;;GAKG;AACH,eAAO,MAAM,KAAK;IAGhB;;OAEG;;IAKH;;;OAGG;cACO,KAAK;IArCf,wCAAwC;oBACxB,MAAM;IACtB,oCAAoC;uBACjB,MAAM,EAAE;IAC3B,+CAA+C;mBAChC,aAAa,GAAG,IAAI;CAuCnC,CAAA"}

package/build/template/stores/schema.js

@@ -0,0 +1,36 @@
+import { proxy, ref } from 'valtio';
+/**
+ * Initial state for the schema store
+ */
+export const initialState = {
+    currentVersion: 'latest',
+    availableVersions: [],
+    currentSchema: null,
+};
+/**
+ * Schema store
+ *
+ * Manages GraphQL schema state including version selection and schema instances.
+ * Used for version switching and schema-aware navigation.
+ */
+export const store = proxy({
+    ...initialState,
+    /**
+     * Reset store to initial state
+     */
+    reset() {
+        Object.assign(store, initialState);
+    },
+    /**
+     * Set store state
+     * @param data - New state data
+     */
+    set(data) {
+        // Set each property individually to avoid issues with complex objects
+        store.currentVersion = data.currentVersion;
+        store.availableVersions = data.availableVersions;
+        // Use ref() to prevent Valtio from deeply proxying the GraphQL schema
+        store.currentSchema = data.currentSchema ? ref(data.currentSchema) : null;
+    },
+});
+//# sourceMappingURL=schema.js.map

package/build/template/stores/schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"schema.js","sourceRoot":"","sources":["../../../src/template/stores/schema.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAA;AAcnC;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAU;IACjC,cAAc,EAAE,QAAQ;IACxB,iBAAiB,EAAE,EAAE;IACrB,aAAa,EAAE,IAAI;CACpB,CAAA;AAED;;;;;GAKG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,CAAC;IACzB,GAAG,YAAY;IAEf;;OAEG;IACH,KAAK;QACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,CAAA;IACpC,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,IAAW;QACb,sEAAsE;QACtE,KAAK,CAAC,cAAc,GAAG,IAAI,CAAC,cAAc,CAAA;QAC1C,KAAK,CAAC,iBAAiB,GAAG,IAAI,CAAC,iBAAiB,CAAA;QAChD,sEAAsE;QACtE,KAAK,CAAC,aAAa,GAAG,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,IAAI,CAAA;IAC3E,CAAC;CACF,CAAC,CAAA"}

package/build/template/stores/toast.d.ts

@@ -0,0 +1,103 @@
+/**
+ * Toast notification types
+ */
+export declare const Type: {
+    readonly info: "info";
+    readonly success: "success";
+    readonly warning: "warning";
+    readonly error: "error";
+};
+export type Type = typeof Type[keyof typeof Type];
+/**
+ * Toast notification interface
+ */
+export interface Toast {
+    /** Unique identifier for the toast */
+    id: string;
+    /** Primary message text */
+    message: string;
+    /** Optional secondary description text */
+    description?: string;
+    /** Visual type/variant of the toast */
+    type?: Type;
+    /** Duration in milliseconds before auto-dismiss. Set to 0 to disable auto-dismiss */
+    duration?: number;
+    /** Optional action buttons configuration */
+    actions: {
+        /** Action button label */
+        label: string;
+        /** Action button click handler */
+        onClick: () => void;
+    }[];
+}
+/**
+ * Toast store state interface
+ */
+export interface State {
+    /** Array of active toast notifications */
+    toasts: Toast[];
+}
+/**
+ * Initial state for the toast store
+ */
+export declare const initialState: State;
+/**
+ * Toast notification store
+ *
+ * Manages toast notifications with auto-dismiss functionality and type-specific convenience methods.
+ */
+export declare const store: {
+    /**
+     * Add a new toast notification
+     * @param toast - Toast configuration (id will be auto-generated)
+     * @returns Generated toast ID
+     */
+    add(toast: Omit<Toast, "id">): string;
+    /**
+     * Remove a toast by ID
+     * @param id - Toast ID to remove
+     */
+    remove(id: string): void;
+    /**
+     * Reset store to initial state
+     */
+    reset(): void;
+    /**
+     * Set store state
+     * @param data - New state data
+     */
+    set(data: State): void;
+    /**
+     * Show an info toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    info(message: string, options?: InputOptions): string;
+    /**
+     * Show a success toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    success(message: string, options?: InputOptions): string;
+    /**
+     * Show a warning toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    warning(message: string, options?: InputOptions): string;
+    /**
+     * Show an error toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    error(message: string, options?: InputOptions): string;
+    /** Array of active toast notifications */
+    toasts: Toast[];
+};
+type InputOptions = Partial<Omit<Toast, 'id' | 'message' | 'type'>>;
+export {};
+//# sourceMappingURL=toast.d.ts.map

package/build/template/stores/toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast.d.ts","sourceRoot":"","sources":["../../../src/template/stores/toast.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,IAAI;;;;;CAKP,CAAA;AAEV,MAAM,MAAM,IAAI,GAAG,OAAO,IAAI,CAAC,MAAM,OAAO,IAAI,CAAC,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,sCAAsC;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,2BAA2B;IAC3B,OAAO,EAAE,MAAM,CAAA;IACf,0CAA0C;IAC1C,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,uCAAuC;IACvC,IAAI,CAAC,EAAE,IAAI,CAAA;IACX,qFAAqF;IACrF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,4CAA4C;IAC5C,OAAO,EAAE;QACP,0BAA0B;QAC1B,KAAK,EAAE,MAAM,CAAA;QACb,kCAAkC;QAClC,OAAO,EAAE,MAAM,IAAI,CAAA;KACpB,EAAE,CAAA;CACJ;AAED;;GAEG;AACH,MAAM,WAAW,KAAK;IACpB,0CAA0C;IAC1C,MAAM,EAAE,KAAK,EAAE,CAAA;CAChB;AAED;;GAEG;AACH,eAAO,MAAM,YAAY,EAAE,KAE1B,CAAA;AAUD;;;;GAIG;AACH,eAAO,MAAM,KAAK;IAGhB;;;;OAIG;eACQ,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,GAAG,MAAM;IAYrC;;;OAGG;eACQ,MAAM,GAAG,IAAI;IAOxB;;OAEG;;IAKH;;;OAGG;cACO,KAAK;IAIf;;;;;OAKG;kBACW,MAAM,YAAY,YAAY;IAI5C;;;;;OAKG;qBACc,MAAM,YAAY,YAAY;IAI/C;;;;;OAKG;qBACc,MAAM,YAAY,YAAY;IAI/C;;;;;OAKG;mBACY,MAAM,YAAY,YAAY;IA1G7C,0CAA0C;YAClC,KAAK,EAAE;CA4Gf,CAAA;AAEF,KAAK,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,GAAG,SAAS,GAAG,MAAM,CAAC,CAAC,CAAA"}

package/build/template/stores/toast.js

@@ -0,0 +1,105 @@
+import { proxy } from 'valtio';
+/**
+ * Toast notification types
+ */
+export const Type = {
+    info: 'info',
+    success: 'success',
+    warning: 'warning',
+    error: 'error',
+};
+/**
+ * Initial state for the toast store
+ */
+export const initialState = {
+    toasts: [],
+};
+/**
+ * Default values for toast properties
+ */
+const toastDefaults = {
+    duration: 5000,
+    actions: [],
+};
+/**
+ * Toast notification store
+ *
+ * Manages toast notifications with auto-dismiss functionality and type-specific convenience methods.
+ */
+export const store = proxy({
+    ...initialState,
+    /**
+     * Add a new toast notification
+     * @param toast - Toast configuration (id will be auto-generated)
+     * @returns Generated toast ID
+     */
+    add(toast) {
+        const id = `${Date.now()}-${Math.random().toString(36).substring(2, 11)}`;
+        store.toasts.push({ ...toast, id });
+        // Auto-remove after duration (default 5 seconds). Set duration to 0 to disable auto-dismiss
+        if (toast.duration !== 0) {
+            setTimeout(() => store.remove(id), toast.duration || toastDefaults.duration);
+        }
+        return id;
+    },
+    /**
+     * Remove a toast by ID
+     * @param id - Toast ID to remove
+     */
+    remove(id) {
+        const index = store.toasts.findIndex(t => t.id === id);
+        if (index > -1) {
+            store.toasts.splice(index, 1);
+        }
+    },
+    /**
+     * Reset store to initial state
+     */
+    reset() {
+        Object.assign(store, initialState);
+    },
+    /**
+     * Set store state
+     * @param data - New state data
+     */
+    set(data) {
+        Object.assign(store, data);
+    },
+    /**
+     * Show an info toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    info(message, options) {
+        return store.add({ ...toastDefaults, ...options, message, type: Type.info });
+    },
+    /**
+     * Show a success toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    success(message, options) {
+        return store.add({ ...toastDefaults, ...options, message, type: Type.success });
+    },
+    /**
+     * Show a warning toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    warning(message, options) {
+        return store.add({ ...toastDefaults, ...options, message, type: Type.warning });
+    },
+    /**
+     * Show an error toast
+     * @param message - Toast message
+     * @param options - Additional toast options
+     * @returns Generated toast ID
+     */
+    error(message, options) {
+        return store.add({ ...toastDefaults, ...options, message, type: Type.error });
+    },
+});
+//# sourceMappingURL=toast.js.map

package/build/template/stores/toast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"toast.js","sourceRoot":"","sources":["../../../src/template/stores/toast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAA;AAE9B;;GAEG;AACH,MAAM,CAAC,MAAM,IAAI,GAAG;IAClB,IAAI,EAAE,MAAM;IACZ,OAAO,EAAE,SAAS;IAClB,OAAO,EAAE,SAAS;IAClB,KAAK,EAAE,OAAO;CACN,CAAA;AAmCV;;GAEG;AACH,MAAM,CAAC,MAAM,YAAY,GAAU;IACjC,MAAM,EAAE,EAAE;CACX,CAAA;AAED;;GAEG;AACH,MAAM,aAAa,GAAG;IACpB,QAAQ,EAAE,IAAI;IACd,OAAO,EAAE,EAAE;CACa,CAAA;AAE1B;;;;GAIG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,KAAK,CAAC;IACzB,GAAG,YAAY;IAEf;;;;OAIG;IACH,GAAG,CAAC,KAAwB;QAC1B,MAAM,EAAE,GAAG,GAAG,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;QACzE,KAAK,CAAC,MAAM,CAAC,IAAI,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,EAAE,CAAC,CAAA;QAEnC,4FAA4F;QAC5F,IAAI,KAAK,CAAC,QAAQ,KAAK,CAAC,EAAE,CAAC;YACzB,UAAU,CAAC,GAAG,EAAE,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC,EAAE,KAAK,CAAC,QAAQ,IAAI,aAAa,CAAC,QAAQ,CAAC,CAAA;QAC9E,CAAC;QAED,OAAO,EAAE,CAAA;IACX,CAAC;IAED;;;OAGG;IACH,MAAM,CAAC,EAAU;QACf,MAAM,KAAK,GAAG,KAAK,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAA;QACtD,IAAI,KAAK,GAAG,CAAC,CAAC,EAAE,CAAC;YACf,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,CAAC,CAAA;QAC/B,CAAC;IACH,CAAC;IAED;;OAEG;IACH,KAAK;QACH,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,YAAY,CAAC,CAAA;IACpC,CAAC;IAED;;;OAGG;IACH,GAAG,CAAC,IAAW;QACb,MAAM,CAAC,MAAM,CAAC,KAAK,EAAE,IAAI,CAAC,CAAA;IAC5B,CAAC;IAED;;;;;OAKG;IACH,IAAI,CAAC,OAAe,EAAE,OAAsB;QAC1C,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,IAAI,EAAE,CAAC,CAAA;IAC9E,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAAe,EAAE,OAAsB;QAC7C,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;IACjF,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAAe,EAAE,OAAsB;QAC7C,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC,CAAA;IACjF,CAAC;IAED;;;;;OAKG;IACH,KAAK,CAAC,OAAe,EAAE,OAAsB;QAC3C,OAAO,KAAK,CAAC,GAAG,CAAC,EAAE,GAAG,aAAa,EAAE,GAAG,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,IAAI,CAAC,KAAK,EAAE,CAAC,CAAA;IAC/E,CAAC;CACF,CAAC,CAAA"}

package/build/template/utils/try-with-toast.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Execute an async function with automatic error handling and toast notifications
+ *
+ * @param fn - Async function to execute
+ * @param errorMessage - Optional custom error message for the toast (defaults to error message)
+ * @returns Promise that resolves to null on success or Error on failure
+ */
+export declare const tryWithToast: <T>(fn: () => Promise<T>, errorMessage?: string) => Promise<Error | null>;
+//# sourceMappingURL=try-with-toast.d.ts.map

package/build/template/utils/try-with-toast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"try-with-toast.d.ts","sourceRoot":"","sources":["../../../src/template/utils/try-with-toast.ts"],"names":[],"mappings":"AAEA;;;;;;GAMG;AACH,eAAO,MAAM,YAAY,GAAU,CAAC,EAClC,IAAI,MAAM,OAAO,CAAC,CAAC,CAAC,EACpB,eAAe,MAAM,KACpB,OAAO,CAAC,KAAK,GAAG,IAAI,CA4BtB,CAAA"}

package/build/template/utils/try-with-toast.js

@@ -0,0 +1,37 @@
+import { Stores } from '../stores/$.js';
+/**
+ * Execute an async function with automatic error handling and toast notifications
+ *
+ * @param fn - Async function to execute
+ * @param errorMessage - Optional custom error message for the toast (defaults to error message)
+ * @returns Promise that resolves to null on success or Error on failure
+ */
+export const tryWithToast = async (fn, errorMessage) => {
+    try {
+        await fn();
+        return null;
+    }
+    catch (error) {
+        // Log to console in all environments
+        console.error('Error in tryWithToast:', error);
+        // Determine the error message
+        const baseMessage = error instanceof Error ? error.message : String(error);
+        const toastMessage = errorMessage || baseMessage;
+        // In development, show detailed error info
+        if (import.meta.env.DEV) {
+            Stores.Toast.store.error(toastMessage, {
+                description: error instanceof Error
+                    ? `${error.name}: ${error.message}${error.stack ? '\n\nStack trace available in console.' : ''}`
+                    : `Error details: ${String(error)}`,
+                duration: 10000, // Longer duration in dev for debugging
+            });
+        }
+        else {
+            // In production, show simplified message
+            Stores.Toast.store.error(toastMessage);
+        }
+        // Return the error for downstream fallback logic
+        return error instanceof Error ? error : new Error(baseMessage);
+    }
+};
+//# sourceMappingURL=try-with-toast.js.map

package/build/template/utils/try-with-toast.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"try-with-toast.js","sourceRoot":"","sources":["../../../src/template/utils/try-with-toast.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,MAAM,EAAE,MAAM,gBAAgB,CAAA;AAEvC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,KAAK,EAC/B,EAAoB,EACpB,YAAqB,EACE,EAAE;IACzB,IAAI,CAAC;QACH,MAAM,EAAE,EAAE,CAAA;QACV,OAAO,IAAI,CAAA;IACb,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,qCAAqC;QACrC,OAAO,CAAC,KAAK,CAAC,wBAAwB,EAAE,KAAK,CAAC,CAAA;QAE9C,8BAA8B;QAC9B,MAAM,WAAW,GAAG,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CAAA;QAC1E,MAAM,YAAY,GAAG,YAAY,IAAI,WAAW,CAAA;QAEhD,2CAA2C;QAC3C,IAAI,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC;YACxB,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,EAAE;gBACrC,WAAW,EAAE,KAAK,YAAY,KAAK;oBACjC,CAAC,CAAC,GAAG,KAAK,CAAC,IAAI,KAAK,KAAK,CAAC,OAAO,GAAG,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,uCAAuC,CAAC,CAAC,CAAC,EAAE,EAAE;oBAChG,CAAC,CAAC,kBAAkB,MAAM,CAAC,KAAK,CAAC,EAAE;gBACrC,QAAQ,EAAE,KAAK,EAAE,uCAAuC;aACzD,CAAC,CAAA;QACJ,CAAC;aAAM,CAAC;YACN,yCAAyC;YACzC,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,KAAK,CAAC,YAAY,CAAC,CAAA;QACxC,CAAC;QAED,iDAAiD;QACjD,OAAO,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,WAAW,CAAC,CAAA;IAChE,CAAC;AACH,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "polen",
-  "version": "0.11.0-next.11",
+  "version": "0.11.0-next.12",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {
@@ -138,6 +138,7 @@
     "tsx": "^4.20.3",
     "typescript": "^5.8.3",
     "unified": "^11.0.5",
+    "valtio": "^2.1.5",
     "vfile": "^6.0.3",
     "vite": "npm:rolldown-vite@^7.0.9",
     "vite-plugin-inspect": "^11.3.0",

package/src/api/iso/schema/$$.ts

@@ -1,5 +1,6 @@
 export * from './constants.js'
 export * as Routing from './routing.js'
+export * as Validation from './validation.js'
 
 // Re-export types from server layer that are needed in template
 export type { ChangelogData, ChangeSets, NonEmptyChangeSets } from '../../schema/schema.js'

package/src/api/iso/schema/routing.ts

@@ -1,3 +1,4 @@
+import { Grafaid } from '#lib/grafaid/index'
 import { VERSION_LATEST } from './constants.js'
 
 export interface ReferencePathParts {
@@ -6,6 +7,11 @@ export interface ReferencePathParts {
   field?: string
 }
 
+interface RouteCheck {
+  pathname: string
+  params: Record<string, string | undefined>
+}
+
 export const createReferencePath = (parts: ReferencePathParts): string => {
   const basePath = createReferenceBasePath(parts.version)
   return joinSegmentsAndPaths(basePath, parts.type, parts.field)
@@ -51,3 +57,86 @@ export const joinSegmentsAndPaths = (
 
   return path
 }
+
+/**
+ * Check if the current route is a reference route
+ * @param route - Route information containing pathname and params
+ * @returns True if on a reference route
+ */
+export const isReferenceRoute = (route: RouteCheck): boolean => {
+  return route.params[`type`] !== undefined
+    || route.params[`field`] !== undefined
+    || route.params[`argument`] !== undefined
+    || route.pathname.includes(`/${segmentLiterals.reference}`)
+}
+
+/**
+ * Assert that the current route is a reference route
+ * @param route - Route information containing pathname and params
+ * @throws {Error} If not on a reference route
+ */
+export const assertReferenceRoute = (route: RouteCheck): void => {
+  if (!isReferenceRoute(route)) {
+    throw new Error('Not on a reference route. This function can only be used on reference routes.')
+  }
+}
+
+/**
+ * View type for reference routes
+ */
+export type ReferenceViewType =
+  | 'index' // No type selected
+  | 'type' // Type selected, no field
+  | 'field' // Type and field selected
+  | 'type-missing' // Type not found in schema
+  | 'field-missing' // Field not found on type
+
+export interface ReferenceViewParams {
+  schema: import('graphql').GraphQLSchema
+  type?: string
+  field?: string
+}
+
+/**
+ * Determine the view type for a reference route based on params and schema
+ */
+export const getReferenceViewType = (params: ReferenceViewParams): ReferenceViewType => {
+  const { schema, type: typeName, field: fieldName } = params
+
+  // No type selected - show index
+  if (!typeName) {
+    return 'index'
+  }
+
+  // Check if type exists
+  const type = schema.getType(typeName)
+  if (!type) {
+    return 'type-missing'
+  }
+
+  // No field selected - show type
+  if (!fieldName) {
+    return 'type'
+  }
+
+  // Check if type has fields
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) {
+    return 'field-missing'
+  }
+
+  // Check if field exists
+  const fields = type.getFields()
+  if (!fields[fieldName]) {
+    return 'field-missing'
+  }
+
+  // Field exists - show field
+  return 'field'
+}
+
+/**
+ * Type guard to check if view type indicates missing content
+ */
+export const isMissingView = (viewType: ReferenceViewType): viewType is 'type-missing' | 'field-missing' => {
+  return viewType === 'type-missing' || viewType === 'field-missing'
+}

package/src/api/iso/schema/validation.ts

@@ -0,0 +1,136 @@
+import { Grafaid } from '#lib/grafaid/index'
+import type { GraphQLFieldMap, GraphQLSchema } from 'graphql'
+
+export interface PathValidation {
+  version?: string
+  type?: string
+  field?: string
+  argument?: string
+}
+
+/**
+ * Check if a reference path exists in the given schema
+ */
+export const doesPathExist = (schema: GraphQLSchema, path: PathValidation): boolean => {
+  if (!path.type) return true
+
+  const type = schema.getType(path.type)
+  if (!type) return false
+
+  if (!path.field) return true
+
+  if (!Grafaid.Schema.TypesLike.isFielded(type)) return false
+
+  const fields = type.getFields() as GraphQLFieldMap<unknown, unknown>
+  const field = fields[path.field]
+  if (!field) return false
+
+  if (!path.argument) return true
+
+  // Check if argument exists
+  const arg = field.args.find(a => a.name === path.argument)
+  return !!arg
+}
+
+/**
+ * Find the best fallback path when the current path doesn't exist
+ */
+export const findFallbackPath = (
+  schema: GraphQLSchema,
+  currentPath: PathValidation,
+): PathValidation => {
+  // If no type specified, return empty path
+  if (!currentPath.type) {
+    return { type: `Query` }
+  }
+
+  // Check if current path exists
+  if (doesPathExist(schema, currentPath)) {
+    return currentPath
+  }
+
+  // If viewing an argument that doesn't exist, fall back to parent field
+  if (currentPath.argument && currentPath.field) {
+    const fieldPath = { type: currentPath.type, field: currentPath.field }
+    if (doesPathExist(schema, fieldPath)) {
+      return fieldPath
+    }
+  }
+
+  // If viewing a field that doesn't exist, fall back to parent type
+  if (currentPath.field) {
+    const typePath = { type: currentPath.type }
+    if (doesPathExist(schema, typePath)) {
+      return typePath
+    }
+  }
+
+  // If viewing a type that doesn't exist, fall back to Query type
+  return { type: `Query` }
+}
+
+/**
+ * Get all available types in a schema
+ */
+export const getAvailableTypes = (schema: GraphQLSchema): string[] => {
+  const typeMap = schema.getTypeMap()
+  return Object.keys(typeMap).filter(name => !name.startsWith(`__`))
+}
+
+/**
+ * Get all available fields for a type
+ */
+export const getAvailableFields = (schema: GraphQLSchema, typeName: string): string[] => {
+  const type = schema.getType(typeName)
+  if (!type || !Grafaid.Schema.TypesLike.isFielded(type)) {
+    return []
+  }
+
+  const fields = type.getFields() as GraphQLFieldMap<unknown, unknown>
+  return Object.keys(fields)
+}
+
+/**
+ * Check if a path would require a redirect when switching to a new schema version
+ */
+export const wouldRequireRedirect = (
+  currentSchema: GraphQLSchema,
+  targetSchema: GraphQLSchema,
+  currentPath: PathValidation,
+): boolean => {
+  const existsInCurrent = doesPathExist(currentSchema, currentPath)
+  const existsInTarget = doesPathExist(targetSchema, currentPath)
+
+  return existsInCurrent && !existsInTarget
+}
+
+/**
+ * Get a human-readable description of what will happen when switching versions
+ */
+export const getRedirectDescription = (
+  targetSchema: GraphQLSchema,
+  currentPath: PathValidation,
+  fallbackPath: PathValidation,
+  targetVersion?: string,
+): string | null => {
+  if (!currentPath.type) return null
+
+  const currentExists = doesPathExist(targetSchema, currentPath)
+  if (currentExists) return null
+
+  const versionInfo = targetVersion ? ` in version ${targetVersion}` : ` in this version`
+
+  if (currentPath.argument && fallbackPath.field) {
+    return `Argument "${currentPath.argument}" doesn't exist${versionInfo}. Redirecting to field "${fallbackPath.field}".`
+  }
+
+  if (currentPath.field && fallbackPath.type && !fallbackPath.field) {
+    return `Field "${currentPath.field}" doesn't exist${versionInfo}. Redirecting to type "${fallbackPath.type}".`
+  }
+
+  if (currentPath.type !== fallbackPath.type) {
+    return `Type "${currentPath.type}" doesn't exist${versionInfo}. Redirecting to type "${fallbackPath.type}".`
+  }
+
+  return `This path doesn't exist${versionInfo}. Redirecting to a valid location.`
+}

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