@effect-app/vue-components 4.0.0-beta.22 → 4.0.0-beta.220

package/src/components/OmegaForm/meta/walker.ts

@@ -0,0 +1,248 @@
+/* eslint-disable @typescript-eslint/no-explicit-any -- AST walker interops with Effect Schema generics */
+/* eslint-disable @typescript-eslint/no-use-before-define -- mutual recursion between walk and helpers (handleStruct/handleUnion/etc.) */
+import { S } from "effect-app"
+import { getFieldMetadataFromAst } from "./checks"
+import { isNullableOrUndefined, unwrapDeclaration } from "./createMeta"
+import type { FieldMeta, MetaRecord, NestedKeyOf, SelectFieldMeta } from "./types"
+
+const isNullishType = (property: S.AST.AST) => S.AST.isUndefined(property) || S.AST.isNull(property)
+
+// TODO: remove after manual _tag deprecation — S.Struct({ _tag: S.Literal("X") }) wraps as Union([Literal("X")])
+const unwrapSingleLiteralUnion = (ast: S.AST.AST): S.AST.AST =>
+  S.AST.isUnion(ast) && ast.types.length === 1 && S.AST.isLiteral(ast.types[0])
+    ? ast.types[0]
+    : ast
+
+const unwrapNestedUnions = (types: readonly S.AST.AST[]): readonly S.AST.AST[] =>
+  types.flatMap((type) => S.AST.isUnion(type) ? unwrapNestedUnions(type.types) : [type])
+
+export type WalkerContext<T> = {
+  acc: Partial<MetaRecord<T>>
+  unionMeta: Record<string, MetaRecord<T>>
+}
+
+export type ParentMeta = {
+  required: boolean
+  nullableOrUndefined: false | "null" | "undefined"
+  /** Set when iterating the members of a nullable discriminated union */
+  isNullableDiscriminatedUnion?: boolean
+  /** Set when this property was declared with S.optionalKey */
+  isOptionalKey?: boolean
+}
+
+export const leafMetaForAst = (
+  ast: S.AST.AST,
+  parentMeta: ParentMeta
+): FieldMeta => {
+  const { nullableOrUndefined, required } = parentMeta
+
+  if (S.AST.isArrays(ast)) {
+    return {
+      required,
+      nullableOrUndefined,
+      type: "multiple",
+      members: ast.elements,
+      rest: ast.rest
+    } as FieldMeta
+  }
+
+  if (S.AST.isLiteral(ast)) {
+    return {
+      required,
+      nullableOrUndefined,
+      type: "select",
+      members: [ast.literal]
+    } as FieldMeta
+  }
+
+  return {
+    ...getFieldMetadataFromAst(ast),
+    required,
+    nullableOrUndefined
+  } as FieldMeta
+}
+
+export const walkStruct = <T>(
+  propertySignatures: readonly S.AST.PropertySignature[],
+  parent: string,
+  parentMeta: ParentMeta,
+  ctx: WalkerContext<T>
+): void => {
+  for (const p of propertySignatures) {
+    const key = parent ? `${parent}.${p.name.toString()}` : p.name.toString()
+    const nullableOrUndefined = isNullableOrUndefined(p.type)
+    const isOptionalKey = (p.type as any).context?.isOptional === true
+
+    let isRequired: boolean
+    if (parentMeta.isNullableDiscriminatedUnion && p.name.toString() === "_tag") {
+      isRequired = false
+    } else if (!parentMeta.required) {
+      isRequired = false
+    } else if (isOptionalKey) {
+      isRequired = false
+    } else {
+      isRequired = !nullableOrUndefined
+    }
+
+    walk(
+      p.type,
+      key,
+      { required: isRequired, nullableOrUndefined, isOptionalKey },
+      ctx
+    )
+  }
+}
+
+export const classifyAndWalkUnion = <T>(
+  unionAst: S.AST.Union,
+  key: string,
+  parentMeta: ParentMeta,
+  ctx: WalkerContext<T>
+): void => {
+  const { acc } = ctx
+  const unwrappedTypes = unwrapNestedUnions(unionAst.types).map(unwrapDeclaration)
+  const nonNullTypes = unwrappedTypes.filter((t) => !isNullishType(t))
+
+  // Boolean literal shortcut (single-value union wrapping a boolean literal)
+  if (nonNullTypes.length === 1 && S.AST.isLiteral(nonNullTypes[0]) && typeof nonNullTypes[0].literal === "boolean") {
+    acc[key as NestedKeyOf<T>] = leafMetaForAst(nonNullTypes[0], parentMeta)
+    return
+  }
+
+  if (nonNullTypes.some(S.AST.isObjects)) {
+    const isNullableDiscriminatedUnion = !!parentMeta.nullableOrUndefined && nonNullTypes.length > 1
+
+    // Mixed union: also create a parent leaf entry from the first non-struct member
+    if (!parentMeta.nullableOrUndefined && key) {
+      const firstNonStruct = nonNullTypes.find((t) => !S.AST.isObjects(t))
+      if (firstNonStruct) {
+        acc[key as NestedKeyOf<T>] = leafMetaForAst(firstNonStruct, parentMeta)
+      }
+    }
+
+    const discriminatorValues: any[] = []
+    const branchParentMeta: ParentMeta = isNullableDiscriminatedUnion
+      ? { required: true, nullableOrUndefined: false, isNullableDiscriminatedUnion: true }
+      : { required: true, nullableOrUndefined: false }
+
+    for (const memberType of nonNullTypes) {
+      if (!S.AST.isObjects(memberType)) continue
+
+      const tagProp = memberType.propertySignatures.find((p) => p.name.toString() === "_tag")
+      const resolvedTagType = tagProp ? unwrapSingleLiteralUnion(tagProp.type) : null
+      let tagValue: string | null = null
+
+      if (resolvedTagType && S.AST.isLiteral(resolvedTagType)) {
+        tagValue = resolvedTagType.literal as string
+        if (!discriminatorValues.includes(tagValue)) discriminatorValues.push(tagValue)
+      }
+
+      const branchCtx: WalkerContext<T> = { acc: {}, unionMeta: ctx.unionMeta }
+      walkStruct(memberType.propertySignatures, key, branchParentMeta, branchCtx)
+
+      if (tagValue) {
+        const existing = ctx.unionMeta[tagValue]
+        if (existing) Object.assign(existing, branchCtx.acc as MetaRecord<T>)
+        else ctx.unionMeta[tagValue] = branchCtx.acc as MetaRecord<T>
+      }
+
+      for (const [metaKey, metaValue] of Object.entries(branchCtx.acc)) {
+        const existing = acc[metaKey as NestedKeyOf<T>]
+        if (existing && existing.type === "select" && (metaValue as any)?.type === "select") {
+          existing.members = [
+            ...existing.members,
+            ...(metaValue as SelectFieldMeta).members.filter((m: any) => !existing.members.includes(m))
+          ]
+        } else {
+          acc[metaKey as NestedKeyOf<T>] = metaValue as FieldMeta
+        }
+      }
+    }
+
+    if (discriminatorValues.length > 0) {
+      const tagKey = key ? `${key}._tag` : "_tag"
+      const existing = acc[tagKey as NestedKeyOf<T>]
+      if (existing && existing.type === "select") {
+        for (const v of discriminatorValues) {
+          if (!existing.members.includes(v)) existing.members.push(v)
+        }
+      } else {
+        acc[tagKey as NestedKeyOf<T>] = {
+          type: "select",
+          members: discriminatorValues,
+          required: !isNullableDiscriminatedUnion
+        } as FieldMeta
+      }
+    }
+    return
+  }
+
+  const ast = nonNullTypes.find(S.AST.isArrays)
+  if (ast) {
+    walk(ast, key, parentMeta, ctx)
+    return
+  }
+
+  // Literal / primitive union (e.g. legacy _tag pattern)
+  const resolvedTypes = unwrappedTypes.map(unwrapSingleLiteralUnion)
+  if (resolvedTypes.every((_) => isNullishType(_) || S.AST.isLiteral(_))) {
+    const { isOptionalKey, nullableOrUndefined, required } = parentMeta
+    const leaf: FieldMeta = {
+      required,
+      nullableOrUndefined,
+      type: "select",
+      members: resolvedTypes.filter(S.AST.isLiteral).map((t) => t.literal)
+    } as FieldMeta
+    if (isOptionalKey) leaf.isOptionalKey = true
+    acc[key as NestedKeyOf<T>] = leaf
+    return
+  }
+
+  // Fallback: recurse into first non-null type
+  const nonNullType = nonNullTypes[0]
+  if (nonNullType) walk(nonNullType, key, parentMeta, ctx)
+}
+
+export const walk = <T>(
+  ast: S.AST.AST,
+  key: string,
+  parentMeta: ParentMeta,
+  ctx: WalkerContext<T>
+): void => {
+  ast = unwrapDeclaration(ast)
+  const { acc } = ctx
+
+  if (S.AST.isObjects(ast)) {
+    walkStruct(ast.propertySignatures, key, parentMeta, ctx)
+    return
+  }
+
+  if (S.AST.isUnion(ast)) {
+    classifyAndWalkUnion(ast, key, parentMeta, ctx)
+    return
+  }
+
+  if (S.AST.isArrays(ast)) {
+    const restElement = ast.rest.length > 0 ? unwrapDeclaration(ast.rest[0]) : null
+    if (restElement && S.AST.isObjects(restElement)) {
+      // Array-of-struct: skip creating a meta entry for the array itself,
+      // recurse into the element struct's properties instead
+      walkStruct(restElement.propertySignatures, key, { required: true, nullableOrUndefined: false }, ctx)
+      return
+    }
+
+    // Primitive or tuple array
+    acc[key as NestedKeyOf<T>] = leafMetaForAst(ast, parentMeta)
+    return
+  }
+
+  // Leaf primitive / literal / unknown
+  const { isOptionalKey, nullableOrUndefined, required } = parentMeta
+  const adjusted: ParentMeta = {
+    required: required && (!S.AST.isString(ast) || !!getFieldMetadataFromAst(ast).minLength),
+    nullableOrUndefined
+  }
+  const leaf = leafMetaForAst(ast, adjusted)
+  if (isOptionalKey) leaf.isOptionalKey = true
+  acc[key as NestedKeyOf<T>] = leaf
+}

package/src/components/OmegaForm/persistency.ts

@@ -0,0 +1,247 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import { isObject } from "@vueuse/core"
+import { computed, type ComputedRef, onBeforeUnmount, onMounted, onUnmounted } from "vue"
+import { type MetaRecord } from "./meta/types"
+
+export type Policies = "local" | "session" | "querystring"
+export type DefaultValuesPriorityUnion = "tanstack" | "persistency" | "schema"
+
+// Backward-compatible alias for the legacy lowercased-prefix type name.
+export type defaultValuesPriorityUnion = DefaultValuesPriorityUnion
+
+export interface PersistencyConfig {
+  /** Order of importance:
+   * - "querystring": Highest priority when persisting
+   * - "local" and then "session": Lower priority storage options
+   */
+  policies?: ReadonlyArray<Policies>
+  overrideDefaultValues?: "deprecated: use defaultValuesPriority"
+  id?: string
+  keys?: ReadonlyArray<string> | "You should only use one of banKeys or keys, not both, moron"
+  banKeys?: ReadonlyArray<string> | "You should only use one of banKeys or keys, not both, moron"
+}
+
+export function deepMerge(target: any, source: any) {
+  const result = { ...target }
+  for (const key in source) {
+    if (Array.isArray(source[key])) {
+      // Arrays should be copied directly, not deep merged
+      result[key] = source[key]
+    } else if (source[key] && isObject(source[key])) {
+      result[key] = deepMerge(result[key], source[key])
+    } else {
+      result[key] = source[key]
+    }
+  }
+  return result
+}
+
+const includesPolicy = (arr: ReadonlyArray<Policies>, policy: Policies) => {
+  return arr.includes(policy)
+}
+
+export interface UsePersistencyOptions<From> {
+  meta: MetaRecord<From>
+  persistency?: PersistencyConfig
+  preventWindowExit?: "prevent" | "prevent-and-reset" | "nope"
+  defaultValuesPriority?: DefaultValuesPriorityUnion[] | readonly DefaultValuesPriorityUnion[]
+  /** Tanstack-provided default values (highest priority by default). */
+  tanstackDefaultValues?: any
+  /** Lazy schema-derived defaults factory. */
+  schemaDefaultValues: () => any
+  /**
+   * Lazy accessor for the form. Lazy because persistency is created BEFORE
+   * the form (its `defaultValues` are passed into `useForm`), but the
+   * persistence callbacks (`persistData`, `saveDataInUrl`, the
+   * `beforeunload` listener) only run later and need the live form.
+   */
+  getForm: () => {
+    store: { state: { values: any; isDirty: boolean } }
+    getFieldValue: (path: any) => any
+  }
+}
+
+export interface UsePersistencyReturn {
+  defaultValues: ComputedRef
+  persistencyKey: ComputedRef<string>
+  persistData: () => void
+  saveDataInUrl: () => void
+  clearUrlParams: () => void
+}
+
+/**
+ * Encapsulates form-data persistency: loading default values from
+ * localStorage / sessionStorage / querystring, persisting them on unmount
+ * or window blur, and the optional `preventWindowExit` warning listener.
+ *
+ * The `prevent-and-reset` reset-on-success behavior is intentionally NOT
+ * owned here — the consumer wires that to its own form submit lifecycle.
+ */
+export const usePersistency = <From>(opts: UsePersistencyOptions<From>): UsePersistencyReturn => {
+  const { getForm, meta, persistency, preventWindowExit, schemaDefaultValues, tanstackDefaultValues } = opts
+
+  const persistencyKey = computed(() => {
+    if (persistency?.id) {
+      return persistency.id
+    }
+    const path = window.location.pathname
+    const keys = Object.keys(meta)
+    return `${path}-${keys.join("-")}`
+  })
+
+  const clearUrlParams = () => {
+    const params = new URLSearchParams(window.location.search)
+    params.delete(persistencyKey.value)
+    const url = new URL(window.location.href)
+    url.search = params.toString()
+    window.history.replaceState({}, "", url.toString())
+  }
+
+  const defaultValues = computed(() => {
+    // will contain what we get from querystring or local/session storage
+    let persistencyDefaultValues
+
+    if (
+      // query string has higher priority than local/session storage
+      persistency?.policies
+      && !persistencyDefaultValues
+      && (includesPolicy(persistency.policies, "local")
+        || includesPolicy(persistency.policies, "session"))
+    ) {
+      const storage = includesPolicy(persistency.policies, "local")
+        ? localStorage
+        : sessionStorage
+      if (storage) {
+        try {
+          const value = JSON.parse(
+            storage.getItem(persistencyKey.value) || "{}"
+          )
+          storage.removeItem(persistencyKey.value)
+          persistencyDefaultValues = value
+        } catch (error) {
+          console.error(error)
+        }
+      }
+    }
+    if (persistency?.policies && includesPolicy(persistency.policies, "querystring")) {
+      try {
+        const params = new URLSearchParams(window.location.search)
+        const value = params.get(persistencyKey.value)
+        clearUrlParams()
+        if (value) {
+          persistencyDefaultValues = deepMerge(persistencyDefaultValues || {}, JSON.parse(value))
+        }
+      } catch (error) {
+        console.error(error)
+      }
+    }
+
+    // to be sure we have a valid object at the end of the gathering process
+    persistencyDefaultValues ??= {}
+
+    const defaults: Record<DefaultValuesPriorityUnion, any> = {
+      tanstack: tanstackDefaultValues || {},
+      persistency: persistencyDefaultValues,
+      schema: schemaDefaultValues()
+    }
+
+    return [...(opts.defaultValuesPriority || ["tanstack", "persistency", "schema"] as const)].reverse().reduce(
+      (acc: any, m: DefaultValuesPriorityUnion) => {
+        if (!Object.keys(acc).length) {
+          return defaults[m]
+        }
+        return deepMerge(acc, defaults[m])
+      },
+      {}
+    )
+  })
+
+  const createNestedObjectFromPaths = (paths: string[]) =>
+    paths.reduce((result, path) => {
+      const parts = path.split(".")
+      parts.reduce((acc, part, i) => {
+        if (i === parts.length - 1) {
+          acc[part] = getForm().getFieldValue(path as any)
+        } else {
+          acc[part] = acc[part] ?? {}
+        }
+        return acc[part]
+      }, result)
+      return result
+    }, {} as Record<string, any>)
+
+  const persistFilter = (p: PersistencyConfig | undefined) => {
+    if (!p) return
+    const { banKeys, keys } = p
+    if (Array.isArray(keys)) {
+      return createNestedObjectFromPaths(keys as string[])
+    }
+    if (Array.isArray(banKeys)) {
+      const subs = Object.keys(meta).filter((metakey) => banKeys.includes(metakey))
+      return createNestedObjectFromPaths(subs)
+    }
+    return getForm().store.state.values
+  }
+
+  const persistData = () => {
+    if (!persistency?.policies || persistency.policies.length === 0) {
+      return
+    }
+    if (
+      includesPolicy(persistency.policies, "local")
+      || includesPolicy(persistency.policies, "session")
+    ) {
+      const storage = includesPolicy(persistency.policies, "local")
+        ? localStorage
+        : sessionStorage
+      if (!storage) return
+      const values = persistFilter(persistency)
+      return storage.setItem(persistencyKey.value, JSON.stringify(values))
+    }
+  }
+
+  const saveDataInUrl = () => {
+    if (!persistency?.policies || persistency.policies.length === 0) {
+      return
+    }
+    if (includesPolicy(persistency.policies, "querystring")) {
+      const values = persistFilter(persistency)
+      const searchParams = new URLSearchParams(window.location.search)
+      searchParams.set(persistencyKey.value, JSON.stringify(values))
+      const url = new URL(window.location.href)
+      url.search = searchParams.toString()
+      window.history.replaceState({}, "", url.toString())
+    }
+  }
+
+  const preventWindowExitListener = (e: BeforeUnloadEvent) => {
+    if (getForm().store.state.isDirty) {
+      e.preventDefault()
+    }
+  }
+
+  onUnmounted(persistData)
+
+  onMounted(() => {
+    window.addEventListener("beforeunload", persistData)
+    window.addEventListener("blur", saveDataInUrl)
+    if (preventWindowExit && preventWindowExit !== "nope") {
+      window.addEventListener("beforeunload", preventWindowExitListener)
+    }
+  })
+  onBeforeUnmount(() => {
+    window.removeEventListener("beforeunload", persistData)
+    window.removeEventListener("blur", saveDataInUrl)
+    if (preventWindowExit && preventWindowExit !== "nope") {
+      window.removeEventListener("beforeunload", preventWindowExitListener)
+    }
+  })
+
+  return {
+    defaultValues,
+    persistencyKey,
+    persistData,
+    saveDataInUrl,
+    clearUrlParams
+  }
+}

package/src/components/OmegaForm/submit.ts

@@ -0,0 +1,128 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import * as api from "@opentelemetry/api"
+import type { DeepKeys, StandardSchemaV1Issue, ValidationError, ValidationErrorMap } from "@tanstack/vue-form"
+import { Data, Effect, Fiber, Option } from "effect-app"
+import { runtimeFiberAsPromise } from "effect-app/utils"
+import type { Fiber as EffectFiber } from "effect/Fiber"
+import type { OmegaFormApi, OmegaFormParams } from "./types"
+
+export class FormErrors<From> extends Data.TaggedError("FormErrors")<{
+  form: {
+    // TODO: error shapes seem off, with `undefined` etc..
+    errors: (Record<string, StandardSchemaV1Issue[]> | undefined)[]
+    errorMap: ValidationErrorMap<
+      undefined,
+      undefined,
+      Record<string, StandardSchemaV1Issue[]>,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined,
+      undefined
+    >
+  }
+  fields: Record<DeepKeys<From>, {
+    errors: ValidationError[]
+    errorMap: ValidationErrorMap
+  }>
+}> {}
+
+export const wrapWithSpan = (span: api.Span | undefined, toWrap: () => any) => {
+  return span ? api.context.with(api.trace.setSpan(api.context.active(), span), toWrap) : toWrap()
+}
+
+export type UserOnSubmit<From, To> = (props: {
+  formApi: OmegaFormParams<From, To>
+  meta: any
+  value: To
+}) => Promise<any> | EffectFiber<any, any> | Effect.Effect<unknown, any>
+
+export type RunPromise = <A, E>(eff: Effect.Effect<A, E>) => Promise<A>
+
+/**
+ * Wraps the user's `onSubmit` to:
+ * - run inside the OpenTelemetry span passed via `meta.currentSpan`
+ * - decode the raw form `value` (validators only validate, they don't transform)
+ * - normalize Promise / Effect / Fiber return values to a Promise
+ *
+ * Returns `undefined` when `userOnSubmit` is `undefined` (so callers can pass it
+ * directly to `useForm({ onSubmit })` without changing semantics).
+ */
+export const wrapOnSubmit = <From, To>(
+  userOnSubmit: UserOnSubmit<From, To> | undefined,
+  decode: (value: From) => Effect.Effect<To, any>,
+  runPromise: RunPromise
+) => {
+  if (!userOnSubmit) return undefined
+  return ({ formApi, meta, value }: { formApi: OmegaFormParams<From, To>; meta: any; value: From }) =>
+    wrapWithSpan(meta?.currentSpan, async () => {
+      // validators only validate, they don't actually transform, so we have to do that manually here.
+      const parsedValue = await runPromise(decode(value))
+      const r = userOnSubmit({
+        formApi: formApi as OmegaFormApi<From, To>,
+        meta,
+        value: parsedValue
+      })
+      if (Fiber.isFiber(r)) {
+        return await runtimeFiberAsPromise(r)
+      }
+      if (Effect.isEffect(r)) {
+        const effectResult = await runPromise(r)
+        return Fiber.isFiber(effectResult)
+          ? await runtimeFiberAsPromise(effectResult)
+          : effectResult
+      }
+      return r
+    })
+}
+
+/**
+ * Builds the public submit handlers from a `useForm`-returned `form`:
+ * - `handleSubmit` injects the current OpenTelemetry span as `meta.currentSpan`.
+ * - `handleSubmitEffect` runs `handleSubmit` inside an Effect that picks up the
+ *   ambient `Effect.currentSpan`. With `checkErrors: true`, it fails with
+ *   `FormErrors<From>` when validation produced errors.
+ */
+export const makeSubmitHandlers = <From, To>(
+  form: OmegaFormApi<From, To>
+) => {
+  const hs = form.handleSubmit.bind(form)
+
+  const handleSubmitInner: typeof form.handleSubmit = async (meta?: Record<string, any>) => {
+    return await hs(meta)
+  }
+
+  const handleSubmit = (meta?: Record<string, any>) => {
+    const span = api.trace.getSpan(api.context.active())
+    return handleSubmitInner({ currentSpan: span, ...meta })
+  }
+
+  const handleSubmitEffect_ = (meta?: Record<string, any>) =>
+    Effect.currentSpan.pipe(
+      Effect.option,
+      Effect
+        .flatMap((span) =>
+          Effect.promise(() => handleSubmitInner(Option.isSome(span) ? { currentSpan: span.value, ...meta } : meta))
+        )
+    )
+
+  const handleSubmitEffect: {
+    (options: { checkErrors: true; meta?: Record<string, any> }): Effect.Effect<void, FormErrors<From>>
+    (options?: { meta?: Record<string, any> }): Effect.Effect<void>
+  } = (
+    options?: { meta?: Record<string, any>; checkErrors?: true }
+  ): any =>
+    options?.checkErrors
+      ? handleSubmitEffect_(options?.meta).pipe(Effect.flatMap(Effect.fnUntraced(function*() {
+        const errors = form.getAllErrors()
+        if (Object.keys(errors.fields).length || errors.form.errors.length) {
+          return yield* Effect.fail(new FormErrors({ form: errors.form, fields: errors.fields }))
+        }
+      })))
+      : handleSubmitEffect_(options?.meta)
+
+  return { handleSubmit, handleSubmitEffect }
+}