@celestia-island/hikari 0.55.341 → 0.55.342

package/package.json

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

package/src/components/HkAddTile.contract.test.ts

@@ -0,0 +1,74 @@
+/**
+ * Source contract: HkAddTile's base class stays NEUTRAL — faint dashed
+ * border, muted ink, no surface, no primary tint. Color belongs to the
+ * drag-over state only (`--drag-over`), which carries the dashed
+ * primary + primary-wash language the product's hand-drawn drag
+ * overlays already use. Pinned because the tile invites every host to
+ * "just tint it a little" — a class-name test cannot catch the base
+ * picking up color, the source contract lives here.
+ */
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/** Extract one top-level rule block's body (`{ ... }`) by selector,
+ *  counting braces so nested `&:hover` blocks stay inside the slice. */
+function fullRule(css: string, selector: string): string {
+  const start = css.indexOf(`${selector} {`);
+  expect(start, `rule ${selector} present`).toBeGreaterThanOrEqual(0);
+  const open = css.indexOf("{", start);
+  let depth = 0;
+  for (let i = open; i < css.length; i++) {
+    if (css[i] === "{") depth++;
+    if (css[i] === "}") {
+      depth--;
+      if (depth === 0) return css.slice(open + 1, i);
+    }
+  }
+  throw new Error(`unbalanced braces in ${selector}`);
+}
+
+/** The rule's DIRECT declarations only — up to the first nested block
+ *  (`&:hover` and friends). Nested states may tint by design; the
+ *  neutrality discipline is about what the resting state paints. */
+function directDecls(css: string, selector: string): string {
+  const body = fullRule(css, selector);
+  const nested = body.indexOf("&:");
+  return nested === -1 ? body : body.slice(0, nested);
+}
+
+describe("HkAddTile neutrality contract", () => {
+  const css = readFileSync(join(here, "HkAddTile.scss"), "utf-8");
+
+  it("resting state: dashed neutral border, no surface, no wash", () => {
+    const base = directDecls(css, ".hk-add-tile");
+    expect(base).toContain("border: 1px dashed");
+    expect(base).toContain("background: transparent");
+    expect(base).not.toContain("rgb(var(--color-primary)");
+  });
+
+  it("compact stays a plain row form: no tint in direct declarations", () => {
+    const compact = directDecls(css, ".hk-add-tile--compact");
+    expect(compact).toContain("flex-direction: row");
+    expect(compact).not.toContain("rgb(var(--color-primary)");
+  });
+
+  it("the drag-over wash lives exclusively in --drag-over", () => {
+    const drag = fullRule(css, ".hk-add-tile--drag-over");
+    expect(drag).toContain("rgb(var(--color-primary) / 8%)");
+    // Whole-file sweep: exactly one top-level rule chunk paints the
+    // wash, and it is the drag-over rule.
+    const chunks = css.split(/(?=\.hk-add-tile)/g).filter((r) => r.includes("/ 8%)"));
+    expect(chunks.length).toBe(1);
+    expect(chunks[0].startsWith(".hk-add-tile--drag-over")).toBe(true);
+  });
+
+  it("disabled resets to neutral (no primary anywhere in the rule)", () => {
+    const disabled = fullRule(css, ".hk-add-tile--disabled");
+    expect(disabled).toContain("cursor: default");
+    expect(disabled).not.toContain("primary");
+  });
+});

package/src/components/HkAddTile.scss

@@ -0,0 +1,71 @@
+@use "../styles/polyfill" as *;
+
+/* HkAddTile — the dashed add / empty affordance tile. The tile is
+ * neutral AT REST: faint dashed border, muted ink, no surface and no
+ * wash. Primary ink comes in through the states that invite (the
+ * hover border/ink tint below, and the drag-over wash) — the primary
+ * SURFACE wash lives exclusively in the --drag-over rule (pinned by
+ * HkAddTile.contract.test.ts, do not creep a wash into any other
+ * rule). */
+.hk-add-tile {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  gap: var(--space-8, 0.5rem);
+  width: 100%;
+  box-sizing: border-box;
+  padding: var(--space-16, 1rem) var(--space-12, 0.75rem);
+  border: 1px dashed var(--border-faint);
+  border-radius: var(--radius-md, 8px);
+  background: transparent;
+  color: rgb(var(--color-muted));
+  font: inherit;
+  font-size: var(--text-xs, 0.75rem);
+  text-align: center;
+  cursor: pointer;
+  @include user-select(none);
+  transition:
+    border-color var(--duration-fast, 0.15s) ease,
+    background-color var(--duration-fast, 0.15s) ease,
+    color var(--duration-fast, 0.15s) ease;
+
+  &:hover {
+    border-color: rgb(var(--color-primary) / 45%);
+    color: rgb(var(--color-primary));
+  }
+
+  &:focus-visible {
+    outline: 2px solid rgb(var(--color-primary));
+    outline-offset: 2px;
+  }
+}
+
+/* List-end form: a slim left-aligned row ("＋ add one more") that rides
+ * the end of a row list instead of floating under it as a button. */
+.hk-add-tile--compact {
+  flex-direction: row;
+  justify-content: flex-start;
+  gap: var(--space-8, 0.5rem);
+  padding: var(--space-8, 0.5rem) var(--space-10, 0.625rem);
+  text-align: start;
+}
+
+/* Drag-over wash — dashed primary over a faint primary floor, matching
+ * the drag overlays the product already draws by hand. */
+.hk-add-tile--drag-over {
+  border-color: rgb(var(--color-primary) / 45%);
+  background: rgb(var(--color-primary) / 8%);
+  color: rgb(var(--color-primary));
+}
+
+.hk-add-tile--disabled {
+  cursor: default;
+  opacity: 0.55;
+
+  &:hover {
+    border-color: var(--border-faint);
+    color: rgb(var(--color-muted));
+    background: transparent;
+  }
+}

package/src/components/HkAddTile.test.tsx

@@ -0,0 +1,204 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick } from "vue";
+
+import HkAddTile from "./HkAddTile";
+
+const mounts: Array<{ app: ReturnType<typeof createApp>; container: HTMLElement }> = [];
+
+function mount(node: ReturnType<typeof h>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp({ render: () => node });
+  app.mount(container);
+  mounts.push({ app, container });
+  return container;
+}
+
+afterEach(() => {
+  for (const { app, container } of mounts.splice(0)) {
+    app.unmount();
+    container.remove();
+  }
+});
+
+/* Functional icon stub with a distinguishing class, same recipe as the
+   HkEmptyState tests, so the icon prop / slot override can be asserted
+   to have actually mounted. */
+const StubIcon = defineComponent({
+  name: "StubIcon",
+  setup() {
+    return () => h("i", { class: "stub-add-icon", "data-stub-icon": "true" });
+  },
+});
+
+/** A drop event carrying the given files — plain Event + a defined
+    dataTransfer, because happy-dom has no real DataTransfer. */
+function dropEvent(files: File[]): Event {
+  const ev = new Event("drop", { bubbles: true, cancelable: true });
+  Object.defineProperty(ev, "dataTransfer", { value: { files } });
+  return ev;
+}
+
+function file(name: string): File {
+  return new File(["x"], name, { type: "text/plain" });
+}
+
+function tileEl(c: HTMLElement): HTMLElement {
+  return c.querySelector(".hk-add-tile") as HTMLElement;
+}
+
+describe("HkAddTile", () => {
+  it("renders the label and the default Plus icon", () => {
+    const c = mount(h(HkAddTile, null, { default: () => "Add one" }));
+    const el = tileEl(c);
+    expect(el.tagName).toBe("BUTTON");
+    expect(el.textContent).toContain("Add one");
+    expect(el.querySelector("svg")).not.toBeNull();
+    expect(el.classList.contains("hk-add-tile--compact")).toBe(false);
+  });
+
+  it("compact form carries the compact modifier", () => {
+    const c = mount(h(HkAddTile, { compact: true }, { default: () => "Add" }));
+    expect(tileEl(c).classList.contains("hk-add-tile--compact")).toBe(true);
+  });
+
+  it("icon prop replaces the default glyph", () => {
+    const c = mount(h(HkAddTile, { icon: StubIcon }, { default: () => "Add" }));
+    expect(c.querySelector(".stub-add-icon")).not.toBeNull();
+  });
+
+  it("icon slot wins over both the default and the icon prop", () => {
+    const c = mount(
+      h(HkAddTile, { icon: StubIcon }, { icon: () => h("i", { class: "slot-icon" }), default: () => "Add" }),
+    );
+    expect(c.querySelector(".slot-icon")).not.toBeNull();
+    expect(c.querySelector(".stub-add-icon")).toBeNull();
+    // The default Plus must not ride along either.
+    expect(tileEl(c).querySelectorAll("svg").length).toBe(0);
+  });
+
+  it("emits click for an enabled tile", () => {
+    const onClick = vi.fn();
+    const c = mount(h(HkAddTile, { onClick }, { default: () => "Add" }));
+    tileEl(c).dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(onClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not emit click when disabled", () => {
+    const onClick = vi.fn();
+    const c = mount(h(HkAddTile, { disabled: true, onClick }, { default: () => "Add" }));
+    const el = tileEl(c);
+    expect(el.classList.contains("hk-add-tile--disabled")).toBe(true);
+    // The handler-level guard (a disabled button never receives the
+    // native click in a real browser, but dispatchEvent bypasses that).
+    el.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+    expect(onClick).not.toHaveBeenCalled();
+  });
+
+  it("emits drop-files with the dropped files", () => {
+    const onDropFiles = vi.fn();
+    const c = mount(h(HkAddTile, { droppable: true, onDropFiles }, { default: () => "Drop" }));
+    const ev = dropEvent([file("a.toml"), file("b.toml")]);
+    tileEl(c).dispatchEvent(ev);
+    expect(onDropFiles).toHaveBeenCalledTimes(1);
+    const files = onDropFiles.mock.calls[0][0] as File[];
+    expect(files.map((f) => f.name)).toEqual(["a.toml", "b.toml"]);
+  });
+
+  it("ignores drops without files (the gesture contract is files)", () => {
+    const onDropFiles = vi.fn();
+    const c = mount(h(HkAddTile, { droppable: true, onDropFiles }, { default: () => "Drop" }));
+    tileEl(c).dispatchEvent(dropEvent([]));
+    expect(onDropFiles).not.toHaveBeenCalled();
+  });
+
+  it("ignores drops when not droppable", () => {
+    const onDropFiles = vi.fn();
+    const c = mount(h(HkAddTile, { onDropFiles }, { default: () => "Nope" }));
+    tileEl(c).dispatchEvent(dropEvent([file("a.toml")]));
+    expect(onDropFiles).not.toHaveBeenCalled();
+  });
+
+  it("ignores drops and drag styling when disabled", () => {
+    const onDropFiles = vi.fn();
+    const c = mount(
+      h(HkAddTile, { disabled: true, droppable: true, onDropFiles }, { default: () => "Off" }),
+    );
+    const el = tileEl(c);
+    el.dispatchEvent(new Event("dragenter", { bubbles: true }));
+    expect(el.classList.contains("hk-add-tile--drag-over")).toBe(false);
+    el.dispatchEvent(dropEvent([file("a.toml")]));
+    expect(onDropFiles).not.toHaveBeenCalled();
+  });
+
+  it("flips the drag-over class across child boundaries without flicker", async () => {
+    const c = mount(h(HkAddTile, { droppable: true }, { default: () => "Drop" }));
+    const el = tileEl(c);
+    // The default slot text is a direct child; enter the tile, then its
+    // label span boundary, then back out of the span only.
+    el.dispatchEvent(new Event("dragenter", { bubbles: true }));
+    await nextTick();
+    expect(el.classList.contains("hk-add-tile--drag-over")).toBe(true);
+    const inner = el.querySelector("span") ?? el.firstElementChild ?? el;
+    inner.dispatchEvent(new Event("dragenter", { bubbles: true })); // depth 2
+    inner.dispatchEvent(new Event("dragleave", { bubbles: true })); // depth 1 — still over
+    await nextTick();
+    expect(el.classList.contains("hk-add-tile--drag-over")).toBe(true);
+    el.dispatchEvent(new Event("dragleave", { bubbles: true })); // depth 0
+    await nextTick();
+    expect(el.classList.contains("hk-add-tile--drag-over")).toBe(false);
+  });
+
+  it("cancels dragenter/dragover exactly when it accepts the drag", () => {
+    // The browser only DELIVERS a drop onto a target whose last dragover
+    // was not cancelled — these defaultPrevented pins ARE the drop-target
+    // contract; deleting either preventDefault keeps every emit-level
+    // test green while killing the feature in real browsers (R2-S2).
+    const c = mount(h(HkAddTile, { droppable: true }, { default: () => "Drop" }));
+    const el = tileEl(c);
+    const enter = new Event("dragenter", { cancelable: true });
+    el.dispatchEvent(enter);
+    expect(enter.defaultPrevented).toBe(true);
+    const over = new Event("dragover", { cancelable: true });
+    el.dispatchEvent(over);
+    expect(over.defaultPrevented).toBe(true);
+  });
+
+  it("never cancels drag events when not droppable or disabled (refusal = no preventDefault)", () => {
+    const c = mount(h(HkAddTile, {}, { default: () => "No" }));
+    const over = new Event("dragover", { cancelable: true });
+    tileEl(c).dispatchEvent(over);
+    expect(over.defaultPrevented).toBe(false);
+    const off = mount(
+      h(HkAddTile, { droppable: true, disabled: true }, { default: () => "Off" }),
+    );
+    const over2 = new Event("dragover", { cancelable: true });
+    tileEl(off).dispatchEvent(over2);
+    expect(over2.defaultPrevented).toBe(false);
+  });
+
+  it("hands the native drop event as the second drop-files argument", () => {
+    const onDropFiles = vi.fn();
+    const c = mount(h(HkAddTile, { droppable: true, onDropFiles }, { default: () => "Drop" }));
+    const ev = dropEvent([file("a.toml")]);
+    tileEl(c).dispatchEvent(ev);
+    expect(onDropFiles.mock.calls[0][1]).toBe(ev);
+  });
+
+  it("clears the drag-over state on drop", async () => {
+    const onDropFiles = vi.fn();
+    const c = mount(h(HkAddTile, { droppable: true, onDropFiles }, { default: () => "Drop" }));
+    const el = tileEl(c);
+    el.dispatchEvent(new Event("dragenter", { bubbles: true }));
+    await nextTick();
+    expect(el.classList.contains("hk-add-tile--drag-over")).toBe(true);
+    el.dispatchEvent(dropEvent([file("a.toml")]));
+    await nextTick();
+    expect(el.classList.contains("hk-add-tile--drag-over")).toBe(false);
+    // A second drop after the depth reset must still emit (no stale
+    // depth leaking into the next drag session).
+    el.dispatchEvent(new Event("dragenter", { bubbles: true }));
+    el.dispatchEvent(dropEvent([file("b.toml")]));
+    expect(onDropFiles).toHaveBeenCalledTimes(2);
+  });
+});

package/src/components/HkAddTile.tsx

@@ -0,0 +1,138 @@
+import { computed, defineComponent, h, ref, type Component, type PropType } from "vue";
+import { Plus } from "lucide-vue-next";
+
+import "./HkAddTile.scss";
+
+/**
+ * HkAddTile — the dashed add / empty affordance tile.
+ *
+ * One standard element for the "dashed placeholder that invites an
+ * action" pattern that product surfaces kept re-drawing by hand: the
+ * empty-list tile, the "add one more" row at the end of a staged list,
+ * and the pick-a-file / drop-files zone. Three blessed forms, one
+ * anatomy:
+ *
+ *   - **default** — a centered vertical block (icon above the label):
+ *     the empty state of a list or panel ("no sources yet — add one to
+ *     begin"). The whole tile is the click target; hosts no longer pair
+ *     a passive dashed box with a separate button below it.
+ *   - **compact** — a slim left-aligned row ("＋ Add node / repo"): the
+ *     tile that rides the END of a list of rows and grows the list. It
+ *     replaces the loose secondary button, so the add affordance reads
+ *     as part of the list instead of floating under it.
+ *   - **droppable** — either form additionally accepts file drags:
+ *     dragover/dragenter flip the tile into the drag-over wash (same
+ *     visual language as the established drag overlays — dashed primary
+ *     on a faint primary floor), and a drop with a non-empty `FileList`
+ *     is handed UP as `drop-files`. The host decides what files mean;
+ *     the tile only standardizes the gesture. Drops of anything but
+ *     files (text, URLs) are ignored — the drag-files-in gesture is the
+ *     contract, so a host can rely on `drop-files` always carrying ≥1
+ *     file.
+ *
+ * Accessibility: a real `<button type="button">` — keyboard focus and
+ * Enter/Space activation come free; `disabled` renders the native
+ * attribute (and a disabled tile refuses drags entirely: it never calls
+ * `preventDefault` on dragover, so the browser disallows the drop).
+ */
+export default defineComponent({
+  name: "HkAddTile",
+  props: {
+    /** Off switches the tile off entirely: no click, no drag acceptance. */
+    disabled: { type: Boolean, default: false },
+    /** Accept file drags; non-empty drops surface as `drop-files`. */
+    droppable: { type: Boolean, default: false },
+    /** List-end form: slim horizontal row instead of the centered block. */
+    compact: { type: Boolean, default: false },
+    /** Icon component (lucide-vue-next style); defaults to Plus. */
+    icon: { type: [Object, Function] as PropType<Component>, default: undefined },
+  },
+  emits: {
+    click: (_e: MouseEvent) => true,
+    /** A drop carrying at least one file: `(files, nativeEvent)`. */
+    "drop-files": (_files: File[], _e: DragEvent) => true,
+  },
+  setup(props, { slots, emit }) {
+    // dragenter/dragleave fire in pairs across EVERY child boundary, so
+    // a boolean flips off the moment the pointer crosses the label —
+    // track depth instead and clear it on drop.
+    const dragDepth = ref(0);
+    const dragOver = computed(
+      () => props.droppable && !props.disabled && dragDepth.value > 0,
+    );
+
+    /** Whether this tile accepts the drag at all. Refusing means NEVER
+     *  calling preventDefault: the browser only permits a drop onto a
+     *  target whose last dragover was not cancelled, so a disabled (or
+     *  non-droppable) tile cannot receive one by construction. */
+    function acceptsDrag(): boolean {
+      return props.droppable && !props.disabled;
+    }
+
+    function onDragenter(e: DragEvent) {
+      if (!acceptsDrag()) return;
+      e.preventDefault();
+      dragDepth.value += 1;
+    }
+
+    function onDragover(e: DragEvent) {
+      if (!acceptsDrag()) return;
+      // preventDefault on EVERY dragover (not just the first) — the
+      // drop allowance expires continuously; missing one cancels the
+      // drop for the whole hover.
+      e.preventDefault();
+    }
+
+    function onDragleave() {
+      if (dragDepth.value > 0) dragDepth.value -= 1;
+    }
+
+    function onDrop(e: DragEvent) {
+      dragDepth.value = 0;
+      if (!acceptsDrag()) return;
+      e.preventDefault();
+      const files = Array.from(e.dataTransfer?.files ?? []);
+      if (files.length === 0) return;
+      emit("drop-files", files, e);
+    }
+
+    function onClick(e: MouseEvent) {
+      if (props.disabled) return;
+      emit("click", e);
+    }
+
+    return () => {
+      // Icon resolution reads `slots` INSIDE the render function — the
+      // slots object is not reactive, so a computed here would cache the
+      // choice across slot add/remove (R2-S1: a parent that adds an icon
+      // slot later rendered the stale default Plus ALONGSIDE the slot;
+      // removing the slot left the tile iconless until an unrelated prop
+      // churned the cache). House style: HkEmptyState reads slots.icon
+      // per render for the same reason. h() rather than JSX: the icon
+      // prop is a Component (object | function) union, which TS cannot
+      // expand as a JSX element type.
+      const Icon = slots.icon ? null : (props.icon ?? Plus);
+      return (
+        <button
+          type="button"
+          class={[
+            "hk-add-tile",
+            props.compact && "hk-add-tile--compact",
+            props.disabled && "hk-add-tile--disabled",
+            dragOver.value && "hk-add-tile--drag-over",
+          ]}
+          disabled={props.disabled}
+          onClick={onClick}
+          onDragenter={onDragenter}
+          onDragover={onDragover}
+          onDragleave={onDragleave}
+          onDrop={onDrop}
+        >
+          {Icon ? h(Icon, { size: props.compact ? 14 : 18, "aria-hidden": true }) : null}
+          {slots.icon?.()}
+          {slots.default?.()}
+        </button>
+      );
+    };
+  },
+});

package/src/index.ts

@@ -26,6 +26,7 @@ export {
   type HkDockBarAnchor as HDockBarAnchor,
   type HkDockBarSurface as HDockBarSurface,
 } from "./components/HkDockBar";
+export { default as HAddTile } from "./components/HkAddTile";
 export { default as HDrawer } from "./components/HkDrawer";
 export { default as HEdgeGlow } from "./components/HkEdgeGlow";
 export { default as HEmptyState } from "./components/HkEmptyState";
@@ -814,6 +815,7 @@ export { default as HkNavItem } from "./components/HkNavItem";
 export { default as HkNumberInput } from "./components/HkNumberInput";
 export { default as HkPhoneInput } from "./components/HkPhoneInput";
 export { default as HkAffixPicker } from "./components/HkAffixPicker";
+export { default as HkAddTile } from "./components/HkAddTile";
 export { default as HkUserPicker, type HkUserOption } from "./components/HkUserPicker";
 export { default as HkPhaseTransition } from "./components/HkPhaseTransition";
 export { default as HkGaugeRing } from "./components/HkGaugeRing";