@hexclave/next 1.0.3 → 1.0.6

package/src/dev-tool/dev-tool-trigger-position.test.ts

@@ -0,0 +1,113 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+import { describe, expect, it } from "vitest";
+import { clampTriggerPosition, getSnappedTriggerPlacement, resolveTriggerPosition } from "./dev-tool-trigger-position";
+
+const triggerSize = { width: 36, height: 36 };
+const viewport = { width: 1000, height: 700 };
+
+describe("corner snapping", () => {
+  it("snaps to bottom-right when trigger is in the bottom-right quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 800, top: 600 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "bottom-right" });
+  });
+
+  it("snaps to top-left when trigger is in the top-left quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 10, top: 20 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "top-left" });
+  });
+
+  it("snaps to top-right when trigger is in the top-right quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 900, top: 50 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "top-right" });
+  });
+
+  it("snaps to bottom-left when trigger is in the bottom-left quadrant", () => {
+    const placement = getSnappedTriggerPlacement({ left: 50, top: 650 }, triggerSize, viewport);
+    expect(placement).toEqual({ corner: "bottom-left" });
+  });
+});
+
+describe("corner position resolution", () => {
+  it("resolves bottom-right to margin from bottom and right edges", () => {
+    const pos = resolveTriggerPosition({ corner: "bottom-right" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 1000 - 36 - 16, top: 700 - 36 - 16 });
+  });
+
+  it("resolves top-left to margin from top and left edges", () => {
+    const pos = resolveTriggerPosition({ corner: "top-left" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 16, top: 16 });
+  });
+
+  it("resolves top-right to margin from top and right edges", () => {
+    const pos = resolveTriggerPosition({ corner: "top-right" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 1000 - 36 - 16, top: 16 });
+  });
+
+  it("resolves bottom-left to margin from bottom and left edges", () => {
+    const pos = resolveTriggerPosition({ corner: "bottom-left" }, triggerSize, viewport);
+    expect(pos).toEqual({ left: 16, top: 700 - 36 - 16 });
+  });
+
+  it("has equal left/top margin for top-left corner", () => {
+    const pos = resolveTriggerPosition({ corner: "top-left" }, triggerSize, viewport);
+    expect(pos.left).toBe(pos.top);
+  });
+
+  it("keeps the trigger on-screen when the viewport is smaller than the margin and trigger", () => {
+    const tinyViewport = { width: 40, height: 40 };
+    const pos = resolveTriggerPosition({ corner: "bottom-right" }, triggerSize, tinyViewport);
+    expect(pos).toEqual({ left: 4, top: 4 });
+  });
+});
+
+describe("resize anchor regression", () => {
+  it("bottom-right corner tracks the bottom-right edge after viewport shrinks", () => {
+    const placement = { corner: "bottom-right" } as const;
+    const pos1 = resolveTriggerPosition(placement, triggerSize, { width: 800, height: 600 });
+    expect(pos1).toEqual({ left: 800 - 36 - 16, top: 600 - 36 - 16 });
+  });
+
+  it("bottom-right corner tracks the bottom-right edge after viewport grows", () => {
+    const placement = { corner: "bottom-right" } as const;
+    const pos2 = resolveTriggerPosition(placement, triggerSize, { width: 1440, height: 900 });
+    expect(pos2).toEqual({ left: 1440 - 36 - 16, top: 900 - 36 - 16 });
+  });
+
+  it("top-right corner tracks the top-right edge across resize cycles", () => {
+    const placement = { corner: "top-right" } as const;
+    for (const vw of [600, 800, 1000, 1440]) {
+      const pos = resolveTriggerPosition(placement, triggerSize, { width: vw, height: 700 });
+      expect(pos.left).toBe(vw - 36 - 16);
+      expect(pos.top).toBe(16);
+    }
+  });
+
+  it("corner does not change on resize (placement is stable)", () => {
+    // The same corner placement always resolves without changing its corner.
+    const placement = getSnappedTriggerPlacement({ left: 950, top: 650 }, triggerSize, viewport);
+    expect(placement.corner).toBe("bottom-right");
+
+    // After resize, applying resolveTriggerPosition still produces bottom-right geometry.
+    const smallVp = resolveTriggerPosition(placement, triggerSize, { width: 400, height: 300 });
+    expect(smallVp.left).toBe(400 - 36 - 16);
+    expect(smallVp.top).toBe(300 - 36 - 16);
+  });
+});
+
+describe("clampTriggerPosition", () => {
+  it("clamps positions outside the viewport", () => {
+    expect(clampTriggerPosition({ left: -50, top: -20 }, triggerSize, viewport)).toEqual({ left: 0, top: 0 });
+    expect(clampTriggerPosition({ left: 9999, top: 9999 }, triggerSize, viewport)).toEqual({
+      left: viewport.width - triggerSize.width,
+      top: viewport.height - triggerSize.height,
+    });
+  });
+
+  it("preserves positions already within bounds", () => {
+    const pos = { left: 200, top: 300 };
+    expect(clampTriggerPosition(pos, triggerSize, viewport)).toEqual(pos);
+  });
+});

package/src/dev-tool/dev-tool-trigger-position.ts

@@ -0,0 +1,109 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+export type TriggerCorner = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export type TriggerPlacement = {
+  corner: TriggerCorner;
+};
+
+export type TriggerPosition = {
+  left: number;
+  top: number;
+};
+
+export type TriggerSize = {
+  width: number;
+  height: number;
+};
+
+export type TriggerViewport = {
+  width: number;
+  height: number;
+};
+
+export const TRIGGER_EDGE_MARGIN = 16;
+
+function getSnapBounds(
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+) {
+  const maxLeft = Math.max(0, viewport.width - triggerSize.width);
+  const maxTop = Math.max(0, viewport.height - triggerSize.height);
+  const minLeft = Math.min(TRIGGER_EDGE_MARGIN, maxLeft);
+  const minTop = Math.min(TRIGGER_EDGE_MARGIN, maxTop);
+  return {
+    minLeft,
+    maxLeft: Math.max(minLeft, maxLeft - TRIGGER_EDGE_MARGIN),
+    minTop,
+    maxTop: Math.max(minTop, maxTop - TRIGGER_EDGE_MARGIN),
+  };
+}
+
+/**
+ * Clamps a position so the trigger stays fully within the viewport.
+ * Used during drag to prevent the pill from leaving the screen.
+ */
+export function clampTriggerPosition(
+  position: TriggerPosition,
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+): TriggerPosition {
+  const maxLeft = Math.max(0, viewport.width - triggerSize.width);
+  const maxTop = Math.max(0, viewport.height - triggerSize.height);
+  return {
+    left: Math.max(0, Math.min(position.left, maxLeft)),
+    top: Math.max(0, Math.min(position.top, maxTop)),
+  };
+}
+
+/**
+ * Returns the exact pixel position for a corner placement.
+ * The trigger is always `TRIGGER_EDGE_MARGIN` px from both adjacent edges.
+ */
+export function resolveTriggerPosition(
+  placement: TriggerPlacement,
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+): TriggerPosition {
+  const bounds = getSnapBounds(triggerSize, viewport);
+  const position = (() => {
+    switch (placement.corner) {
+      case 'top-left': {
+        return { left: bounds.minLeft, top: bounds.minTop };
+      }
+      case 'top-right': {
+        return { left: bounds.maxLeft, top: bounds.minTop };
+      }
+      case 'bottom-left': {
+        return { left: bounds.minLeft, top: bounds.maxTop };
+      }
+      case 'bottom-right': {
+        return { left: bounds.maxLeft, top: bounds.maxTop };
+      }
+    }
+  })();
+
+  return clampTriggerPosition(position, triggerSize, viewport);
+}
+
+/**
+ * Snaps a free position to the nearest corner by checking which viewport
+ * quadrant the trigger center falls in.
+ */
+export function getSnappedTriggerPlacement(
+  position: TriggerPosition,
+  triggerSize: TriggerSize,
+  viewport: TriggerViewport,
+): TriggerPlacement {
+  const cx = position.left + triggerSize.width / 2;
+  const cy = position.top + triggerSize.height / 2;
+
+  const corner: TriggerCorner =
+    cy < viewport.height / 2
+      ? cx < viewport.width / 2 ? 'top-left' : 'top-right'
+      : cx < viewport.width / 2 ? 'bottom-left' : 'bottom-right';
+
+  return { corner };
+}

package/src/dev-tool/index.ts

@@ -0,0 +1,149 @@
+
+//===========================================
+// THIS FILE IS AUTO-GENERATED FROM TEMPLATE. DO NOT EDIT IT DIRECTLY UNLESS YOU ALSO EDIT THE CORRESPONDING FILE IN packages/template
+//===========================================
+
+import type { StackClientApp } from "../lib/hexclave-app";
+import { captureError } from "@hexclave/shared/dist/utils/errors";
+import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
+import { isLocalhost } from "@hexclave/shared/dist/utils/urls";
+import type { createDevTool as CreateDevToolFn } from "./dev-tool-core";
+
+// Hexclave rebrand: UI-only local pref — straight rename (one-time reset is harmless)
+const OVERRIDE_KEY = '__hexclave-dev-tool-override';
+
+function hasAppendChild(value: unknown): value is { appendChild(node: Node): void } {
+  return typeof value === 'object' && value !== null && typeof Reflect.get(value, 'appendChild') === 'function';
+}
+
+function canMountIntoDom(): boolean {
+  if (typeof window === 'undefined' || typeof document === 'undefined') {
+    return false;
+  }
+  if (typeof document.createElement !== 'function') {
+    return false;
+  }
+  return hasAppendChild(Reflect.get(document, 'body'));
+}
+
+function getOverride(): boolean | null {
+  try {
+    const val = localStorage.getItem(OVERRIDE_KEY);
+    if (val === 'true') return true;
+    if (val === 'false') return false;
+  } catch {}
+  return null;
+}
+
+function shouldShow(): boolean {
+  const override = getOverride();
+  if (override !== null) return override;
+  if (!canMountIntoDom()) return false;
+  return isLocalhost(window.location.href);
+}
+
+let activeCleanup: (() => void) | null = null;
+let activeApp: StackClientApp<true> | null = null;
+let mountGeneration = 0;
+
+let createDevToolPromise: Promise<typeof CreateDevToolFn> | null = null;
+function loadCreateDevTool(): Promise<typeof CreateDevToolFn> {
+  if (!createDevToolPromise) {
+    createDevToolPromise = import("./dev-tool-core").then(m => m.createDevTool).catch((err) => {
+      createDevToolPromise = null;
+      throw err;
+    });
+  }
+  return createDevToolPromise;
+}
+
+function tryMount() {
+  if (activeCleanup) {
+    activeCleanup();
+    activeCleanup = null;
+  }
+
+  if (!shouldShow() || !activeApp || !canMountIntoDom()) return;
+
+  const generation = ++mountGeneration;
+  const app = activeApp;
+
+  runAsynchronously(async () => {
+    const createDevTool = await loadCreateDevTool();
+    if (generation !== mountGeneration) return;
+    if (!shouldShow() || activeApp !== app || !canMountIntoDom()) return;
+    activeCleanup = createDevTool(app);
+  }, {
+    noErrorLogging: true,
+    onError: (error) => {
+      captureError("dev-tool-mount", error);
+    },
+  });
+}
+
+/**
+ * Mounts the Hexclave dev tool on the page.
+ *
+ * - Only renders on localhost (or when overridden via console)
+ * - Lazily loads the dev tool UI via dynamic import
+ * - Returns a cleanup function to unmount
+ *
+ * Console commands (also work in production):
+ *   HexclaveDevTool.enable()  — force-show the dev tool
+ *   HexclaveDevTool.disable() — force-hide the dev tool
+ *   HexclaveDevTool.reset()   — revert to default (localhost-only)
+ */
+export function mountDevTool(app: StackClientApp<true>): () => void {
+  activeApp = app;
+  tryMount();
+
+  // Capture the cleanup created by THIS specific mount call so that React
+  // StrictMode's double-invoke doesn't let the first effect's cleanup tear
+  // down the second mount (which would cause the tool to disappear silently).
+  const myCleanup = activeCleanup;
+
+  return () => {
+    activeApp = null;
+    if (activeCleanup === myCleanup && myCleanup != null) {
+      activeCleanup = null;
+      myCleanup();
+    }
+  };
+}
+
+// Expose console commands: HexclaveDevTool.enable() / .disable() / .reset()
+if (typeof window !== 'undefined') {
+  // Hexclave rebrand: expose under both the legacy and new global names.
+  (window as any).HexclaveDevTool = (window as any).HexclaveDevTool = {
+    enable() {
+      try {
+        localStorage.setItem(OVERRIDE_KEY, 'true');
+      } catch {}
+      tryMount();
+      console.log('[Stack DevTool] Enabled. Refresh if the panel does not appear.');
+    },
+    disable() {
+      try {
+        localStorage.setItem(OVERRIDE_KEY, 'false');
+      } catch {}
+      if (activeCleanup) {
+        activeCleanup();
+        activeCleanup = null;
+      }
+      console.log('[Stack DevTool] Disabled.');
+    },
+    reset() {
+      try {
+        localStorage.removeItem(OVERRIDE_KEY);
+      } catch {}
+      if (shouldShow()) {
+        tryMount();
+      } else if (activeCleanup) {
+        activeCleanup();
+        activeCleanup = null;
+      }
+      console.log('[Stack DevTool] Reset to default (visible on localhost only).');
+    },
+  };
+}
+

package/src/generated/.gitignore

@@ -0,0 +1,3 @@
+/*
+!.gitignore
+!/quetzal-translations.ts