stimeo-ui 0.16.0 → 0.17.0

data/dist/controllers/persist_controller.js

@@ -1,28 +1,177 @@
 import { Controller } from '@hotwired/stimulus';
 
-// src/controllers/persist_controller.ts
+function sharedRegistry(key, create) {
+  const symbol = Symbol.for(key);
+  const scope = globalThis;
+  const existing = scope[symbol];
+  if (existing !== void 0) return existing;
+  const registry = create();
+  Object.defineProperty(globalThis, symbol, { value: registry });
+  return registry;
+}
+
+function isAttributeValue(value) {
+  return value === null || typeof value === "string";
+}
+function readLeaseRecord(element, record) {
+  try {
+    const parsed = JSON.parse(element.getAttribute(record) ?? "null");
+    if (!Array.isArray(parsed)) return void 0;
+    const [original, written, ...rest] = parsed;
+    const linked = rest[0] !== false;
+    const beneath = linked ? rest : rest.slice(1);
+    if (!beneath.every((under) => typeof under === "string")) return void 0;
+    return isAttributeValue(original) && isAttributeValue(written) ? { original, written, linked, beneath } : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function leasedAuthorValue(element, attribute) {
+  const suffix = `-${attribute}-lease`;
+  for (const name of element.getAttributeNames()) {
+    if (!name.startsWith("data-") || !name.endsWith(suffix)) continue;
+    const record = readLeaseRecord(element, name);
+    if (record) return record.original;
+  }
+  return void 0;
+}
+(class _AttributeLease {
+  static #registry = sharedRegistry(
+    "stimeo-ui.attribute-lease.registry.v1",
+    () => ({ stacks: /* @__PURE__ */ new WeakMap(), names: /* @__PURE__ */ new Map() })
+  );
+  #attribute;
+  #record;
+  #base;
+  #held = /* @__PURE__ */ new Set();
+  constructor(attribute, owner, options = {}) {
+    this.#attribute = attribute;
+    this.#record = `data-${owner}-${attribute}-lease`;
+    this.#base = options.base === true;
+    const names = _AttributeLease.#registry.names;
+    names.set(attribute, (names.get(attribute) ?? /* @__PURE__ */ new Set()).add(this.#record));
+  }
+  write(element, value) {
+    const stack = this.#stack(element);
+    const hold = this.#take(stack) ?? this.#acquire(element, stack);
+    this.#held.add(element);
+    const shows = !this.#covered(element, stack, hold);
+    hold.written = value;
+    this.#mark(element, stack);
+    if (shows) this.#reflect(element, value);
+  }
+  return(element) {
+    const held = this.#held.delete(element);
+    const known = _AttributeLease.#registry.stacks.get(element)?.has(this.#attribute);
+    const stack = held || known || element.hasAttribute(this.#record) ? this.#stack(element) : [];
+    const hold = this.#take(stack);
+    if (!hold) return false;
+    const carries = element.getAttribute(this.#attribute) === hold.written;
+    const owns = carries && !this.#covered(element, stack, hold);
+    const index = stack.indexOf(hold);
+    stack.splice(index, 1);
+    const above = stack[index];
+    if (above) above.linked &&= hold.linked;
+    this.#mark(element, stack);
+    if (!owns) return true;
+    const below = hold.linked ? stack[index - 1] : void 0;
+    this.#reflect(element, below ? below.written : hold.original);
+    return true;
+  }
+  returnAll() {
+    for (const element of Array.from(this.#held)) this.return(element);
+  }
+  #stack(element) {
+    const stacks = _AttributeLease.#registry.stacks;
+    const byAttribute = stacks.get(element) ?? /* @__PURE__ */ new Map();
+    stacks.set(element, byAttribute);
+    const stack = byAttribute.get(this.#attribute) ?? this.#seed(element);
+    byAttribute.set(this.#attribute, stack);
+    return stack;
+  }
+  #seed(element) {
+    const found = [];
+    for (const record of _AttributeLease.#registry.names.get(this.#attribute) ?? []) {
+      const read = readLeaseRecord(element, record);
+      if (read) found.push({ ...read, record });
+    }
+    const depth = ({ beneath }) => beneath.filter((name) => found.some((other) => other.record === name)).length;
+    return found.sort((one, other) => depth(one) - depth(other)).map(({ record, written, original, linked }, index) => ({
+      lease: null,
+      record,
+      written,
+      original,
+      linked: linked && index > 0
+    }));
+  }
+  #take(stack) {
+    const hold = stack.find((held) => held.lease === this) ?? stack.find((held) => held.lease === null && held.record === this.#record);
+    if (hold) hold.lease = this;
+    return hold;
+  }
+  #acquire(element, stack) {
+    const current = element.getAttribute(this.#attribute);
+    const top = stack.at(-1);
+    const bottom = stack[0];
+    const over = top?.written === current ? top : void 0;
+    const from = this.#base ? bottom : over;
+    const hold = {
+      lease: this,
+      record: this.#record,
+      written: current,
+      original: from ? from.original : current,
+      linked: !this.#base && over !== void 0
+    };
+    if (this.#base && bottom) {
+      bottom.linked = true;
+      stack.unshift(hold);
+    } else stack.push(hold);
+    return hold;
+  }
+  #covered(element, stack, hold) {
+    const current = element.getAttribute(this.#attribute);
+    return stack.slice(stack.indexOf(hold) + 1).some((above) => above.written === current);
+  }
+  #mark(element, stack) {
+    const records = /* @__PURE__ */ new Map([[this.#record, null]]);
+    stack.forEach((hold, index) => {
+      const names = stack.slice(0, index).map((under) => under.record);
+      const beneath = [...new Set(names.reverse())].filter((name) => name !== hold.record);
+      const marker = hold.linked || beneath.length === 0 ? [] : [false];
+      records.set(
+        hold.record,
+        hold.written === hold.original && beneath.length === 0 && index === stack.length - 1 ? null : JSON.stringify([hold.original, hold.written, ...marker, ...beneath])
+      );
+    });
+    for (const [name, recorded] of records) {
+      if (element.getAttribute(name) === recorded) continue;
+      if (recorded === null) element.removeAttribute(name);
+      else element.setAttribute(name, recorded);
+    }
+  }
+  #reflect(element, value) {
+    if (element.getAttribute(this.#attribute) === value) return;
+    if (value === null) element.removeAttribute(this.#attribute);
+    else element.setAttribute(this.#attribute, value);
+  }
+});
 
-// src/utils/microtask_coalescer.ts
 var MicrotaskCoalescer = class {
   #run;
   #queued = false;
   #active = false;
   #generation = 0;
-  /** @param run - the single reconciliation pass, invoked at most once per batch. */
   constructor(run) {
     this.#run = run;
   }
-  /** Opens the window in which {@link schedule} is honoured; call from `connect()`. */
   activate() {
     this.#active = true;
   }
-  /** Closes the window and drops any pending pass; call from `disconnect()`. */
   cancel() {
     this.#active = false;
     this.#queued = false;
     this.#generation += 1;
   }
-  /** Requests one pass after the batch settles. Idempotent; inert outside the window. */
   schedule() {
     if (!this.#active || this.#queued) return;
     this.#queued = true;
@@ -35,7 +184,52 @@ var MicrotaskCoalescer = class {
   }
 };
 
-// src/utils/safe_storage.ts
+var MAX_TIMER_DELAY_MS = 2147483647;
+
+var NUMBER_BOUNDS = {
+  timer: { finite: true, min: 0, max: MAX_TIMER_DELAY_MS }};
+function matchesNumberBounds(value, bounds) {
+  if (!Number.isFinite(value)) {
+    const direction = value === Infinity ? "positive" : value === -Infinity ? "negative" : null;
+    if (direction === null) return false;
+    if (bounds.allowInfinity !== "both" && bounds.allowInfinity !== direction) return false;
+  }
+  if (bounds.min !== void 0 && value < bounds.min) return false;
+  if (bounds.max !== void 0 && value > bounds.max) return false;
+  if (bounds.exclusiveMin !== void 0 && value <= bounds.exclusiveMin) return false;
+  if (bounds.integer && !Number.isInteger(value)) return false;
+  if (bounds.allowedValues !== void 0 && !bounds.allowedValues.includes(value)) return false;
+  return true;
+}
+
+function readNumber(raw, fallback, bounds) {
+  return matchesNumberBounds(raw, bounds) ? raw : fallback;
+}
+
+var NumberValueReader = class {
+  #lastRejected = /* @__PURE__ */ new Map();
+  read(owner, name, raw, fallback, bounds) {
+    const resolved = readNumber(raw, fallback, bounds);
+    if (matchesNumberBounds(raw, bounds)) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    const attribute = `data-${owner.identifier}-${name.replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`)}-value`;
+    const literal = owner.element.getAttribute(attribute);
+    if (literal === null) {
+      this.#lastRejected.delete(name);
+      return resolved;
+    }
+    if (this.#lastRejected.get(name) !== literal) {
+      this.#lastRejected.set(name, literal);
+      console.warn(
+        `Stimeo UI: "${owner.identifier}" has an invalid number Value "${name}" declaration ${JSON.stringify(literal)}; using ${fallback}.`
+      );
+    }
+    return resolved;
+  }
+};
+
 function readLocalStorage(key) {
   try {
     return { ok: true, value: window.localStorage.getItem(key) };
@@ -60,43 +254,24 @@ function removeLocalStorage(key) {
   }
 }
 
-// src/utils/safe_timeout.ts
 var TimerRegistry = class {
-  /** Live timer ids that have not yet been cleared (or, for timeouts, fired). */
   ids = /* @__PURE__ */ new Set();
-  /**
-   * Cancels a single tracked timer.
-   *
-   * No-ops if the id is unknown (already cleared, fired, or never owned by this
-   * registry), so callers can clear defensively without guarding.
-   */
   clear(id) {
     if (this.ids.delete(id)) {
       this.cancel(id);
     }
   }
-  /**
-   * Cancels every tracked timer. Call this from a controller's `disconnect()`
-   * to guarantee no timer outlives the element.
-   */
   clearAll() {
     for (const id of this.ids) {
       this.cancel(id);
     }
     this.ids.clear();
   }
-  /** Number of timers currently tracked (pending). */
   get size() {
     return this.ids.size;
   }
 };
 var SafeTimeout = class extends TimerRegistry {
-  /**
-   * Schedules `callback` after `delay` ms and returns the timer id.
-   *
-   * The id is removed from the registry automatically when the timeout fires,
-   * so {@link TimerRegistry.size | size} reflects only still-pending timers.
-   */
   set(callback, delay) {
     const id = this.schedule(() => {
       this.ids.delete(id);
@@ -113,7 +288,6 @@ var SafeTimeout = class extends TimerRegistry {
   }
 };
 
-// src/utils/string_list.ts
 function parseStringList(raw, fallback = []) {
   const text = raw.trim();
   if (text.length === 0) return [...fallback];
@@ -127,19 +301,16 @@ function parseStringList(raw, fallback = []) {
   return parsed.filter((entry) => typeof entry === "string");
 }
 
-// src/utils/transient_hooks.ts
 var TransientHooks = class {
   #attributes;
   constructor(options) {
     this.#attributes = options.attributes;
   }
-  /** Drops the declared hooks from `element`; what it carries besides stays. */
   reset(element) {
     for (const attribute of this.#attributes) element.removeAttribute(attribute);
   }
 };
 
-// src/controllers/persist_controller.ts
 var TRANSIENT = new TransientHooks({ attributes: ["data-persist-restored"] });
 var NON_VALUE_TYPES = /* @__PURE__ */ new Set(["file", "submit", "reset", "button", "image"]);
 var SENSITIVE_TYPES = /* @__PURE__ */ new Set(["password"]);
@@ -171,15 +342,18 @@ var parsePayload = (raw) => {
   return { version: 1, fields };
 };
 var isPersistField = (node) => node instanceof HTMLInputElement || node instanceof HTMLTextAreaElement || node instanceof HTMLSelectElement;
-var PersistController = class extends Controller {
+var PersistController = class _PersistController extends Controller {
+  #numbers = new NumberValueReader();
   static targets = ["field"];
   static values = {
     key: { type: String, default: "" },
     debounce: { type: Number, default: DEFAULT_DEBOUNCE },
-    // A malformed JSON list must fall back without aborting Stimulus connection.
     exclude: { type: String, default: "" },
     clearOn: { type: String, default: "" }
   };
+  static valueConstraints = {
+    debounce: NUMBER_BOUNDS.timer
+  };
   static actions = ["clear"];
   static events = ["restore", "save", "clear", "error"];
   #timeouts = new SafeTimeout();
@@ -208,14 +382,13 @@ var PersistController = class extends Controller {
     this.#connected = true;
     this.#logicalKey = this.#resolveLogicalKey();
     this.#excluded = parseStringList(this.excludeValue, DEFAULT_EXCLUDE);
-    this.#knownFields = /* @__PURE__ */ new WeakSet();
-    this.#forcedRestore.clear();
     this.element.addEventListener("input", this.#onInput);
     this.element.addEventListener("change", this.#onInput);
     this.#syncClearOn();
     this.#restoreDynamic.activate();
     this.#observer.observe(this.element, {
       attributes: true,
+      attributeOldValue: true,
       attributeFilter: [
         "checked",
         "data-controller",
@@ -240,12 +413,9 @@ var PersistController = class extends Controller {
     this.#unbindClearOn();
     this.#observer.disconnect();
     this.#restoreDynamic.cancel();
-    this.#forcedRestore.clear();
-    this.#timeouts.clearAll();
     TRANSIENT.reset(this.element);
     this.#payload = null;
   }
-  /** Drops the active draft after storage confirms the removal. */
   clear() {
     const logicalKey = this.#logicalKey ?? this.#resolveLogicalKey();
     if (logicalKey === null) return;
@@ -259,19 +429,12 @@ var PersistController = class extends Controller {
     this.element.removeAttribute("data-persist-restored");
     this.dispatch("clear", { detail: { key: logicalKey } });
   }
-  /** Rebinds the external clear event when its Value changes. */
   clearOnValueChanged() {
     if (this.#connected) this.#syncClearOn();
   }
-  /** Switches storage namespaces without writing old edits under the new key. */
   keyValueChanged() {
     if (this.#connected) this.#switchLogicalKey();
   }
-  /** Reschedules a pending write against the current debounce delay. */
-  debounceValueChanged() {
-    if (this.#connected && this.#pendingSave !== null) this.#scheduleSave();
-  }
-  /** Restores every field the new exclusion list makes eligible. */
   excludeValueChanged() {
     const previous = this.#excluded;
     this.#excluded = parseStringList(this.excludeValue, DEFAULT_EXCLUDE);
@@ -283,7 +446,6 @@ var PersistController = class extends Controller {
     }
     this.#restoreDynamic.schedule();
   }
-  /** Schedules a debounced save. */
   #scheduleSave() {
     const logicalKey = this.#logicalKey;
     if (logicalKey === null) return;
@@ -294,21 +456,19 @@ var PersistController = class extends Controller {
     }, this.#debounceDelay);
     this.#pendingSave = { id, logicalKey };
   }
-  /** Cancels the currently pending save, if any. */
   #cancelPendingSave() {
     const pending = this.#pendingSave;
     if (pending === null) return;
     this.#timeouts.clear(pending.id);
     this.#pendingSave = null;
   }
-  /** Flushes a pending edit through the same success/error event path as a timer. */
   #flushPendingSave() {
     const pending = this.#pendingSave;
     if (pending === null) return;
     this.#cancelPendingSave();
     this.#save(pending.logicalKey);
+    this.#cancelPendingSave();
   }
-  /** Writes the active payload and emits `save` only after storage succeeds. */
   #save(logicalKey) {
     const payload = this.#serialize();
     const result = writeLocalStorage(this.#storageKey(logicalKey), JSON.stringify(payload));
@@ -320,7 +480,6 @@ var PersistController = class extends Controller {
     this.dispatch("save", { detail: { key: logicalKey } });
     return true;
   }
-  /** Serializes every persistable field into a versioned, typed payload. */
   #serialize() {
     const fields = [];
     for (const { field, key } of this.#fieldEntries()) {
@@ -339,17 +498,13 @@ var PersistController = class extends Controller {
     }
     return { version: 1, fields };
   }
-  /** Reads, validates, and restores the active namespace. */
   #loadActiveDraft() {
     TRANSIENT.reset(this.element);
     this.#payload = null;
     this.#knownFields = /* @__PURE__ */ new WeakSet();
     this.#forcedRestore.clear();
     const logicalKey = this.#logicalKey;
-    if (logicalKey === null) {
-      this.#markCurrentFieldsKnown();
-      return;
-    }
+    if (logicalKey === null) return;
     const result = readLocalStorage(this.#storageKey(logicalKey));
     if (!result.ok) {
       this.#dispatchError(logicalKey, "read", "unavailable");
@@ -371,7 +526,6 @@ var PersistController = class extends Controller {
     this.#payload = payload;
     this.#restoreEntries(null);
   }
-  /** Restores fields inserted or made eligible after the initial connection. */
   #restoreDynamicFields() {
     const selected = new Set(this.#forcedRestore);
     this.#forcedRestore.clear();
@@ -380,7 +534,6 @@ var PersistController = class extends Controller {
     }
     this.#restoreEntries(selected);
   }
-  /** Applies the active payload to all fields, or only the supplied candidates. */
   #restoreEntries(selected) {
     const entries = this.#fieldEntries();
     for (const { field } of entries) this.#knownFields.add(field);
@@ -413,7 +566,6 @@ var PersistController = class extends Controller {
       this.dispatch("restore", { detail: { key: this.#logicalKey } });
     }
   }
-  /** Applies a type-compatible stored value without coercion. */
   #applyValue(field, value) {
     if (field instanceof HTMLInputElement && field.type === "checkbox") {
       if (typeof value !== "boolean") return false;
@@ -439,16 +591,11 @@ var PersistController = class extends Controller {
     field.value = value;
     return true;
   }
-  /** Every control this instance owns, before the exclusion list narrows them. */
   #candidateFields() {
     return this.hasFieldTarget ? this.fieldTargets.filter(isPersistField) : Array.from(this.element.querySelectorAll("input, textarea, select")).filter(
       (field) => this.#ownsField(field)
     );
   }
-  /**
-   * Pairs persistable fields with DOM-order occurrence keys. Every HTML radio
-   * group (same name and form owner) occupies one shared occurrence slot.
-   */
   #fieldEntries() {
     const entries = [];
     const eligible = [];
@@ -480,26 +627,22 @@ var PersistController = class extends Controller {
     }
     return entries;
   }
-  /** Whether a field carries a restorable, non-excluded value. */
   #persistable(field, excluded) {
     if (NON_VALUE_TYPES.has(field.type) || SENSITIVE_TYPES.has(field.type)) return false;
+    if (SENSITIVE_TYPES.has(leasedAuthorValue(field, "type") ?? "")) return false;
     if (excluded.includes(field.type)) return false;
     if (field.name.length > 0 && excluded.includes(field.name)) return false;
     return true;
   }
-  /** A stable storage sub-key for a field (its name, else id). */
   #keyOf(field) {
     return field.name || field.id || null;
   }
-  /** Whether this instance, rather than a nested Persist host, owns a field. */
   #ownsField(field) {
     return field.closest(`[data-controller~="${this.identifier}"]`) === this.element;
   }
-  /** Marks all currently eligible fields without applying a payload. */
   #markCurrentFieldsKnown() {
     for (const { field } of this.#fieldEntries()) this.#knownFields.add(field);
   }
-  /** Switches namespace after flushing the old namespace's pending edit. */
   #switchLogicalKey() {
     const next = this.#resolveLogicalKey();
     if (next === this.#logicalKey) return;
@@ -507,7 +650,6 @@ var PersistController = class extends Controller {
     this.#logicalKey = next;
     this.#loadActiveDraft();
   }
-  /** Synchronizes the exact event name owned by the `clearOn` Value. */
   #syncClearOn() {
     const next = this.#validEventName(this.clearOnValue);
     if (next === this.#registeredClearOn) return;
@@ -516,52 +658,47 @@ var PersistController = class extends Controller {
     this.element.addEventListener(next, this.#onClearEvent);
     this.#registeredClearOn = next;
   }
-  /** Removes the event listener using the name that was actually registered. */
   #unbindClearOn() {
     if (this.#registeredClearOn === null) return;
     this.element.removeEventListener(this.#registeredClearOn, this.#onClearEvent);
     this.#registeredClearOn = null;
   }
-  /** Returns a non-whitespace event type, or null when the hook is disabled. */
   #validEventName(value) {
     const name = value.trim();
     return name.length > 0 && !/\s/.test(name) ? name : null;
   }
-  /**
-   * Collects dynamic controls and select-option changes into one restore pass.
-   *
-   * @stimeoRuntimeOnly `key` decides whether an id change moves the storage namespace; it decides
-   *   nothing shown.
-   */
   #onMutations(records) {
     let rootIdChanged = false;
+    const ownershipBefore = /* @__PURE__ */ new Map();
     for (const record of records) {
       if (record.type === "attributes") {
         if (record.target === this.element && record.attributeName === "id") {
           rootIdChanged = true;
         }
-        this.#collectAttributeCandidate(record.target, record.attributeName);
+        if (record.attributeName === OWNERSHIP_ATTRIBUTE) {
+          const element = record.target;
+          if (!ownershipBefore.has(element)) ownershipBefore.set(element, record.oldValue);
+          continue;
+        }
+        this.#collectControlCandidate(record.target);
         continue;
       }
       for (const node of record.addedNodes) this.#collectRestoreCandidate(node);
     }
+    for (const [element, before] of ownershipBefore) {
+      this.#collectOwnershipCandidate(element, before);
+    }
     if (rootIdChanged && this.keyValue.length === 0) this.#switchLogicalKey();
     this.#restoreDynamic.schedule();
   }
-  /**
-   * Adds the controls one mutated attribute can affect. Only an ownership change on a
-   * descendant moves fields between Persist hosts, so that is the single case worth a
-   * subtree sweep; every other observed attribute describes one control, and sweeping
-   * from its container would re-apply the stored draft over edits still being debounced.
-   */
-  #collectAttributeCandidate(target, attributeName) {
-    if (attributeName === OWNERSHIP_ATTRIBUTE && target !== this.element) {
-      this.#collectRestoreCandidate(target);
-      return;
-    }
-    this.#collectControlCandidate(target);
+  #collectOwnershipCandidate(element, before) {
+    const after = element.getAttribute(OWNERSHIP_ATTRIBUTE);
+    if (this.#namesThisIdentifier(before) === this.#namesThisIdentifier(after)) return;
+    this.#collectRestoreCandidate(element);
+  }
+  #namesThisIdentifier(tokens) {
+    return (tokens ?? "").split(/\s+/).includes(this.identifier);
   }
-  /** Adds a native control, or the select that owns a mutated option. */
   #collectControlCandidate(node) {
     if (isPersistField(node)) {
       this.#forcedRestore.add(node);
@@ -572,7 +709,6 @@ var PersistController = class extends Controller {
       if (select) this.#forcedRestore.add(select);
     }
   }
-  /** Adds every control inside an inserted or newly owned subtree. */
   #collectRestoreCandidate(node) {
     this.#collectControlCandidate(node);
     if (!(node instanceof Element)) return;
@@ -580,31 +716,29 @@ var PersistController = class extends Controller {
       this.#forcedRestore.add(field);
     }
   }
-  /**
-   * Resolves the logical key from the Value, falling back to the host id.
-   *
-   * @stimeoRuntimeOnly `key` names the storage namespace; the restored fields come from what is
-   *   stored there.
-   */
   #resolveLogicalKey() {
     const key = this.keyValue || this.element.id;
     return key.length > 0 ? key : null;
   }
-  /** Namespaces one logical key within localStorage. */
   #storageKey(logicalKey) {
     return `${STORAGE_PREFIX}${logicalKey}`;
   }
-  /** Normalizes an invalid `debounce` Value to the `debounce` default. */
   get #debounceDelay() {
-    const value = this.debounceValue;
-    return Number.isFinite(value) && value >= 0 ? value : DEFAULT_DEBOUNCE;
+    return this.#safeDebounce;
   }
-  /** Dispatches one observable storage failure without exposing browser errors. */
   #dispatchError(key, operation, reason) {
     this.dispatch("error", { detail: { key, operation, reason } });
   }
+  get #safeDebounce() {
+    return this.#numbers.read(
+      this,
+      "debounce",
+      this.debounceValue,
+      _PersistController.values.debounce.default,
+      _PersistController.valueConstraints.debounce
+    );
+  }
 };
 
 export { PersistController };
-//# sourceMappingURL=persist_controller.js.map
 //# sourceMappingURL=persist_controller.js.map