@leavepulse/ui 0.28.5 → 0.29.1

package/src/composables/useFormDraft.ts

@@ -0,0 +1,259 @@
+import {
+  onScopeDispose,
+  ref,
+  toValue,
+  watch,
+  type MaybeRefOrGetter,
+  type Ref,
+} from "vue"
+
+/*
+ * "The form I had filled in is still here."
+ *
+ * Long forms get abandoned mid-way by things that have nothing to do with the
+ * person filling them in: a session that ages out, a reload, a tab closed by
+ * accident, a laptop that sleeps. What was typed is held in component state,
+ * so all of those end the same way — an empty form and a person who has to
+ * remember what they had already read off the thing in their hand.
+ *
+ * The panel's own inventory forms are the case that prompted this: an operator
+ * standing at a shelf, copying figures off a label, is exactly the person who
+ * cannot retype them from memory.
+ *
+ * Consumers were writing this by hand, field by field: one object literal to
+ * save thirty values and thirty typed branches to read them back, which has to
+ * be kept in step with the form forever and silently stops covering whatever
+ * field was added last. This owns the mechanism instead — what to keep is the
+ * caller's business, keeping it is not.
+ *
+ * What this deliberately does NOT do: decide that a draft is worth restoring.
+ * It reports one and hands back the value; showing it, and asking, is the
+ * caller's, because only the caller knows whether the record moved underneath
+ * it in the meantime.
+ */
+
+/** Bumped when the envelope changes shape. A draft written by an older kit is
+ *  dropped rather than half-read: a partially-applied draft is worse than none,
+ *  because it looks like something a person typed. */
+const ENVELOPE_VERSION = 1
+
+interface DraftEnvelope<T> {
+  version: number
+  savedAt: string
+  value: T
+}
+
+export interface UseFormDraftOptions<T> {
+  /**
+   * Where this draft lives. Include whatever identifies the subject — a draft
+   * for device A must not surface while editing device B.
+   */
+  key: MaybeRefOrGetter<string>
+  /** The form's current value. Watched deeply; every change rewrites the draft. */
+  value: MaybeRefOrGetter<T>
+  /**
+   * Whether there is anything worth keeping. Return false while the form still
+   * matches what was loaded, so an untouched form leaves nothing behind and no
+   * later visit is offered its own starting state back as a "draft".
+   */
+  dirty?: MaybeRefOrGetter<boolean>
+  /**
+   * How long a draft stays offerable, in milliseconds. Older ones are dropped
+   * on read: a fortnight-old draft of a record that has been edited twice since
+   * is not a rescue, it is a way to overwrite current facts with stale ones.
+   * Defaults to a week. `0` keeps them indefinitely.
+   */
+  maxAgeMs?: number
+  /** Skip the write without tearing the composable out of the component. */
+  disabled?: MaybeRefOrGetter<boolean>
+}
+
+export interface UseFormDraft<T> {
+  /** A draft was found for this key, and has not been restored or discarded. */
+  hasDraft: Ref<boolean>
+  /** When that 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
+   * what to do with each field, because only it knows the form's shape.
+   */
+  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". */
+  save: () => void
+}
+
+function storage(): Storage | null {
+  // Private windows, storage disabled by policy, SSR. A form that cannot keep
+  // a draft still has to work, so every access is allowed to fail.
+  try {
+    if (typeof window === "undefined") return null
+    return window.localStorage
+  } catch {
+    return null
+  }
+}
+
+const WEEK_MS = 7 * 24 * 60 * 60 * 1000
+
+/**
+ * Keeps an unsaved form in browser storage, so losing the page does not lose
+ * what was typed into it.
+ *
+ * ```ts
+ * const draft = useFormDraft({
+ *   key: () => `lp.draft.device-power:${deviceId.value}`,
+ *   value: () => interfaces.value,
+ *   dirty: () => hasUnsavedChanges.value,
+ * })
+ * ```
+ * ```vue
+ * <LpAlert v-if="draft.hasDraft.value" variant="info">
+ *   {{ t("draft.found", { when: draft.savedAt.value }) }}
+ *   <LpButton @click="applyDraft">Restore</LpButton>
+ *   <LpButton variant="ghost" @click="draft.discard()">Discard</LpButton>
+ * </LpAlert>
+ * ```
+ *
+ * `hasDraft` answers for the key as it is now, so a form that switches subject
+ * re-reads rather than carrying the previous subject's answer.
+ *
+ * Call `discard()` once the record is saved. A draft that outlives the save it
+ * describes is offered back on the next visit as though it were newer than the
+ * record, which is how a form helpfully undoes somebody's work.
+ */
+export function useFormDraft<T>(options: UseFormDraftOptions<T>): UseFormDraft<T> {
+  const hasDraft = ref(false)
+  const savedAt = ref<string | null>(null)
+  const maxAge = options.maxAgeMs ?? WEEK_MS
+
+  function currentKey(): string {
+    return String(toValue(options.key) || "").trim()
+  }
+
+  function read(): T | null {
+    const store = storage()
+    const key = currentKey()
+    if (!store || !key) return null
+    let raw: string | null = null
+    try {
+      raw = store.getItem(key)
+    } catch {
+      return null
+    }
+    if (!raw) return null
+    try {
+      const parsed = JSON.parse(raw) as DraftEnvelope<T>
+      if (!parsed || parsed.version !== ENVELOPE_VERSION) {
+        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
+      // about it on every visit forever.
+      discard()
+      return null
+    }
+  }
+
+  function write(value: 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,
+          value,
+        } satisfies DraftEnvelope<T>),
+      )
+    } catch {
+      // Quota, or storage turned off between the read and now. The form is
+      // unharmed; it simply has no safety net.
+      return
+    }
+    hasDraft.value = true
+    savedAt.value = stamp
+  }
+
+  function discard() {
+    const store = storage()
+    const key = currentKey()
+    hasDraft.value = false
+    savedAt.value = null
+    if (!store || !key) return
+    try {
+      store.removeItem(key)
+    } catch {
+      // Nothing to do about it, and nothing depends on it.
+    }
+  }
+
+  function save() {
+    write(toValue(options.value))
+  }
+
+  // Look for an existing draft, and look again when the subject changes.
+  watch(
+    () => currentKey(),
+    () => {
+      hasDraft.value = false
+      savedAt.value = null
+      const store = storage()
+      const key = currentKey()
+      if (!store || !key) return
+      let raw: string | null = null
+      try {
+        raw = store.getItem(key)
+      } catch {
+        return
+      }
+      if (!raw) return
+      try {
+        const parsed = JSON.parse(raw) as DraftEnvelope<T>
+        if (parsed?.version !== ENVELOPE_VERSION) return
+        hasDraft.value = true
+        savedAt.value = parsed.savedAt
+      } catch {
+        // Left for `read` to clear: reporting it here would mean writing to
+        // storage from what is meant to be a look.
+      }
+    },
+    { immediate: true },
+  )
+
+  watch(
+    () => [toValue(options.value), toValue(options.dirty), toValue(options.disabled)],
+    ([value, dirty, disabled]) => {
+      if (disabled) 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
+      write(value as T)
+    },
+    { deep: true },
+  )
+
+  onScopeDispose(() => {
+    // The draft outlives the component on purpose — that is the whole point —
+    // so there is nothing to clean up but the local flags.
+    hasDraft.value = false
+  })
+
+  return { hasDraft, savedAt, read, discard, save }
+}

package/src/index.ts

@@ -213,6 +213,9 @@ export { useReveal } from "./composables/useReveal"
 export type { UseReveal, UseRevealOptions } from "./composables/useReveal"
 export { useRovingFocus } from "./composables/useRovingFocus"
 export type { RovingItem, UseRovingFocusOptions } from "./composables/useRovingFocus"
+export { useFormDraft } from "./composables/useFormDraft"
+export type { UseFormDraft, UseFormDraftOptions } from "./composables/useFormDraft"
+
 export { useSettled } from "./composables/useSettled"
 export type { UseSettledOptions } from "./composables/useSettled"
 export { useShift } from "./composables/useShift"

package/dist/chunks/LpTable-DTj52qlg.js

@@ -1,266 +0,0 @@
-import { defineComponent, computed, ref, watch, onBeforeUnmount, openBlock, createBlock, withCtx, createElementVNode, normalizeClass, createElementBlock, createVNode, createCommentVNode, Fragment, renderList, normalizeStyle, createTextVNode, toDisplayString, unref, mergeProps, withModifiers, renderSlot } from "vue";
-import { _ as _sfc_main$2 } from "./LpCheckbox-BO0zuuPh.js";
-import { _ as _sfc_main$4 } from "./LpContextMenu-D0mzXqA7.js";
-import { _ as _sfc_main$3 } from "./LpIcon-CCnX5_2j.js";
-import { _ as _sfc_main$1 } from "./LpScrollArea-D8xyKXcF.js";
-import { useRovingFocus } from "../composables/useRovingFocus.js";
-const _hoisted_1 = { class: "w-full border-collapse text-sm" };
-const _hoisted_2 = { class: "border-b border-line bg-surface-soft" };
-const _hoisted_3 = {
-  key: 0,
-  class: "w-px px-4 py-3"
-};
-const _hoisted_4 = ["aria-sort"];
-const _hoisted_5 = ["onClick"];
-const _hoisted_6 = { key: 0 };
-const _hoisted_7 = ["colspan"];
-const _hoisted_8 = ["onClick"];
-const _sfc_main = /* @__PURE__ */ defineComponent({
-  __name: "LpTable",
-  props: {
-    columns: {},
-    rows: {},
-    rowKey: {},
-    emptyLabel: { default: "Nothing here yet" },
-    emptyIcon: { default: "lucide:inbox" },
-    selectable: { type: Boolean, default: false },
-    selected: { default: () => [] },
-    sort: { default: null },
-    stickyHeader: { type: Boolean },
-    rowMenu: {}
-  },
-  emits: ["update:selected", "update:sort", "rowClick"],
-  setup(__props, { emit: __emit }) {
-    const props = __props;
-    const emit = __emit;
-    function keyFor(row, index) {
-      if (typeof props.rowKey === "function") return props.rowKey(row);
-      if (props.rowKey) return row[props.rowKey];
-      return index;
-    }
-    function alignClass(align) {
-      if (align === "right") return "text-right";
-      if (align === "center") return "text-center";
-      return "text-left";
-    }
-    function menuFor(row) {
-      return props.rowMenu?.(row) ?? [];
-    }
-    const displayRows = computed(() => {
-      const s = props.sort;
-      if (!s) return props.rows;
-      const col = props.columns.find((c) => c.key === s.key);
-      if (!col?.sortable) return props.rows;
-      const factor = s.dir === "asc" ? 1 : -1;
-      return [...props.rows].sort((a, b) => compare(a[s.key], b[s.key]) * factor);
-    });
-    function compare(a, b) {
-      if (a == null && b == null) return 0;
-      if (a == null) return -1;
-      if (b == null) return 1;
-      if (typeof a === "number" && typeof b === "number") return a - b;
-      return String(a).localeCompare(String(b), void 0, { numeric: true });
-    }
-    function toggleSort(col) {
-      if (!col.sortable) return;
-      const s = props.sort;
-      let next;
-      if (!s || s.key !== col.key) next = { key: col.key, dir: "asc" };
-      else if (s.dir === "asc") next = { key: col.key, dir: "desc" };
-      else next = null;
-      emit("update:sort", next);
-    }
-    function sortIcon(col) {
-      if (props.sort?.key !== col.key) return "lucide:chevrons-up-down";
-      return props.sort.dir === "asc" ? "lucide:arrow-up" : "lucide:arrow-down";
-    }
-    const selectedSet = computed(() => new Set(props.selected));
-    const allKeys = computed(() => props.rows.map((r, i) => keyFor(r, i)));
-    const allChecked = computed(
-      () => allKeys.value.length > 0 && allKeys.value.every((k) => selectedSet.value.has(k))
-    );
-    const someChecked = computed(
-      () => !allChecked.value && allKeys.value.some((k) => selectedSet.value.has(k))
-    );
-    function toggleAll(checked) {
-      emit("update:selected", checked ? [...allKeys.value] : []);
-    }
-    function toggleRow(key, checked) {
-      const next = new Set(selectedSet.value);
-      if (checked) next.add(key);
-      else next.delete(key);
-      emit("update:selected", [...next]);
-    }
-    const colSpan = computed(() => props.columns.length + (props.selectable ? 1 : 0));
-    const rovingItems = computed(
-      () => displayRows.value.map((row, index) => ({
-        id: String(keyFor(row, index)),
-        label: String(row[props.columns[0]?.key ?? ""] ?? "")
-      }))
-    );
-    const rowByKey = computed(() => {
-      const map = /* @__PURE__ */ new Map();
-      displayRows.value.forEach((row, index) => map.set(String(keyFor(row, index)), row));
-      return map;
-    });
-    const roving = useRovingFocus(rovingItems, {
-      onActivate: (id) => {
-        const row = rowByKey.value.get(id);
-        if (!row) return;
-        emit("rowClick", row);
-      }
-    });
-    function onRowKeydown(event) {
-      if (event.key === " " && props.selectable && roving.activeId.value) {
-        event.preventDefault();
-        const key = roving.activeId.value;
-        const row = rowByKey.value.get(key);
-        if (row) {
-          const rowKey = keyFor(row, displayRows.value.indexOf(row));
-          toggleRow(rowKey, !selectedSet.value.has(rowKey));
-        }
-        return;
-      }
-      roving.onKeydown(event);
-    }
-    const headEl = ref(null);
-    const headHeight = ref(0);
-    let ro;
-    watch(
-      [headEl, () => props.stickyHeader],
-      ([el, sticky]) => {
-        ro?.disconnect();
-        if (!el || !sticky || typeof ResizeObserver === "undefined") {
-          headHeight.value = 0;
-          return;
-        }
-        ro = new ResizeObserver(() => {
-          headHeight.value = el.offsetHeight;
-        });
-        ro.observe(el);
-        headHeight.value = el.offsetHeight;
-      },
-      { immediate: true, flush: "post" }
-    );
-    onBeforeUnmount(() => ro?.disconnect());
-    const barInsetTop = computed(
-      () => props.stickyHeader && headHeight.value ? `${headHeight.value}px` : void 0
-    );
-    return (_ctx, _cache) => {
-      return openBlock(), createBlock(_sfc_main$1, {
-        fade: false,
-        class: "rounded-card border border-line",
-        "bar-inset-top": barInsetTop.value
-      }, {
-        default: withCtx(() => [
-          createElementVNode("table", _hoisted_1, [
-            createElementVNode("thead", {
-              ref_key: "headEl",
-              ref: headEl,
-              class: normalizeClass(__props.stickyHeader ? "sticky top-0 z-10" : "")
-            }, [
-              createElementVNode("tr", _hoisted_2, [
-                __props.selectable ? (openBlock(), createElementBlock("th", _hoisted_3, [
-                  createVNode(_sfc_main$2, {
-                    "model-value": allChecked.value,
-                    indeterminate: someChecked.value,
-                    "onUpdate:modelValue": toggleAll
-                  }, null, 8, ["model-value", "indeterminate"])
-                ])) : createCommentVNode("", true),
-                (openBlock(true), createElementBlock(Fragment, null, renderList(__props.columns, (col) => {
-                  return openBlock(), createElementBlock("th", {
-                    key: col.key,
-                    style: normalizeStyle(col.width ? { width: col.width } : void 0),
-                    class: normalizeClass(["px-4 py-3 text-[11px] font-semibold uppercase tracking-[0.08em] text-muted", alignClass(col.align)]),
-                    "aria-sort": __props.sort?.key === col.key ? __props.sort.dir === "asc" ? "ascending" : "descending" : void 0
-                  }, [
-                    col.sortable ? (openBlock(), createElementBlock("button", {
-                      key: 0,
-                      type: "button",
-                      class: normalizeClass(["group/sort -mx-1 inline-flex items-center gap-1 rounded px-1 outline-none transition-colors duration-[var(--duration-fast)] hover:text-ink focus-visible:ring-2 focus-visible:ring-ring", [
-                        col.align === "right" ? "flex-row-reverse" : "",
-                        __props.sort?.key === col.key ? "text-ink" : ""
-                      ]]),
-                      onClick: ($event) => toggleSort(col)
-                    }, [
-                      createTextVNode(toDisplayString(col.label) + " ", 1),
-                      createVNode(_sfc_main$3, {
-                        name: sortIcon(col),
-                        size: 13,
-                        class: normalizeClass(["shrink-0 transition-[transform,opacity] duration-[var(--duration-fast)] ease-[var(--ease-emphasized)]", __props.sort?.key === col.key ? "opacity-100" : "opacity-40 group-hover/sort:opacity-70"])
-                      }, null, 8, ["name", "class"])
-                    ], 10, _hoisted_5)) : (openBlock(), createElementBlock(Fragment, { key: 1 }, [
-                      createTextVNode(toDisplayString(col.label), 1)
-                    ], 64))
-                  ], 14, _hoisted_4);
-                }), 128))
-              ])
-            ], 2),
-            createElementVNode("tbody", {
-              ref: (el) => unref(roving).setContainer(el)
-            }, [
-              displayRows.value.length === 0 ? (openBlock(), createElementBlock("tr", _hoisted_6, [
-                createElementVNode("td", {
-                  colspan: colSpan.value,
-                  class: "px-4 py-10 text-center text-muted"
-                }, [
-                  createVNode(_sfc_main$3, {
-                    name: __props.emptyIcon,
-                    size: 22,
-                    class: "mx-auto mb-2 opacity-60"
-                  }, null, 8, ["name"]),
-                  createElementVNode("div", null, toDisplayString(__props.emptyLabel), 1)
-                ], 8, _hoisted_7)
-              ])) : createCommentVNode("", true),
-              (openBlock(true), createElementBlock(Fragment, null, renderList(displayRows.value, (row, index) => {
-                return openBlock(), createBlock(_sfc_main$4, {
-                  key: keyFor(row, index),
-                  items: menuFor(row)
-                }, {
-                  default: withCtx(() => [
-                    createElementVNode("tr", mergeProps({
-                      class: ["border-b border-line/60 outline-none transition-colors last:border-0 hover:bg-surface-soft/60 focus-visible:ring-2 focus-visible:ring-inset focus-visible:ring-ring data-[active]:bg-surface-soft/40", selectedSet.value.has(keyFor(row, index)) ? "bg-brand-soft/40" : ""]
-                    }, { ref_for: true }, unref(roving).itemProps(String(keyFor(row, index))), {
-                      onClick: ($event) => emit("rowClick", row),
-                      onKeydown: onRowKeydown
-                    }), [
-                      __props.selectable ? (openBlock(), createElementBlock("td", {
-                        key: 0,
-                        class: "w-px px-4 py-3",
-                        onClick: _cache[0] || (_cache[0] = withModifiers(() => {
-                        }, ["stop"]))
-                      }, [
-                        createVNode(_sfc_main$2, {
-                          "model-value": selectedSet.value.has(keyFor(row, index)),
-                          "onUpdate:modelValue": (v) => toggleRow(keyFor(row, index), v)
-                        }, null, 8, ["model-value", "onUpdate:modelValue"])
-                      ])) : createCommentVNode("", true),
-                      (openBlock(true), createElementBlock(Fragment, null, renderList(__props.columns, (col) => {
-                        return openBlock(), createElementBlock("td", {
-                          key: col.key,
-                          class: normalizeClass(["px-4 py-3 text-ink", alignClass(col.align)])
-                        }, [
-                          renderSlot(_ctx.$slots, `cell-${col.key}`, {
-                            row,
-                            value: row[col.key]
-                          }, () => [
-                            createTextVNode(toDisplayString(row[col.key]), 1)
-                          ])
-                        ], 2);
-                      }), 128))
-                    ], 16, _hoisted_8)
-                  ]),
-                  _: 2
-                }, 1032, ["items"]);
-              }), 128))
-            ], 512)
-          ])
-        ]),
-        _: 3
-      }, 8, ["bar-inset-top"]);
-    };
-  }
-});
-export {
-  _sfc_main as _
-};