@leavepulse/ui 0.43.4 → 0.45.0

package/src/components/tags.ts

@@ -0,0 +1,62 @@
+/*
+ * The add pipeline behind LpTagsInput, kept pure so its rules are testable:
+ * split what was typed or pasted, normalise each part, then accept or reject
+ * it against the limit, the duplicate policy and the consumer's validator.
+ */
+
+export type TagDuplicates = "reject" | "ignore" | "allow"
+
+/** An error message for an invalid tag; anything else accepts it. */
+export type TagValidator = (tag: string, tags: readonly string[]) => string | null | undefined | void
+
+export type TagRejection = { value: string; reason: "max" | "duplicate" | "invalid"; message?: string }
+
+export interface AddTagsOptions {
+  max?: number
+  duplicates?: TagDuplicates
+  validate?: TagValidator
+  normalize?: (tag: string) => string
+}
+
+export function splitTags(text: string, delimiter: string | RegExp | readonly string[]): string[] {
+  const parts =
+    delimiter instanceof RegExp
+      ? text.split(new RegExp(delimiter.source, delimiter.flags.includes("g") ? delimiter.flags : `${delimiter.flags}g`))
+      : (typeof delimiter === "string" ? [delimiter] : delimiter).reduce<string[]>(
+          (acc, d) => (d ? acc.flatMap((p) => p.split(d)) : acc),
+          [text],
+        )
+  return parts.map((p) => p.trim()).filter(Boolean)
+}
+
+export function addTags(
+  current: readonly string[],
+  candidates: readonly string[],
+  options: AddTagsOptions = {},
+): { tags: string[]; rejected: TagRejection[]; ignored: string[] } {
+  const tags = [...current]
+  const rejected: TagRejection[] = []
+  /** Repeats dropped under the "ignore" policy, as stored, so the UI can point at the original. */
+  const ignored: string[] = []
+  const duplicates = options.duplicates ?? "reject"
+  for (const candidate of candidates) {
+    const value = options.normalize ? options.normalize(candidate) : candidate
+    if (!value) continue
+    if (tags.includes(value) && duplicates !== "allow") {
+      if (duplicates === "reject") rejected.push({ value: candidate, reason: "duplicate" })
+      else ignored.push(value)
+      continue
+    }
+    if (options.max && tags.length >= options.max) {
+      rejected.push({ value: candidate, reason: "max" })
+      continue
+    }
+    const message = options.validate?.(value, tags)
+    if (typeof message === "string" && message) {
+      rejected.push({ value: candidate, reason: "invalid", message })
+      continue
+    }
+    tags.push(value)
+  }
+  return { tags, rejected, ignored }
+}

package/src/composables/useField.ts

@@ -0,0 +1,83 @@
+import { computed, inject, provide, useId, type ComputedRef, type InjectionKey } from "vue"
+import type { FieldNoticeOptions } from "./useFieldNotice"
+
+/*
+ * What a form field tells the control inside it: the id its label points at,
+ * the id of the hint/error line the control should be described by, and the
+ * states the control should reflect. LpFormField provides it; every kit control
+ * consumes it, and so can a consumer's own control placed inside a field.
+ */
+export interface FieldContext {
+  id: string
+  /** Id of the visible label, for controls a `<label for>` cannot name (groups). */
+  labelId?: string
+  describedBy?: string
+  invalid: boolean
+  required: boolean
+  disabled: boolean
+  /** Float a short note under the control without moving the layout (see useFieldNotice). */
+  notify?: (text: string, options?: FieldNoticeOptions) => void
+  clearNotice?: () => void
+}
+
+export const LP_FIELD: InjectionKey<ComputedRef<FieldContext>> = Symbol.for("lp-field")
+
+export function provideField(context: ComputedRef<FieldContext>): void {
+  provide(LP_FIELD, context)
+}
+
+/** The nearest LpFormField's context, or null outside one. */
+export function useField(): ComputedRef<FieldContext> | null {
+  return inject(LP_FIELD, null)
+}
+
+export function fieldMessageId(id: string): string {
+  return `${id}-message`
+}
+
+export interface FieldControlState {
+  /** The control wraps itself in its own LpFormField (it has a label, hint or error prop). */
+  wrapped: boolean
+  /** That own field renders a hint or error line. */
+  hasMessage?: boolean
+  /** An id the consumer set on the control, which must win over a generated one. */
+  id?: string
+  invalid?: boolean
+  required?: boolean
+  disabled?: boolean
+}
+
+/**
+ * The field state a control renders with: its own wrapping field when it has
+ * one, otherwise the field around it, with the control's own flags or-ed in.
+ * `id` is undefined only for a bare control outside any field.
+ */
+export function useFieldControl(
+  own: () => FieldControlState,
+): ComputedRef<Omit<FieldContext, "id"> & { id?: string }> {
+  const outer = useField()
+  const generated = useId()
+  return computed(() => {
+    const state = own()
+    if (state.wrapped) {
+      const id = state.id ?? generated
+      return {
+        id,
+        labelId: undefined,
+        describedBy: state.hasMessage ? fieldMessageId(id) : undefined,
+        invalid: !!state.invalid,
+        required: !!state.required,
+        disabled: !!state.disabled,
+      }
+    }
+    const field = outer?.value
+    return {
+      id: state.id ?? field?.id,
+      labelId: field?.labelId,
+      describedBy: field?.describedBy,
+      invalid: !!state.invalid || !!field?.invalid,
+      required: !!state.required || !!field?.required,
+      disabled: !!state.disabled || !!field?.disabled,
+    }
+  })
+}

package/src/composables/useFieldNotice.ts

@@ -0,0 +1,59 @@
+import { getCurrentScope, onScopeDispose, ref, type Ref } from "vue"
+
+/*
+ * A short note about what just happened to a field ("already added", "up to 5
+ * items") that floats under it instead of taking a line in the layout. A
+ * validation message belongs in the field's message line and may push the
+ * form down; a passing remark about one keystroke should not, or every refused
+ * paste would jolt the fields below.
+ *
+ * Render it with LpFieldNotice inside a `relative` box around the control.
+ * LpFormField does that for its control and hands `notify` down the field
+ * context, so a control inside a field (or the app) can raise one without
+ * owning any markup.
+ */
+export type FieldNoticeTone = "info" | "danger"
+
+export interface FieldNoticeOptions {
+  tone?: FieldNoticeTone
+  /** How long it stays, in ms. 0 keeps it until `clear()`. */
+  duration?: number
+}
+
+export interface FieldNotice {
+  message: Ref<string>
+  tone: Ref<FieldNoticeTone>
+  /** Bumped on every `show`, so a repeat of the same note can nudge rather than sit still. */
+  seq: Ref<number>
+  show: (text: string, options?: FieldNoticeOptions) => void
+  clear: () => void
+}
+
+export const FIELD_NOTICE_MS = 2600
+
+export function useFieldNotice(defaultDuration = FIELD_NOTICE_MS): FieldNotice {
+  const message = ref("")
+  const tone = ref<FieldNoticeTone>("info")
+  const seq = ref(0)
+  let timer: ReturnType<typeof setTimeout> | undefined
+
+  function clear() {
+    if (timer) clearTimeout(timer)
+    timer = undefined
+    message.value = ""
+  }
+
+  function show(text: string, options: FieldNoticeOptions = {}) {
+    if (timer) clearTimeout(timer)
+    timer = undefined
+    message.value = text
+    tone.value = options.tone ?? "info"
+    seq.value++
+    const duration = options.duration ?? defaultDuration
+    if (duration > 0 && text) timer = setTimeout(clear, duration)
+  }
+
+  if (getCurrentScope()) onScopeDispose(clear)
+
+  return { message, tone, seq, show, clear }
+}

package/src/composables/useForm.ts

@@ -0,0 +1,314 @@
+import {
+  computed,
+  reactive,
+  ref,
+  toRaw,
+  toValue,
+  watch,
+  type ComputedRef,
+  type MaybeRefOrGetter,
+  type Ref,
+  type UnwrapRef,
+} from "vue"
+
+/*
+ * Form state that every form ends up writing by hand: the values, which
+ * fields were touched, whether anything differs from what was loaded, the
+ * errors, and a submit that cannot run twice.
+ *
+ * Errors are computed for every field but shown only once a field was touched
+ * (blurred, or edited after a blur) or a submit was attempted, so nobody is
+ * told off for a field they have not reached yet.
+ *
+ * `dirty` is the same signal useFormDraft asks for, so the two pair directly:
+ *
+ * ```ts
+ * const form = useForm({ initial: () => record.value, rules: { email: required } })
+ * const draft = useFormDraft({ key: () => `draft:${id}`, value: () => form.values, dirty: form.dirty })
+ * function restore() { form.setValues(draft.read() ?? {}); draft.discard() }
+ * const save = form.handleSubmit(async (values) => { await api.save(values); draft.discard() })
+ * ```
+ *
+ * A reactive `initial` (a record that loads after mount) is adopted while the
+ * form is untouched, and becomes the new baseline for `dirty`; once the user
+ * has changed something, a reload of the record no longer overwrites it.
+ */
+
+export type FormErrorMessage = string | null | undefined | void | false
+export type FieldRule<V, T> = (value: V, values: T) => FormErrorMessage | Promise<FormErrorMessage>
+export type FormRules<T> = { [K in keyof T]?: FieldRule<T[K], T> | FieldRule<T[K], T>[] }
+export type FormErrors<T> = Partial<Record<keyof T | "form", string>>
+
+export interface UseFormOptions<T extends object> {
+  initial: MaybeRefOrGetter<T>
+  rules?: FormRules<T>
+  /** Cross-field checks; return messages by field, or under `form` for the whole form. */
+  validate?: (values: T) => FormErrors<T> | void | Promise<FormErrors<T> | void>
+}
+
+export interface FieldBinding<V> {
+  modelValue: V
+  "onUpdate:modelValue": (value: V) => void
+  onBlur: () => void
+  error: string | undefined
+  invalid: boolean
+}
+
+export interface UseForm<T extends object> {
+  values: UnwrapRef<T>
+  /** Errors as currently computed, shown or not. */
+  errors: ComputedRef<FormErrors<T>>
+  /** Errors the user should see now. */
+  visibleErrors: ComputedRef<FormErrors<T>>
+  touched: Partial<Record<keyof T, boolean>>
+  dirty: ComputedRef<boolean>
+  valid: ComputedRef<boolean>
+  validating: Ref<boolean>
+  submitting: Ref<boolean>
+  submitCount: Ref<number>
+  isDirty: (name: keyof T) => boolean
+  /** Props for a kit control: `<LpInput v-bind="form.field('email')" />`. */
+  field: <K extends keyof T>(name: K) => FieldBinding<T[K]>
+  set: <K extends keyof T>(name: K, value: T[K]) => void
+  setValues: (values: Partial<T>) => void
+  touch: (name: keyof T) => void
+  /** Run the checks for one field, or all of them; resolves to whether it passed. */
+  validate: (name?: keyof T) => Promise<boolean>
+  /** Errors from elsewhere, a server reply most often. Cleared field by field on edit. */
+  setErrors: (errors: FormErrors<T>) => void
+  /** Back to `values` (or the current initial), which also become the new baseline. */
+  reset: (values?: T) => void
+  /**
+   * Wrap the submit handler: touches everything, validates, and calls `fn`
+   * only when valid and not already submitting. A successful `fn` makes the
+   * submitted values the new baseline.
+   */
+  handleSubmit: (fn: (values: T) => unknown) => (event?: Event) => Promise<void>
+}
+
+function clone<T>(value: T): T {
+  try {
+    return structuredClone(toRaw(value))
+  } catch {
+    return JSON.parse(JSON.stringify(value)) as T
+  }
+}
+
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (Object.is(a, b)) return true
+  if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime()
+  if (typeof a !== "object" || typeof b !== "object" || a === null || b === null) return false
+  if (Array.isArray(a) !== Array.isArray(b)) return false
+  const ka = Object.keys(a)
+  const kb = Object.keys(b)
+  if (ka.length !== kb.length) return false
+  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]))
+}
+
+function message(result: FormErrorMessage): string | undefined {
+  return typeof result === "string" && result ? result : undefined
+}
+
+export function useForm<T extends object>(options: UseFormOptions<T>): UseForm<T> {
+  let baseline = clone(toValue(options.initial))
+  const values = reactive(clone(baseline)) as UnwrapRef<T>
+  const plain = () => values as unknown as T
+  const errors = reactive<FormErrors<T>>({}) as FormErrors<T>
+  const external = reactive<FormErrors<T>>({}) as FormErrors<T>
+  const touched = reactive<Partial<Record<keyof T, boolean>>>({}) as Partial<Record<keyof T, boolean>>
+  const validating = ref(false)
+  const submitting = ref(false)
+  const submitCount = ref(0)
+  const runs = new Map<keyof T | "form", number>()
+  const baseVersion = ref(0)
+
+  const keys = (): (keyof T)[] => Object.keys(plain()) as (keyof T)[]
+
+  const dirty = computed(() => {
+    void baseVersion.value
+    return !deepEqual(plain(), baseline)
+  })
+
+  function isDirty(name: keyof T): boolean {
+    void baseVersion.value
+    return !deepEqual(plain()[name], baseline[name])
+  }
+
+  async function checkField(name: keyof T): Promise<string | undefined> {
+    const rule = options.rules?.[name]
+    const list = (Array.isArray(rule) ? rule : rule ? [rule] : []) as FieldRule<unknown, T>[]
+    for (const r of list) {
+      const found = message(await r(plain()[name], plain()))
+      if (found) return found
+    }
+    return undefined
+  }
+
+  async function runField(name: keyof T): Promise<boolean> {
+    const run = (runs.get(name) ?? 0) + 1
+    runs.set(name, run)
+    const found = await checkField(name)
+    if (runs.get(name) !== run) return !errors[name]
+    if (found) errors[name] = found
+    else delete errors[name]
+    return !found && !external[name]
+  }
+
+  async function runForm(): Promise<boolean> {
+    if (!options.validate) return true
+    const run = (runs.get("form") ?? 0) + 1
+    runs.set("form", run)
+    const found = (await options.validate(plain())) ?? {}
+    if (runs.get("form") !== run) return true
+    let ok = true
+    for (const [name, text] of Object.entries(found) as [keyof T | "form", string | undefined][]) {
+      if (!text) continue
+      ok = false
+      if (!errors[name]) errors[name] = text
+    }
+    return ok
+  }
+
+  async function validate(name?: keyof T): Promise<boolean> {
+    validating.value = true
+    try {
+      if (name !== undefined) return await runField(name)
+      if (errors.form) delete errors.form
+      const fields = await Promise.all(keys().map(runField))
+      const form = await runForm()
+      return fields.every(Boolean) && form && !Object.values(external).some(Boolean)
+    } finally {
+      validating.value = false
+    }
+  }
+
+  function touch(name: keyof T): void {
+    touched[name] = true
+    void validate(name)
+  }
+
+  function set<K extends keyof T>(name: K, value: T[K]): void {
+    ;(values as unknown as T)[name] = value
+  }
+
+  function setValues(next: Partial<T>): void {
+    for (const [k, v] of Object.entries(next) as [keyof T, T[keyof T]][]) set(k, v)
+  }
+
+  function clearState(): void {
+    for (const k of Object.keys(errors)) delete errors[k as keyof T]
+    for (const k of Object.keys(external)) delete external[k as keyof T]
+    for (const k of Object.keys(touched)) delete touched[k as keyof T]
+    runs.clear()
+    submitCount.value = 0
+  }
+
+  function adopt(next: T): void {
+    baseline = clone(next)
+    const target = values as unknown as Record<string, unknown>
+    for (const k of Object.keys(target)) if (!(k in (baseline as object))) delete target[k]
+    Object.assign(target, clone(baseline))
+    baseVersion.value++
+  }
+
+  function reset(next?: T): void {
+    adopt(next ?? toValue(options.initial))
+    clearState()
+  }
+
+  function setErrors(next: FormErrors<T>): void {
+    for (const [k, v] of Object.entries(next) as [keyof T | "form", string | undefined][]) {
+      if (v) external[k] = v
+      else delete external[k]
+    }
+  }
+
+  watch(
+    () => toValue(options.initial),
+    (next) => {
+      if (!dirty.value && !deepEqual(next, baseline)) adopt(next)
+    },
+    { deep: true },
+  )
+
+  // An edit re-checks a field already touched, and drops an external error on it.
+  let snapshot = clone(plain())
+  watch(
+    plain,
+    () => {
+      const now = clone(plain())
+      for (const name of Object.keys(now) as (keyof T)[]) {
+        if (deepEqual(now[name], snapshot[name])) continue
+        if (external[name]) delete external[name]
+        if (touched[name] || submitCount.value) void validate(name)
+      }
+      snapshot = now
+    },
+    { deep: true },
+  )
+
+  const merged = computed<FormErrors<T>>(() => ({ ...errors, ...external }))
+  const visibleErrors = computed<FormErrors<T>>(() => {
+    const all = merged.value
+    if (submitCount.value) return all
+    const shown: FormErrors<T> = {}
+    for (const [k, v] of Object.entries(all) as [keyof T, string][]) {
+      if (touched[k] || external[k]) shown[k] = v
+    }
+    return shown
+  })
+  const valid = computed(() => !Object.values(merged.value).some(Boolean))
+
+  function field<K extends keyof T>(name: K): FieldBinding<T[K]> {
+    const error = visibleErrors.value[name]
+    return {
+      modelValue: (values as unknown as T)[name],
+      "onUpdate:modelValue": (value: T[K]) => set(name, value),
+      onBlur: () => touch(name),
+      error,
+      invalid: !!error,
+    }
+  }
+
+  function handleSubmit(fn: (values: T) => unknown) {
+    return async (event?: Event) => {
+      event?.preventDefault()
+      if (submitting.value) return
+      submitting.value = true
+      try {
+        submitCount.value++
+        for (const name of keys()) touched[name] = true
+        if (!(await validate())) return
+        const submitted = clone(plain())
+        await fn(submitted)
+        if (deepEqual(plain(), submitted)) {
+          baseline = submitted
+          baseVersion.value++
+        }
+      } finally {
+        submitting.value = false
+      }
+    }
+  }
+
+  return {
+    values,
+    errors: merged,
+    visibleErrors,
+    touched,
+    dirty,
+    valid,
+    validating,
+    submitting,
+    submitCount,
+    isDirty,
+    field,
+    set,
+    setValues,
+    touch,
+    validate,
+    setErrors,
+    reset,
+    handleSubmit,
+  }
+}

package/src/composables/useFormDraft.ts

@@ -69,9 +69,16 @@ export interface UseFormDraftOptions<T> {
 }
 
 export interface UseFormDraft<T> {
-  /** A draft was found for this key, and has not been restored or discarded. */
+  /**
+   * A draft was found for this key, and has not been restored or discarded.
+   * Only a draft found on reading counts: the writes this composable makes as
+   * the user types never raise it. While it is up, automatic writes are held
+   * back, so the draft on offer cannot be overwritten by the form's own state
+   * (an async load of the record, or typing past the banner) before the user
+   * has answered.
+   */
   hasDraft: Ref<boolean>
-  /** When that draft was written, ISO-8601, or `null` when there is none. */
+  /** When the found draft was written, ISO-8601, or `null` when there is none. */
   savedAt: Ref<string | null>
   /**
    * The stored value, or `null`. Reading does not apply it — the caller decides
@@ -80,7 +87,7 @@ export interface UseFormDraft<T> {
   read: () => T | null
   /** Forget the draft. Call after applying it, and after a successful save. */
   discard: () => void
-  /** Write now, ignoring `dirty`. For "save and come back to this later". */
+  /** Write now, ignoring `dirty` and a pending draft. For "save and come back to this later". */
   save: () => void
 }
 
@@ -132,6 +139,17 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
     return String(toValue(options.key) || "").trim()
   }
 
+  // An envelope still worth offering, or null. No side effects: the key watcher
+  // only looks, and `read` decides what to clear.
+  function fresh(parsed: DraftEnvelope<T> | null): boolean {
+    if (!parsed || parsed.version !== ENVELOPE_VERSION) return false
+    if (maxAge <= 0) return true
+    // NaN when the stamp is unreadable, and NaN > maxAge is false — an
+    // unreadable stamp is treated as "no idea how old", which errs towards
+    // offering the draft rather than throwing away somebody's typing.
+    return !(Date.now() - Date.parse(parsed.savedAt) > maxAge)
+  }
+
   function read(): T | null {
     const store = storage()
     const key = currentKey()
@@ -145,20 +163,10 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
     if (!raw) return null
     try {
       const parsed = JSON.parse(raw) as DraftEnvelope<T>
-      if (!parsed || parsed.version !== ENVELOPE_VERSION) {
+      if (!fresh(parsed)) {
         discard()
         return null
       }
-      if (maxAge > 0) {
-        const age = Date.now() - Date.parse(parsed.savedAt)
-        // NaN when the stamp is unreadable, and NaN > maxAge is false — an
-        // unreadable stamp is treated as "no idea how old", which errs towards
-        // offering the draft rather than throwing away somebody's typing.
-        if (age > maxAge) {
-          discard()
-          return null
-        }
-      }
       return parsed.value
     } catch {
       // Corrupt or hand-edited. Nothing to rescue, and leaving it means asking
@@ -172,13 +180,12 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
     const store = storage()
     const key = currentKey()
     if (!store || !key) return
-    const stamp = new Date().toISOString()
     try {
       store.setItem(
         key,
         JSON.stringify({
           version: ENVELOPE_VERSION,
-          savedAt: stamp,
+          savedAt: new Date().toISOString(),
           value,
         } satisfies DraftEnvelope<T>),
       )
@@ -187,8 +194,6 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
       // unharmed; it simply has no safety net.
       return
     }
-    hasDraft.value = true
-    savedAt.value = stamp
   }
 
   function discard() {
@@ -226,7 +231,7 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
       if (!raw) return
       try {
         const parsed = JSON.parse(raw) as DraftEnvelope<T>
-        if (parsed?.version !== ENVELOPE_VERSION) return
+        if (!fresh(parsed)) return
         hasDraft.value = true
         savedAt.value = parsed.savedAt
       } catch {
@@ -240,7 +245,7 @@ export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T
   watch(
     () => [toValue(options.value), toValue(options.dirty), toValue(options.disabled)],
     ([value, dirty, disabled]) => {
-      if (disabled) return
+      if (disabled || hasDraft.value) return
       // `dirty` unset means "every change is worth keeping"; the option exists
       // so a form that knows it is untouched leaves no trace.
       if (options.dirty !== undefined && !dirty) return