@celestia-island/hikari 0.55.197 → 0.55.198

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.197",
+  "version": "0.55.198",
   "private": false,
   "type": "module",
   "description": "Hikari UI library, Vue 3 runtime — one design system for Vue 3 and Rust/WASM applications",

package/src/components/HkWindowControls.scss

@@ -0,0 +1,75 @@
+// HkWindowControls — the two deliberate modes (2026-10-23 user ruling).
+//
+// standard: borderless ghost buttons at the header chrome's own size
+// step (2rem boxes, 16px glyphs, 0.375rem gaps) — no borders, no
+// dividers, no container chrome; the close hover is a small rounded
+// red wash. Reads as one family with gear/search icon buttons.
+//
+// flush: edge-riding squares for thin captions — the host zeroes its
+// own right padding (the s-header-bar--chrome contract pattern); the
+// buttons stretch the host height, radius 0, wash-on-hover only.
+
+.hk-window-controls {
+  display: flex;
+  align-items: center;
+  gap: 0.375rem;
+  align-self: center;
+}
+
+.hk-window-controls__btn {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 2rem;
+  height: 2rem;
+  padding: 0;
+  border: none;
+  border-radius: 0.375rem;
+  background: transparent;
+  /* Inherit the host's foreground — a fixed gray literal is invisible
+   * on light floors and wrong in dark mode. */
+  color: inherit;
+  cursor: pointer;
+  transition: background 0.12s ease, color 0.12s ease;
+
+  &:hover {
+    background: rgb(var(--color-muted, 108 108 108) / 16%);
+  }
+
+  &--close {
+    &:hover {
+      background: rgb(232 17 35);
+      color: #fff;
+    }
+  }
+}
+
+// ── flush (thin captions) ───────────────────────────────────────────
+.hk-window-controls--flush {
+  gap: 0;
+  align-self: stretch;
+  margin-left: 0.25rem;
+
+  .hk-window-controls__btn {
+    width: 2.75rem;
+    height: auto;
+    min-height: 2.25rem;
+    border-radius: 0;
+
+    & + & {
+      /* No dividers in flush mode either — wash-on-hover only. */
+      border-left: none;
+    }
+  }
+}
+
+// Phones: the cluster shrinks so the full action row fits.
+@media (max-width: 767px) {
+  .hk-window-controls {
+    gap: 0.25rem;
+  }
+  .hk-window-controls__btn {
+    width: 1.75rem;
+    height: 1.75rem;
+  }
+}

package/src/components/HkWindowControls.test.tsx

@@ -0,0 +1,93 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, type App } from "vue";
+
+import HkWindowControls, { isApplePlatform } from "./HkWindowControls";
+
+const containers: HTMLElement[] = [];
+
+function mountControls(props: Record<string, unknown> = {}): {
+  app: App;
+  container: HTMLElement;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const Wrapper = defineComponent({
+    render: () => h(HkWindowControls as never, props),
+  });
+  const app = createApp(Wrapper);
+  app.mount(container);
+  return { app, container };
+}
+
+afterEach(() => {
+  for (const c of containers.splice(0)) c.remove();
+  vi.unstubAllGlobals();
+});
+
+/** A fake __TAURI__ window API so the render gates pass off-desktop. */
+function stubTauriWindow(): void {
+  vi.stubGlobal("__TAURI__", {
+    window: {
+      getCurrentWindow: () => ({
+        minimize: () => Promise.resolve(),
+        toggleMaximize: () => Promise.resolve(),
+        close: () => Promise.resolve(),
+        isMaximized: () => Promise.resolve(false),
+        onResized: () => Promise.resolve(() => {}),
+      }),
+    },
+  });
+}
+
+describe("HkWindowControls (two deliberate modes, explicit None)", () => {
+  it("renders the three buttons in standard mode", () => {
+    stubTauriWindow();
+    const t = mountControls({ variant: "standard" });
+    const btns = t.container.querySelectorAll<HTMLButtonElement>(
+      ".hk-window-controls__btn",
+    );
+    expect(btns).toHaveLength(3);
+    expect(t.container.querySelector(".hk-window-controls--flush")).toBeNull();
+    t.app.unmount();
+  });
+
+  it("renders the flush modifier in flush mode", () => {
+    stubTauriWindow();
+    const t = mountControls({ variant: "flush" });
+    expect(t.container.querySelector(".hk-window-controls--flush")).not.toBeNull();
+    expect(
+      t.container.querySelectorAll(".hk-window-controls__btn"),
+    ).toHaveLength(3);
+    t.app.unmount();
+  });
+
+  it("renders NOTHING without a variant (the explicit-None contract)", () => {
+    stubTauriWindow();
+    const t = mountControls({});
+    expect(t.container.querySelector(".hk-window-controls")).toBeNull();
+    t.app.unmount();
+  });
+
+  it("renders nothing for an invalid variant (validator escape)", () => {
+    stubTauriWindow();
+    const t = mountControls({ variant: "rounded" });
+    expect(t.container.querySelector(".hk-window-controls")).toBeNull();
+    t.app.unmount();
+  });
+
+  it("renders nothing on Apple platforms (the OS owns the traffic lights)", () => {
+    stubTauriWindow();
+    vi.stubGlobal("navigator", { userAgent: "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7)" });
+    expect(isApplePlatform()).toBe(true);
+    const t = mountControls({ variant: "standard" });
+    expect(t.container.querySelector(".hk-window-controls")).toBeNull();
+    t.app.unmount();
+  });
+
+  it("renders nothing without a Tauri window API (browser preview)", () => {
+    const t = mountControls({ variant: "standard" });
+    expect(t.container.querySelector(".hk-window-controls")).toBeNull();
+    t.app.unmount();
+  });
+});

package/src/components/HkWindowControls.tsx

@@ -0,0 +1,144 @@
+import { defineComponent, onMounted, onUnmounted, ref, type PropType } from "vue";
+
+import { Minus, Square, X, Copy } from "lucide-vue-next";
+
+import "./HkWindowControls.scss";
+
+/**
+ * HkWindowControls — the minimize / maximize / close cluster for hosts
+ * that own their window chrome (Tauri custom titlebars, Electron
+ * frameless). Three modes, and the choice is DELIBERATELY explicit
+ * (user direction 2026-10-23):
+ *
+ * - `standard` — three borderless ghost icon buttons at the same size
+ *   step as the header's other chrome (ghost/32, 16px glyphs), spaced
+ *   with comfortable gaps. The whole top-right reads as one family of
+ *   identical buttons; the close hover is a small rounded red wash.
+ *   THE mode for content-height headers (3rem-class bars).
+ *
+ * - `flush` — edge-riding squares that fill the host's height (the
+ *   host must zero its own right padding so the close button rides
+ *   the window edge; wash-on-hover only, radius 0). THE mode for real
+ *   thin captions (32px-class native-titlebar strips).
+ *
+ * - **omitted → nothing renders.** There is NO default variant: a
+ *   forgetful host shows no control buttons (the app stays closable
+ *   via the taskbar/OS), which fails loudly at design review instead
+ *   of silently shipping the wrong chrome.
+ *
+ * macOS: the traffic lights belong to the OS titlebar — this component
+ * renders nothing on Apple platforms and the header degrades to its
+ * browser-face look automatically.
+ *
+ * The window API rides `__TAURI__.window.getCurrentWindow()` when
+ * present; on a non-Tauri host (browser preview) the buttons render
+ * but the calls no-op, keeping visual parity for storybook/tests.
+ */
+
+interface TauriWindowLike {
+  minimize(): Promise<void>;
+  toggleMaximize(): Promise<void>;
+  close(): Promise<void>;
+  isMaximized(): Promise<boolean>;
+  onResized(cb: () => void): Promise<() => void>;
+}
+
+function currentWindow(): TauriWindowLike | null {
+  const w = (
+    window as unknown as {
+      __TAURI__?: { window?: { getCurrentWindow?: () => TauriWindowLike } };
+    }
+  ).__TAURI__?.window;
+  return w?.getCurrentWindow?.() ?? null;
+}
+
+/** Apple platforms own their traffic lights — we never render there. */
+export function isApplePlatform(): boolean {
+  return /Mac|iPhone|iPad|iPod/.test(
+    (typeof navigator !== "undefined" && navigator.userAgent) || "",
+  );
+}
+
+export type WindowControlsVariant = "standard" | "flush";
+
+export const HkWindowControls = defineComponent({
+  name: "HkWindowControls",
+  props: {
+    /** REQUIRED — no default. One of the two deliberate modes; omit it
+     *  and the component renders nothing (the explicit-None contract). */
+    variant: {
+      type: String as PropType<WindowControlsVariant>,
+      required: true,
+      validator: (v: unknown) => v === "standard" || v === "flush",
+    },
+  },
+  setup(props) {
+    const maximized = ref(false);
+    let unlisten: (() => void) | null = null;
+
+    onMounted(async () => {
+      const win = currentWindow();
+      if (!win) return;
+      try {
+        const refresh = () => void win.isMaximized().then((m) => (maximized.value = m));
+        refresh();
+        const off = await win.onResized(refresh);
+        unlisten = off;
+      } catch {
+        /* the window API is optional furniture */
+      }
+    });
+
+    onUnmounted(() => {
+      unlisten?.();
+    });
+
+    return () => {
+      // Two render gates before any chrome: Apple owns its traffic
+      // lights, and a host that forgot the variant gets NOTHING (the
+      // explicit-None contract — belt for runtime JS where TS cannot
+      // enforce the required prop).
+      if (isApplePlatform()) return null;
+      if (props.variant !== "standard" && props.variant !== "flush") return null;
+      const win = currentWindow();
+      if (!win) return null;
+
+      const flush = props.variant === "flush";
+      return (
+        <div
+          class={{ "hk-window-controls": true, "hk-window-controls--flush": flush }}
+          data-tauri-drag-region={false}
+        >
+          <button
+            type="button"
+            class="hk-window-controls__btn"
+            aria-label="Minimize"
+            onClick={() => void win.minimize()}
+          >
+            <Minus size={flush ? 14 : 16} />
+          </button>
+          <button
+            type="button"
+            class="hk-window-controls__btn"
+            aria-label={maximized.value ? "Restore" : "Maximize"}
+            onClick={() => void win.toggleMaximize()}
+          >
+            {maximized.value
+              ? <Copy size={flush ? 12 : 14} style={{ transform: "rotate(180deg)" }} />
+              : <Square size={flush ? 12 : 14} />}
+          </button>
+          <button
+            type="button"
+            class="hk-window-controls__btn hk-window-controls__btn--close"
+            aria-label="Close"
+            onClick={() => void win.close()}
+          >
+            <X size={flush ? 14 : 16} />
+          </button>
+        </div>
+      );
+    };
+  },
+});
+
+export default HkWindowControls;

package/src/index.ts

@@ -614,6 +614,8 @@ export { default as HkCopyBadge } from "./components/HkCopyBadge";
 export { default as HkConfirmDialog } from "./components/HkConfirmDialog";
 export { default as HkCrossfade } from "./components/HkCrossfade";
 export { default as HkTransitionContainer } from "./components/HkTransitionContainer";
+export { default as HkWindowControls, isApplePlatform } from "./components/HkWindowControls";
+export type { WindowControlsVariant } from "./components/HkWindowControls";
 export { default as HkDivider } from "./components/HkDivider";
 export { default as HkDiffViewer } from "./components/HkDiffViewer";
 export { parseUnifiedDiff, computeGaps } from "./components/diffParse";