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

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

@@ -0,0 +1,66 @@
+import * as S from "effect-app/Schema"
+
+/*
+ * Checks if an AST node is a S.Redacted Declaration without encoding.
+ * These need to be swapped to S.RedactedFromValue for form usage
+ * because S.Redacted expects Redacted objects, not plain strings.
+ */
+const isRedactedWithoutEncoding = (ast: S.AST.AST): boolean =>
+  S.AST.isDeclaration(ast)
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Effect Schema AST annotations are loosely typed
+  && (ast.annotations as any)?.typeConstructor?._tag === "effect/Redacted"
+  && !ast.encoding
+
+/*
+ * Creates a form-compatible schema by replacing S.Redacted(X) with
+ * S.RedactedFromValue(X). S.Redacted is a Declaration that expects
+ * Redacted<A> on both encoded and type sides, so form inputs (which
+ * produce plain strings) fail validation. S.RedactedFromValue accepts
+ * plain values on the encoded side and wraps them in Redacted on decode.
+ */
+export const toFormSchema = <From, To>(
+  schema: S.Codec<To, From>
+): S.Codec<To, From> => {
+  const ast = schema.ast
+  const objAst = S.AST.isObjects(ast)
+    ? ast
+    : S.AST.isDeclaration(ast)
+    ? S.AST.toEncoded(ast)
+    : null
+
+  if (!objAst || !("propertySignatures" in objAst)) return schema
+
+  let hasRedacted = false
+  const props: Record<string, S.Struct.Fields[string]> = {}
+
+  for (const p of objAst.propertySignatures) {
+    if (isRedactedWithoutEncoding(p.type)) {
+      hasRedacted = true
+      const innerSchema = S.make((p.type as S.AST.Declaration).typeParameters[0])
+      props[p.name as string] = S.RedactedFromValue(innerSchema)
+    } else if (S.AST.isUnion(p.type)) {
+      const types = p.type.types
+      const redactedType = types.find(isRedactedWithoutEncoding)
+      if (redactedType) {
+        hasRedacted = true
+        const innerSchema = S.make((redactedType as S.AST.Declaration).typeParameters[0])
+        const hasNull = types.some(S.AST.isNull)
+        const hasUndefined = types.some(S.AST.isUndefined)
+        const base = S.RedactedFromValue(innerSchema)
+        props[p.name as string] = hasNull && hasUndefined
+          ? S.NullishOr(base)
+          : hasNull
+          ? S.NullOr(base)
+          : hasUndefined
+          ? S.UndefinedOr(base)
+          : base
+      } else {
+        props[p.name as string] = S.make(p.type)
+      }
+    } else {
+      props[p.name as string] = S.make(p.type)
+    }
+  }
+
+  return hasRedacted ? S.Struct(props) as unknown as S.Codec<To, From> : schema
+}

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

@@ -0,0 +1,78 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { DeepKeys } from "@tanstack/vue-form"
+import type * as S from "effect-app/Schema"
+import type { Redacted } from "effect/Redacted"
+
+// Recursively replace Redacted<A> with its inner type so DeepKeys treats it as a leaf
+type StripRedacted<T> = T extends Redacted<any> ? string
+  : T extends ReadonlyArray<infer U> ? ReadonlyArray<StripRedacted<U>>
+  : T extends Record<string, any> ? { [K in keyof T]: StripRedacted<T[K]> }
+  : T
+
+export type NestedKeyOf<T> = DeepKeys<StripRedacted<T>>
+
+// Field metadata type definitions
+export type BaseFieldMeta = {
+  required: boolean
+  nullableOrUndefined?: false | "undefined" | "null"
+  /**
+   * True when the schema property is `S.optionalKey` (AST
+   * `context.isOptional`) — i.e. the key should be ABSENT from the submitted
+   * object when empty, not present with `undefined`. Distinct from
+   * `required: false`, which may also mean "empty string is valid" for
+   * unconstrained `S.String` fields.
+   */
+  isOptionalKey?: boolean
+}
+
+export type StringFieldMeta = BaseFieldMeta & {
+  type: "string"
+  maxLength?: number
+  minLength?: number
+  format?: string
+}
+
+export type NumberFieldMeta = BaseFieldMeta & {
+  type: "number"
+  minimum?: number
+  maximum?: number
+  exclusiveMinimum?: number
+  exclusiveMaximum?: number
+  refinement?: "int"
+}
+
+export type SelectFieldMeta = BaseFieldMeta & {
+  type: "select"
+  members: any[] // TODO: should be non empty array?
+}
+
+export type MultipleFieldMeta = BaseFieldMeta & {
+  type: "multiple"
+  members: any[] // TODO: should be non empty array?
+  rest: readonly S.AST.AST[]
+}
+
+export type BooleanFieldMeta = BaseFieldMeta & {
+  type: "boolean"
+}
+
+export type DateFieldMeta = BaseFieldMeta & {
+  type: "date"
+}
+
+export type UnknownFieldMeta = BaseFieldMeta & {
+  type: "unknown"
+}
+
+export type FieldMeta =
+  | StringFieldMeta
+  | NumberFieldMeta
+  | SelectFieldMeta
+  | MultipleFieldMeta
+  | BooleanFieldMeta
+  | DateFieldMeta
+  | UnknownFieldMeta
+
+export type MetaRecord<T = string> = {
+  [K in NestedKeyOf<T>]?: FieldMeta
+}

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 * as S from "effect-app/Schema"
+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
+  }
+}