@grimoire-rs/indexer 0.5.0 → 0.5.2

package/dist/renderer/astro/components/Catalog.tsx

@@ -12,6 +12,7 @@ import {
   ArrowUpNarrowWide,
   LayoutGrid,
   List,
+  X,
 } from "lucide-preact";
 import { PackageCard } from "./PackageCard.js";
 import { PackageRow } from "./PackageRow.js";
@@ -41,6 +42,13 @@ export type View = "cards" | "table";
  */
 const KEYWORD_CHIP_LIMIT = 8;
 
+/**
+ * `popovertarget` needs an id, and the catalog is a singleton on its page —
+ * one island, one toolbar, one overflow menu — so this is a constant rather
+ * than something generated per mount.
+ */
+const KEYWORD_MENU_ID = "grim-keyword-overflow";
+
 /**
  * The direction each field is *worth* reading first in — A→Z for a name,
  * newest and best-liked first for the two ranked keys.
@@ -326,9 +334,71 @@ export default function Catalog({
   ];
 
   const railRefs = useRef(new Map<string, HTMLElement>());
-  const railRects = useRef(new Map<string, DOMRect>());
+  /**
+   * Where each chip sat at the last commit, as `offsetLeft`/`offsetTop`.
+   *
+   * Layout positions, deliberately, not `getBoundingClientRect`: the offsets
+   * ignore transforms and page scroll, so a chip measured mid-slide reports
+   * the seat it is animating towards rather than the box it is drawn in this
+   * frame. See the FLIP effect below for why that distinction is the whole
+   * fix.
+   */
+  const railSeats = useRef(new Map<string, { x: number; y: number }>());
+  /** The slide each chip is currently running, so a new one can replace it. */
+  const railSlides = useRef(new WeakMap<HTMLElement, Animation>());
   const railRef = useRef<HTMLDivElement>(null);
 
+  const kwMenuRef = useRef<HTMLDivElement>(null);
+  const kwTriggerRef = useRef<HTMLButtonElement>(null);
+  // Drives the trigger's own `aria-expanded` and its open styling. The panel's
+  // visibility is the popover's business, not this flag's.
+  const [kwMenuOpen, setKwMenuOpen] = useState(false);
+
+  /**
+   * Seat the overflow menu under its trigger.
+   *
+   * The panel is a popover, so it lives in the top layer and is positioned
+   * against the viewport rather than against any ancestor — which is the whole
+   * point (`.filter-row` is a scroll container and used to crop it). That
+   * leaves the seat to us.
+   *
+   * It always opens downward: the toolbar sits at the top of the page, and a
+   * flip would only ever fire on a viewport short enough that the panel has
+   * nowhere to go either way. What does not fit becomes `max-height` and
+   * scrolls inside the list.
+   *
+   * Called twice per open, from `beforetoggle` and again from `toggle`. The
+   * first runs while the panel is still `display: none`, so its measured width
+   * is 0 and the horizontal clamp is a no-op — but the vertical seat is right,
+   * which is what stops it appearing in the wrong place for a frame. The
+   * second has a real width and finishes the clamp.
+   */
+  const placeKwMenu = () => {
+    const panel = kwMenuRef.current;
+    const trigger = kwTriggerRef.current;
+    if (!panel || !trigger) return;
+    const seat = trigger.getBoundingClientRect();
+    const gap = 8;
+    const width = panel.getBoundingClientRect().width;
+    panel.style.left = `${Math.max(gap, Math.min(seat.left, window.innerWidth - width - gap))}px`;
+    panel.style.top = `${seat.bottom + gap}px`;
+    panel.style.maxHeight = `${Math.max(120, window.innerHeight - seat.bottom - gap * 3)}px`;
+  };
+
+  // A fixed panel does not travel with the trigger, so it is re-seated rather
+  // than left behind. Only while open — there is nothing to follow otherwise.
+  useEffect(() => {
+    if (!kwMenuOpen) return;
+    const reseat = () => placeKwMenu();
+    // Capturing: the scroll may be any ancestor's, including `.filter-row`'s.
+    window.addEventListener("scroll", reseat, { capture: true, passive: true });
+    window.addEventListener("resize", reseat);
+    return () => {
+      window.removeEventListener("scroll", reseat, { capture: true });
+      window.removeEventListener("resize", reseat);
+    };
+  }, [kwMenuOpen]);
+
   /**
    * How many keyword chips actually fit on the row, measured.
    *
@@ -391,39 +461,79 @@ export default function Catalog({
    * between two frames reads as having been *replaced*, and a reader who
    * cannot see that a chip moved has no reason to believe it is the same one.
    *
-   * First (the map of rects kept from the last commit), Last (measured now),
-   * Invert (an inline translate back to where the chip was), Play (dropped on
-   * the next frame, so the stylesheet's transition carries it home). Measure
-   * every chip before transforming any: `translate` composites and does not
-   * reflow, but reading a rect after writing a style on a sibling is the
-   * shape that makes a layout thrash, and this runs per keystroke.
+   * Two choices carry the whole thing, and both are here because the shape
+   * they replace — an inline `translate` under the stylesheet's transition,
+   * dropped again on a `requestAnimationFrame` — could leave a chip stopped
+   * off its seat with no path back:
+   *
+   * - **Seats come from `offsetLeft`/`offsetTop`, never from
+   *   `getBoundingClientRect`.** The offsets are layout positions and ignore
+   *   both transforms and scroll; a rect is where the chip is *drawn*, so a
+   *   chip measured mid-slide recorded its animated box and the next
+   *   inversion compounded that error — the stutter. Mid-slide is the common
+   *   case, not a rare one: the fit measurement above commits a second time
+   *   whenever a rescore changes how many chips fit, and that commit lands
+   *   inside the previous slide. Because the offsets are transform-blind,
+   *   that second commit now measures the same seats and starts nothing.
+   * - **The slide is a Web Animation, not an inline style.** It needs no
+   *   frame to start, so no commit can land between an invert and its play
+   *   and freeze a chip at the offset. It writes nothing to `style`, so
+   *   there is nothing left to strip when a chip unmounts or a pass is
+   *   superseded. And it clears itself the instant it finishes or is
+   *   cancelled, which makes "the rail always ends up in its real state" a
+   *   property of the mechanism rather than of a cleanup remembering to run.
    */
   useLayoutEffect(() => {
-    const previous = railRects.current;
-    const current = new Map<string, DOMRect>();
+    const previous = railSeats.current;
+    const current = new Map<string, { x: number; y: number }>();
     const moved: { el: HTMLElement; dx: number; dy: number }[] = [];
     for (const [keyword, el] of railRefs.current) {
-      const rect = el.getBoundingClientRect();
-      current.set(keyword, rect);
+      const x = el.offsetLeft;
+      const y = el.offsetTop;
+      current.set(keyword, { x, y });
       const was = previous.get(keyword);
       if (!was) continue;
-      const dx = was.left - rect.left;
-      const dy = was.top - rect.top;
+      const dx = was.x - x;
+      const dy = was.y - y;
       if (dx !== 0 || dy !== 0) moved.push({ el, dx, dy });
     }
-    railRects.current = current;
+    // Rebuilt from `railRefs` every pass, so a chip that left the rail leaves
+    // this map with it and cannot seed a slide if it comes back elsewhere.
+    railSeats.current = current;
     if (moved.length === 0) return;
+    const rail = railRef.current;
+    // Guarded rather than assumed, like the fit observer above: the test
+    // renderer's DOM has no Web Animations API, and a rail that does not
+    // slide is not worth throwing during a render over.
+    if (!rail || typeof rail.animate !== "function") return;
+    // The motion is the ornament here — the filtering works identically
+    // without it — so a reader who asked for less of it gets none.
+    if (window.matchMedia?.("(prefers-reduced-motion: reduce)").matches) return;
+    // The stylesheet stays the source of truth for how long a slide runs:
+    // `--grim-duration-slow` is written in milliseconds and that is the unit
+    // the Web Animations API takes, so the token survives the move out of CSS.
+    // Read once, after every seat above, so the reads and the writes below
+    // stay in two passes rather than interleaving per chip.
+    const ms = Number.parseFloat(
+      getComputedStyle(rail).getPropertyValue("--grim-duration-slow"),
+    );
     for (const { el, dx, dy } of moved) {
-      el.style.transition = "none";
-      el.style.translate = `${dx}px ${dy}px`;
+      // One slide per chip. A chip that moves again mid-slide takes the new
+      // delta from its layout seat, which starts the second slide a step off
+      // where the first had drawn it — a jump measured in the pixels one
+      // frame of easing covers, and it is bounded, unlike two animations
+      // compositing the same property against each other.
+      // ponytail: not blended with the in-flight offset, which would cost a
+      // computed-style read per chip in the middle of the write pass.
+      railSlides.current.get(el)?.cancel();
+      railSlides.current.set(
+        el,
+        el.animate(
+          { translate: [`${dx}px ${dy}px`, "none"] },
+          { duration: Number.isFinite(ms) ? ms : 200, easing: "ease-out" },
+        ),
+      );
     }
-    const frame = requestAnimationFrame(() => {
-      for (const { el } of moved) {
-        el.style.transition = "";
-        el.style.translate = "";
-      }
-    });
-    return () => cancelAnimationFrame(frame);
   });
 
   /** Move focus `delta` cards along, clamping at both ends rather than wrapping. */
@@ -961,14 +1071,42 @@ export default function Catalog({
             // catalog's keyword vocabulary is open-ended, and a few hundred
             // chips at once is a wall, not a control.
             //
-            // A `<details>` for the same reason the platform picker and the
-            // version menus are: it opens, closes and takes Escape on its
-            // own, with no popover library and no script.
-            <details class="kw-menu">
-              <summary class="chip" data-slot="filter-chip">
+            // A popover, and not by preference: the panel used to be an
+            // absolutely-positioned child of `.filter-row`, which is a scroll
+            // container, so it was cropped to the row and stretched the row's
+            // scroll extent — an invisible menu and two stray scrollbars. The
+            // top layer is outside every ancestor's `overflow`. Escape and
+            // light dismiss come with it; only the seat is ours to compute,
+            // and that is `placeKwMenu` above.
+            <div class="kw-menu">
+              <button
+                type="button"
+                class="chip"
+                data-slot="filter-chip"
+                ref={kwTriggerRef}
+                popovertarget={KEYWORD_MENU_ID}
+                aria-expanded={kwMenuOpen}
+              >
                 +{menuKeywords.length} more
-              </summary>
-              <div class="kw-menu-panel">
+              </button>
+              <div
+                class="kw-menu-panel"
+                id={KEYWORD_MENU_ID}
+                popover="auto"
+                ref={kwMenuRef}
+                // Both, and in this order: `beforetoggle` runs synchronously
+                // inside the show steps, so the panel is seated before it is
+                // ever painted; `toggle` runs after, when its width can
+                // actually be measured for the clamp.
+                onBeforeToggle={(e) => {
+                  setKwMenuOpen(e.newState === "open");
+                  placeKwMenu();
+                }}
+                onToggle={(e) => {
+                  setKwMenuOpen(e.newState === "open");
+                  placeKwMenu();
+                }}
+              >
                 <input
                   type="text"
                   class="kw-menu-search"
@@ -996,7 +1134,38 @@ export default function Catalog({
                   )}
                 </div>
               </div>
-            </details>
+            </div>
+          )}
+          {keywords.length > 0 && (
+            // Lifts every keyword at once. Only rendered while there is
+            // something to lift — a permanently visible control that does
+            // nothing most of the time is a chip's width spent on nothing, and
+            // this row is already the one that runs out of room first.
+            //
+            // Keywords only, deliberately. Escape clears the search and the
+            // kinds along with them, and a button that quietly did the same
+            // would undo a filter the reader did not ask about; the label
+            // names exactly what it lifts.
+            <button
+              type="button"
+              class="chip kw-clear"
+              data-slot="filter-chip"
+              title="Clear the keyword filters"
+              onKeyDown={onChipKeyDown}
+              onClick={(e) => {
+                setKeywords([]);
+                // This button is the last thing standing when it is pressed:
+                // clearing the facets unmounts it, and focus would land on
+                // `<body>`, sending a keyboard reader back to the top of the
+                // document. `detail === 0` is a click synthesized by Enter or
+                // Space, so a pointer user is left alone and a keyboard one
+                // gets the toolbar's own anchor instead of nothing.
+                if (e.detail === 0) searchRef.current?.focus();
+              }}
+            >
+              <X size={13} aria-hidden="true" />
+              clear {keywords.length}
+            </button>
           )}
           {hasDeprecated && (
             // A toggle, not a filter: `aria-pressed` rather than the `active`

package/dist/renderer/astro/components/CodeBlock.astro

@@ -0,0 +1,74 @@
+---
+// SPDX-License-Identifier: Apache-2.0
+// Copyright 2026 The Grimoire Authors
+
+// A highlighted code block wearing the site's own copy affordance, and
+// optionally a link out to VS Code.
+//
+// It exists for the same reason `CommandBar.astro` does: an index's own page
+// under `theme/pages/` should be able to draw what the rest of the site draws
+// rather than a `<pre>` that looks almost like it. A setup guide showing a
+// config snippet, a publish guide showing a workflow — both want this, and
+// neither wants to restate the Shiki theme pair or the copy markup.
+//
+//   ---
+//   import CodeBlock from "@grim/components/CodeBlock.astro";
+//   import { vscodeUrl } from "@grim/lib/catalog";
+//   import { data } from "@grim/lib/data";
+//   ---
+//   <CodeBlock code="grim add acme/code-review" name="add command"
+//              vscodeHref={vscodeUrl(data.config.vscodeExtension, "acme/code-review")}
+//              vscodeLabel="Open in VS Code" />
+//
+// The copy button itself is NOT rendered here. `Base.astro` injects one into
+// every code block on the page — it has to, because a block inside rendered
+// markdown has no markup to hang one on — and it fills the `.code-actions`
+// slot below when it finds it. One button, one clipboard path, one toast, and
+// no second copy of the markup to drift.
+import { Code } from "astro:components";
+import { mdiMicrosoftVisualStudioCode } from "@mdi/js";
+import { BrandMark } from "./BrandMark.tsx";
+import { SHIKI_THEMES } from "../lib/code";
+
+interface Props {
+  /** The snippet, verbatim. What the copy button copies. */
+  code: string;
+  /** Shiki language id. `sh` covers the commands this site mostly shows. */
+  lang?: string;
+  /** What the copy toast calls this, e.g. `"add command"`. */
+  name?: string;
+  /**
+   * Any URL for the trailing button — a `vscode://` deep link from
+   * `@grim/lib/catalog`'s builders, or one written by hand. Null or omitted
+   * draws no button, which is what an index with `vscodeExtension: null` gets
+   * from those builders.
+   */
+  vscodeHref?: string | null;
+  /** Accessible name for that button. */
+  vscodeLabel?: string;
+}
+
+const {
+  code,
+  lang = "sh",
+  name,
+  vscodeHref = null,
+  vscodeLabel = "Open in VS Code",
+} = Astro.props;
+---
+
+<div class="code-block" data-slot="code-block" data-copy-name={name}>
+  <Code code={code} lang={lang} themes={SHIKI_THEMES} />
+  {/* Present even when empty: it is where `Base.astro` puts the copy button,
+      and a block that renders one before the script runs would flash a second
+      one after it. */}
+  <span class="code-actions">
+    {
+      vscodeHref && (
+        <a class="code-vscode" href={vscodeHref} title={vscodeLabel} aria-label={vscodeLabel}>
+          <BrandMark path={mdiMicrosoftVisualStudioCode} size={15} />
+        </a>
+      )
+    }
+  </span>
+</div>

package/dist/renderer/astro/components/PackageCard.js

@@ -38,7 +38,7 @@ export function PackageCard({ pkg: p, vscodeExtension, activeKeywords, onToggleK
                             const thread = externalUrl(p.rating.url);
                             const vote = vscodeVoteUrl(vscodeExtension, p.ref);
                             return (_jsxs("span", { class: "rating-group", children: [thread ? (_jsxs("a", { class: "rating-count", href: thread, target: "_blank", rel: "noopener noreferrer", tabIndex: -1, title: `${votes} — open the thread to vote`, "aria-label": `${p.name}: ${votes}. Open the voting thread`, children: [_jsx(ArrowBigUp, { size: 13, "aria-hidden": "true" }), p.rating.up] })) : (_jsxs("span", { class: "rating-count", title: votes, children: [_jsx(ArrowBigUp, { size: 13, "aria-hidden": "true" }), p.rating.up] })), vote && (_jsx("a", { class: "rating-vote", href: vote, tabIndex: -1, title: "Upvote in VS Code", "aria-label": `Upvote ${p.name} in VS Code`, children: _jsx(BrandMark, { path: mdiMicrosoftVisualStudioCode, size: 12 }) }))] }));
-                        })(), _jsxs("p", { class: "namespace", children: [_jsx("span", { class: "kind", "data-slot": "package-kind", children: p.kind }), _jsx("span", { "aria-hidden": "true", children: " \u00B7 " }), p.namespace] })] }), p.keywords && p.keywords.length > 0 && (_jsx("div", { class: "keywords", "data-slot": "package-keywords", children: p.keywords.slice(0, 5).map((kw) => (_jsx("button", { type: "button", class: activeKeywords.includes(kw)
+                        })(), _jsxs("p", { class: "namespace", children: [_jsx("span", { class: "kind", "data-slot": "package-kind", children: p.kind }), _jsx("span", { "aria-hidden": "true", children: " \u00B7 " }), _jsx("span", { class: "address", title: p.namespace, children: p.namespace })] })] }), p.keywords && p.keywords.length > 0 && (_jsx("div", { class: "keywords", "data-slot": "package-keywords", children: p.keywords.slice(0, 5).map((kw) => (_jsx("button", { type: "button", class: activeKeywords.includes(kw)
                         ? "chip keyword active"
                         : "chip keyword", "aria-pressed": activeKeywords.includes(kw), tabIndex: -1, onClick: () => onToggleKeyword(kw), children: kw }, kw))) })), p.description && _jsx("p", { class: "description", children: p.description }), _jsxs("div", { class: "card-foot", children: [_jsxs("div", { class: "copy-group", children: [_jsx(CopyButton, { command: `grim add --global ${p.ref}`, variant: "global", name: `global add for ${p.name}` }), _jsx(CopyButton, { command: `grim add ${p.ref}`, name: `project add for ${p.name}` }), vscodeUrl(vscodeExtension, p.ref) && (_jsx("a", { class: "copy vscode", href: vscodeUrl(vscodeExtension, p.ref), title: "Open in VS Code", "aria-label": `Open ${p.name} in VS Code`, tabIndex: -1, children: _jsx(BrandMark, { path: mdiMicrosoftVisualStudioCode }) }))] }), (() => {
                         const at = lastUpdated(p);

package/dist/renderer/astro/components/PackageCard.tsx

@@ -175,7 +175,15 @@ export function PackageCard({
               {p.kind}
             </span>
             <span aria-hidden="true"> · </span>
-            {p.namespace}
+            {/* Its own element so the row can give the address the slack and
+                nothing else: the kind is one short word and keeps its width,
+                and what does not fit is dropped off the FRONT — a registry
+                host is the least distinguishing part of an address and the
+                repository is the most. `title` keeps the whole of it
+                reachable, since the ellipsis hides the head. */}
+            <span class="address" title={p.namespace}>
+              {p.namespace}
+            </span>
           </p>
         </div>
         {/* Under the head, above the description: what the package