@celestia-island/hikari 0.40.0 → 0.40.1

package/package.json

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

package/src/components/HkAdaptiveDialog.tsx

@@ -38,7 +38,7 @@ import { useBreakpoint } from "../runtime/useBreakpoint";
 import "./HkAdaptiveDialog.scss";
 import HButton from "./HkButton";
 import HDrawer from "./HkDrawer";
-import HModal, { type ModalAction } from "./HkModal";
+import HModal, { type ModalAction, type ModalWidth } from "./HkModal";
 
 export default defineComponent({
   name: "HkAdaptiveDialog",
@@ -47,7 +47,7 @@ export default defineComponent({
     title: { type: String, default: undefined },
     closable: { type: Boolean, default: true },
     /** Desktop modal width (HkModal `width`). */
-    width: { type: String, default: "32rem" },
+    width: { type: String as PropType<ModalWidth>, default: "32rem" },
     /** Mobile drawer height (HkDrawer `size`). HkDrawer's bottom-side CSS
      *  clamps panels at maxHeight 70vh, so the default equals the cap;
      *  pass `panelClass` with a custom max-height for taller sheets. */

package/src/components/HkCaptchaModal.tsx

@@ -1,5 +1,5 @@
 import { defineComponent, type PropType } from "vue";
-import { HModal } from "@celestia-island/hikari";
+import { HModal, type ModalWidth } from "@celestia-island/hikari";
 
 import { useI18n } from "../i18n/context";
 
@@ -23,7 +23,7 @@ export const HkCaptchaModal = defineComponent({
     scriptUrl: { type: String, default: undefined },
     attempt: { type: Number, default: 0 },
     title: { type: String, default: undefined },
-    width: { type: String, default: "30rem" },
+    width: { type: String as PropType<ModalWidth>, default: "30rem" },
   },
   emits: {
     "update:modelValue": (_v: boolean) => true,

package/src/components/HkLogWindow.tsx

@@ -1,6 +1,6 @@
 import { computed, defineComponent, nextTick, ref, watch, type PropType } from "vue";
 import { Copy, Eraser, Pause, Play, ScrollText } from "lucide-vue-next";
-import { HModal, HScrollContainer, useClipboard } from "@celestia-island/hikari";
+import { HModal, HScrollContainer, useClipboard, type ModalWidth } from "@celestia-island/hikari";
 
 import { useI18n } from "../i18n/context";
 
@@ -47,7 +47,7 @@ export const HkLogWindow = defineComponent({
     /** Height of the log body (CSS length, e.g. "55vh"). */
     height: { type: String, default: "55vh" },
     title: { type: String, default: undefined },
-    width: { type: String, default: "60rem" },
+    width: { type: String as PropType<ModalWidth>, default: "60rem" },
   },
   emits: {
     "update:modelValue": (_v: boolean) => true,

package/src/components/HkModal.tsx

@@ -34,6 +34,84 @@ export interface ModalAction {
   onClick?: () => void;
 }
 
+/**
+ * Named width presets for the `width` prop. Callers kept reaching for
+ * semantic sizes (`width="sm"`) which, passed through as raw CSS
+ * `max-width`, are silently dropped by the browser — the frame fell back
+ * to `width: 100%` and spanned the whole viewport (chest #662-era change
+ * password modal rendered 2048px wide). Named values now resolve here;
+ * anything else keeps passing through as a CSS max-width value.
+ */
+export const MODAL_WIDTH_PRESETS = {
+  xs: "20rem",
+  sm: "32rem",
+  md: "40rem",
+  lg: "56rem",
+  xl: "72rem",
+} as const;
+
+export type ModalWidthPreset = keyof typeof MODAL_WIDTH_PRESETS;
+
+/**
+ * `width` accepts a named preset or any CSS max-width value. The
+ * `(string & {})` arm keeps preset autocomplete in TSX while still
+ * allowing arbitrary lengths ("32rem", "560px", "50%").
+ */
+export type ModalWidth = ModalWidthPreset | (string & {});
+
+const warnedWidths = new Set<string>();
+/** Dev-only warn-once memory cap: a session feeding dynamically generated
+ *  garbage widths must not grow the set forever. Prod never reaches this
+ *  code (DEV is statically false there). */
+const MAX_WARNED_WIDTHS = 50;
+
+/** Valid digit-free CSS max-width keywords: the browser honors these, so
+ *  the "would span the viewport" dev warn must stay silent for them. */
+const WIDTH_KEYWORDS = new Set([
+  "auto",
+  "none",
+  "min-content",
+  "max-content",
+  "fit-content",
+]);
+
+/**
+ * Resolve the `width` prop to a concrete CSS max-width value: presets map
+ * through `MODAL_WIDTH_PRESETS`, everything else passes through untouched.
+ * In dev, a value that is neither a preset, a keyword, nor a length (no
+ * digit anywhere — e.g. a stray token like `"wide"`) warns once: as a raw
+ * max-width it would be dropped by the browser and the modal would span
+ * the viewport.
+ */
+export function resolveModalWidth(width: string): string {
+  // Coerce defensively: a JS consumer passing width={560} skips the prop
+  // type check at runtime and Vue would have rendered the number as px.
+  const value = String(width);
+  // hasOwnProperty.call instead of Object.hasOwn (ES2022): the package
+  // ships TS source, so consumers' bundlers will not polyfill new
+  // built-ins — this must not raise the runtime floor. The own-property
+  // guard is what keeps inherited members ("constructor", "toString")
+  // from resolving as presets past the dev warn.
+  const key = value.trim();
+  const preset = Object.prototype.hasOwnProperty.call(MODAL_WIDTH_PRESETS, key)
+    ? MODAL_WIDTH_PRESETS[key as ModalWidthPreset]
+    : undefined;
+  if (preset !== undefined) return preset;
+  if (
+    import.meta.env?.DEV &&
+    !/\d/.test(value) &&
+    !WIDTH_KEYWORDS.has(key) &&
+    warnedWidths.size < MAX_WARNED_WIDTHS &&
+    !warnedWidths.has(value)
+  ) {
+    warnedWidths.add(value);
+    console.warn(
+      `[HkModal] width "${value}" is neither a named preset (${Object.keys(MODAL_WIDTH_PRESETS).join("/")}) nor a CSS length — the browser would drop it and the modal would span the viewport.`,
+    );
+  }
+  return value;
+}
+
 const FOCUSABLE_SELECTOR =
   'a[href], button:not([disabled]), textarea:not([disabled]), input:not([disabled]), select:not([disabled]), [tabindex]:not([tabindex="-1"])';
 
@@ -44,7 +122,8 @@ export default defineComponent({
     modelValue: { type: Boolean, required: true },
     title: { type: String, default: undefined },
     closable: { type: Boolean, default: true },
-    width: { type: String, default: "32rem" },
+    /** Named preset ("xs"…"xl") or any CSS max-width value (see ModalWidth). */
+    width: { type: String as PropType<ModalWidth>, default: "32rem" },
     /**
      * Escape hatch: extra class appended to the .hk-modal-content frame
      * so hosts can restyle the surface without forking the modal (e.g.
@@ -114,7 +193,7 @@ export default defineComponent({
 
     const overlayZ = computed(() => handle.value?.zIndex ?? 0);
     const contentZ = computed(() => (handle.value?.zIndex ?? 0) + 1);
-    const resolvedWidth = computed(() => props.width);
+    const resolvedWidth = computed(() => resolveModalWidth(props.width));
     // Layer/dialog name: the explicit surface name wins over the header
     // title (which header-less surfaces never pass).
     const resolvedSurfaceName = computed(() => props.surfaceTitle ?? props.title);

package/src/components/HkModal.width.test.tsx

@@ -0,0 +1,114 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { createApp, defineComponent, h, nextTick, ref } from "vue";
+
+import HkModal, { MODAL_WIDTH_PRESETS, resolveModalWidth } from "./HkModal";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+afterEach(async () => {
+  for (const app of mounts.splice(0)) app.unmount();
+  for (const el of containers.splice(0)) el.remove();
+  vi.restoreAllMocks();
+});
+
+describe("resolveModalWidth", () => {
+  it("maps every named preset to its CSS max-width value", () => {
+    for (const [name, css] of Object.entries(MODAL_WIDTH_PRESETS)) {
+      expect(resolveModalWidth(name)).toBe(css);
+    }
+  });
+
+  it("keeps the default-sized presets bounded and ordered", () => {
+    // Sanity on the scale itself: xs < sm(default) < md < lg < xl.
+    expect(MODAL_WIDTH_PRESETS.xs).toBe("20rem");
+    expect(MODAL_WIDTH_PRESETS.sm).toBe("32rem");
+    expect(MODAL_WIDTH_PRESETS.md).toBe("40rem");
+    expect(MODAL_WIDTH_PRESETS.lg).toBe("56rem");
+    expect(MODAL_WIDTH_PRESETS.xl).toBe("72rem");
+  });
+
+  it("passes arbitrary CSS max-width values through untouched", () => {
+    expect(resolveModalWidth("32rem")).toBe("32rem");
+    expect(resolveModalWidth("560px")).toBe("560px");
+    expect(resolveModalWidth("50%")).toBe("50%");
+    expect(resolveModalWidth("min(90vw, 48rem)")).toBe("min(90vw, 48rem)");
+  });
+
+  it("passes digit-free max-width keywords through without warning", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    for (const keyword of ["auto", "none", "min-content", "max-content", "fit-content"]) {
+      expect(resolveModalWidth(keyword)).toBe(keyword);
+    }
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("coerces a numeric width from JS consumers instead of throwing", () => {
+    expect(resolveModalWidth(560 as unknown as string)).toBe("560");
+  });
+
+  it("does not inherit Object.prototype members as presets", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // A bare index lookup would resolve "constructor"/"toString" to
+    // inherited functions and early-return them past the warn — the
+    // guard must treat them as unknown values instead.
+    for (const hostile of ["constructor", "toString", "valueOf"]) {
+      expect(resolveModalWidth(hostile)).toBe(hostile);
+    }
+    expect(warn).toHaveBeenCalledTimes(3);
+  });
+
+  it("trims surrounding whitespace before the preset lookup", () => {
+    expect(resolveModalWidth(" sm ")).toBe("32rem");
+    expect(resolveModalWidth(" 560px ")).toBe(" 560px ");
+  });
+
+  it("warns once in dev for a value that is neither a preset nor a length", () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    // A unique digit-free token per run: the warn-once set is module
+    // state, and any digit would classify the value as a length.
+    const stray = `wide-${Math.random().toString(36).slice(2).replace(/\d/g, "") || "wide"}`;
+    expect(resolveModalWidth(stray)).toBe(stray);
+    expect(resolveModalWidth(stray)).toBe(stray);
+    expect(warn).toHaveBeenCalledTimes(1);
+    expect(warn.mock.calls[0]?.[0]).toContain(stray);
+  });
+});
+
+describe("HkModal width rendering", () => {
+  async function mountModal(width: string): Promise<HTMLElement> {
+    const container = document.createElement("div");
+    document.body.appendChild(container);
+    containers.push(container);
+
+    const open = ref(true);
+    const Wrapper = defineComponent({
+      setup() {
+        return () =>
+          h(HkModal, {
+            modelValue: open.value,
+            width,
+          }, { default: () => h("div", "content") });
+      },
+    });
+    const app = createApp(Wrapper);
+    mounts.push(app);
+    app.mount(container);
+    await nextTick();
+
+    // HkModal Teleports to document.body — the mount container stays empty.
+    const content = document.body.querySelector<HTMLElement>(".hk-modal-content");
+    expect(content).toBeTruthy();
+    return content!;
+  }
+
+  it("renders a named preset as the frame's max-width", async () => {
+    const content = await mountModal("sm");
+    expect(content.style.maxWidth).toBe("32rem");
+  });
+
+  it("renders an arbitrary CSS length as the frame's max-width", async () => {
+    const content = await mountModal("560px");
+    expect(content.style.maxWidth).toBe("560px");
+  });
+});

package/src/components/HkProtocolModal.tsx

@@ -1,5 +1,5 @@
-import { computed, defineComponent, onBeforeUnmount, ref, watch } from "vue";
-import { HMarkdownRenderer, HModal, useClipboard, type ModalAction } from "@celestia-island/hikari";
+import { computed, defineComponent, onBeforeUnmount, ref, watch, type PropType } from "vue";
+import { HMarkdownRenderer, HModal, useClipboard, type ModalAction, type ModalWidth } from "@celestia-island/hikari";
 
 import { useI18n } from "../i18n/context";
 import { attachOverlayScrollbars, type OverlayScrollbarHandle } from "../composables/useOverlayScrollbar";
@@ -29,7 +29,7 @@ export const HkProtocolModal = defineComponent({
     declineLabel: { type: String, default: undefined },
     /** Allow dismissing without a decision (overlay/ESC/X). Default true. */
     closable: { type: Boolean, default: true },
-    width: { type: String, default: "48rem" },
+    width: { type: String as PropType<ModalWidth>, default: "48rem" },
     /** Cap the scroll body height (e.g. "60vh"). */
     bodyHeight: { type: String, default: undefined },
   },

package/src/index.ts

@@ -115,6 +115,11 @@ export { type BoardNodeInput, type BoardEdgeInput } from "./components/HkBoard";
 export { type BoardAnchorMode, type BoardEdgeStyle, type BoardPoint } from "./utils/boardEdges";
 export { type BoardCamera, type BoardRect, type BoardViewport } from "./utils/boardCamera";
 export { type ModalAction } from "./components/HkModal";
+export {
+  type ModalWidth,
+  type ModalWidthPreset,
+  resolveModalWidth,
+} from "./components/HkModal";
 export { type TreeNode, type TreeSize, type TreeRowScope } from "./components/HkTree";
 export { type DragListItem } from "./components/HkDraggableList";
 export { type GridItem } from "./components/HkDraggableGrid";