@celestia-island/hikari 0.55.52 → 0.55.53

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celestia-island/hikari",
-  "version": "0.55.52",
+  "version": "0.55.53",
   "private": false,
   "type": "module",
   "description": "Hikari Vue 3 component library — production-grade UI components based on shittim-chest design system",

package/src/components/HkSettingsDialog.scss

@@ -0,0 +1,169 @@
+// HkSettingsDialog — the sectioned settings shell (rail + pane) and its
+// content vocabulary (group / sub / hint). Grammar extracted from the
+// wowsp settings window (the pattern this component upstreams): values
+// are the L2 scale tokens wowsp already used, so existing surfaces
+// migrate without repainting.
+//
+// Scroll ownership: inside the dialog (host class `hk-settings-host`)
+// the shell gets a STABLE height sized under the modal body scroller's
+// inner padding, so HkModal's floating overlay scrollbar stays idle and
+// the pane's own edge bar is the only scrollbar. The negative-margin
+// trick puts that edge — and its scrollbar — flush with the modal
+// window's right edge; the padding re-applies the content inset between
+// the scrollbar and the cards. A page-embedded body (no host class)
+// skips both: plain scroll container, host-managed layout.
+
+.hk-settings {
+  display: flex;
+  align-items: stretch;
+  gap: var(--space-20);
+
+  /* ── section rail (mirrors the main sidebar nav look) ── */
+  &__rail {
+    flex: none;
+    width: 10.5rem;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-2);
+    padding: var(--space-4) var(--space-12) var(--space-4) 0;
+    border-right: 1px solid rgb(var(--color-border) / 15%);
+    overflow-y: auto;
+  }
+
+  &__rail-item {
+    display: flex;
+    align-items: center;
+    gap: var(--space-10);
+    padding: var(--space-8) var(--space-12);
+    border: 0;
+    border-radius: var(--radius-sm);
+    background: transparent;
+    text-align: left;
+    color: rgb(var(--color-muted));
+    font-size: var(--text-sm);
+    font-family: inherit;
+    cursor: pointer;
+    transition:
+      color var(--duration-short) var(--ease-standard),
+      background var(--duration-short) var(--ease-standard);
+
+    &:hover:not(:disabled) {
+      color: rgb(var(--color-text));
+      background: rgb(var(--color-primary) / 8%);
+    }
+
+    &:focus-visible {
+      outline: 2px solid rgb(var(--color-primary));
+      outline-offset: 1px;
+    }
+
+    &:disabled {
+      opacity: 0.45;
+      cursor: not-allowed;
+    }
+
+    &.is-active {
+      color: rgb(var(--color-primary));
+      background: rgb(var(--color-primary) / 12%);
+      font-weight: 500;
+    }
+  }
+
+  &__rail-icon {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    width: var(--space-20);
+    height: var(--space-20);
+  }
+
+  &__rail-label {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+
+  /* ── content pane: one section at a time, this is the scroller ── */
+  &__pane {
+    flex: 1;
+    min-width: 0;
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-16);
+    overflow-y: auto;
+  }
+}
+
+/* ── Dialog host: stable frame + flush scrollbar edge ────────────────── */
+
+/* Give the body inner a definite height so the shell's fit is computed
+   against the real scroll area (wowsp's host rule, verbatim). */
+.hk-settings-host .hk-modal-body-inner {
+  height: 100%;
+}
+
+.hk-settings-host .hk-settings {
+  height: var(--hk-settings-height, calc(70vh - 6.5rem));
+}
+
+/* Cancel the modal body's fixed right padding so the pane's scrollbar
+   sits flush at the window edge; re-apply the inset between the bar and
+   the cards. HkModal retunes the body padding to 1rem under 768px —
+   follow it or the pane overshoots the edge. */
+.hk-settings-host .hk-settings__pane {
+  margin-right: calc(-1 * var(--hk-modal-padding-body, 1.5rem));
+  padding-right: var(--space-28);
+
+  @media (max-width: 767px) {
+    margin-right: -1rem;
+    padding-right: var(--space-20);
+  }
+}
+
+/* ── Content vocabulary ───────────────────────────────────────────────── */
+
+/* One titled card per settings area. Slightly translucent so the cards
+   sit quietly on image wallpapers. */
+.hk-settings-group {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-12);
+  padding: var(--space-16) var(--space-20);
+  background: rgb(var(--color-surface) / 55%);
+  border: 1px solid rgb(var(--color-border) / 15%);
+  border-radius: var(--radius-md);
+}
+
+.hk-settings-group-title {
+  margin: 0;
+  font-size: var(--text-sm);
+  font-weight: 600;
+  color: rgb(var(--color-text));
+}
+
+/* Titled sub-block inside a group. */
+.hk-settings-sub {
+  display: flex;
+  flex-direction: column;
+  gap: var(--space-8);
+  margin-top: var(--space-4);
+}
+
+.hk-settings-sub-title {
+  margin: 0;
+  font-size: var(--text-xs);
+  font-weight: 600;
+  color: rgb(var(--color-muted));
+  text-transform: uppercase;
+  letter-spacing: 0.04em;
+}
+
+/* The small muted explanation line under a control. */
+.hk-settings-hint {
+  margin: 0;
+  font-size: var(--text-xs);
+  line-height: 1.5;
+  color: rgb(var(--color-muted));
+}

package/src/components/HkSettingsDialog.test.tsx

@@ -0,0 +1,249 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+import { Languages, Globe } from "lucide-vue-next";
+import {
+  HkSettingsBody as HSettingsBody,
+  HkSettingsDialog as HSettingsDialog,
+  HkSettingsGroup as HSettingsGroup,
+  HkSettingsHint as HSettingsHint,
+  HkSettingsSub as HSettingsSub,
+} from "./HkSettingsDialog";
+
+function mount(component: ReturnType<typeof defineComponent>) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const app = createApp(component);
+  app.mount(container);
+  return { container, unmount: () => { app.unmount(); container.remove(); } };
+}
+
+const SECTIONS = [
+  { key: "language", label: "Language", icon: Languages },
+  { key: "network", label: "Network", icon: Globe },
+  { key: "locked", label: "Locked", disabled: true },
+];
+
+const Host = defineComponent({
+  setup() {
+    const section = ref("language");
+    return () => (
+      <HSettingsBody sections={SECTIONS} v-model:section={section.value}
+        onUpdate:section={(v: string) => (section.value = v)}>
+        {{
+          language: () => <div data-test="pane-language">lang pane</div>,
+          network: () => <div data-test="pane-network">net pane</div>,
+          locked: () => <div data-test="pane-locked">locked pane</div>,
+        }}
+      </HSettingsBody>
+    );
+  },
+});
+
+describe("HSettingsBody", () => {
+  it("renders every rail entry and the first section's pane", () => {
+    const { container, unmount } = mount(Host);
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    expect(items).toHaveLength(3);
+    expect(items[0].textContent).toContain("Language");
+    expect(items[0].querySelector(".hk-settings__rail-icon svg")).toBeTruthy();
+    // First section active by default (internal state, unbound prop).
+    expect(items[0].classList.contains("is-active")).toBe(true);
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    expect(container.querySelector('[data-test="pane-network"]')).toBeNull();
+    unmount();
+  });
+
+  it("switches the pane on rail click and reports aria-current", async () => {
+    const { container, unmount } = mount(Host);
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    items[1].click();
+    await nextTick();
+    expect(container.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    expect(items[1].getAttribute("aria-current")).toBe("true");
+    expect(items[0].getAttribute("aria-current")).toBeNull();
+    unmount();
+  });
+
+  it("never activates a disabled entry", async () => {
+    const { container, unmount } = mount(Host);
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    expect(items[2].disabled).toBe(true);
+    items[2].click();
+    await nextTick();
+    // Still on the first section.
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    expect(items[2].classList.contains("is-active")).toBe(false);
+    unmount();
+  });
+
+  it("restarts the pane scroll on section switch", async () => {
+    const scrolled = ref(false);
+    const Probe = defineComponent({
+      setup() {
+        const section = ref("language");
+        return () => (
+          <HSettingsBody
+            sections={SECTIONS.slice(0, 2)}
+            section={section.value}
+            onUpdate:section={(v: string) => (section.value = v)}
+          >
+            {{
+              language: () => <div style="height: 2000px">lang</div>,
+              network: () => <div style="height: 2000px">net</div>,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Probe);
+    const pane = container.querySelector<HTMLElement>(".hk-settings__pane")!;
+    pane.scrollTop = 500;
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    items[1].click();
+    await nextTick();
+    await nextTick();
+    scrolled.value = pane.scrollTop === 0;
+    expect(scrolled.value).toBe(true);
+    unmount();
+  });
+
+  it("honors an externally driven section change (deep-link landing)", async () => {
+    const section = ref("language");
+    const Deep = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody sections={SECTIONS.slice(0, 2)} section={section.value}>
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Deep);
+    section.value = "network";
+    await nextTick();
+    expect(container.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    unmount();
+  });
+});
+
+describe("HSettingsDialog", () => {
+  it("hosts the shell inside an open HModal and lands on the bound section", async () => {
+    const section = ref("network");
+    const Dialog = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsDialog
+            modelValue
+            title="Settings"
+            sections={SECTIONS.slice(0, 2)}
+            section={section.value}
+            onUpdate:section={(v: string) => (section.value = v)}
+          >
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+            }}
+          </HSettingsDialog>
+        );
+      },
+    });
+    const { unmount } = mount(Dialog);
+    await nextTick();
+    await new Promise((r) => setTimeout(r, 0));
+    // HkModal teleports to document.body — the shell lives there, not in
+    // the mount container.
+    const host = document.body.querySelector(".hk-settings-host");
+    expect(host).toBeTruthy();
+    expect(host!.querySelector(".hk-settings__rail")).toBeTruthy();
+    // The bound section won over the default-first.
+    expect(host!.querySelector('[data-test="pane-network"]')).toBeTruthy();
+    unmount();
+  });
+});
+
+describe("settings content vocabulary", () => {
+  it("renders group / sub / hint with their titles", () => {
+    const { container, unmount } = mount(
+      defineComponent({
+        setup() {
+          return () => (
+            <HSettingsGroup title="Network">
+              <HSettingsSub title="Proxy">
+                <HSettingsHint>Applies to every request.</HSettingsHint>
+              </HSettingsSub>
+            </HSettingsGroup>
+          );
+        },
+      }),
+    );
+    expect(container.querySelector(".hk-settings-group-title")!.textContent).toBe("Network");
+    expect(container.querySelector(".hk-settings-sub-title")!.textContent).toBe("Proxy");
+    expect(container.querySelector(".hk-settings-hint")!.textContent)
+      .toContain("Applies to every request");
+    unmount();
+  });
+
+  it("renders a group without a title (untitled card)", () => {
+    const { container, unmount } = mount(
+      defineComponent({
+        setup() {
+          return () => h(HSettingsGroup, null, { default: () => "body" });
+        },
+      }),
+    );
+    expect(container.querySelector(".hk-settings-group-title")).toBeNull();
+    unmount();
+  });
+});
+
+describe("settings dialog SCSS host contract (source-level)", () => {
+  // The stable-frame contract is three rules in the SCSS that happy-dom's
+  // cascade-free environment cannot exercise behaviorally — pin them at
+  // the source so a silent deletion turns this red (the R1 mutation-d
+  // gap). Known-positive control: the base rail rule every variant
+  // depends on.
+  // vitest serves modules through its own scheme, so import.meta.url is
+  // not a file URL here; the suite's cwd is packages/vue.
+  const scss = readFileSync("src/components/HkSettingsDialog.scss", "utf8");
+
+  it("self-check: the extractor sees a rule that exists", () => {
+    // The shell rules are BEM-nested in the source (&__rail-item inside
+    // .hk-settings) — the positive control matches the nested form.
+    expect(scss).toContain("&__rail-item {");
+  });
+
+  it("pins the stable-frame host rules (idle modal scrollbar, flush edge)", () => {
+    expect(scss).toContain(".hk-settings-host .hk-modal-body-inner {");
+    expect(scss).toContain("height: var(--hk-settings-height, calc(70vh - 6.5rem));");
+    expect(scss).toContain("margin-right: calc(-1 * var(--hk-modal-padding-body, 1.5rem));");
+  });
+
+  it("never activates a disabled section through a deep-linked prop", async () => {
+    const Deep = defineComponent({
+      setup() {
+        return () => (
+          <HSettingsBody sections={SECTIONS} section="locked">
+            {{
+              language: () => <div data-test="pane-language" />,
+              network: () => <div data-test="pane-network" />,
+              locked: () => <div data-test="pane-locked" />,
+            }}
+          </HSettingsBody>
+        );
+      },
+    });
+    const { container, unmount } = mount(Deep);
+    await nextTick();
+    // The disabled key did not win: first usable section shows, the
+    // locked pane never renders, its rail entry stays grey.
+    expect(container.querySelector('[data-test="pane-language"]')).toBeTruthy();
+    expect(container.querySelector('[data-test="pane-locked"]')).toBeNull();
+    const items = container.querySelectorAll<HTMLButtonElement>(".hk-settings__rail-item");
+    expect(items[2].classList.contains("is-active")).toBe(false);
+    unmount();
+  });
+});

package/src/components/HkSettingsDialog.tsx

@@ -0,0 +1,237 @@
+import {
+  defineComponent,
+  h,
+  nextTick,
+  ref,
+  watch,
+  type Component,
+  type PropType,
+} from "vue";
+
+import HModal from "./HkModal";
+import "./HkSettingsDialog.scss";
+
+/** One rail entry of the settings dialog. */
+export interface HkSettingsSection {
+  /** Identity of the section — also the name of the slot that renders its
+   *  content pane (`{ [key]: () => … }`). */
+  key: string;
+  /** Rail label. */
+  label: string;
+  /** Leading rail icon (a lucide-style component; rendered at 16px). */
+  icon?: Component;
+  /** A disabled entry renders but cannot be activated. */
+  disabled?: boolean;
+}
+
+/**
+ * HkSettingsBody — the sectioned settings shell: a left rail of icon+label
+ * nav entries and a right scrollable pane rendering the active section's
+ * slot. Extracted from the pattern wowsp, the flasher and the admin
+ * consoles each hand-rolled (the "classic settings window" anatomy).
+ *
+ * Standalone by design: the BODY can be embedded in a page (the phone
+ * surface pattern — wowsp renders it inside its own /settings route) or
+ * inside {@link HSettingsDialog}, which wraps it in an HModal window.
+ * Section identity is a `v-model:section` so openers can land on a
+ * specific section; leaving it unbound keeps the state internal
+ * (first section active).
+ *
+ * Scroll ownership: the pane is the only scroller — switching sections
+ * restarts it from the top (arriving on a half-scrolled pane reads as a
+ * broken page). Inside the dialog the modal body's own scroller is made
+ * mathematically idle by the host height rule (see the SCSS); on a page
+ * the host manages its own layout.
+ */
+export const HkSettingsBody = defineComponent({
+  name: "HkSettingsBody",
+  props: {
+    /** Rail entries, in rail order. */
+    sections: { type: Array as PropType<HkSettingsSection[]>, required: true },
+    /** Active section key (v-model:section). Unbound = internal state. */
+    section: { type: String, default: undefined },
+    /** Accessible name for the rail navigation. */
+    navLabel: { type: String, default: undefined },
+  },
+  emits: {
+    "update:section": (key: string) => typeof key === "string",
+  },
+  setup(props, { emit, slots }) {
+    const internal = ref(props.sections[0]?.key ?? "");
+    // Controlled while a section prop is bound: external changes flow in,
+    // clicks flow out. Unbound: the internal ref alone decides. Immediate
+    // so an opener that mounts ALREADY on a deep-linked section
+    // (section="network" from the first render) wins over the first-entry
+    // default — a non-immediate watch would never fire for it.
+    watch(
+      () => props.section,
+      (key) => {
+        if (key == null) return;
+        // A disabled (or unknown) key never activates — a host that
+        // deep-links to one keeps the first usable section instead
+        // (R1 gap: the locked pane used to render with its rail entry
+        // greyed out, contradicting "renders but cannot be activated").
+        if (props.sections.some((sec) => sec.key === key && !sec.disabled)) {
+          internal.value = key;
+        }
+      },
+      { immediate: true },
+    );
+    const active = () =>
+      props.sections.some((s) => s.key === internal.value)
+        ? internal.value
+        : (props.sections[0]?.key ?? "");
+
+    const paneRef = ref<HTMLElement | null>(null);
+    // Section switches restart the pane from the top.
+    watch(active, () => {
+      void nextTick(() => {
+        if (paneRef.value) paneRef.value.scrollTop = 0;
+      });
+    });
+
+    function pick(key: string) {
+      const entry = props.sections.find((s) => s.key === key);
+      if (!entry || entry.disabled) return;
+      internal.value = key;
+      emit("update:section", key);
+    }
+
+    return () => (
+      <div class="hk-settings">
+        <nav class="hk-settings__rail" aria-label={props.navLabel}>
+          {props.sections.map((s) => {
+            const Icon = s.icon;
+            const on = active() === s.key && !s.disabled;
+            return (
+              <button
+                key={s.key}
+                type="button"
+                class={["hk-settings__rail-item", on ? "is-active" : ""]}
+                aria-current={on ? "true" : undefined}
+                aria-disabled={s.disabled || undefined}
+                disabled={s.disabled}
+                onClick={() => pick(s.key)}
+              >
+                {typeof Icon === "function" ? (
+                  <span class="hk-settings__rail-icon" aria-hidden="true">
+                    <Icon size={16} />
+                  </span>
+                ) : null}
+                <span class="hk-settings__rail-label">{s.label}</span>
+              </button>
+            );
+          })}
+        </nav>
+        <div class="hk-settings__pane" ref={paneRef}>
+          {slots[active()]?.()}
+        </div>
+      </div>
+    );
+  },
+});
+
+/**
+ * HkSettingsDialog — the settings window: an HModal carrying the
+ * {@link HSettingsBody} shell with a stable frame height, so the modal
+ * body's floating scrollbar stays idle and the pane's edge bar is the
+ * only scrollbar (the wowsp-proven contract). Width defaults to the
+ * settings-standard 58rem; `height` styles the shell (the 70vh default
+ * fits a modal with title and paddings).
+ *
+ * Like every HkModal composite it bottom-sheets under 768px; hosts that
+ * want a phone page instead render HSettingsBody in their own route and
+ * simply never mount this dialog there.
+ */
+export const HkSettingsDialog = defineComponent({
+  name: "HkSettingsDialog",
+  props: {
+    modelValue: { type: Boolean, default: false },
+    title: { type: String, default: "" },
+    /** Modal max-width (CSS value or HkModal preset). */
+    width: { type: String, default: "58rem" },
+    /** Rail entries — passed through to the body. */
+    sections: { type: Array as PropType<HkSettingsSection[]>, required: true },
+    /** Active section key (v-model:section). */
+    section: { type: String, default: undefined },
+    /** Accessible name for the rail navigation. */
+    navLabel: { type: String, default: undefined },
+    /** Shell height — the stable frame the pane scrolls inside. */
+    height: { type: String, default: "calc(70vh - 6.5rem)" },
+  },
+  emits: {
+    "update:modelValue": (v: boolean) => typeof v === "boolean",
+    "update:section": (key: string) => typeof key === "string",
+  },
+  setup(props, { emit, slots }) {
+    return () => (
+      <HModal
+        modelValue={props.modelValue}
+        onUpdate:modelValue={(v: boolean) => emit("update:modelValue", v)}
+        title={props.title}
+        width={props.width}
+        contentClass="hk-settings-host"
+      >
+        {/* The per-section slots flow through h()'s third argument — the
+            canonical slots channel. JSX children would wrap the slots
+            object into a vnode child and the keys would never reach the
+            body (caught by the dialog mount test). */}
+        {h(
+          HkSettingsBody,
+          {
+            sections: props.sections,
+            section: props.section,
+            navLabel: props.navLabel,
+            "onUpdate:section": (key: string) => emit("update:section", key),
+            style: { "--hk-settings-height": props.height },
+          },
+          slots,
+        )}
+      </HModal>
+    );
+  },
+});
+
+/**
+ * HSettingsGroup — one titled card in the content pane: the standard
+ * container of a section's controls. Slightly translucent so cards sit
+ * quietly on image wallpapers.
+ */
+export const HkSettingsGroup = defineComponent({
+  name: "HkSettingsGroup",
+  props: {
+    title: { type: String, default: undefined },
+  },
+  setup(props, { slots }) {
+    return () => (
+      <section class="hk-settings-group">
+        {props.title ? <h3 class="hk-settings-group-title">{props.title}</h3> : null}
+        {slots.default?.()}
+      </section>
+    );
+  },
+});
+
+/** HSettingsSub — a titled sub-block inside a group. */
+export const HkSettingsSub = defineComponent({
+  name: "HkSettingsSub",
+  props: {
+    title: { type: String, default: undefined },
+  },
+  setup(props, { slots }) {
+    return () => (
+      <div class="hk-settings-sub">
+        {props.title ? <h4 class="hk-settings-sub-title">{props.title}</h4> : null}
+        {slots.default?.()}
+      </div>
+    );
+  },
+});
+
+/** HSettingsHint — the small muted explanation line under a control. */
+export const HkSettingsHint = defineComponent({
+  name: "HkSettingsHint",
+  setup(_props, { slots }) {
+    return () => <p class="hk-settings-hint">{slots.default?.()}</p>;
+  },
+});

package/src/index.ts

@@ -435,6 +435,15 @@ export {
   type HAboutLinkIcon,
 } from "./components/HkAboutModal";
 export { HkLogWindow as HLogWindow, type HLogTab } from "./components/HkLogWindow";
+export {
+  HkSettingsBody as HSettingsBody,
+  HkSettingsDialog as HSettingsDialog,
+  HkSettingsGroup as HSettingsGroup,
+  HkSettingsSub as HSettingsSub,
+  HkSettingsHint as HSettingsHint,
+  type HkSettingsSection,
+} from "./components/HkSettingsDialog";
+
 export { HkCookieConsent as HCookieConsent } from "./components/HkCookieConsent";
 export {
   HkAttachmentModal as HAttachmentModal,