@urbicon-ui/blocks 6.4.0 → 6.5.0

package/dist/components/Guide/Guide.svelte

@@ -32,7 +32,7 @@
 
   const guide = getGuideContext();
 
-  if (import.meta.env.DEV && !guide) {
+  if (import.meta.env?.DEV && !guide) {
     console.warn(
       '[Guide] <Guide> is used without a <GuideProvider> ancestor — the tour will not render.'
     );
@@ -217,7 +217,7 @@
   // clickable, and only an app-side controller.next() from outside the spotlight can advance.
   // Usually a step-definition mistake; mirrors the unresolved-target warning.
   $effect(() => {
-    if (!import.meta.env.DEV || !guide) return;
+    if (!import.meta.env?.DEV || !guide) return;
     if (step?.advance === 'action' && !step.interactive) {
       console.warn(
         `[Guide] tour "${guide.activeTour?.id}" step ${stepIndex}: advance:'action' without ` +

package/dist/components/Guide/GuideArticle.svelte

@@ -8,6 +8,7 @@
   let {
     id,
     title,
+    group,
     children,
     class: className = '',
     unstyled: unstyledProp = false,
@@ -21,9 +22,9 @@
 
   // Register with the parent panel's list view. Runs regardless of whether this
   // article is the active one, so every article shows up in the list. Cleans up
-  // on unmount and re-registers if id/title change.
+  // on unmount and re-registers if id/title/group change.
   $effect(() => {
-    return panel?.registerArticle(id, title);
+    return panel?.registerArticle(id, title, group);
   });
 
   const blocksConfig = getBlocksConfig();

package/dist/components/Guide/GuideBeacon.svelte

@@ -22,7 +22,7 @@
 
   const guide = getGuideContext();
 
-  if (import.meta.env.DEV && !guide) {
+  if (import.meta.env?.DEV && !guide) {
     console.warn(
       '[Guide] <GuideBeacon> is used without a <GuideProvider> ancestor — it will not render.'
     );

package/dist/components/Guide/GuideHint.svelte

@@ -37,7 +37,7 @@
 
   const guide = getGuideContext();
 
-  if (import.meta.env.DEV && !guide) {
+  if (import.meta.env?.DEV && !guide) {
     console.warn(
       '[Guide] <GuideHint> is used without a <GuideProvider> ancestor — it will not render.'
     );
@@ -75,7 +75,7 @@
   $effect(() => {
     if (trigger === 'manual') {
       if (open) dismissed = false;
-    } else if (import.meta.env.DEV && open) {
+    } else if (import.meta.env?.DEV && open) {
       console.warn('[Guide] <GuideHint open> is ignored unless trigger="manual".');
     }
   });
@@ -179,7 +179,7 @@
   // DEV resilience: a requested hint whose target can't be resolved is a silent
   // no-op otherwise — warn so a wrong `for` id is noticed (mirrors the engine).
   $effect(() => {
-    if (import.meta.env.DEV && guide && visible && !guide.resolveTarget(topicId)) {
+    if (import.meta.env?.DEV && guide && visible && !guide.resolveTarget(topicId)) {
       console.warn(
         `[Guide] <GuideHint for="${topicId}"> cannot anchor — no element with [data-guide="${topicId}"] (or registered target) found.`
       );

package/dist/components/Guide/GuideMarker.svelte

@@ -24,7 +24,7 @@
 
   const guide = getGuideContext();
 
-  if (import.meta.env.DEV && !guide) {
+  if (import.meta.env?.DEV && !guide) {
     console.warn(
       '[Guide] <GuideMarker> is used without a <GuideProvider> ancestor — it renders inert.'
     );

package/dist/components/Guide/GuideMention.svelte

@@ -18,7 +18,7 @@
 
   const guide = getGuideContext();
 
-  if (import.meta.env.DEV && !guide) {
+  if (import.meta.env?.DEV && !guide) {
     console.warn(
       '[Guide] <GuideMention> is used without a <GuideProvider> ancestor — it renders as plain text.'
     );
@@ -42,7 +42,7 @@
   const interactive = $derived(!!guide && effectiveDirection !== 'to-guide');
 
   $effect(() => {
-    if (import.meta.env.DEV && guide && effectiveDirection === 'to-guide') {
+    if (import.meta.env?.DEV && guide && effectiveDirection === 'to-guide') {
       console.warn(
         `[Guide] <GuideMention for="${topicId}"> points at a topic whose direction excludes Guide→UI ('to-guide') — it renders as plain text.`
       );

package/dist/components/Guide/GuidePanel.svelte

@@ -6,6 +6,7 @@
   import { getBlocksConfig, resolveSlotClasses } from '../../provider';
   import { getGuideContext } from './guide.context';
   import { setGuidePanelContext } from './guide-panel.context';
+  import { filterArticles, groupArticles, hasNamedGroups } from './guide-panel.articles';
   import { guidePanelVariants, type GuidePanelVariants } from './guide.variants';
   import type { GuidePanelProps } from './index';
 
@@ -16,6 +17,7 @@
     placement = 'right',
     size = 'md',
     title,
+    searchable = false,
     closeOnEscape = true,
     footer,
     children,
@@ -35,7 +37,7 @@
   // Re-registers if the id changes; releases it on unmount.
   $effect(() => guide?.registerPanel(panelId));
 
-  if (import.meta.env.DEV && !guide) {
+  if (import.meta.env?.DEV && !guide) {
     console.warn(
       '[Guide] <GuidePanel> is used without a <GuideProvider> ancestor — it will not render.'
     );
@@ -44,12 +46,16 @@
   // Article registry feeding the list view. GuideArticle children register here.
   // untrack mirrors GuideController.registerTarget: writes happen from a child's
   // $effect, so untracking guards the list derived against effect_update_depth_exceeded.
-  const articleMap = new SvelteMap<string, string>();
+  // SvelteMap preserves insertion order, so the index follows definition order.
+  const articleMap = new SvelteMap<string, { title: string; group?: string }>();
   setGuidePanelContext({
-    registerArticle(id, articleTitle) {
-      untrack(() => articleMap.set(id, articleTitle));
+    registerArticle(id, articleTitle, group) {
+      untrack(() => articleMap.set(id, { title: articleTitle, group }));
       return () => untrack(() => articleMap.delete(id));
-    }
+    },
+    // Tracked read (no untrack): a GuideRef's reactive resolvable re-runs as
+    // articles register/unregister.
+    hasArticle: (id) => articleMap.has(id)
   });
 
   const blocksConfig = getBlocksConfig();
@@ -62,11 +68,28 @@
 
   const open = $derived(guide?.panelOpen ?? false);
   const activeArticle = $derived(guide?.activeArticle ?? null);
-  const articles = $derived([...articleMap].map(([id, t]) => ({ id, title: t })));
+  const articles = $derived(
+    // Normalize a blank/whitespace `group` to `undefined` so it collapses into the
+    // ungrouped block instead of rendering an empty (padded) section header.
+    [...articleMap].map(([id, a]) => ({ id, title: a.title, group: a.group?.trim() || undefined }))
+  );
   const headerTitle = $derived(
-    (activeArticle ? articleMap.get(activeArticle) : undefined) ?? title ?? bt('guide.openHelp', {})
+    (activeArticle ? articleMap.get(activeArticle)?.title : undefined) ??
+      title ??
+      bt('guide.openHelp', {})
   );
 
+  // Optional title filter (#26). Grouping below runs on the filtered set, so a
+  // search narrows the index while keeping non-empty sections' headers.
+  let searchQuery = $state('');
+  const filteredArticles = $derived(searchable ? filterArticles(articles, searchQuery) : articles);
+  const isFiltering = $derived(searchable && searchQuery.trim().length > 0);
+
+  // Group the index into sections (first-occurrence order; ungrouped articles in
+  // one headerless block). When no article sets a group, this is a flat list.
+  const sections = $derived(groupArticles(filteredArticles));
+  const hasGroups = $derived(hasNamedGroups(sections));
+
   const panelTransform = $derived(
     open ? 'translateX(0)' : placement === 'left' ? 'translateX(-100%)' : 'translateX(100%)'
   );
@@ -88,7 +111,7 @@
   // shows an empty body with no signal. Deferred past the current flush via `tick()` so a
   // sibling <GuideArticle> registering in the same render isn't a false positive.
   $effect(() => {
-    if (!import.meta.env.DEV) return;
+    if (!import.meta.env?.DEV) return;
     const id = activeArticle;
     if (!id) return;
     let cancelled = false;
@@ -180,25 +203,79 @@
     </header>
 
     <div class={unstyled ? (slotClasses?.body ?? '') : styles.body({ class: slotClasses?.body })}>
+      {#snippet articleListItem(article: { id: string; title: string })}
+        <li>
+          <button
+            type="button"
+            class={unstyled
+              ? (slotClasses?.listItem ?? '')
+              : styles.listItem({ class: slotClasses?.listItem })}
+            onclick={() => guide?.setArticle(article.id)}
+          >
+            <span class="flex-1">{article.title}</span>
+            <ChevronRightIcon class="h-4 w-4 opacity-50" />
+          </button>
+        </li>
+      {/snippet}
       {#if !activeArticle}
-        <ul
-          class={unstyled ? (slotClasses?.list ?? '') : styles.list({ class: slotClasses?.list })}
-        >
-          {#each articles as article (article.id)}
-            <li>
-              <button
-                type="button"
+        {#if searchable}
+          <input
+            type="search"
+            class={unstyled
+              ? (slotClasses?.searchInput ?? '')
+              : styles.searchInput({ class: slotClasses?.searchInput })}
+            placeholder={bt('guide.filterPlaceholder', {})}
+            aria-label={bt('guide.filterPlaceholder', {})}
+            bind:value={searchQuery}
+          />
+          <!-- Persistent polite announcer: present in the a11y tree before the result
+               set empties, so a filter narrowing to zero is reliably announced (a region
+               inserted together with its text is dropped by some screen readers). The
+               visible empty-state below carries no role, to avoid a duplicate region. -->
+          <p aria-live="polite" class="sr-only">
+            {#if isFiltering && filteredArticles.length === 0}{bt('guide.noResults', {})}{/if}
+          </p>
+        {/if}
+        {#if isFiltering && filteredArticles.length === 0}
+          <p
+            class={unstyled
+              ? (slotClasses?.noResults ?? '')
+              : styles.noResults({ class: slotClasses?.noResults })}
+          >
+            {bt('guide.noResults', {})}
+          </p>
+        {:else if hasGroups}
+          {#each sections as section, i (section.group ?? '')}
+            {#if section.group}
+              <h3
+                id={`${panelId}-group-${i}`}
                 class={unstyled
-                  ? (slotClasses?.listItem ?? '')
-                  : styles.listItem({ class: slotClasses?.listItem })}
-                onclick={() => guide.setArticle(article.id)}
+                  ? (slotClasses?.groupHeader ?? '')
+                  : styles.groupHeader({ class: slotClasses?.groupHeader })}
               >
-                <span class="flex-1">{article.title}</span>
-                <ChevronRightIcon class="h-4 w-4 opacity-50" />
-              </button>
-            </li>
+                {section.group}
+              </h3>
+            {/if}
+            <ul
+              class={unstyled
+                ? (slotClasses?.list ?? '')
+                : styles.list({ class: slotClasses?.list })}
+              aria-labelledby={section.group ? `${panelId}-group-${i}` : undefined}
+            >
+              {#each section.articles as article (article.id)}
+                {@render articleListItem(article)}
+              {/each}
+            </ul>
           {/each}
-        </ul>
+        {:else}
+          <ul
+            class={unstyled ? (slotClasses?.list ?? '') : styles.list({ class: slotClasses?.list })}
+          >
+            {#each filteredArticles as article (article.id)}
+              {@render articleListItem(article)}
+            {/each}
+          </ul>
+        {/if}
       {/if}
       {@render children?.()}
     </div>

package/dist/components/Guide/GuideRef.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+  import { tick } from 'svelte';
+  import { getBlocksConfig, resolveSlotClasses } from '../../provider';
+  import { getGuideContext } from './guide.context';
+  import { getGuidePanelContext } from './guide-panel.context';
+  import { guideRefVariants, type GuideRefVariants } from './guide.variants';
+  import type { GuideRefProps } from './index';
+
+  let {
+    article,
+    children,
+    class: className = '',
+    unstyled: unstyledProp = false,
+    slotClasses: slotClassesProp = {},
+    preset,
+    ...restProps
+  }: GuideRefProps = $props();
+
+  const guide = getGuideContext();
+  const panel = getGuidePanelContext();
+
+  if (import.meta.env?.DEV && !guide) {
+    console.warn(
+      '[Guide] <GuideRef> is used without a <GuideProvider> ancestor — it renders as plain text.'
+    );
+  } else if (import.meta.env?.DEV && !panel) {
+    console.warn('[Guide] <GuideRef> is used outside a <GuidePanel> — it renders as plain text.');
+  }
+
+  const blocksConfig = getBlocksConfig();
+  const unstyled = $derived(unstyledProp || blocksConfig?.unstyled || false);
+  const variantProps: GuideRefVariants = $derived({});
+  const styles = $derived(guideRefVariants(variantProps));
+  const slotClasses = $derived(
+    resolveSlotClasses(blocksConfig, 'GuideRef', preset, variantProps, slotClassesProp)
+  );
+
+  // Interactive only when wired to a panel that actually registers the target
+  // article; otherwise (no provider, outside a panel, or an unknown id) it degrades
+  // to plain inline text — mirrors GuideMention's no-provider fallback. Articles
+  // register from a child `$effect`, so `hasArticle` is false during SSR *and* the
+  // first client render → both emit a `<span>` (no hydration mismatch); a known
+  // article reactively upgrades to a `<button>` once its registration effect runs.
+  const resolvable = $derived(!!panel?.hasArticle(article));
+  const interactive = $derived(!!guide && resolvable);
+
+  // DEV-only: warn for an article id that stays unresolved past this flush — deferred
+  // via `tick()` so a target `<GuideArticle>` registering in the same render isn't a
+  // false positive (mirrors GuidePanel's missing-active-article warning).
+  $effect(() => {
+    if (!import.meta.env?.DEV || !guide || !panel) return;
+    const target = article;
+    let cancelled = false;
+    tick().then(() => {
+      if (!cancelled && !panel.hasArticle(target)) {
+        console.warn(
+          `[Guide] <GuideRef article="${target}"> points at an article that is not registered — it renders as plain text.`
+        );
+      }
+    });
+    return () => {
+      cancelled = true;
+    };
+  });
+
+  function navigate() {
+    guide?.setArticle(article);
+  }
+</script>
+
+{#if interactive}
+  <button
+    type="button"
+    class={unstyled
+      ? [slotClasses?.ref, className].filter(Boolean).join(' ')
+      : styles.ref({ class: [slotClasses?.ref, className] })}
+    data-guide-ref
+    onclick={navigate}
+    {...restProps}
+  >
+    {@render children?.()}
+  </button>
+{:else}
+  <span class={[slotClasses?.ref, className].filter(Boolean).join(' ') || undefined} {...restProps}>
+    {@render children?.()}
+  </span>
+{/if}

package/dist/components/Guide/GuideRef.svelte.d.ts

@@ -0,0 +1,4 @@
+import type { GuideRefProps } from './index.js';
+declare const GuideRef: import("svelte").Component<GuideRefProps, {}, "">;
+type GuideRef = ReturnType<typeof GuideRef>;
+export default GuideRef;

package/dist/components/Guide/guide-panel.articles.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Pure transforms for the `GuidePanel` article index — grouping (#25) and
+ * filtering (#26). Kept framework-free so the index logic is unit-testable
+ * without rendering the panel (mirrors `pagination.engine` / `planner.bucket`).
+ */
+/** A registered article as surfaced to the panel index. */
+export interface IndexArticle {
+    id: string;
+    title: string;
+    /** Optional section label; `undefined` means the ungrouped block. */
+    group?: string;
+}
+/** One section of the grouped index. */
+export interface ArticleSection {
+    /** The section's group label, or `undefined` for the headerless ungrouped block. */
+    group: string | undefined;
+    articles: IndexArticle[];
+}
+/**
+ * Group articles into sections keyed by `group`, in first-occurrence order over
+ * the (insertion-ordered) input. Articles without a `group` collect into one
+ * headerless section, positioned where its first ungrouped article appears.
+ * When no article sets a `group`, the result is a single ungrouped section —
+ * i.e. a flat list.
+ */
+export declare function groupArticles(articles: IndexArticle[]): ArticleSection[];
+/** Whether any section carries a real group label (drives grouped vs. flat rendering). */
+export declare function hasNamedGroups(sections: ArticleSection[]): boolean;
+/**
+ * Filter articles by a case-insensitive substring match on the title. A blank
+ * query returns the input unchanged. Whitespace around the query is ignored.
+ */
+export declare function filterArticles(articles: IndexArticle[], query: string): IndexArticle[];

package/dist/components/Guide/guide-panel.articles.js

@@ -0,0 +1,39 @@
+/**
+ * Pure transforms for the `GuidePanel` article index — grouping (#25) and
+ * filtering (#26). Kept framework-free so the index logic is unit-testable
+ * without rendering the panel (mirrors `pagination.engine` / `planner.bucket`).
+ */
+/**
+ * Group articles into sections keyed by `group`, in first-occurrence order over
+ * the (insertion-ordered) input. Articles without a `group` collect into one
+ * headerless section, positioned where its first ungrouped article appears.
+ * When no article sets a `group`, the result is a single ungrouped section —
+ * i.e. a flat list.
+ */
+export function groupArticles(articles) {
+    const byGroup = new Map();
+    for (const article of articles) {
+        const key = article.group ?? '';
+        let section = byGroup.get(key);
+        if (!section) {
+            section = { group: article.group, articles: [] };
+            byGroup.set(key, section);
+        }
+        section.articles.push(article);
+    }
+    return [...byGroup.values()];
+}
+/** Whether any section carries a real group label (drives grouped vs. flat rendering). */
+export function hasNamedGroups(sections) {
+    return sections.some((s) => s.group !== undefined);
+}
+/**
+ * Filter articles by a case-insensitive substring match on the title. A blank
+ * query returns the input unchanged. Whitespace around the query is ignored.
+ */
+export function filterArticles(articles, query) {
+    const q = query.trim().toLowerCase();
+    if (!q)
+        return articles;
+    return articles.filter((a) => a.title.toLowerCase().includes(q));
+}

package/dist/components/Guide/guide-panel.context.d.ts

@@ -4,8 +4,17 @@
  * outside a `GuidePanel` simply renders inert.
  */
 export interface GuidePanelContext {
-    /** Register an article (by title) and return an unregister cleanup. */
-    registerArticle(id: string, title: string): () => void;
+    /**
+     * Register an article (by title, with an optional `group` for the index's
+     * section headers) and return an unregister cleanup.
+     */
+    registerArticle(id: string, title: string, group?: string): () => void;
+    /**
+     * Whether an article with this id is currently registered. Reactive — lets a
+     * `GuideRef` degrade to plain text for an unknown article. Reads the registry
+     * untracked-free so callers re-run when articles register/unregister.
+     */
+    hasArticle(id: string): boolean;
 }
 declare const getGuidePanelContext: () => GuidePanelContext | undefined, setGuidePanelContext: (value: GuidePanelContext | undefined) => GuidePanelContext | undefined;
 export { getGuidePanelContext, setGuidePanelContext };

package/dist/components/Guide/guide.variants.d.ts

@@ -68,6 +68,27 @@ export declare const guidePanelVariants: (props?: import("../../utils/variants.j
         class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
+    searchInput: (props?: ({
+        placement?: "right" | "left" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+    } & {
+        class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+        className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+    }) | undefined) => string;
+    noResults: (props?: ({
+        placement?: "right" | "left" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+    } & {
+        class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+        className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+    }) | undefined) => string;
+    groupHeader: (props?: ({
+        placement?: "right" | "left" | undefined;
+        size?: "sm" | "md" | "lg" | undefined;
+    } & {
+        class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+        className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+    }) | undefined) => string;
     list: (props?: ({
         placement?: "right" | "left" | undefined;
         size?: "sm" | "md" | "lg" | undefined;
@@ -140,6 +161,18 @@ export declare const guideMentionVariants: (props?: import("../../utils/variants
         className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
     }) | undefined) => string;
 };
+/**
+ * Styling for `GuideRef` — an inline article→article link inside article prose.
+ * Mirrors `GuideMention`'s link-like reset, but with a *solid* underline (vs the
+ * Mention's dotted one) that thickens on hover/focus, so a panel-internal jump
+ * reads distinctly from a Mention's UI highlight.
+ */
+export declare const guideRefVariants: (props?: import("../../utils/variants.js").TVProps<{}> | undefined) => {
+    ref: (props?: ({} & {
+        class?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+        className?: string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | (string | false | /*elided*/ any | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined)[] | null | undefined;
+    }) | undefined) => string;
+};
 /**
  * Styling for `GuideHint` — a small, non-blocking bubble anchored to a
  * `data-guide` element via `floating.ts`, rendered in the native popover
@@ -275,6 +308,7 @@ export type GuideBeaconVariants = VariantProps<typeof guideBeaconVariants>;
 export type GuideArticleVariants = VariantProps<typeof guideArticleVariants>;
 export type GuideMarkerVariants = VariantProps<typeof guideMarkerVariants>;
 export type GuideMentionVariants = VariantProps<typeof guideMentionVariants>;
+export type GuideRefVariants = VariantProps<typeof guideRefVariants>;
 export type GuideHintVariants = VariantProps<typeof guideHintVariants>;
 /** Slot names derived from each `tv()` config — single source of truth for `slotClasses`. */
 export type GuidePanelSlots = SlotNames<typeof guidePanelVariants>;
@@ -283,4 +317,5 @@ export type GuideBeaconSlots = SlotNames<typeof guideBeaconVariants>;
 export type GuideArticleSlots = SlotNames<typeof guideArticleVariants>;
 export type GuideMarkerSlots = SlotNames<typeof guideMarkerVariants>;
 export type GuideMentionSlots = SlotNames<typeof guideMentionVariants>;
+export type GuideRefSlots = SlotNames<typeof guideRefVariants>;
 export type GuideHintSlots = SlotNames<typeof guideHintVariants>;

package/dist/components/Guide/guide.variants.js

@@ -25,6 +25,19 @@ export const guidePanelVariants = tv({
             'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-2 focus-visible:ring-primary/50'
         ],
         body: ['flex-1 overflow-y-auto overscroll-contain px-5 py-4'],
+        // Filter input above the index (opt-in via GuidePanel `searchable`).
+        searchInput: [
+            'mb-3 w-full rounded-lg border border-border-hairline bg-surface-base px-3 py-2 text-sm',
+            'text-text-primary placeholder:text-text-tertiary',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-primary/50'
+        ],
+        // Empty-state shown when a search filters every article out.
+        noResults: ['px-3 py-6 text-center text-sm text-text-tertiary'],
+        // Section label above a group of articles in the index (opt-in via GuideArticle `group`).
+        groupHeader: [
+            'px-3 pb-1 pt-4 text-xs font-semibold uppercase tracking-wide text-text-tertiary',
+            'first:pt-1'
+        ],
         list: ['flex flex-col gap-1'],
         listItem: [
             'flex w-full items-center gap-2 rounded-lg px-3 py-2.5 text-left text-sm transition-colors',
@@ -107,6 +120,23 @@ export const guideMentionVariants = tv({
         ]
     }
 });
+/**
+ * Styling for `GuideRef` — an inline article→article link inside article prose.
+ * Mirrors `GuideMention`'s link-like reset, but with a *solid* underline (vs the
+ * Mention's dotted one) that thickens on hover/focus, so a panel-internal jump
+ * reads distinctly from a Mention's UI highlight.
+ */
+export const guideRefVariants = tv({
+    slots: {
+        ref: [
+            'm-0 inline cursor-pointer border-0 bg-transparent p-0 text-left font-medium text-primary',
+            'underline decoration-solid decoration-1 underline-offset-2',
+            'transition-[text-decoration-thickness] duration-[var(--blocks-duration-fast)]',
+            'hover:decoration-2 focus-visible:decoration-2',
+            'focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-offset-1 focus-visible:ring-primary/50 focus-visible:rounded-[0.2em]'
+        ]
+    }
+});
 /**
  * Styling for `GuideHint` — a small, non-blocking bubble anchored to a
  * `data-guide` element via `floating.ts`, rendered in the native popover

package/dist/components/Guide/index.d.ts

@@ -1,6 +1,6 @@
 import type { Snippet } from 'svelte';
 import type { GuideController, GuideDirection, GuideStorageAdapter, GuideTour, Placement } from '../../utils/index.js';
-import type { GuideArticleSlots, GuideBeaconSlots, GuideBeaconVariants, GuideHintSlots, GuideMarkerSlots, GuideMarkerVariants, GuideMentionSlots, GuidePanelSlots, GuidePanelVariants, GuideTourSlots } from './guide.variants.js';
+import type { GuideArticleSlots, GuideBeaconSlots, GuideBeaconVariants, GuideHintSlots, GuideMarkerSlots, GuideMarkerVariants, GuideMentionSlots, GuidePanelSlots, GuidePanelVariants, GuideRefSlots, GuideTourSlots } from './guide.variants.js';
 /**
  * @description Root provider for the Guide help system. Instantiates a `GuideController`
  * and shares it via context with all Guide surfaces (Panel, Marker, Mention, Hint, Tour).
@@ -74,6 +74,13 @@ export interface GuidePanelProps {
     size?: GuidePanelVariants['size'];
     /** Heading shown when no article is open. @default i18n `guide.openHelp` */
     title?: string;
+    /**
+     * Render a filter input above the article index that matches article titles
+     * (case-insensitive). Off by default. Pairs with article grouping — filtered
+     * results keep their section headers and empty sections disappear.
+     * @default false
+     */
+    searchable?: boolean;
     /** Close the panel when Escape is pressed. @default true */
     closeOnEscape?: boolean;
     /** Optional footer content. */
@@ -111,6 +118,14 @@ export interface GuideArticleProps {
     id: string;
     /** Title shown in the panel list and header. */
     title: string;
+    /**
+     * Optional section this article belongs to in the panel index. Articles that
+     * share a `group` are rendered under one section header (sections appear in
+     * the order their first article is defined); articles without a `group` stay
+     * in an ungrouped block. When no article sets a `group`, the index is a flat
+     * list — unchanged from today.
+     */
+    group?: string;
     /** Article body. */
     children?: Snippet;
     /** Additional classes on the article root. */
@@ -216,6 +231,41 @@ export interface GuideMentionProps {
     /** Apply a named preset registered via `<BlocksProvider presets={{ GuideMention: {...} }}>`. */
     preset?: string;
 }
+/**
+ * @description An inline article→article link inside a `GuideArticle` body — the
+ * help-internal analogue of `GuideMention` (which links out to a UI element). A real
+ * `<button>` that navigates the open `GuidePanel` to the target article via the
+ * controller (`setArticle`). Degrades to plain inline text without a `GuideProvider`,
+ * outside a `GuidePanel`, or for an unknown `article` id; keyboard/focus parity with
+ * `GuideMention`.
+ * @tag navigation
+ * @related GuideArticle
+ * @related GuidePanel
+ * @related GuideMention
+ * @stability beta
+ * @standalone
+ *
+ * @example
+ * ```svelte
+ * <GuideArticle id="cost-pot" title="Cost pot">
+ *   <p>The pot is split by the <GuideRef article="splitting">splitting method</GuideRef>.</p>
+ * </GuideArticle>
+ * ```
+ */
+export interface GuideRefProps {
+    /** Id of the `GuideArticle` to navigate to. Inert (plain text) for an unknown id. */
+    article: string;
+    /** The link text. */
+    children?: Snippet;
+    /** Additional classes on the ref. */
+    class?: string;
+    /** Strip all default styles. @default false */
+    unstyled?: boolean;
+    /** Per-slot class overrides. */
+    slotClasses?: Partial<Record<GuideRefSlots, string>>;
+    /** Apply a named preset registered via `<BlocksProvider presets={{ GuideRef: {...} }}>`. */
+    preset?: string;
+}
 /**
  * @description A contextual, non-blocking hint anchored to a `data-guide` element via
  * `floating.ts` (flip/shift/arrow), rendered in the native popover top-layer. Waits at the
@@ -409,4 +459,5 @@ export { default as GuideMarker } from './GuideMarker.svelte';
 export { default as GuideMention } from './GuideMention.svelte';
 export { default as GuidePanel } from './GuidePanel.svelte';
 export { default as GuideProvider } from './GuideProvider.svelte';
-export { type GuideArticleVariants, type GuideBeaconVariants, type GuideHintVariants, type GuideMarkerVariants, type GuideMentionVariants, type GuidePanelVariants, type GuideTourVariants, guideArticleVariants, guideBeaconVariants, guideHintVariants, guideMarkerVariants, guideMentionVariants, guidePanelVariants, guideTourVariants } from './guide.variants.js';
+export { default as GuideRef } from './GuideRef.svelte';
+export { type GuideArticleVariants, type GuideBeaconVariants, type GuideHintVariants, type GuideMarkerVariants, type GuideMentionVariants, type GuidePanelVariants, type GuideRefVariants, type GuideTourVariants, guideArticleVariants, guideBeaconVariants, guideHintVariants, guideMarkerVariants, guideMentionVariants, guidePanelVariants, guideRefVariants, guideTourVariants } from './guide.variants.js';

package/dist/components/Guide/index.js

@@ -6,7 +6,8 @@ export { default as GuideMarker } from './GuideMarker.svelte';
 export { default as GuideMention } from './GuideMention.svelte';
 export { default as GuidePanel } from './GuidePanel.svelte';
 export { default as GuideProvider } from './GuideProvider.svelte';
-export { guideArticleVariants, guideBeaconVariants, guideHintVariants, guideMarkerVariants, guideMentionVariants, guidePanelVariants, guideTourVariants } from './guide.variants.js';
+export { default as GuideRef } from './GuideRef.svelte';
+export { guideArticleVariants, guideBeaconVariants, guideHintVariants, guideMarkerVariants, guideMentionVariants, guidePanelVariants, guideRefVariants, guideTourVariants } from './guide.variants.js';
 // Note: getGuideContext/setGuideContext are intentionally NOT re-exported here.
 // They are an internal wiring seam — surfaces import them directly from
 // './guide.context' (mirrors Tab/Icon, which keep their context helpers private).

package/dist/i18n/index.d.ts

@@ -128,6 +128,8 @@ declare const blocksTranslations: {
             readonly dismiss: "Dismiss hint";
             readonly startTour: "Start the guided tour";
             readonly actionRequired: "Complete the highlighted action to continue";
+            readonly filterPlaceholder: "Filter topics…";
+            readonly noResults: "No matching topics";
         };
         readonly datepicker: {
             readonly placeholder: "Select a date...";
@@ -297,6 +299,8 @@ declare const blocksTranslations: {
             readonly dismiss: "Hinweis ausblenden";
             readonly startTour: "Geführte Tour starten";
             readonly actionRequired: "Führe die markierte Aktion aus, um fortzufahren";
+            readonly filterPlaceholder: "Themen filtern…";
+            readonly noResults: "Keine passenden Themen";
         };
         readonly datepicker: {
             readonly placeholder: "Datum wählen...";

package/dist/primitives/Badge/badge.variants.js

@@ -18,7 +18,10 @@ export const badgeVariants = tv({
             'transition-[color,background-color,border-color,box-shadow,opacity] duration-[var(--blocks-duration-fast)] ease-out'
             // Radius driven by `tier` axis below.
         ],
-        content: ['flex items-center gap-inherit'],
+        // `[gap:inherit]` (arbitrary property), NOT `gap-inherit` — Tailwind v4 emits
+        // no `gap-inherit` rule, so the icon↔label gap would collapse to 0. The
+        // arbitrary property inherits `base`'s per-size gap. (Codeberg #21)
+        content: ['flex items-center [gap:inherit]'],
         // tier: modify — small remove-control on a commit-tier badge.
         removeButton: [
             'ml-1 shrink-0 rounded-modify transition-colors text-current',

package/dist/primitives/Button/button.variants.js

@@ -10,7 +10,13 @@ export const buttonVariants = tv({
             'disabled:opacity-50 disabled:cursor-not-allowed disabled:pointer-events-none'
         ],
         content: [
-            'flex items-center gap-inherit transition-opacity duration-[var(--blocks-duration-fast)]'
+            // `[gap:inherit]` (arbitrary property), NOT `gap-inherit`: Tailwind v4 has
+            // no `gap-inherit` utility — the spacing-based `gap-*` scale has no
+            // `inherit` member (unlike `text-inherit`/`border-inherit`), so that class
+            // emits no rule and the icon↔label gap silently collapses to 0. The
+            // arbitrary property makes `content` inherit `base`'s per-size gap as
+            // intended. (Codeberg #21)
+            'flex items-center [gap:inherit] transition-opacity duration-[var(--blocks-duration-fast)]'
         ],
         spinner: [
             'flex items-center justify-center opacity-0 pointer-events-none transition-opacity duration-[var(--blocks-duration-fast)]'

package/dist/primitives/Combobox/Combobox.svelte

@@ -104,6 +104,25 @@
   // Focus never leaves the `<input>` while open — the active option is
   // surfaced via `aria-activedescendant`, not by moving DOM focus into
   // the listbox.
+  //
+  // The focus restore in `select`/`clear` must NOT re-open the listbox the way
+  // a user-initiated focus does. `inputEl.focus()` dispatches `focus`
+  // synchronously, so without this guard `handleFocus` would flip `open = true`
+  // again on the very next line — negating the `open = false` above and leaving
+  // the listbox open after every mouse-click selection/clear (Codeberg #19).
+  // The flag is raised immediately before `focus()` and lowered immediately
+  // after, so it masks only that one synchronous event; when `focus()` is a
+  // no-op (input already focused, e.g. an Enter-key selection) it fires no
+  // `focus` event and the flag is simply lowered again — never left dangling
+  // for the next genuine focus.
+  let suppressFocusOpen = false;
+
+  function focusInputWithoutOpening() {
+    suppressFocusOpen = true;
+    inputEl?.focus();
+    suppressFocusOpen = false;
+  }
+
   function select(opt: ComboboxOption<T>) {
     if (opt.disabled) return;
     value = opt.value;
@@ -111,7 +130,7 @@
     open = false;
     activeIndex = -1;
     onValueChange?.(opt.value);
-    inputEl?.focus();
+    focusInputWithoutOpening();
   }
 
   function clear() {
@@ -120,7 +139,7 @@
     open = false;
     activeIndex = -1;
     onValueChange?.(null);
-    inputEl?.focus();
+    focusInputWithoutOpening();
   }
 
   function handleInput() {
@@ -133,6 +152,7 @@
   }
 
   function handleFocus() {
+    if (suppressFocusOpen) return;
     if (!disabled) open = true;
   }
 

package/dist/primitives/Dialog/Dialog.svelte

@@ -42,7 +42,7 @@
   }: DialogProps = $props();
 
   if (
-    import.meta.env.DEV &&
+    import.meta.env?.DEV &&
     hideCloseButton &&
     closeOnEscape === false &&
     closeOnBackdropClick === false

package/dist/primitives/Drawer/Drawer.svelte

@@ -42,7 +42,7 @@
   }: DrawerProps = $props();
 
   if (
-    import.meta.env.DEV &&
+    import.meta.env?.DEV &&
     hideCloseButton &&
     closeOnEscape === false &&
     closeOnBackdropClick === false

package/dist/translations/de.d.ts

@@ -126,6 +126,8 @@ declare const _default: {
         readonly dismiss: "Hinweis ausblenden";
         readonly startTour: "Geführte Tour starten";
         readonly actionRequired: "Führe die markierte Aktion aus, um fortzufahren";
+        readonly filterPlaceholder: "Themen filtern…";
+        readonly noResults: "Keine passenden Themen";
     };
     readonly datepicker: {
         readonly placeholder: "Datum wählen...";

package/dist/translations/de.js

@@ -125,7 +125,9 @@ export default {
         infoAbout: 'Mehr Informationen zu {{label}}',
         dismiss: 'Hinweis ausblenden',
         startTour: 'Geführte Tour starten',
-        actionRequired: 'Führe die markierte Aktion aus, um fortzufahren'
+        actionRequired: 'Führe die markierte Aktion aus, um fortzufahren',
+        filterPlaceholder: 'Themen filtern…',
+        noResults: 'Keine passenden Themen'
     },
     datepicker: {
         placeholder: 'Datum wählen...',

package/dist/translations/en.d.ts

@@ -126,6 +126,8 @@ declare const _default: {
         readonly dismiss: "Dismiss hint";
         readonly startTour: "Start the guided tour";
         readonly actionRequired: "Complete the highlighted action to continue";
+        readonly filterPlaceholder: "Filter topics…";
+        readonly noResults: "No matching topics";
     };
     readonly datepicker: {
         readonly placeholder: "Select a date...";

package/dist/translations/en.js

@@ -125,7 +125,9 @@ export default {
         infoAbout: 'More information about {{label}}',
         dismiss: 'Dismiss hint',
         startTour: 'Start the guided tour',
-        actionRequired: 'Complete the highlighted action to continue'
+        actionRequired: 'Complete the highlighted action to continue',
+        filterPlaceholder: 'Filter topics…',
+        noResults: 'No matching topics'
     },
     datepicker: {
         placeholder: 'Select a date...',

package/dist/utils/guide.svelte.d.ts

@@ -109,7 +109,7 @@ export interface GuideControllerOptions {
     storage?: GuideStorageAdapter;
     /** Overlay stack to integrate with. @default the shared `overlayStack` singleton */
     overlayStack?: GuideOverlayStackLike;
-    /** Force DEV-mode warnings on/off. @default `import.meta.env.DEV` */
+    /** Force DEV-mode warnings on/off. @default `import.meta.env?.DEV ?? false` */
     dev?: boolean;
 }
 /**

package/dist/utils/guide.svelte.js

@@ -112,7 +112,10 @@ export class GuideController {
     constructor(options = {}) {
         this.#storage = options.storage ?? createLocalStorageAdapter();
         this.#overlayStack = options.overlayStack ?? overlayStack;
-        this.#dev = options.dev ?? import.meta.env.DEV;
+        // `import.meta.env?.DEV` is `boolean | undefined` (undefined outside Vite);
+        // `?? false` keeps `#dev` a strict boolean and means non-Vite consumers
+        // simply get no dev warnings (rather than a crash).
+        this.#dev = options.dev ?? import.meta.env?.DEV ?? false;
         this.#seen = new SvelteSet(this.#storage.load());
     }
     // ─── Target registry ──────────────────────────────────────────────────────

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@urbicon-ui/blocks",
-  "version": "6.4.0",
+  "version": "6.5.0",
   "description": "Svelte 5 UI component library with Tailwind CSS 4, OKLCH design tokens and zero runtime dependencies",
   "license": "MIT",
   "repository": {
@@ -91,8 +91,8 @@
     "@sveltejs/package": "^2.5.8",
     "@sveltejs/vite-plugin-svelte": "^7.0.0",
     "@tailwindcss/vite": "^4.3.1",
-    "@urbicon-ui/i18n": "6.4.0",
-    "@urbicon-ui/shared-types": "6.4.0",
+    "@urbicon-ui/i18n": "6.5.0",
+    "@urbicon-ui/shared-types": "6.5.0",
     "prettier": "^3.8.4",
     "prettier-plugin-svelte": "^4.1.1",
     "prettier-plugin-tailwindcss": "^0.8.0",