attaform 0.21.1 → 0.22.0

package/dist/runtime/components/AttaformDevtoolsPanel.vue

@@ -1,230 +1,410 @@
-<script setup>
-import { computed, onUnmounted, ref, watch } from "vue";
-import { canonicalizePath } from "attaform";
-import DevtoolsValueTree from "./DevtoolsValueTree.vue";
-const props = defineProps({
-  bridge: { type: Object, required: true }
-});
-const updateTick = ref(0);
-const registry = computed(() => props.bridge.registry);
-const formEntries = computed(() => {
-  void updateTick.value;
-  return Array.from(registry.value.forms.entries());
-});
-const selectedFormKey = ref(null);
-const activeKey = computed(() => {
-  if (selectedFormKey.value !== null && registry.value.forms.has(selectedFormKey.value)) {
-    return selectedFormKey.value;
-  }
-  return formEntries.value[0]?.[0] ?? null;
-});
-const activeForm = computed(() => {
-  const key = activeKey.value;
-  return key !== null ? registry.value.forms.get(key) ?? null : null;
-});
-const formValueView = computed(() => {
-  void updateTick.value;
-  const form = activeForm.value;
-  if (form === null) return null;
-  return form.form.value;
-});
-const schemaErrorRows = computed(() => {
-  void updateTick.value;
-  const form = activeForm.value;
-  if (form === null) return [];
-  return Array.from(form.schemaErrors.entries());
-});
-const userErrorRows = computed(() => {
-  void updateTick.value;
-  const form = activeForm.value;
-  if (form === null) return [];
-  return Array.from(form.userErrors.entries());
-});
-const aggregates = computed(() => {
-  void updateTick.value;
-  const form = activeForm.value;
-  if (form === null) return null;
-  return {
-    submitting: form.submitting.value,
-    submissionAttempts: form.submissionAttempts.value,
-    submitError: form.submitError.value,
-    activeValidations: form.activeValidations.value
-  };
-});
-function selectForm(key) {
-  selectedFormKey.value = key;
-}
-function humanizePathKey(key) {
-  try {
-    const parsed = JSON.parse(key);
-    if (Array.isArray(parsed)) {
-      return parsed.map((seg) => String(seg)).join(".");
+<script setup lang="ts">
+import { computed, onUnmounted, ref, watch } from 'vue'
+  // Imports route through the public `attaform` entry so the published
+  // `.vue` file (shipped via mkdist under `dist/runtime/components/`)
+  // can resolve through the consumer's node_modules → `dist/index.mjs`,
+  // rather than through brittle relative paths into the rollup-bundled
+  // shared chunks (which mkdist doesn't co-locate). Type-only imports of
+  // internal types stay relative — they're erased at compile time and
+  // don't need to resolve at the consumer's runtime.
+  import { type AttaformDevtoolsBridge, canonicalizePath, type Segment } from 'attaform'
+  import type { FormStore } from '../core/create-form-store'
+  import type { GenericForm } from '../types/types-core'
+  import type { FormKey } from '../types/types-api'
+  import DevtoolsValueTree from './DevtoolsValueTree.vue'
+
+  const props = defineProps<{
+    bridge: AttaformDevtoolsBridge
+  }>()
+
+  // Cross-iframe reactivity bridge. Vue's reactivity system is module-
+  // scoped — the host's `@vue/reactivity` instance and the panel's are
+  // different copies of the same module, each with its own targetMap.
+  // When the panel reads `host.form.value` in a `computed`, the proxy's
+  // get trap runs in the host's tracking context (the function lives
+  // there) but `getCurrentEffect()` returns nothing because the panel's
+  // active effect is in a different runtime. The dependency never
+  // registers, and the computed never re-evaluates on host mutations.
+  //
+  // Workaround: a tick ref that all data-fetching computeds depend on.
+  // We bump the tick on every host event we DO have a callback for
+  // (`onFormChange` / `onSubmitSuccess` / `onReset`), plus a 250ms
+  // polling fallback for state that changes outside those events (user
+  // errors via `setFieldErrors*`, submit-lifecycle flags). The panel's
+  // own reactivity then re-evaluates everything in one pass — cheap
+  // because the underlying reads are direct property accesses.
+  const updateTick = ref(0)
+
+  const registry = computed(() => props.bridge.registry)
+  const formEntries = computed(() => {
+    // Touch the tick so the form list refreshes when new forms register
+    // (the registry's reactive Map updates wouldn't notify us otherwise).
+    void updateTick.value
+    return Array.from(registry.value.forms.entries())
+  })
+
+  // Explicit selection. `null` means "auto-pick first available form".
+  const selectedFormKey = ref<FormKey | null>(null)
+
+  const activeKey = computed<FormKey | null>(() => {
+    if (selectedFormKey.value !== null && registry.value.forms.has(selectedFormKey.value)) {
+      return selectedFormKey.value
+    }
+    return formEntries.value[0]?.[0] ?? null
+  })
+
+  const activeForm = computed(() => {
+    const key = activeKey.value
+    return key !== null ? (registry.value.forms.get(key) ?? null) : null
+  })
+
+  const formValueView = computed(() => {
+    void updateTick.value
+    const form = activeForm.value
+    if (form === null) return null
+    // Devtools is dev-only; render raw values. Consumers concerned about
+    // screen-share leaks should close the panel before sharing, the same
+    // way they'd hide their browser DevTools console.
+    return form.form.value
+  })
+
+  const schemaErrorRows = computed(() => {
+    void updateTick.value
+    const form = activeForm.value
+    if (form === null) return []
+    return Array.from(form.schemaErrors.entries())
+  })
+
+  const userErrorRows = computed(() => {
+    void updateTick.value
+    const form = activeForm.value
+    if (form === null) return []
+    return Array.from(form.userErrors.entries())
+  })
+
+  const aggregates = computed(() => {
+    void updateTick.value
+    const form = activeForm.value
+    if (form === null) return null
+    return {
+      submitting: form.submitting.value,
+      submissionAttempts: form.submissionAttempts.value,
+      submitError: form.submitError.value,
+      activeValidations: form.activeValidations.value,
     }
-  } catch {
+  })
+
+  function selectForm(key: FormKey): void {
+    selectedFormKey.value = key
   }
-  return key;
-}
-function fmt(v) {
-  if (v === null) return "null";
-  if (v === void 0) return "undefined";
-  if (typeof v === "string") return v;
-  if (typeof v === "number" || typeof v === "boolean" || typeof v === "bigint") {
-    return String(v);
+
+  /**
+   * Convert a canonical PathKey (e.g. `'["users",0,"name"]'`) back to a
+   * readable dotted form (`users.0.name`) for the error table. Falls
+   * back to the raw key if it's not a JSON-array shape.
+   */
+  function humanizePathKey(key: string): string {
+    try {
+      const parsed = JSON.parse(key) as unknown[]
+      if (Array.isArray(parsed)) {
+        return parsed.map((seg) => String(seg)).join('.')
+      }
+    } catch {
+      // not JSON, render as-is
+    }
+    return key
   }
-  try {
-    return JSON.stringify(v);
-  } catch {
-    return String(v);
+
+  /**
+   * Render a JS value as a debug-friendly string with no masking —
+   * `null` / `undefined` show as their literal names, booleans and
+   * numbers as-is, strings bare (no surrounding quotes), everything
+   * else JSON-stringified. Devtools is for inspecting state, not for
+   * pretty-printing it; the user-author sees the actual runtime
+   * shape.
+   */
+  function fmt(v: unknown): string {
+    if (v === null) return 'null'
+    if (v === undefined) return 'undefined'
+    if (typeof v === 'string') return v
+    if (typeof v === 'number' || typeof v === 'boolean' || typeof v === 'bigint') {
+      return String(v)
+    }
+    try {
+      return JSON.stringify(v)
+    } catch {
+      return String(v)
+    }
   }
-}
-const selectedPath = ref(null);
-const selectedKey = computed(
-  () => selectedPath.value === null ? null : JSON.stringify(selectedPath.value)
-);
-function selectPath(path) {
-  const key = JSON.stringify(path);
-  if (selectedKey.value === key) {
-    selectedPath.value = null;
-  } else {
-    selectedPath.value = path;
+
+  /**
+   * Commit a leaf edit from the value tree. Mirrors the exact flow the
+   * Vue DevTools `editInspectorState` handler uses in
+   * `src/runtime/core/devtools.ts` so both surfaces have identical
+   * semantics:
+   *   1. canonicalize the structured path
+   *   2. refuse sensitive-name paths (the tree already gates the UI,
+   *      but a defensive check here keeps the contract honest)
+   *   3. derive the persist flag from the path's element opt-ins
+   *   4. call setValueAtPath with the same write-meta the bound input
+   *      would have produced
+   */
+  // Field-state inspector. Click any key in the Form value tree to
+  // "select" that path; the Field state section below resolves
+  // `form.fields(path)` for it. Click the same key again to deselect.
+  const selectedPath = ref<ReadonlyArray<string | number> | null>(null)
+  const selectedKey = computed(() =>
+    selectedPath.value === null ? null : JSON.stringify(selectedPath.value)
+  )
+
+  function selectPath(path: ReadonlyArray<string | number>): void {
+    const key = JSON.stringify(path)
+    if (selectedKey.value === key) {
+      selectedPath.value = null
+    } else {
+      selectedPath.value = path
+    }
   }
-}
-const selectedFieldState = computed(() => {
-  void updateTick.value;
-  const form = activeForm.value;
-  const path = selectedPath.value;
-  if (form === null || path === null) return null;
-  try {
-    const { key: canonicalKey } = canonicalizePath(path);
-    const record = form.fields.get(canonicalKey) ?? null;
-    let value = form.form.value;
-    for (const seg of path) {
-      if (value === null || typeof value !== "object") {
-        value = void 0;
-        break;
+
+  /**
+   * Raw field data at the selected path, composed from `FormStore`
+   * primitives. The callable `form.fields(path)` proxy lives on the
+   * public `useForm` return, not on `FormStore` — the bridge exposes
+   * the store, so we synthesise the same data from `fields.get(key)`
+   * + the error Maps + an inline value walk.
+   *
+   * Returns the raw `FieldRecord` (updatedAt / focused / blurred /
+   * touched / connected) rather than the wrapped `FieldState`
+   * surface. Sufficient for inspection — the full aggregated
+   * FieldState would require either lifting the surface-proxy into
+   * `FormStore` (architectural change) or rebuilding the aggregation
+   * walker in the panel (duplication).
+   */
+  const selectedFieldState = computed<{
+    record: {
+      updatedAt: string | null
+      connected: boolean
+      focused: boolean | null
+      blurred: boolean | null
+      touched: boolean | null
+    } | null
+    value: unknown
+    errors: ReadonlyArray<{ message: string; code: string }>
+    schemaErrorCount: number
+    userErrorCount: number
+  } | null>(() => {
+    void updateTick.value
+    const form = activeForm.value
+    const path = selectedPath.value
+    if (form === null || path === null) return null
+    try {
+      const { key: canonicalKey } = canonicalizePath(path as readonly Segment[])
+      const record =
+        (form.fields.get(canonicalKey) as
+          | {
+              updatedAt: string | null
+              connected: boolean
+              focused: boolean | null
+              blurred: boolean | null
+              touched: boolean | null
+            }
+          | undefined) ?? null
+
+      // Inline path walk (avoids importing path-walker through the
+      // bridge — it lives in the host's shared chunk).
+      let value: unknown = form.form.value
+      for (const seg of path) {
+        if (value === null || typeof value !== 'object') {
+          value = undefined
+          break
+        }
+        value = (value as Record<string | number, unknown>)[seg]
+      }
+
+      const schemaEntries =
+        (form.schemaErrors.get(canonicalKey) as
+          | ReadonlyArray<{ message: string; code: string }>
+          | undefined) ?? []
+      const userEntries =
+        (form.userErrors.get(canonicalKey) as
+          | ReadonlyArray<{ message: string; code: string }>
+          | undefined) ?? []
+
+      return {
+        record,
+        value,
+        errors: [...schemaEntries, ...userEntries],
+        schemaErrorCount: schemaEntries.length,
+        userErrorCount: userEntries.length,
       }
-      value = value[seg];
+    } catch (err) {
+      console.error('[attaform devtools] field-state lookup failed', { path, err })
+      return null
     }
-    const schemaEntries = form.schemaErrors.get(canonicalKey) ?? [];
-    const userEntries = form.userErrors.get(canonicalKey) ?? [];
-    return {
-      record,
-      value,
-      errors: [...schemaEntries, ...userEntries],
-      schemaErrorCount: schemaEntries.length,
-      userErrorCount: userEntries.length
-    };
-  } catch (err) {
-    console.error("[attaform devtools] field-state lookup failed", { path, err });
-    return null;
+  })
+
+  function humanizeSelectedPath(): string {
+    const path = selectedPath.value
+    if (path === null || path.length === 0) return '(root)'
+    return path.map((seg) => String(seg)).join('.')
   }
-});
-function humanizeSelectedPath() {
-  const path = selectedPath.value;
-  if (path === null || path.length === 0) return "(root)";
-  return path.map((seg) => String(seg)).join(".");
-}
-function selectedValueView() {
-  const fs = selectedFieldState.value;
-  if (fs === null) return null;
-  return fs.value;
-}
-function handleEdit(rawPath, next) {
-  const form = activeForm.value;
-  if (form === null) return;
-  try {
-    const { segments: canonicalPath, key: canonicalKey } = canonicalizePath(
-      rawPath
-    );
-    form.setValueAtPath(canonicalPath, next, {
-      persist: form.persistOptIns.hasAnyOptInForPath(canonicalKey)
-    });
-  } catch (err) {
-    console.error("[attaform devtools] edit failed", { rawPath, next, err });
+
+  function selectedValueView(): unknown {
+    const fs = selectedFieldState.value
+    if (fs === null) return null
+    return fs.value
   }
-}
-const MAX_TIMELINE_EVENTS = 200;
-const events = ref([]);
-const expandedEventId = ref(null);
-let eventIdCounter = 0;
-function pushEvent(seed) {
-  const entry = { id: ++eventIdCounter, ...seed };
-  const next = [entry, ...events.value];
-  if (next.length > MAX_TIMELINE_EVENTS) next.length = MAX_TIMELINE_EVENTS;
-  events.value = next;
-}
-function clearTimeline() {
-  events.value = [];
-  expandedEventId.value = null;
-}
-function toggleEvent(id) {
-  expandedEventId.value = expandedEventId.value === id ? null : id;
-}
-function formatTime(time) {
-  const d = new Date(time);
-  const hh = String(d.getHours()).padStart(2, "0");
-  const mm = String(d.getMinutes()).padStart(2, "0");
-  const ss = String(d.getSeconds()).padStart(2, "0");
-  const ms = String(d.getMilliseconds()).padStart(3, "0");
-  return `${hh}:${mm}:${ss}.${ms}`;
-}
-const subscribers = /* @__PURE__ */ new Map();
-function subscribeForm(key, form) {
-  if (subscribers.has(key)) return;
-  const captureValue = () => {
+
+  function handleEdit(rawPath: ReadonlyArray<string | number>, next: unknown): void {
+    const form = activeForm.value
+    if (form === null) return
     try {
-      return structuredClone(form.form.value);
-    } catch {
-      return form.form.value;
-    }
-  };
-  const unsubChange = form.onFormChange(() => {
-    pushEvent({ type: "form.change", formKey: key, time: Date.now(), value: captureValue() });
-    updateTick.value++;
-  });
-  const unsubSubmit = form.onSubmitSuccess(() => {
-    pushEvent({ type: "submit.success", formKey: key, time: Date.now(), value: captureValue() });
-    updateTick.value++;
-  });
-  const unsubReset = form.onReset(() => {
-    pushEvent({ type: "reset", formKey: key, time: Date.now(), value: captureValue() });
-    updateTick.value++;
-  });
-  subscribers.set(key, () => {
-    unsubChange();
-    unsubSubmit();
-    unsubReset();
-  });
-}
-watch(
-  formEntries,
-  (entries) => {
-    const liveKeys = new Set(entries.map(([k]) => k));
-    for (const [key, form] of entries) {
-      if (!subscribers.has(key)) subscribeForm(key, form);
+      const { segments: canonicalPath, key: canonicalKey } = canonicalizePath(
+        rawPath as readonly Segment[]
+      )
+      form.setValueAtPath(canonicalPath, next, {
+        persist: form.persistOptIns.hasAnyOptInForPath(canonicalKey),
+      })
+      // The host's setValueAtPath fires `onFormChange` listeners, which
+      // bumps our updateTick (see subscribeForm) — that refreshes the
+      // panel's view of the new value on the next microtask.
+    } catch (err) {
+      // Surface cross-iframe write failures (e.g., type-instance checks
+      // tripping over panel-vs-host Array constructors) so we don't
+      // silently swallow them. Devtools-only path, so console.error is
+      // appropriate.
+
+      console.error('[attaform devtools] edit failed', { rawPath, next, err })
     }
-    for (const [key, unsub] of subscribers) {
-      if (!liveKeys.has(key)) {
-        unsub();
-        subscribers.delete(key);
+  }
+
+  // Timeline log ----------------------------------------------------------
+
+  type TimelineEventType = 'form.change' | 'submit.success' | 'reset'
+
+  interface TimelineEvent {
+    id: number
+    type: TimelineEventType
+    formKey: FormKey
+    time: number
+    value: unknown
+  }
+
+  /**
+   * Hard cap on the in-memory event log. Sized for a debugging session,
+   * not an audit log — older events fall off the back when capacity
+   * fills. Tunable later if real consumers ask for more.
+   */
+  const MAX_TIMELINE_EVENTS = 200
+  const events = ref<TimelineEvent[]>([])
+  const expandedEventId = ref<number | null>(null)
+  let eventIdCounter = 0
+
+  function pushEvent(seed: Omit<TimelineEvent, 'id'>): void {
+    const entry: TimelineEvent = { id: ++eventIdCounter, ...seed }
+    const next = [entry, ...events.value]
+    if (next.length > MAX_TIMELINE_EVENTS) next.length = MAX_TIMELINE_EVENTS
+    events.value = next
+  }
+
+  function clearTimeline(): void {
+    events.value = []
+    expandedEventId.value = null
+  }
+
+  function toggleEvent(id: number): void {
+    expandedEventId.value = expandedEventId.value === id ? null : id
+  }
+
+  function formatTime(time: number): string {
+    const d = new Date(time)
+    const hh = String(d.getHours()).padStart(2, '0')
+    const mm = String(d.getMinutes()).padStart(2, '0')
+    const ss = String(d.getSeconds()).padStart(2, '0')
+    const ms = String(d.getMilliseconds()).padStart(3, '0')
+    return `${hh}:${mm}:${ss}.${ms}`
+  }
+
+  // Per-form subscriber bookkeeping. Re-scoped whenever the registry's
+  // form set changes so newly-registered forms wire up automatically and
+  // evicted forms drop their subscribers (no leaks across HMR reloads).
+  const subscribers = new Map<FormKey, () => void>()
+
+  function subscribeForm(key: FormKey, form: FormStore<GenericForm>): void {
+    if (subscribers.has(key)) return
+    // Deep-clone the form value at the moment of fire — FormStore
+    // mutates form data in place, so a stored reference would update
+    // every existing timeline entry whenever the form changed again
+    // ("type a, delete a, both timeline events show the empty value"
+    // bug). `structuredClone` also crosses the iframe-realm boundary,
+    // landing a panel-native plain object instead of the host's
+    // reactive proxy.
+    const captureValue = (): unknown => {
+      try {
+        return structuredClone(form.form.value)
+      } catch {
+        // Non-cloneable values (functions, Symbols, Vue refs, etc.) —
+        // fall back to the live reference. Worst case: that one entry
+        // still shows the current state, same as before this fix.
+        return form.form.value
       }
     }
-  },
-  { immediate: true }
-);
-const POLL_INTERVAL_MS = 120;
-const pollHandle = window.setInterval(() => {
-  updateTick.value++;
-}, POLL_INTERVAL_MS);
-onUnmounted(() => {
-  window.clearInterval(pollHandle);
-  for (const unsub of subscribers.values()) unsub();
-  subscribers.clear();
-});
+    const unsubChange = form.onFormChange(() => {
+      pushEvent({ type: 'form.change', formKey: key, time: Date.now(), value: captureValue() })
+      updateTick.value++
+    })
+    const unsubSubmit = form.onSubmitSuccess(() => {
+      pushEvent({ type: 'submit.success', formKey: key, time: Date.now(), value: captureValue() })
+      updateTick.value++
+    })
+    const unsubReset = form.onReset(() => {
+      pushEvent({ type: 'reset', formKey: key, time: Date.now(), value: captureValue() })
+      updateTick.value++
+    })
+    subscribers.set(key, () => {
+      unsubChange()
+      unsubSubmit()
+      unsubReset()
+    })
+  }
+
+  watch(
+    formEntries,
+    (entries) => {
+      const liveKeys = new Set(entries.map(([k]) => k))
+      for (const [key, form] of entries) {
+        if (!subscribers.has(key)) subscribeForm(key, form as FormStore<GenericForm>)
+      }
+      for (const [key, unsub] of subscribers) {
+        if (!liveKeys.has(key)) {
+          unsub()
+          subscribers.delete(key)
+        }
+      }
+    },
+    { immediate: true }
+  )
+
+  // Polling fallback for state that changes outside the `onFormChange` /
+  // `onSubmitSuccess` / `onReset` event surface — user errors injected
+  // via `setFieldErrors*`, submit-lifecycle flags between events, or
+  // new forms registered in the host's registry. 120ms is faster than
+  // a human can notice between an input event and a visible panel
+  // refresh; gas-cost is negligible (one ref-bump every 120ms).
+  const POLL_INTERVAL_MS = 120
+  const pollHandle = window.setInterval(() => {
+    updateTick.value++
+  }, POLL_INTERVAL_MS)
+
+  onUnmounted(() => {
+    window.clearInterval(pollHandle)
+    for (const unsub of subscribers.values()) unsub()
+    subscribers.clear()
+  })
 </script>
 
 <template>
-  <div class="atf-panel">
+<div class="atf-panel">
     <header class="atf-header">
       <div class="atf-brand">
         <svg
@@ -401,7 +581,7 @@ onUnmounted(() => {
             <h2 class="atf-section-title">
               Timeline
               <span v-if="events.length" class="atf-badge atf-badge-neutral">
-                {{ events.length }}{{ events.length === MAX_TIMELINE_EVENTS ? "+" : "" }}
+                {{ events.length }}{{ events.length === MAX_TIMELINE_EVENTS ? '+' : '' }}
               </span>
               <button
                 v-if="events.length"
@@ -423,16 +603,16 @@ onUnmounted(() => {
                   :key="event.id"
                   class="atf-timeline-entry"
                   :class="[
-  `atf-timeline-${event.type.split('.')[0]}`,
-  { expanded: expandedEventId === event.id }
-]"
+                    `atf-timeline-${event.type.split('.')[0]}`,
+                    { expanded: expandedEventId === event.id },
+                  ]"
                 >
                   <div class="atf-timeline-row" @click="toggleEvent(event.id)">
                     <span class="atf-timeline-time">{{ formatTime(event.time) }}</span>
                     <span class="atf-timeline-type">{{ event.type }}</span>
                     <span class="atf-timeline-form">{{ event.formKey }}</span>
                     <span class="atf-timeline-caret">
-                      {{ expandedEventId === event.id ? "\u2212" : "+" }}
+                      {{ expandedEventId === event.id ? '−' : '+' }}
                     </span>
                   </div>
                   <div v-if="expandedEventId === event.id" class="atf-timeline-detail">