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

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.10",
+  "version": "0.11.0-next.12",
   "type": "module",
   "description": "A framework for delightful GraphQL developer portals",
   "author": {
@@ -35,6 +35,9 @@
     "#*": {
       "default": "./build/*.js"
     },
+    "#api/iso": {
+      "default": "./build/api/iso/$.js"
+    },
     "#lib/mask": {
       "default": "./build/lib/mask/$.js"
     },
@@ -135,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/api.ts

@@ -1,6 +1,12 @@
+// Re-export everything from isomorphic layer
+export * from './iso/$$.js'
+
+// Server-only exports
 export * from './builder/index.js'
 export * from './config-resolver/index.js'
 export * from './config/index.js'
 export * as Project from './project/index.js'
-export * from './schema/index.js'
 export * from './static/index.js'
+
+// Re-export schema with server-only extensions
+export { Schema } from './schema/index.js'

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

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

package/src/api/iso/$.ts

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

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

@@ -0,0 +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/$.ts

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

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

@@ -0,0 +1,49 @@
+/**
+ * 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')
+}
+
+/**
+ * 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}`)
+}
+
+/**
+ * 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
+}

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

@@ -0,0 +1,142 @@
+import { Grafaid } from '#lib/grafaid/index'
+import { VERSION_LATEST } from './constants.js'
+
+export interface ReferencePathParts {
+  version?: string
+  type?: string
+  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)
+}
+
+/**
+ * Create a base path for reference pages based on the current version
+ * Used for sidebar navigation and other UI components that need version-aware paths
+ */
+export const createReferenceBasePath = (version?: string): string => {
+  return joinSegmentsAndPaths(segmentLiterals.reference, createReferenceVersionPath(version))
+}
+
+export const segmentLiterals = {
+  reference: 'reference',
+  version: 'version',
+}
+
+/**
+ * Create a base path for reference pages based on the current version
+ * Used for sidebar navigation and other UI components that need version-aware paths
+ */
+export const createReferenceVersionPath = (version?: string): string => {
+  if (version === undefined) return ''
+  return version === VERSION_LATEST
+    ? ``
+    : `/${segmentLiterals.version}/${version}`
+}
+
+export const joinSegmentsAndPaths = (
+  ...segmentsOrPaths: (string | undefined | null | (string | null | undefined)[])[]
+): string => {
+  const path = '/' + segmentsOrPaths
+    .flat()
+    .filter((_): _ is string => _ !== undefined && _ !== null)
+    .map(chunkUnformatted =>
+      chunkUnformatted
+        .replace(/^\//, '')
+        .replace(/\/$/, '')
+    )
+    .filter(Boolean)
+    .join('/')
+
+  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/api/iso.ts

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