@3sln/nook 0.0.0-stage → 0.1.0

package/src/providers/attention.js

@@ -0,0 +1,99 @@
+export const attentionKey = "@3sln/nook:attention:v1";
+const burstMs = 6000;
+const minimumRetryMs = 45 * 60 * 1000;
+const retryRangeMs = 30 * 60 * 1000;
+
+// A document-shared lease owns the timer and browser listeners. Its persisted
+// deadline prevents reloading/reconnecting from restarting attention bursts.
+export function attentionResource({
+  owner,
+  storage,
+  hasSeen,
+  now = Date.now,
+  random = Math.random,
+  setTimer = (callback, delay) => setTimeout(callback, delay),
+  clearTimer = (timer) => clearTimeout(timer),
+}) {
+  const listeners = new Set();
+  let timer;
+  let record;
+  let active = false;
+  const emit = (value) => {
+    if (active === value) return;
+    active = value;
+    for (const listener of listeners) listener(value);
+  };
+  const clear = () => {
+    if (timer !== undefined) clearTimer(timer);
+    timer = undefined;
+  };
+  const read = () => {
+    try {
+      const saved = JSON.parse(storage?.getItem(attentionKey) || "null");
+      if (
+        saved &&
+        Number.isFinite(saved.until) &&
+        Number.isFinite(saved.next) &&
+        saved.next >= saved.until &&
+        saved.next <= now() + 75 * 60 * 1000 &&
+        saved.until <= now() + burstMs
+      )
+        record = saved;
+    } catch {}
+    return record;
+  };
+  const write = () => {
+    try {
+      storage?.setItem(attentionKey, JSON.stringify(record));
+    } catch {}
+  };
+  const advance = () => {
+    clear();
+    if (!listeners.size || hasSeen() || owner?.visibilityState === "hidden") {
+      emit(false);
+      return;
+    }
+    const time = now();
+    read();
+    if (!record || time >= record.next) {
+      record = {
+        until: time + burstMs,
+        next:
+          time +
+          minimumRetryMs +
+          Math.floor(Math.max(0, Math.min(1, random())) * retryRangeMs),
+      };
+      write();
+    }
+    const inviting = time < record.until;
+    emit(inviting);
+    timer = setTimer(
+      advance,
+      Math.max(1, (inviting ? record.until : record.next) - time),
+    );
+  };
+  return {
+    subscribe(listener) {
+      listeners.add(listener);
+      listener(active);
+      if (listeners.size === 1) {
+        owner?.addEventListener?.("visibilitychange", advance);
+        owner?.defaultView?.addEventListener?.("storage", advance);
+      }
+      advance();
+      return () => {
+        listeners.delete(listener);
+        if (!listeners.size) {
+          clear();
+          active = false;
+          owner?.removeEventListener?.("visibilitychange", advance);
+          owner?.defaultView?.removeEventListener?.("storage", advance);
+        }
+      };
+    },
+    acknowledge() {
+      clear();
+      emit(false);
+    },
+  };
+}

package/src/providers/onboarding.js

@@ -0,0 +1,35 @@
+import { attentionResource } from "./attention.js";
+export const onboardingKey = "@3sln/nook:tutorial:v1";
+// The provider owns a page-scoped fallback. Weak ownership lets the document and
+// its in-memory preferences go away together, even when storage is denied.
+const sessions = new WeakMap();
+export function onboardingResource({ storage, owner }) {
+  if (!sessions.has(owner)) sessions.set(owner, { seen: new Set() });
+  const page = sessions.get(owner);
+  const session = page.seen;
+  const resource = {
+    hasSeen() {
+      if (session.has(onboardingKey)) return true;
+      try {
+        return storage?.getItem(onboardingKey) === "seen";
+      } catch {
+        return false;
+      }
+    },
+    markSeen() {
+      session.add(onboardingKey);
+      page.attention?.acknowledge();
+      try {
+        storage?.setItem(onboardingKey, "seen");
+      } catch {}
+    },
+  };
+  page.attention ??= attentionResource({
+    owner,
+    storage,
+    hasSeen: () => resource.hasSeen(),
+  });
+  resource.subscribeAttention = (listener) =>
+    page.attention.subscribe(listener);
+  return resource;
+}

package/src/ui/bounds.js

@@ -0,0 +1,159 @@
+const definitions = new Set([
+  "nook-action",
+  "nook-setting",
+  "nook-menu",
+  "nook-panel",
+  "nook-command",
+  "nook-arg",
+  "nook-option",
+  "template",
+  "script",
+  "style",
+]);
+export function hasAppContent(host) {
+  return [...host.childNodes].some((node) =>
+    node.nodeType === 3
+      ? Boolean(node.textContent.trim())
+      : node.nodeType === 1 && !definitions.has(node.localName),
+  );
+}
+export default function bounds(host, { signal, onChange }) {
+  const view = host.ownerDocument.defaultView;
+  const visualViewport = view.visualViewport;
+  const probe = host.ownerDocument.createElement("span");
+  probe.hidden = true;
+  probe.className = "boundary-measure";
+  host.shadowRoot.append(probe);
+  let frame, previous;
+  const update = () => {
+    frame = undefined;
+    // Fixed UI uses layout-viewport coordinates. The keyboard can shrink and
+    // pan only the visual viewport without changing innerHeight.
+    const viewport = {
+      left: visualViewport?.offsetLeft ?? 0,
+      top: visualViewport?.offsetTop ?? 0,
+      width: visualViewport?.width ?? view.innerWidth,
+      height: visualViewport?.height ?? view.innerHeight,
+    };
+    viewport.right = viewport.left + viewport.width;
+    viewport.bottom = viewport.top + viewport.height;
+    const wrapped =
+      host.getAttribute("boundary") === "self" ||
+      (host.getAttribute("boundary") !== "viewport" && hasAppContent(host));
+    const raw = wrapped ? host.getBoundingClientRect() : viewport;
+    const style = view.getComputedStyle(probe);
+    const length = (name) => parseFloat(style[name]) || 0;
+    const left = Math.max(
+      viewport.left,
+      raw.left + length("marginLeft"),
+      viewport.left + length("paddingLeft"),
+    );
+    const top = Math.max(
+      viewport.top,
+      raw.top + length("marginTop"),
+      viewport.top + length("paddingTop"),
+    );
+    const right = Math.min(
+      viewport.right,
+      raw.right - length("marginRight"),
+      viewport.right - length("paddingRight"),
+    );
+    const bottom = Math.min(
+      viewport.bottom,
+      raw.bottom - length("marginBottom"),
+      viewport.bottom - length("paddingBottom"),
+    );
+    const rect = {
+      left,
+      top,
+      right,
+      bottom,
+      width: Math.max(0, right - left),
+      height: Math.max(0, bottom - top),
+      wrapped,
+      visible: right > left && bottom > top,
+    };
+    host.toggleAttribute("data-contained", wrapped);
+    host.toggleAttribute("data-bound-hidden", !rect.visible);
+    const values = {
+      top,
+      left,
+      right: view.innerWidth - right,
+      bottom: view.innerHeight - bottom,
+      width: rect.width,
+      height: rect.height,
+    };
+    for (const [name, value] of Object.entries(values)) {
+      const key = `--nook-bound-${name}`,
+        text = `${Math.max(0, value)}px`;
+      if (host.style.getPropertyValue(key) !== text)
+        host.style.setProperty(key, text);
+    }
+    const scheme = view.getComputedStyle(host).colorScheme;
+    const inherited = scheme && scheme !== "normal" ? scheme : "light dark";
+    if (
+      host.style.getPropertyValue("--nook-inherited-color-scheme") !== inherited
+    )
+      host.style.setProperty("--nook-inherited-color-scheme", inherited);
+    if (
+      !previous ||
+      Object.keys(rect).some((key) => rect[key] !== previous[key])
+    ) {
+      previous = rect;
+      onChange(rect);
+    }
+  };
+  const schedule = () => {
+    if (frame === undefined && !signal.aborted)
+      frame = view.requestAnimationFrame(update);
+  };
+  const observer = new view.MutationObserver((records) => {
+    if (
+      records.some(
+        (record) =>
+          record.target === host.ownerDocument.documentElement &&
+          record.attributeName === "lang",
+      )
+    )
+      host.i18n.refresh();
+    if (
+      hasAppContent(host) ||
+      records.some(
+        (record) =>
+          record.target === host ||
+          record.target === host.ownerDocument.documentElement,
+      )
+    )
+      schedule();
+  });
+  observer.observe(host.ownerDocument.documentElement, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    attributeFilter: ["style", "class", "hidden", "lang", "boundary"],
+  });
+  const resize = view.ResizeObserver ? new view.ResizeObserver(schedule) : null;
+  resize?.observe(host);
+  visualViewport?.addEventListener("resize", schedule, { signal });
+  visualViewport?.addEventListener("scroll", schedule, { signal });
+  view.addEventListener("resize", schedule, { signal });
+  view.addEventListener("scroll", schedule, { signal, capture: true });
+  host.appSlot.addEventListener("slotchange", schedule, { signal });
+  signal.addEventListener(
+    "abort",
+    () => {
+      observer.disconnect();
+      resize?.disconnect();
+      if (frame !== undefined) view.cancelAnimationFrame(frame);
+      probe.remove();
+    },
+    { once: true },
+  );
+  update();
+  return {
+    refresh: schedule,
+    get rect() {
+      return previous;
+    },
+  };
+}

package/src/ui/commandPalette.js

@@ -0,0 +1,236 @@
+import { commandMatches, argumentValues } from "../bl/commands.js";
+
+// Persistent result buttons and forms belong to the DOM renderer. Filtering only
+// changes visibility; it never replaces an argument field or its current value.
+export default function commandPalette({
+  view,
+  make,
+  i18n,
+  choose,
+  run,
+  supported,
+  createEnum,
+}) {
+  const search = make("input", "command-search");
+  search.type = "search";
+  search.className = "command-search";
+  i18n.attr(search, "placeholder", "Search commands…");
+  i18n.attr(search, "aria-label", "Search commands");
+  search.autocomplete = "off";
+  const list = make("div", "command-list");
+  list.className = "command-list";
+  const empty = make("p", "command-empty", "No matching commands.");
+  empty.className = "command-empty";
+  empty.setAttribute("role", "status");
+  const results = make("div", "command-results");
+  results.className = "command-results";
+  results.append(list, empty);
+  view.body.append(search, results);
+  const records = new Map();
+  let active = null;
+  let order = [];
+  const status = make("span", "command-status");
+  status.className = "live";
+  status.id = "nook-command-status";
+  status.setAttribute("role", "status");
+  view.body.append(status);
+  search.setAttribute("aria-describedby", status.id);
+  const visible = () => order.filter((record) => !record.button.hidden);
+  const highlight = (record) => {
+    active = record;
+    i18n.text(
+      status,
+      record ? "{name}. {description}" : "",
+      record
+        ? () => ({
+            name: record.name.textContent,
+            description: record.description.textContent,
+          })
+        : undefined,
+    );
+    for (const candidate of records.values())
+      candidate.button.dataset.active = String(candidate === record);
+  };
+  const filter = () => {
+    for (const [source, record] of records) {
+      record.button.hidden = !commandMatches(
+        record.name.textContent,
+        record.description.textContent,
+        search.value,
+      );
+    }
+    const candidates = visible();
+    empty.hidden = Boolean(candidates.length);
+    if (!candidates.includes(active)) highlight(candidates[0] || null);
+  };
+  search.addEventListener("input", filter);
+  search.addEventListener("keydown", (event) => {
+    const candidates = visible();
+    if (["ArrowDown", "ArrowUp", "Enter"].includes(event.key)) {
+      event.preventDefault();
+      event.stopPropagation();
+      if (event.key === "Enter") {
+        active?.button.click();
+        return;
+      }
+      const delta = event.key === "ArrowDown" ? 1 : -1;
+      highlight(
+        candidates[
+          (candidates.indexOf(active) + delta + candidates.length) %
+            candidates.length
+        ] || null,
+      );
+      active?.button.scrollIntoView?.({ block: "nearest" });
+    }
+  });
+  return {
+    search,
+    reset() {
+      search.value = "";
+      filter();
+    },
+    reconcile(commands) {
+      const wanted = new Set(commands);
+      for (const [source, record] of records)
+        if (!wanted.has(source)) {
+          record.button.remove();
+          records.delete(source);
+        }
+      let cursor = list.firstChild;
+      for (const source of commands) {
+        let record = records.get(source);
+        if (!record) {
+          const button = make("button", "command-result");
+          button.type = "button";
+          button.className = "command-result";
+          const name = make("span", "command-name");
+          const description = make("small", "command-description");
+          const binding = make("kbd", "command-keybind");
+          binding.className = "keyboard-only";
+          const number = make("span", "number");
+          number.className = "number";
+          number.setAttribute("aria-hidden", "true");
+          button.append(name, description, binding, number);
+          button.onclick = () => choose(source);
+          record = { button, name, description, binding };
+          records.set(source, record);
+        }
+        const name = source.getAttribute("name").trim(),
+          description = source.getAttribute("description").trim();
+        i18n.text(record.name, name);
+        i18n.text(record.description, description);
+        const binding = source.getAttribute("keybind") || "";
+        if (record.binding.textContent !== binding)
+          record.binding.textContent = binding;
+        record.binding.hidden = !binding || !supported(binding);
+        i18n.attr(record.button, "aria-label", name);
+        if (record.button !== cursor) list.insertBefore(record.button, cursor);
+        cursor = record.button.nextSibling;
+      }
+      order = commands.map((source) => records.get(source));
+      filter();
+    },
+    mountForm(source, body) {
+      const form = make("form", "command-form");
+      form.className = "command-form";
+      const description = make("p", "command-description");
+      description.className = "command-description";
+      const fields = make("div", "command-fields");
+      fields.className = "command-fields";
+      const submit = make("button", "command-run", "Run command");
+      submit.type = "submit";
+      submit.className = "command-run";
+      form.append(description, fields, submit);
+      body.append(form);
+      const controls = new Map();
+      form.addEventListener("submit", (event) => {
+        event.preventDefault();
+        event.stopPropagation();
+        if (form.reportValidity()) run(source, argumentValues(form));
+      });
+      return {
+        form,
+        dispose() {
+          for (const record of controls.values()) record.enum?.dispose();
+        },
+        reconcile() {
+          i18n.text(description, source.getAttribute("description"));
+          const args = [...source.querySelectorAll("nook-arg")].filter(
+            (arg) =>
+              arg.closest("nook-command") === source &&
+              arg.getAttribute("name")?.trim() &&
+              !arg.hidden,
+          );
+          const wanted = new Set(args);
+          for (const [arg, record] of controls)
+            if (!wanted.has(arg)) {
+              record.enum?.dispose();
+              record.row.remove();
+              controls.delete(arg);
+            }
+          let cursor = fields.firstChild;
+          for (const arg of args) {
+            const type = arg.getAttribute("type") || "text";
+            let record = controls.get(arg);
+            if (record && record.type !== type) {
+              record.enum?.dispose();
+              record.row.remove();
+              controls.delete(arg);
+              record = null;
+            }
+            if (!record) {
+              const isEnum = ["enum", "select"].includes(type);
+              const row = make(isEnum ? "div" : "label", "command-field");
+              row.className = "command-field";
+              const caption = make("span", "command-arg-label");
+              let picker;
+              const control = isEnum
+                ? (picker = createEnum(
+                    arg,
+                    () => arg.getAttribute("label") || arg.getAttribute("name"),
+                    () => {
+                      control.dispatchEvent(
+                        new Event("input", { bubbles: true }),
+                      );
+                      control.dispatchEvent(
+                        new Event("change", { bubbles: true }),
+                      );
+                    },
+                    arg.getAttribute("value") || "",
+                  )).proxy
+                : make("input", "command-arg-control");
+              if (!isEnum) control.type = type === "toggle" ? "checkbox" : type;
+              control.value = arg.getAttribute("value") || "";
+              if (control.type === "checkbox")
+                control.checked = arg.getAttribute("value") === "true";
+              row.append(caption, picker ? picker.element : control);
+              record = { row, caption, control, type, enum: picker };
+              controls.set(arg, record);
+            }
+            const { row, caption, control } = record;
+            const title = arg.getAttribute("label") || arg.getAttribute("name");
+            i18n.text(caption, title);
+            control.name = arg.getAttribute("name");
+            control.required = arg.hasAttribute("required");
+            control.disabled = arg.hasAttribute("disabled");
+            for (const key of [
+              "min",
+              "max",
+              "step",
+              "placeholder",
+              "pattern",
+            ]) {
+              const value = arg.getAttribute(key);
+              if (value === null) control.removeAttribute(key);
+              else if (key === "placeholder") i18n.attr(control, key, value);
+              else control.setAttribute(key, value);
+            }
+            record.enum?.reconcile();
+            if (row !== cursor) fields.insertBefore(row, cursor);
+            cursor = row.nextSibling;
+          }
+        },
+      };
+    },
+  };
+}