@inferencesh/ui 0.0.0-stage → 0.1.1

package/src/lib/schema.ts

@@ -0,0 +1,320 @@
+/**
+ * JSON Schema types and utilities for parsing and resolving references
+ */
+
+export type SchemaTypeName =
+  | "string"
+  | "number"
+  | "integer"
+  | "boolean"
+  | "object"
+  | "array"
+  | "any"
+  | "null";
+
+export type SchemaType =
+  | string
+  | number
+  | boolean
+  | Record<string, unknown>
+  | unknown[]
+  | null
+  | undefined;
+
+export interface SchemaAlternative extends Omit<Schema, 'type'> {
+  type: SchemaTypeName;
+}
+
+export interface Schema {
+  $id?: string;
+  $ref?: string;
+  $schema?: string;
+  $comment?: string;
+  $defs?: Record<string, Schema>;
+
+  type?: SchemaTypeName | SchemaTypeName[];
+  enum?: SchemaType[];
+  const?: SchemaType;
+
+  // String validations
+  minLength?: number;
+  maxLength?: number;
+  pattern?: string;
+
+  // Number validations
+  multipleOf?: number;
+  maximum?: number;
+  exclusiveMaximum?: number;
+  minimum?: number;
+  exclusiveMinimum?: number;
+
+  // Object validations
+  maxProperties?: number;
+  minProperties?: number;
+  required?: string[];
+  properties?: Record<string, Schema>;
+  patternProperties?: Record<string, Schema>;
+  additionalProperties?: Schema | boolean;
+
+  // Array validations
+  items?: Schema | Schema[];
+  additionalItems?: Schema;
+  maxItems?: number;
+  minItems?: number;
+  uniqueItems?: boolean;
+  contains?: Schema;
+
+  // Conditionals
+  if?: Schema;
+  then?: Schema;
+  else?: Schema;
+
+  // Combiners
+  allOf?: SchemaAlternative[];
+  anyOf?: SchemaAlternative[];
+  oneOf?: SchemaAlternative[];
+  not?: SchemaAlternative;
+
+  format?: string;
+  contentMediaType?: string;
+  contentEncoding?: string;
+
+  // Metadata
+  title?: string;
+  description?: string;
+  default?: SchemaType;
+  readOnly?: boolean;
+  writeOnly?: boolean;
+  examples?: SchemaType | SchemaType[];
+  definitions?: Record<string, Schema>;
+
+  // Set by the form layer when an `anyOf [T, null]` is collapsed to T, so a
+  // renderer can offer "unset" and default builders can leave it absent.
+  nullable?: boolean;
+
+  // Vendor extensions
+  'x-promoted'?: boolean;
+}
+
+/**
+ * A field parsed from a schema with resolved references.
+ * `displayType` holds the human-readable type string from `resolveDisplayType`
+ * (e.g. "object | string", "file | object") while `type` stays compatible
+ * with Schema for structural operations.
+ */
+export interface SchemaField extends Schema {
+  displayType: string;
+  key: string;
+  resolved?: Schema;
+  isRequired?: boolean;
+  promoted?: boolean;
+}
+
+// Type guards
+function hasRef(value: unknown): value is Schema & { $ref: string } {
+  return typeof value === 'object' && value !== null && '$ref' in value && typeof (value as Schema).$ref === 'string';
+}
+
+/**
+ * Deeply resolves all $ref references in a schema
+ */
+export function resolveSchemaReferences(schema: Schema, rootSchema: Schema): Schema {
+  if (!schema) return schema;
+
+  // Handle direct reference
+  if (hasRef(schema) && rootSchema.$defs) {
+    const refName = schema.$ref.replace('#/$defs/', '');
+    const resolvedSchema = rootSchema.$defs[refName];
+    if (resolvedSchema) {
+      const fullyResolved = resolveSchemaReferences(resolvedSchema, rootSchema);
+      return {
+        ...fullyResolved,
+        ...schema,
+        $ref: schema.$ref
+      };
+    }
+  }
+
+  // Handle nested references in properties
+  if (schema.properties) {
+    const resolvedProperties: Record<string, Schema> = {};
+    for (const [key, propSchema] of Object.entries(schema.properties)) {
+      resolvedProperties[key] = resolveSchemaReferences(propSchema, rootSchema);
+    }
+    schema = { ...schema, properties: resolvedProperties };
+  }
+
+  // Handle references in array items
+  if (schema.items) {
+    if (Array.isArray(schema.items)) {
+      schema = {
+        ...schema,
+        items: schema.items.map(itemSchema => resolveSchemaReferences(itemSchema, rootSchema))
+      };
+    } else {
+      schema = {
+        ...schema,
+        items: resolveSchemaReferences(schema.items, rootSchema)
+      };
+    }
+  }
+
+  // Handle references in anyOf, oneOf, allOf
+  const combiners = ['anyOf', 'oneOf', 'allOf'] as const;
+  for (const key of combiners) {
+    const schemas = schema[key];
+    if (schemas) {
+      schema = {
+        ...schema,
+        [key]: schemas.map((subSchema: Schema) => resolveSchemaReferences(subSchema, rootSchema))
+      };
+    }
+  }
+
+  return schema;
+}
+
+/**
+ * Process anyOf to handle nullable fields
+ */
+function processAnyOf(schema: Schema): { processedSchema: Schema; isNullable: boolean } {
+  if (!schema.anyOf || schema.anyOf.length > 2) {
+    return { processedSchema: schema, isNullable: false };
+  }
+
+  const nullSchema = schema.anyOf.find(type => type.type === 'null');
+  const nonNullSchema = schema.anyOf.find(type => type.type !== 'null');
+
+  if (!nullSchema) {
+    return { processedSchema: schema, isNullable: false };
+  }
+
+  if (!nonNullSchema) {
+    return {
+      processedSchema: { ...schema, type: 'null', anyOf: undefined },
+      isNullable: true
+    };
+  }
+
+  return {
+    processedSchema: {
+      ...schema,
+      ...nonNullSchema,
+      description: schema.description || nonNullSchema.description,
+      default: schema.default || nonNullSchema.default,
+      anyOf: undefined
+    },
+    isNullable: true
+  };
+}
+
+/**
+ * Synthesize a display type from a oneOf schema.
+ * Special-cases the File schema ($id: /schemas/File) to show "file" instead of "object".
+ */
+function resolveOneOfType(schema: Schema): string | undefined {
+  if (!schema.oneOf || schema.oneOf.length === 0) return undefined;
+
+  const isFileSchema = schema.$id === '/schemas/File';
+  const types: string[] = [];
+  for (const alt of schema.oneOf) {
+    if (isFileSchema && alt.type === 'object') {
+      types.push('file');
+    } else if (typeof alt.type === 'string') {
+      types.push(alt.type);
+    } else {
+      types.push('any');
+    }
+  }
+
+  if (types.length === 0) return undefined;
+  if (types.length === 1) return types[0];
+  return types.join(' | ');
+}
+
+/**
+ * Normalize a schema type to a single SchemaTypeName.
+ * JSON Schema allows type arrays (e.g. ["string", "null"]) — pick the
+ * first non-null entry so field logic can use simple === comparisons.
+ */
+export function normalizeType(schema: Schema): SchemaTypeName | undefined {
+  if (!schema.type) return undefined;
+  if (!Array.isArray(schema.type)) return schema.type;
+  return schema.type.find(t => t !== 'null') ?? schema.type[0];
+}
+
+/**
+ * Determine the display type for a resolved schema
+ */
+export function resolveDisplayType(schema: Schema): string {
+  if (schema.format) {
+    return schema.format;
+  }
+  if (schema.type) {
+    return Array.isArray(schema.type) ? schema.type.join(' | ') : schema.type;
+  }
+  const oneOfType = resolveOneOfType(schema);
+  if (oneOfType) return oneOfType;
+  if (schema.anyOf?.length) {
+    return schema.anyOf.map(alt => alt.type ?? 'any').join(' | ');
+  }
+  return 'any';
+}
+
+/**
+ * Create a field from a schema property
+ */
+function createFieldFromSchema(
+  schema: Schema,
+  key: string,
+  rootSchema: Schema,
+  required?: string[]
+): SchemaField {
+  const resolvedSchema = resolveSchemaReferences(schema, rootSchema);
+
+  const promoted = schema['x-promoted'] === true || resolvedSchema['x-promoted'] === true;
+
+  const type = normalizeType(resolvedSchema);
+
+  if (hasRef(schema)) {
+    return {
+      ...schema,
+      ...resolvedSchema,
+      key,
+      type,
+      displayType: resolveDisplayType(resolvedSchema),
+      title: resolvedSchema.title || key,
+      isRequired: required?.includes(key),
+      ...(promoted && { promoted }),
+      resolved: resolvedSchema,
+      $ref: schema.$ref
+    };
+  }
+
+  return {
+    ...resolvedSchema,
+    key,
+    type,
+    displayType: resolveDisplayType(resolvedSchema),
+    title: schema.title || key,
+    isRequired: required?.includes(key),
+    ...(promoted && { promoted }),
+  };
+}
+
+/**
+ * Parse a JSON Schema into a list of fields with resolved references
+ */
+export function getFieldsFromSchema(schema: Schema): { fields: SchemaField[] } {
+  if (!schema || !schema.properties) {
+    return { fields: [] };
+  }
+
+  const fields = Object.entries(schema.properties).map(([key, fieldData]): SchemaField => {
+    const resolvedFieldData = resolveSchemaReferences(fieldData, schema);
+    const { processedSchema } = processAnyOf(resolvedFieldData);
+    return createFieldFromSchema(processedSchema, key, schema, schema.required);
+  });
+
+  return { fields };
+}

package/src/lib/storage.ts

@@ -0,0 +1,108 @@
+/**
+ * The browser's localStorage and sessionStorage, for a page that may not be
+ * allowed either. Framed by another site (the app inside ChatGPT, Claude or
+ * Codex) with third-party storage blocked, reading `window.localStorage`
+ * itself throws a SecurityError; elsewhere a write can be refused (a full
+ * quota, some private modes). Neither reaches the caller: what the browser
+ * will not keep is kept in memory until the page goes away, so a value reads
+ * back the same and simply does not outlive the page.
+ *
+ * Every use of web storage goes through `localStore` and `sessionStore`; lint
+ * rejects the browser globals outside this module. Both are also what
+ * zustand's `createJSONStorage` expects (a `StateStorage`).
+ */
+
+/** The part of the DOM `Storage` interface the stores provide. */
+export interface WebStorage {
+  /** How many keys are stored. */
+  readonly length: number
+  /** The key at `index`, or null past the end. */
+  key(index: number): string | null
+  getItem(key: string): string | null
+  setItem(key: string, value: string): void
+  removeItem(key: string): void
+}
+
+/**
+ * A store over the Storage `resolve` returns. `resolve` runs once, on first
+ * use rather than when the module loads, and may throw or return nothing:
+ * the store is then memory only.
+ */
+export function createSafeStorage(resolve: () => Storage | null | undefined): WebStorage {
+  let browser: Storage | null | undefined
+  // What the browser does not hold: everything when there is no Storage, and
+  // otherwise each value it refused to write. A key here shadows the browser's.
+  const kept = new Map<string, string>()
+
+  const storage = (): Storage | null => {
+    if (browser === undefined) {
+      try {
+        browser = usable(resolve())
+      } catch {
+        browser = null
+      }
+    }
+    return browser
+  }
+
+  const keys = (): string[] => {
+    const browser = storage()
+    const all = new Set<string>()
+    for (let i = 0; browser && i < browser.length; i++) {
+      const key = browser.key(i)
+      if (key !== null) all.add(key)
+    }
+    for (const key of kept.keys()) all.add(key)
+    return [...all]
+  }
+
+  return {
+    get length() {
+      return kept.size === 0 ? (storage()?.length ?? 0) : keys().length
+    },
+    key(index) {
+      return (kept.size === 0 ? storage()?.key(index) : keys()[index]) ?? null
+    },
+    getItem(key) {
+      return kept.get(key) ?? storage()?.getItem(key) ?? null
+    },
+    setItem(key, value) {
+      const browser = storage()
+      if (browser) {
+        try {
+          browser.setItem(key, value)
+          kept.delete(key)
+          return
+        } catch {
+          // refused this write: the value is kept below instead
+        }
+      }
+      kept.set(key, String(value))
+    },
+    removeItem(key) {
+      kept.delete(key)
+      storage()?.removeItem(key)
+    },
+  }
+}
+
+// A Storage that answers the calls the store makes, else null. Node 25 gives
+// every process a `localStorage` global without its methods unless it is
+// started with --localstorage-file, and a DOM shim can hand that one back.
+function usable(candidate: Storage | null | undefined): Storage | null {
+  if (!candidate) return null
+  const s = candidate as Partial<Storage>
+  return typeof s.getItem === 'function' && typeof s.setItem === 'function' && typeof s.removeItem === 'function' && typeof s.key === 'function'
+    ? candidate
+    : null
+}
+
+// Without a window (a server render, a test) there is no web storage to ask
+// for. Node's own `localStorage` global is not it, and is left alone.
+const browserWindow = (): Window | undefined => (typeof window === 'undefined' ? undefined : window)
+
+/** localStorage: kept across visits when the browser allows it. */
+export const localStore = createSafeStorage(() => browserWindow()?.localStorage)
+
+/** sessionStorage: kept for the tab's lifetime when the browser allows it. */
+export const sessionStore = createSafeStorage(() => browserWindow()?.sessionStorage)