@leavepulse/ui 0.44.0 → 0.45.0

package/src/components/tableFilter.ts

@@ -0,0 +1,122 @@
+/*
+ * The rules behind LpTable's value filters and remembered state, kept pure so
+ * they can be tested. A column's filter is the set of HIDDEN values (see
+ * LpTable): a value nobody has seen before shows up rather than staying out.
+ */
+
+/** Hide everything except `keep`: "show only this" in one step. */
+export function onlyValues(values: readonly unknown[], keep: readonly unknown[]): Set<unknown> {
+  const kept = new Set(keep)
+  return new Set(values.filter((v) => !kept.has(v)))
+}
+
+/** Hide every value: the "None" step before ticking the few that matter. */
+export function hideAllValues(values: readonly unknown[]): Set<unknown> {
+  return new Set(values)
+}
+
+/** Swap shown and hidden among the values the column holds. */
+export function invertHidden(values: readonly unknown[], hidden: ReadonlySet<unknown>): Set<unknown> {
+  return new Set(values.filter((v) => !hidden.has(v)))
+}
+
+/** Show these values again, leaving the rest of the filter as it was. */
+export function unhideValues(hidden: ReadonlySet<unknown>, values: readonly unknown[]): Set<unknown> {
+  const next = new Set(hidden)
+  for (const v of values) next.delete(v)
+  return next
+}
+
+/** Lower-cased and stripped of accents, so "cafe" finds "Café". */
+export function foldText(text: string): string {
+  return text.normalize("NFKD").replace(/\p{M}/gu, "").toLocaleLowerCase()
+}
+
+/** Every word of the query appears somewhere in the label, in any order. */
+export function matchesQuery(label: string, query: string): boolean {
+  const words = foldText(query).split(/\s+/).filter(Boolean)
+  if (!words.length) return true
+  const hay = foldText(label)
+  return words.every((w) => hay.includes(w))
+}
+
+/** How many rows hold each value of a column. */
+export function countValues<Row extends Record<string, unknown>>(
+  rows: readonly Row[],
+  key: string,
+): Map<unknown, number> {
+  const counts = new Map<unknown, number>()
+  for (const row of rows) counts.set(row[key], (counts.get(row[key]) ?? 0) + 1)
+  return counts
+}
+
+/**
+ * A chip's text for one column's filter: the values still shown, the first
+ * `listed` by name and the rest as "+N", which says more than "3 of 12".
+ */
+export function summarizeShown(shownLabels: readonly string[], listed = 2): string {
+  if (shownLabels.length <= listed) return shownLabels.join(", ")
+  return `${shownLabels.slice(0, listed).join(", ")} +${shownLabels.length - listed}`
+}
+
+// ── remembered state ───────────────────────────────────────────
+
+export interface PersistedTableState {
+  sort?: { key: string; dir: "asc" | "desc" } | null
+  hidden?: Record<string, unknown[]>
+  columns?: string[]
+}
+
+type Plain = string | number | boolean | null
+
+function isPlain(value: unknown): value is Plain {
+  return value === null || ["string", "number", "boolean"].includes(typeof value)
+}
+
+/**
+ * The state worth keeping across visits, as JSON. Only plain values survive:
+ * a Date or an object hidden in a filter cannot come back as the same value
+ * (the filter compares by identity), so it is left out rather than restored
+ * as something that matches nothing.
+ */
+export function serializeTableState(state: PersistedTableState): string {
+  const hidden: Record<string, Plain[]> = {}
+  for (const [key, values] of Object.entries(state.hidden ?? {})) {
+    const plain = values.filter(isPlain)
+    if (plain.length) hidden[key] = plain
+  }
+  return JSON.stringify({ sort: state.sort ?? null, hidden, columns: state.columns ?? [] })
+}
+
+/** Read it back, dropping anything about columns the table no longer has. */
+export function parseTableState(raw: string | null, columnKeys: readonly string[]): PersistedTableState | null {
+  if (!raw) return null
+  let data: unknown
+  try {
+    data = JSON.parse(raw)
+  } catch {
+    return null
+  }
+  if (!data || typeof data !== "object") return null
+  const known = new Set(columnKeys)
+  const record = data as Record<string, unknown>
+  const out: PersistedTableState = {}
+
+  const sort = record.sort as { key?: unknown; dir?: unknown } | null | undefined
+  if (sort === null) out.sort = null
+  else if (sort && typeof sort.key === "string" && known.has(sort.key) && (sort.dir === "asc" || sort.dir === "desc")) {
+    out.sort = { key: sort.key, dir: sort.dir }
+  }
+
+  if (record.hidden && typeof record.hidden === "object") {
+    out.hidden = {}
+    for (const [key, values] of Object.entries(record.hidden as Record<string, unknown>)) {
+      if (known.has(key) && Array.isArray(values)) out.hidden[key] = values.filter(isPlain)
+    }
+  }
+
+  if (Array.isArray(record.columns)) {
+    out.columns = record.columns.filter((c): c is string => typeof c === "string" && known.has(c))
+  }
+  return out
+}

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

@@ -1,4 +1,5 @@
 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,
@@ -14,6 +15,9 @@ export interface FieldContext {
   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")

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,
+  }
+}