@celestia-island/hikari 0.51.2 → 0.52.0

package/package.json

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

package/src/components/HkAboutModal.scss

@@ -295,6 +295,28 @@
   vertical-align: baseline;
 }
 
+// Accent face: bare text like `plain`, but tinted in the primary colour so
+// the link visibly stands out of the run it sits in — the "this is
+// clickable" cue (user direction 2026-09-15; the pure `plain` face melted
+// the credits names into the sentence too well). No frame, no pill padding,
+// and no underline at rest; the hover deepens the tint and adds one.
+//
+// Same specificity story as the `plain` block above: this rule (0,2,0) beats
+// the chip base (0,1,0), and the `[data-face="accent"]:hover` / `:active`
+// rules below (0,3,0) keep the chip's tinted hover box off the bare text.
+.s-about-modal-link[data-face="accent"] {
+  display: inline;
+  margin: 0;
+  padding: 0;
+  border: 0;
+  border-radius: 0;
+  background: none;
+  color: rgb(var(--color-primary));
+  font-size: inherit;
+  line-height: inherit;
+  vertical-align: baseline;
+}
+
 // A link carrying an icon is one aligned unit (the mark, then the optional
 // label) — icon-only links are how the GitHub mark rides beside the domains.
 // Same specificity as the `plain` block above, so source order decides: this
@@ -339,6 +361,15 @@
   color: rgb(var(--color-primary));
 }
 
+// The accent face already rests in the primary colour, so the hover cue is
+// the deepened tint plus an underline — the glyph colour alone cannot move.
+.s-about-modal-link[data-face="accent"]:hover {
+  background: none;
+  color: var(--c-primary-strong, rgb(var(--color-primary) / 80%));
+  text-decoration: underline;
+  text-underline-offset: 0.15em;
+}
+
 .s-about-modal-link:active {
   background: var(--c-primary-subtle, rgb(var(--color-primary) / 8%));
 }
@@ -348,6 +379,11 @@
   color: var(--c-primary-strong, rgb(var(--color-primary) / 40%));
 }
 
+.s-about-modal-link[data-face="accent"]:active {
+  background: none;
+  color: rgb(var(--color-muted));
+}
+
 .s-about-modal-link:focus-visible {
   outline: none;
   box-shadow:

package/src/components/HkAboutModal.styles.test.ts

@@ -136,6 +136,44 @@ describe("HkAboutModal stylesheet contract", () => {
       expect(declaration(ruleBody(css, `${PLAIN}:active`), "background")).toBe("none");
     });
 
+    const ACCENT = ".s-about-modal-link[data-face=accent]";
+
+    it("keeps the accent face a bare text link tinted in the primary colour", () => {
+      const accent = ruleBody(css, ACCENT);
+      expect(accent, "the accent-face rule must survive compilation").not.toBe("");
+      expect({
+        padding: declaration(accent, "padding"),
+        border: declaration(accent, "border"),
+        radius: declaration(accent, "border-radius"),
+        background: declaration(accent, "background"),
+        // The tint IS the face: bare geometry like `plain`, but the colour
+        // comes from the theme's primary token rather than `inherit`.
+        color: declaration(accent, "color"),
+        fontSize: declaration(accent, "font-size"),
+        lineHeight: declaration(accent, "line-height"),
+      }).toEqual({
+        padding: "0",
+        border: "0",
+        radius: "0",
+        background: "none",
+        color: "rgb(var(--color-primary))",
+        fontSize: "inherit",
+        lineHeight: "inherit",
+      });
+      // No underline at rest — the tint is the cue; the hover adds one.
+      expect(declaration(accent, "text-decoration")).not.toContain("underline");
+    });
+
+    it("gives the accent hover an added cue beyond the resting tint", () => {
+      // The accent face already rests in the primary colour, so a hover that
+      // only re-set the same colour would be invisible — the deepened tint
+      // plus the underline is the contract.
+      const hover = ruleBody(css, `${ACCENT}:hover`);
+      expect(declaration(hover, "background")).toBe("none");
+      expect(declaration(hover, "text-decoration")).toContain("underline");
+      expect(declaration(ruleBody(css, `${ACCENT}:active`), "background")).toBe("none");
+    });
+
     it("keeps an icon link one aligned unit with a visible mark", () => {
       const iconLink = ruleBody(css, ".s-about-modal-link.s-about-modal-link-has-icon");
       expect(declaration(iconLink, "display")).toBe("inline-flex");

package/src/components/HkAboutModal.test.tsx

@@ -16,7 +16,8 @@ import { setLocale } from "../i18n/context";
  * - the backdrop factory renders inside the clipped backdrop layer
  * - licenses and links render as chips under one centered block
  * - footer (filing) links render as external links
- * - `face: "plain"` turns any of them into a bare text link (still a link,
+ * - `face: "plain"` / `face: "accent"` turn any of them into a bare text
+ *   link (still a link,
  *   still a new tab), and an entry carrying an `icon` renders the mark, with
  *   an accessible name when it has no label to be named by
  *
@@ -156,6 +157,31 @@ describe("HkAboutModal branding", () => {
     }
   });
 
+  it("renders a credit name as a tinted accent link when the entry asks for it", async () => {
+    mountAbout({
+      credits: [
+        { text: "来自 " },
+        { name: "Celestia Island", href: "https://github.com/celestia-island", face: "accent" },
+        { text: "，由 " },
+        { name: "伊欧", href: "https://github.com/langyo", face: "accent" },
+        { text: " 主创" },
+      ],
+    });
+    await flushModal();
+    const links = [
+      ...document.body.querySelectorAll<HTMLAnchorElement>(".s-about-modal-credit-link"),
+    ];
+    // Same bare-text shape as `plain` (no chip geometry), but the entry's
+    // face reaches the stylesheet as `accent`.
+    expect(links.map((link) => link.textContent)).toEqual(["Celestia Island", "伊欧"]);
+    for (const link of links) {
+      expect(link.getAttribute("data-face")).toBe("accent");
+      expect(link.classList.contains("s-about-modal-link")).toBe(true);
+      expect(link.getAttribute("target")).toBe("_blank");
+      expect(link.getAttribute("aria-label")).toBeNull();
+    }
+  });
+
   it("renders plain faces across the link rows and the legal filings", async () => {
     mountAbout({
       links: [

package/src/components/HkAboutModal.tsx

@@ -11,11 +11,13 @@ import "./HkAboutModal.scss";
  *
  * `chip` is the dialog's original face — a ghost tag. `plain` is bare text:
  * no frame, no underline, so the hover colour shift is the whole
- * affordance. Chosen per link, because one dialog can want both (the
- * credits names / URLs / filings read as sentence text, the licenses stay
- * tags).
+ * affordance. `accent` is also bare text, but tinted in the primary colour
+ * so the link visibly stands out of the sentence it sits in — the "this is
+ * clickable" cue (user direction 2026-09-15). Chosen per link, because one
+ * dialog can want both (the credits names / URLs / filings read as sentence
+ * text, the licenses stay tags).
  */
-export type HAboutLinkFace = "chip" | "plain";
+export type HAboutLinkFace = "chip" | "plain" | "accent";
 
 /** Leading icon a link can carry; an icon-only link shows it alone. */
 export type HAboutLinkIcon = "github";
@@ -90,8 +92,8 @@ export interface HAboutComponentVersion {
  * bordered spec card holding the software-component versions, and the
  * link rows — licenses, external links and legal filings. Every link opens
  * in a new tab and renders in the face its entry asks for: the ghost chip,
- * or bare text (`plain`) for names / URLs / filings that should read as
- * ordinary sentence text. Every branding prop is optional — the modal
+ * or bare text (`plain` / tinted `accent`) for names / URLs / filings that
+ * should read as ordinary sentence text. Every branding prop is optional — the modal
  * degrades to the plain identity card when none are given.
  */
 export const HkAboutModal = defineComponent({
@@ -111,7 +113,8 @@ export const HkAboutModal = defineComponent({
     /**
      * Credits sentence, assembled from text runs and linked names
      * (e.g. 来自 <Celestia Island>，由 <伊欧> 主创). Each name renders in the
-     * face its entry asks for — `chip`, or bare text with `plain`.
+     * face its entry asks for — `chip`, bare text with `plain`, or bare
+     * text tinted in the primary colour with `accent`.
      */
     credits: { type: Array as PropType<HAboutCredit[]>, default: () => [] },
     /** License links (e.g. SySL-1.0 / BUSL-1.1), rendered centered. */

package/src/components/HkScrollContainer.dock.test.tsx

@@ -0,0 +1,92 @@
+// Dock-slot contract for HkScrollContainer.
+//
+// A dock (dockTop / dockBottom named slot) renders as a NON-scrolling
+// flex sibling of the viewport: pinned to its edge, occupying layout
+// space (the flex: 1 viewport shrinks by the dock's height — content
+// can never slide under it). The container measures each mounted dock
+// and publishes --hk-scroll-dock-top / --hk-scroll-dock-bottom on the
+// host so consumers size their content end-padding against the dock
+// without hand-rolled px. The dock-edge fade rides on data-dock-fade.
+//
+// House style: raw createApp mounts on shared containers (no
+// @vue/test-utils).
+import { afterEach, describe, expect, it } from "vitest";
+import { createApp, h, defineComponent } from "vue";
+
+import HkScrollContainer from "./HkScrollContainer";
+
+const mounts: ReturnType<typeof createApp>[] = [];
+const containers: HTMLElement[] = [];
+
+function mountDock(slots: Record<string, () => any>, props: Record<string, unknown> = {}) {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  containers.push(container);
+  const app = createApp(defineComponent({
+    setup() {
+      return () => h(HkScrollContainer, props, slots);
+    },
+  }));
+  mounts.push(app);
+  return app.mount(container);
+}
+
+afterEach(() => {
+  for (const app of mounts) app.unmount();
+  mounts.length = 0;
+  for (const el of containers) el.remove();
+  containers.length = 0;
+});
+
+describe("HkScrollContainer dock slots", () => {
+  it("renders a bottom dock as a non-scrolling sibling with the fade marker", () => {
+    const vm = mountDock({
+      default: () => h("div", { class: "content" }, "rows"),
+      dockBottom: () => h("div", { class: "the-dock" }, "dock"),
+    });
+    const host = vm.$el as HTMLElement;
+    const dock = host.querySelector(".hk-scroll-dock[data-side='bottom']");
+    expect(dock).toBeTruthy();
+    // Sibling of the viewport, not inside it — the dock never scrolls.
+    const viewport = host.querySelector(".hk-scroll-container-viewport")!;
+    expect(viewport.contains(dock as Node)).toBe(false);
+    // The dock-edge fade engages by default for a bottom dock.
+    expect(host.getAttribute("data-dock-fade")).toBe("bottom");
+    // The measured-height vars are published on the host (0px in
+    // happy-dom — no layout; the contract is the vars exist + RO wired).
+    expect(host.style.getPropertyValue("--hk-scroll-dock-bottom")).toBe("0px");
+    expect(host.style.getPropertyValue("--hk-scroll-dock-top")).toBe("0px");
+  });
+
+  it("renders a top dock and fades the top edge instead", () => {
+    const vm = mountDock({
+      default: () => h("div", { class: "content" }, "rows"),
+      dockTop: () => h("div", { class: "the-dock" }, "progress"),
+    });
+    const host = vm.$el as HTMLElement;
+    expect(host.querySelector(".hk-scroll-dock[data-side='top']")).toBeTruthy();
+    expect(host.getAttribute("data-dock-fade")).toBe("top");
+    expect(host.querySelector(".hk-scroll-dock[data-side='bottom']")).toBeNull();
+  });
+
+  it("omits the dock fade marker when dockFade is off", () => {
+    const vm = mountDock(
+      {
+        default: () => h("div", { class: "content" }, "rows"),
+        dockBottom: () => h("div", { class: "the-dock" }, "dock"),
+      },
+      { dockFade: false },
+    );
+    const host = vm.$el as HTMLElement;
+    expect(host.querySelector(".hk-scroll-dock[data-side='bottom']")).toBeTruthy();
+    expect(host.getAttribute("data-dock-fade")).toBeNull();
+  });
+
+  it("publishes no dock marker without dock slots", () => {
+    const vm = mountDock({ default: () => h("div", { class: "content" }, "rows") });
+    const host = vm.$el as HTMLElement;
+    expect(host.querySelector(".hk-scroll-dock")).toBeNull();
+    expect(host.getAttribute("data-dock-fade")).toBeNull();
+    expect(host.style.getPropertyValue("--hk-scroll-dock-bottom")).toBe("");
+  });
+});

package/src/components/HkScrollContainer.scss

@@ -53,6 +53,38 @@
   mask-image: linear-gradient(to left, transparent 0, #000 var(--hk-scroll-fade-size));
 }
 
+/* ── Anchored docks (dockTop / dockBottom slots) ─────────────────
+   A dock renders as a NON-scrolling flex sibling of the viewport: it
+   stays pinned to its edge, never scrolls, and occupies layout space —
+   the flex: 1 viewport shrinks by the dock's height, so the content's
+   scroll end lands exactly at the dock's edge and can never slide
+   under it. The container measures each mounted dock (ResizeObserver)
+   and publishes --hk-scroll-dock-top / --hk-scroll-dock-bottom on the
+   host, so a consumer's content end-padding clears the dock with
+   breathing room (padding-bottom: calc(var(--hk-scroll-dock-bottom)
+   + 2rem)) instead of hand-rolled px guesses that go stale when the
+   dock reflows. */
+.hk-scroll-dock {
+  flex: none;
+  min-height: 0;
+}
+
+/* Dock-edge fade: mid-scroll content dissolving at the dock's edge
+   (opacity 100 -> 0 across --hk-scroll-dock-fade) reads as intentional
+   instead of a hard clip against the dock's top edge. Content never
+   sits under the dock, so this fades the viewport's last few pixels,
+   not the dock itself. */
+.hk-scroll-container[data-dock-fade="bottom"] > .hk-scroll-container-viewport {
+  -webkit-mask-image: linear-gradient(to bottom, #000 calc(100% - var(--hk-scroll-dock-fade, 2rem)), transparent);
+  mask-image: linear-gradient(to bottom, #000 calc(100% - var(--hk-scroll-dock-fade, 2rem)), transparent);
+}
+
+.hk-scroll-container[data-dock-fade="top"] > .hk-scroll-container-viewport {
+  -webkit-mask-image: linear-gradient(to bottom, transparent, #000 var(--hk-scroll-dock-fade, 2rem));
+  mask-image: linear-gradient(to bottom, transparent, #000 var(--hk-scroll-dock-fade, 2rem));
+}
+
+
 .hk-scroll-container[data-fade="true"][data-h-overflow="start"] > .hk-scroll-container-viewport {
   -webkit-mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));
   mask-image: linear-gradient(to right, transparent 0, #000 var(--hk-scroll-fade-size));

package/src/components/HkScrollContainer.tsx

@@ -80,12 +80,21 @@ export default defineComponent({
      *  approaching (`approachEnd`). Read live, so runtime changes need
      *  no remount. */
     approachDistance: { type: Number, default: 160 },
+    /** Fade the viewport's bottom edge (CSS mask, --hk-scroll-dock-fade
+     *  tall, opacity 100 -> 0) while a dock slot is mounted, so mid-
+     *  scroll content dissolving at the dock's edge reads as
+     *  intentional instead of a hard clip. */
+    dockFade: { type: Boolean, default: true },
   },
   emits: { approachEnd: () => true },
   setup(props, { slots, expose, emit }) {
     const { t } = useI18n();
     const viewportRef = ref<HTMLElement>();
+    const hostRef = ref<HTMLElement>();
+    const dockTopRef = ref<HTMLElement>();
+    const dockBottomRef = ref<HTMLElement>();
     let ro: ResizeObserver | null = null;
+    let dockRO: ResizeObserver | null = null;
     let scheduled: AnimationHandle | null = null;
     // Overlay track/thumb machinery lives in the shared composable;
     // this component keeps overflow sensing, autoFollow, the aligner,
@@ -292,10 +301,40 @@ export default defineComponent({
       }
     }
 
+    /** Publish each mounted dock's measured height as a host-level custom
+     *  property (`--hk-scroll-dock-top` / `--hk-scroll-dock-bottom`). The
+     *  dock is a non-scrolling flex sibling, so the viewport already
+     *  shrinks by its height; the published var exists so a consumer's
+     *  content end-padding can clear the dock with breathing room
+     *  (padding-bottom: calc(var(--hk-scroll-dock-bottom, 0px) + 2rem))
+     *  instead of hand-rolled px guesses that go stale when the dock
+     *  reflows. ResizeObserver keeps it live across dock reflows. */
+    function publishDockSizes() {
+      const host = hostRef.value;
+      if (!host) return;
+      const top = dockTopRef.value;
+      const bottom = dockBottomRef.value;
+      host.style.setProperty(
+        "--hk-scroll-dock-top",
+        top ? `${Math.round(top.getBoundingClientRect().height)}px` : "0px",
+      );
+      host.style.setProperty(
+        "--hk-scroll-dock-bottom",
+        bottom ? `${Math.round(bottom.getBoundingClientRect().height)}px` : "0px",
+      );
+    }
+
     onMounted(() => {
       const vp = viewportRef.value;
       if (!vp) return;
 
+      if (dockTopRef.value || dockBottomRef.value) {
+        dockRO = new ResizeObserver(publishDockSizes);
+        if (dockTopRef.value) dockRO.observe(dockTopRef.value);
+        if (dockBottomRef.value) dockRO.observe(dockBottomRef.value);
+        publishDockSizes();
+      }
+
       if (props.scrollbar) {
         mountScrollbars();
       }
@@ -340,6 +379,8 @@ export default defineComponent({
       settleHandle = null;
       ro?.disconnect();
       ro = null;
+      dockRO?.disconnect();
+      dockRO = null;
       followRO?.disconnect();
       followRO = null;
       alignRO?.disconnect();
@@ -431,13 +472,34 @@ export default defineComponent({
       if (alignCenter()) {
         content = <div ref={setAligner} class="hk-scroll-container-aligner">{content}</div>;
       }
+      // Anchored dock slots: a dock renders as a NON-scrolling flex
+      // sibling of the viewport — it stays pinned to its edge, never
+      // scrolls, and occupies layout space (the flex: 1 viewport shrinks
+      // by the dock's height). The container measures each mounted dock
+      // and publishes --hk-scroll-dock-top/bottom so consumers can size
+      // their content end-padding against the dock without guessing px.
+      const dockTopSlot = slots.dockTop;
+      const dockBottomSlot = slots.dockBottom;
       return (
         <Tag
+          ref={hostRef}
           class="hk-scroll-container"
           data-axis={props.axis}
           data-align={alignCenter() ? "center" : undefined}
           data-fade={props.fade ? "true" : undefined}
+          data-dock-fade={
+            props.dockFade && dockBottomSlot
+              ? "bottom"
+              : props.dockFade && dockTopSlot
+                ? "top"
+                : undefined
+          }
         >
+          {dockTopSlot && (
+            <div ref={dockTopRef} class="hk-scroll-dock" data-side="top">
+              {dockTopSlot()}
+            </div>
+          )}
           {/* Scroll-pin host marker: the viewport participates in the pin
               contract with its live axis; generic containers declare no
               standard padding, so pins inside resolve their strategy from
@@ -449,6 +511,11 @@ export default defineComponent({
           >
             {content}
           </div>
+          {dockBottomSlot && (
+            <div ref={dockBottomRef} class="hk-scroll-dock" data-side="bottom">
+              {dockBottomSlot()}
+            </div>
+          )}
           {showAutoTag.value && (
             <span class="hk-scroll-container-autotag" aria-hidden="true">{t("hikari::scrollContainer.auto", "Auto")}</span>
           )}