@3sln/nook 0.0.0-stage → 0.1.0

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@3sln/nook",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A quiet, contextual corner for web app extras.",
+  "exports": {
+    ".": "./src/index.js",
+    "./model": "./src/bl/menu.js",
+    "./icons": "./src/ui/icons.js",
+    "./capture": "./src/capture.js"
+  },
+  "files": [
+    "src",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.mjs",
+    "dev": "bun demo/server.js",
+    "test:browser": "playwright test",
+    "check:package": "node scripts/check-package.mjs"
+  },
+  "dependencies": {
+    "@3sln/bab": "^0.2.0",
+    "@3sln/ngin": "^0.0.5"
+  },
+  "devDependencies": {
+    "@playwright/test": "^1.56.0",
+    "happy-dom": "^18.0.1"
+  },
+  "packageManager": "bun@1.3.14",
+  "license": "MIT",
+  "author": "Stubbs Software Solutions LLC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/3sln/nook.git"
+  },
+  "homepage": "https://github.com/3sln/nook#readme",
+  "bugs": {
+    "url": "https://github.com/3sln/nook/issues"
+  },
+  "keywords": [
+    "web-components",
+    "custom-elements",
+    "context-menu",
+    "command-palette",
+    "feedback",
+    "accessibility"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/src/bl/commands.js

@@ -0,0 +1,27 @@
+export function commandMatches(name, description, query) {
+  const words = query.toLocaleLowerCase().trim().split(/\s+/).filter(Boolean);
+  const haystack = `${name} ${description}`.toLocaleLowerCase();
+  return words.every((word) => haystack.includes(word));
+}
+export function validCommand(item) {
+  return Boolean(
+    item.getAttribute("name")?.trim() &&
+      item.getAttribute("description")?.trim(),
+  );
+}
+export function argumentValues(form) {
+  const values = [];
+  for (const field of form.elements) {
+    if (!field.name || field.disabled) continue;
+    const value =
+      field.type === "checkbox"
+        ? field.checked
+        : field.type === "number" || field.type === "range"
+          ? field.value === ""
+            ? null
+            : Number(field.value)
+          : field.value;
+    values.push([field.name, value]);
+  }
+  return Object.fromEntries(values);
+}

package/src/bl/menu.js

@@ -0,0 +1,311 @@
+import { Query } from "@3sln/ngin/queries";
+
+export const corners = ["bottom-right", "bottom-left", "top-left", "top-right"];
+export const positions = [
+  ...corners,
+  "top-center",
+  "right-center",
+  "bottom-center",
+  "left-center",
+];
+export function responsivePositions({ width, height, touch = false }) {
+  return touch && width < 480 && height > width
+    ? positions.filter(
+        (position) => position !== "top-center" && position !== "bottom-center",
+      )
+    : [...positions];
+}
+export function positionPoint(position, width, height) {
+  if (position === "top-center") return [width / 2, 0];
+  if (position === "right-center") return [width, height / 2];
+  if (position === "bottom-center") return [width / 2, height];
+  if (position === "left-center") return [0, height / 2];
+  return [
+    position.endsWith("right") ? width : 0,
+    position.startsWith("bottom") ? height : 0,
+  ];
+}
+export function availablePositions(disabled) {
+  const blocked = new Set(
+    Array.isArray(disabled) ? disabled : String(disabled || "").split(/[\s,]+/),
+  );
+  return positions.filter((position) => !blocked.has(position));
+}
+export function closestAllowedPosition(
+  x,
+  y,
+  width,
+  height,
+  allowed = positions,
+) {
+  let nearest = null,
+    best = Infinity;
+  for (const position of allowed) {
+    const [px, py] = positionPoint(position, width, height);
+    const distance = (x - px) ** 2 + (y - py) ** 2;
+    if (distance < best) {
+      best = distance;
+      nearest = position;
+    }
+  }
+  return nearest;
+}
+export function gesture(dx, dy, threshold = 32) {
+  if (Math.hypot(dx, dy) < threshold) return null;
+  const ratio = Math.abs(dx) / Math.max(Math.abs(dy), 1);
+  return ratio < 0.55 ? "settings" : "all";
+}
+export function nearestCorner(x, y, width, height) {
+  return `${y < height / 2 ? "top" : "bottom"}-${x < width / 2 ? "left" : "right"}`;
+}
+export function availableCorners(disabled) {
+  const blocked = new Set(
+    Array.isArray(disabled) ? disabled : String(disabled || "").split(/[\s,]+/),
+  );
+  return corners.filter((corner) => !blocked.has(corner));
+}
+export function closestAllowedCorner(x, y, width, height, allowed = corners) {
+  let nearest = null,
+    best = Infinity;
+  for (const corner of allowed) {
+    const cx = corner.endsWith("right") ? width : 0,
+      cy = corner.startsWith("bottom") ? height : 0;
+    const distance = (x - cx) ** 2 + (y - cy) ** 2;
+    if (distance < best) {
+      best = distance;
+      nearest = corner;
+    }
+  }
+  return nearest;
+}
+function keyPattern(binding) {
+  const bits = (binding || "")
+    .toLowerCase()
+    .split("+")
+    .map((value) => value.trim());
+  const key = bits.pop();
+  const aliases = {
+    opt: "alt",
+    option: "alt",
+    cmd: "meta",
+    command: "meta",
+    control: "ctrl",
+  };
+  return { key, bits: bits.map((value) => aliases[value] || value) };
+}
+export function bindingSupported(binding, layout) {
+  const { key, bits } = keyPattern(binding);
+  if (!key) return false;
+  // Alt/Option can produce unrelated characters or dead keys. Only the browser's
+  // unmodified layout map establishes which base key the binding refers to.
+  if (bits.includes("alt") && [...key].length === 1)
+    return Boolean(
+      layout &&
+        [...layout.values()].some((value) => value.toLowerCase() === key),
+    );
+  return true;
+}
+export function matchesKey(event, binding, layout) {
+  if (
+    !bindingSupported(binding, layout) ||
+    event.getModifierState?.("AltGraph")
+  )
+    return false;
+  const { key, bits } = keyPattern(binding);
+  return (
+    (event.key.toLowerCase() === key ||
+      (event.altKey && layout?.get(event.code)?.toLowerCase() === key)) &&
+    event.altKey === bits.includes("alt") &&
+    event.ctrlKey === bits.includes("ctrl") &&
+    event.metaKey === bits.includes("meta") &&
+    event.shiftKey === bits.includes("shift")
+  );
+}
+export function transition(state, intent) {
+  switch (intent.type) {
+    case "open":
+      return { ...state, path: [intent.view] };
+    case "enter":
+      return { ...state, path: [...state.path, intent.view] };
+    case "back":
+      return { ...state, path: state.path.slice(0, -1) };
+    case "overflow-availability": {
+      if (intent.available || !state.path.includes("full")) return state;
+      const path = state.path.filter((view) => view !== "full");
+      if (!path.length || state.path[0] === "full") path.unshift("root");
+      return { ...state, path };
+    }
+    case "close":
+      return { ...state, path: [], introTarget: null };
+    case "introduce":
+      return {
+        ...state,
+        needsIntro: false,
+        path: ["welcome"],
+        introTarget: intent.view,
+      };
+    case "finish-intro":
+      return {
+        ...state,
+        path: [intent.view || state.introTarget || "root"],
+        introTarget: null,
+      };
+    case "configure-positions": {
+      const configured = availablePositions(intent.disabled);
+      const allowed = configured.filter((position) =>
+        (intent.options || positions).includes(position),
+      );
+      const preferredPosition = state.preferredPosition || state.corner;
+      const [x, y] = positionPoint(preferredPosition, 1, 1);
+      const corner = allowed.includes(preferredPosition)
+        ? preferredPosition
+        : allowed.includes(state.corner)
+          ? state.corner
+          : closestAllowedPosition(x, y, 1, 1, allowed) || state.corner;
+      return {
+        ...state,
+        corner,
+        preferredPosition,
+        configuredPositions: configured,
+        allowedPositions: allowed,
+        allowedCorners: allowed.filter((position) =>
+          corners.includes(position),
+        ),
+      };
+    }
+    case "configure-corners": {
+      const allowed = availableCorners(intent.disabled);
+      const corner = allowed.includes(state.corner)
+        ? state.corner
+        : closestAllowedCorner(
+            state.corner.endsWith("right") ? 1 : 0,
+            state.corner.startsWith("bottom") ? 1 : 0,
+            1,
+            1,
+            allowed,
+          ) || state.corner;
+      return { ...state, allowedCorners: allowed, corner };
+    }
+    case "corner": {
+      if (
+        !(
+          state.configuredPositions ||
+          state.allowedPositions ||
+          state.allowedCorners ||
+          positions
+        ).includes(intent.corner)
+      )
+        return state;
+      const allowed =
+        state.allowedPositions || state.allowedCorners || positions;
+      const [x, y] = positionPoint(intent.corner, 1, 1);
+      const corner = allowed.includes(intent.corner)
+        ? intent.corner
+        : closestAllowedPosition(x, y, 1, 1, allowed) || state.corner;
+      return { ...state, corner, preferredPosition: intent.corner };
+    }
+    default:
+      return state;
+  }
+}
+// A Query owns the only menu projection and its listener lifetime. The DOM edge
+// supplies intent; it never maintains a parallel menu/navigation store.
+export class MenuState extends Query {
+  static deps = ["intents", "onboarding"];
+  constructor(corner, disabled, options = positions) {
+    super();
+    this.corner = corner;
+    this.disabled = disabled;
+    this.options = options;
+  }
+  boot({ intents, onboarding }, { notify }) {
+    let state = {
+      corner: positions.includes(this.corner) ? this.corner : corners[0],
+      path: [],
+      needsIntro: !onboarding.hasSeen(),
+      attentionActive: false,
+      introTarget: null,
+    };
+    state = transition(state, {
+      type: "configure-positions",
+      disabled: this.disabled,
+      options: this.options,
+    });
+    const receive = (event) => {
+      let intent = event.detail;
+      if (state.needsIntro && ["open", "enter"].includes(intent.type)) {
+        // Another tab or Nook instance may have shown the guide since boot.
+        if (onboarding.hasSeen()) state = { ...state, needsIntro: false };
+        else {
+          onboarding.markSeen();
+          intent = { type: "introduce", view: intent.view };
+        }
+      }
+      state = transition(state, intent);
+      notify(state);
+    };
+    intents.addEventListener("intent", receive);
+    notify(state);
+    const releaseAttention = onboarding.subscribeAttention((active) => {
+      state = { ...state, attentionActive: active };
+      notify(state);
+    });
+    this.kill = () => {
+      releaseAttention();
+      intents.removeEventListener("intent", receive);
+    };
+  }
+}
+
+// Item count is the default policy; embedders can explicitly choose presentation
+// for custom content whose size cannot be known from its declarative shape.
+export function presentation(kind, count, override = "auto") {
+  if (override === "compact" || override === "expanded") return override;
+  if (
+    kind === "panel" ||
+    kind === "welcome" ||
+    kind === "commands" ||
+    kind === "feedback" ||
+    kind === "enum" ||
+    kind === "command"
+  )
+    return "expanded";
+  return count <= (kind === "settings" ? 3 : kind === "root" ? 5 : 4)
+    ? "compact"
+    : "expanded";
+}
+
+export function inheritedPresentation(path, base) {
+  return path.some((id) => base(id) === "expanded")
+    ? "expanded"
+    : base(path.at(-1));
+}
+
+export function selectionNumber(event, layout) {
+  if (
+    !event.altKey ||
+    event.ctrlKey ||
+    event.metaKey ||
+    event.shiftKey ||
+    !layout ||
+    event.getModifierState?.("AltGraph")
+  )
+    return null;
+  const value = layout.get(event.code);
+  return /^[1-9]$/.test(value || "") ? Number(value) : null;
+}
+
+// Sorting is stable: equal priorities keep their authored order. One root slot
+// is reserved for More only when it is needed.
+export function distributeItems(entries, capacity) {
+  const ranked = entries
+    .map((entry, index) => ({ ...entry, index }))
+    .sort(
+      (a, b) =>
+        (Number(b.priority) || 0) - (Number(a.priority) || 0) ||
+        a.index - b.index,
+    );
+  const slots = Math.max(1, Math.floor(capacity));
+  const split = ranked.length <= slots ? ranked.length : Math.max(0, slots - 1);
+  return { root: ranked.slice(0, split), overflow: ranked.slice(split) };
+}

package/src/capture.js

@@ -0,0 +1,129 @@
+// Native sharing always requires the browser's surface chooser. A session reuses
+// the chosen stream for multiple snapshots and releases it on Done/abort.
+export function createTabCaptureSession({ window = globalThis.window } = {}) {
+  let stream,
+    controller,
+    boundSignal,
+    boundAbort,
+    busy = false,
+    count = 0;
+  const stop = () => {
+    const current = stream;
+    stream = null;
+    controller?.abort();
+    controller = null;
+    if (boundSignal && boundAbort)
+      boundSignal.removeEventListener("abort", boundAbort);
+    boundSignal = null;
+    boundAbort = null;
+    for (const track of current?.getTracks() || []) track.stop();
+  };
+  const capture = async ({ signal, name } = {}) => {
+    if (busy) throw new Error("A snapshot is already being captured.");
+    if (signal?.aborted)
+      throw new DOMException("Capture canceled", "AbortError");
+    if (!window.navigator.mediaDevices?.getDisplayMedia)
+      throw new Error("Screen capture is not available in this browser.");
+    busy = true;
+    if (!controller) controller = new AbortController();
+    const lifetime = controller.signal;
+    if (signal !== boundSignal) {
+      if (boundSignal && boundAbort)
+        boundSignal.removeEventListener("abort", boundAbort);
+      boundSignal = signal;
+      boundAbort = stop;
+      signal?.addEventListener("abort", stop, { once: true });
+    }
+    try {
+      if (!stream) {
+        const chosen = await window.navigator.mediaDevices.getDisplayMedia({
+          video: true,
+          audio: false,
+          preferCurrentTab: true,
+          selfBrowserSurface: "include",
+        });
+        if (lifetime.aborted) {
+          chosen.getTracks().forEach((track) => track.stop());
+          throw new DOMException("Capture canceled", "AbortError");
+        }
+        stream = chosen;
+        for (const track of stream.getTracks())
+          track.addEventListener?.("ended", stop, { once: true });
+      }
+      const result = await snapshot(stream, {
+        window,
+        signal: lifetime,
+        name: name || `app-screenshot-${count + 1}.png`,
+      });
+      count++;
+      return result;
+    } catch (error) {
+      if (!stream) stop();
+      throw error;
+    } finally {
+      busy = false;
+    }
+  };
+  return { capture, stop };
+}
+export async function captureTabScreenshot({
+  signal,
+  window = globalThis.window,
+} = {}) {
+  const session = createTabCaptureSession({ window });
+  try {
+    return await session.capture({ signal, name: "app-screenshot.png" });
+  } finally {
+    session.stop();
+  }
+}
+async function snapshot(stream, { window, signal, name }) {
+  const video = window.document.createElement("video");
+  try {
+    if (signal.aborted)
+      throw new DOMException("Capture canceled", "AbortError");
+    video.srcObject = stream;
+    video.muted = true;
+    await video.play();
+    await new Promise((resolve, reject) => {
+      let frame;
+      const finish = () => {
+        signal.removeEventListener("abort", abort);
+        resolve();
+      };
+      const abort = () => {
+        if (frame !== undefined) {
+          if (video.cancelVideoFrameCallback)
+            video.cancelVideoFrameCallback(frame);
+          else window.cancelAnimationFrame?.(frame);
+        }
+        reject(new DOMException("Capture canceled", "AbortError"));
+      };
+      signal.addEventListener("abort", abort, { once: true });
+      if (signal.aborted) {
+        abort();
+        return;
+      }
+      frame = video.requestVideoFrameCallback
+        ? video.requestVideoFrameCallback(finish)
+        : window.requestAnimationFrame(finish);
+    });
+    if (signal.aborted)
+      throw new DOMException("Capture canceled", "AbortError");
+    const canvas = window.document.createElement("canvas");
+    canvas.width = video.videoWidth;
+    canvas.height = video.videoHeight;
+    if (!canvas.width || !canvas.height)
+      throw new Error("The shared view is not ready.");
+    canvas.getContext("2d").drawImage(video, 0, 0);
+    const blob = await new Promise((resolve) =>
+      canvas.toBlob(resolve, "image/png"),
+    );
+    if (signal.aborted)
+      throw new DOMException("Capture canceled", "AbortError");
+    if (!blob) throw new Error("Could not create a screenshot.");
+    return new File([blob], name, { type: "image/png" });
+  } finally {
+    video.srcObject = null;
+  }
+}