@mkbabb/glass-ui 0.2.0

package/src/components/custom/search/composables/fuzzySearchIndex.ts

@@ -0,0 +1,224 @@
+/**
+ * Generic fuzzy search index — builds a flat searchable index from items
+ * and scores queries with VSCode-style fuzzy matching.
+ * Pure functions, no Vue reactivity.
+ */
+import type { SearchableItem, SearchResult } from "./types";
+
+// ── Internal index entry ────────────────────────────────────
+
+interface IndexEntry<T extends SearchableItem> {
+    item: T;
+    /** Pre-lowercased fields, built once at index time. */
+    _lc: {
+        label: string;
+        text: string;
+        type: string;
+    };
+}
+
+/** Opaque index handle. */
+export type SearchIndex<T extends SearchableItem = SearchableItem> = IndexEntry<T>[];
+
+// ── Fuzzy matching (VSCode-style subsequence scorer) ─────────
+
+/**
+ * Scores a fuzzy subsequence match of `pattern` against `text`.
+ * Every character in `pattern` must appear in `text` in order.
+ * Returns null if no match, otherwise { score, matches }.
+ *
+ * Scoring bonuses:
+ *   +8  match at index 0 (start of string)
+ *   +7  match after a word separator (space, -, _, ., /, \, :)
+ *   +6  camelCase boundary (lowercase -> uppercase)
+ *   +5  consecutive characters in a run
+ *   +3  pattern index === text index (prefix alignment)
+ *   +1  base per-character match
+ *  -0.1 per excess character in text (prefer tighter matches)
+ */
+export function fuzzyMatch(
+    pattern: string,
+    text: string,
+): { score: number; matches: number[] } | null {
+    const pLen = pattern.length;
+    const tLen = text.length;
+    if (pLen === 0) return { score: 0, matches: [] };
+    if (pLen > tLen) return null;
+
+    const matches: number[] = [];
+    let pi = 0;
+    let score = 0;
+    let prevIdx = -2;
+
+    for (let ti = 0; ti < tLen && pi < pLen; ti++) {
+        if (pattern[pi] !== text[ti]) continue;
+
+        matches.push(ti);
+        let cs = 1;
+
+        if (prevIdx === ti - 1) cs += 5;
+
+        if (ti === 0) {
+            cs += 8;
+        } else {
+            const prev = text[ti - 1];
+            if (" -_./\\:()".includes(prev)) {
+                cs += 7;
+            } else if (
+                text[ti] >= "A" &&
+                text[ti] <= "Z" &&
+                prev >= "a" &&
+                prev <= "z"
+            ) {
+                cs += 6;
+            }
+        }
+
+        if (pi === ti) cs += 3;
+
+        score += cs;
+        prevIdx = ti;
+        pi++;
+    }
+
+    if (pi < pLen) return null;
+
+    score -= Math.max(0, (tLen - pLen) * 0.1);
+
+    return { score, matches };
+}
+
+// ── Multi-token fuzzy search ─────────────────────────────────
+
+interface TokenMatch {
+    score: number;
+    matches: number[];
+}
+
+/**
+ * Matches a query against a single text field. The query is split into
+ * whitespace tokens; every token must fuzzy-match independently (AND logic).
+ */
+function multiTokenFuzzy(
+    queryTokens: string[],
+    text: string,
+): TokenMatch | null {
+    if (!text) return null;
+    let total = 0;
+    const allMatches: number[] = [];
+
+    for (const token of queryTokens) {
+        const m = fuzzyMatch(token, text);
+        if (!m) return null;
+        total += m.score;
+        for (const idx of m.matches) allMatches.push(idx);
+    }
+
+    return { score: total, matches: allMatches };
+}
+
+/**
+ * Scores one query against one entry. Tries each field with different
+ * weights and returns the best composite score.
+ */
+function scoreEntry<T extends SearchableItem>(
+    tokens: string[],
+    entry: IndexEntry<T>,
+): { score: number; matches: number[] } | null {
+    let best = 0;
+    let bestMatches: number[] = [];
+
+    const fields: [string, number][] = [
+        [entry._lc.label, 12],
+        [entry._lc.type, 10],
+        [entry._lc.text, 3],
+    ];
+
+    for (const [text, weight] of fields) {
+        if (!text) continue;
+        const m = multiTokenFuzzy(tokens, text);
+        if (m && m.score * weight > best) {
+            best = m.score * weight;
+            bestMatches = text === entry._lc.label ? m.matches : [];
+        }
+    }
+
+    if (best <= 0) return null;
+    return { score: best, matches: bestMatches };
+}
+
+// ── Index construction ───────────────────────────────────────
+
+/** Build a search index from a list of items. */
+export function buildIndex<T extends SearchableItem>(items: T[]): SearchIndex<T> {
+    return items.map((item) => ({
+        item,
+        _lc: {
+            label: item.label.toLowerCase(),
+            text: item.text.toLowerCase(),
+            type: item.type?.toLowerCase() ?? "",
+        },
+    }));
+}
+
+// ── Search function ──────────────────────────────────────────
+
+/** Query result cache — cleared when prefix diverges. */
+let _cache: Map<string, SearchResult<any>[]> = new Map();
+
+/** Search the index for items matching `query`. */
+export function searchIndex<T extends SearchableItem>(
+    index: SearchIndex<T>,
+    query: string,
+    maxResults = 30,
+): SearchResult<T>[] {
+    const q = query.toLowerCase().trim();
+    if (!q) {
+        _cache.clear();
+        return [];
+    }
+
+    const cached = _cache.get(q);
+    if (cached) return cached;
+
+    if (_cache.size > 200) _cache.clear();
+
+    const tokens = q.split(/\s+/).filter(Boolean);
+    if (tokens.length === 0) return [];
+
+    // Narrow from prefix cache if available
+    let candidates: IndexEntry<T>[] = index;
+    if (q.length > 1) {
+        const prefix = q.slice(0, -1);
+        const prefixResults = _cache.get(prefix);
+        if (prefixResults) {
+            // Re-wrap previous results back into IndexEntry form
+            candidates = prefixResults.map((r: SearchResult<T>) => ({
+                item: r.item,
+                _lc: {
+                    label: r.item.label.toLowerCase(),
+                    text: r.item.text.toLowerCase(),
+                    type: r.item.type?.toLowerCase() ?? "",
+                },
+            }));
+        }
+    }
+
+    const scored: SearchResult<T>[] = [];
+    for (const entry of candidates) {
+        const m = scoreEntry(tokens, entry);
+        if (m) {
+            scored.push({ item: entry.item, score: m.score, matchIndices: m.matches });
+        }
+    }
+
+    scored.sort((a, b) => b.score - a.score);
+    const results = scored.slice(0, maxResults);
+    _cache.set(q, results);
+    return results;
+}
+
+/** Clear the search cache (call when index changes). */
+export function clearSearchCache(): void {
+    _cache.clear();
+}

package/src/components/custom/search/composables/index.ts

@@ -0,0 +1,5 @@
+export { useFuzzySearch } from "./useFuzzySearch";
+export type { UseFuzzySearchOptions } from "./useFuzzySearch";
+export { buildIndex, searchIndex, fuzzyMatch, clearSearchCache } from "./fuzzySearchIndex";
+export type { SearchIndex } from "./fuzzySearchIndex";
+export type { SearchableItem, SearchResult, FuzzySearchState } from "./types";

package/src/components/custom/search/composables/types.ts

@@ -0,0 +1,34 @@
+import type { Ref, ComputedRef } from "vue";
+
+/** A searchable item — the generic unit of the fuzzy search index. */
+export interface SearchableItem {
+    id: string;
+    /** Primary display label (title, heading, name). */
+    label: string;
+    /** Full-text content to search against. */
+    text: string;
+    /** Optional type tag for badge display (e.g. "section", "code"). */
+    type?: string;
+}
+
+/** A single fuzzy match result with score and highlight positions. */
+export interface SearchResult<T extends SearchableItem = SearchableItem> {
+    item: T;
+    score: number;
+    /** Character positions in `item.label` that matched the query. */
+    matchIndices: number[];
+}
+
+/** Reactive state returned by `useFuzzySearch`. */
+export interface FuzzySearchState<T extends SearchableItem = SearchableItem> {
+    query: Ref<string>;
+    results: ComputedRef<SearchResult<T>[]>;
+    selectedIndex: Ref<number>;
+    isOpen: Ref<boolean>;
+    isExpanded: Ref<boolean>;
+    onKeydown(e: KeyboardEvent): void;
+    selectResult(result: SearchResult<T>): void;
+    toggleExpanded(): void;
+    close(): void;
+    open(): void;
+}

package/src/components/custom/search/composables/useFuzzySearch.ts

@@ -0,0 +1,115 @@
+/**
+ * Vue composable for fuzzy search — manages reactive state, debouncing,
+ * keyboard navigation, modal expand, and result selection.
+ */
+import { ref, watch, computed } from "vue";
+import type { SearchableItem, SearchResult, FuzzySearchState } from "./types";
+import { buildIndex, searchIndex, clearSearchCache } from "./fuzzySearchIndex";
+
+export interface UseFuzzySearchOptions<T extends SearchableItem = SearchableItem> {
+    /** Reactive or static list of searchable items. */
+    items: T[] | (() => T[]);
+    /** Debounce delay in ms (default: 120). */
+    debounceMs?: number;
+    /** Maximum results to return (default: 30). */
+    maxResults?: number;
+    /** Callback when a result is selected (Enter or click). */
+    onSelect?: (result: SearchResult<T>) => void;
+}
+
+export function useFuzzySearch<T extends SearchableItem = SearchableItem>(
+    options: UseFuzzySearchOptions<T>,
+): FuzzySearchState<T> {
+    const getItems = typeof options.items === "function" ? options.items : () => options.items as T[];
+    const debounceMs = options.debounceMs ?? 120;
+    const maxResults = options.maxResults ?? 30;
+
+    const query = ref("");
+    const isOpen = ref(false);
+    const isExpanded = ref(false);
+    const selectedIndex = ref(0);
+    const debouncedQuery = ref("");
+
+    // Inline debounce
+    let debounceTimer: ReturnType<typeof setTimeout> | undefined;
+    watch(query, (val) => {
+        clearTimeout(debounceTimer);
+        debounceTimer = setTimeout(() => {
+            debouncedQuery.value = val;
+        }, debounceMs);
+    });
+
+    const results = computed(() => {
+        const index = buildIndex(getItems());
+        return searchIndex<T>(index, debouncedQuery.value, maxResults);
+    });
+
+    watch(results, () => {
+        selectedIndex.value = 0;
+    });
+
+    function selectResult(r: SearchResult<T>) {
+        options.onSelect?.(r);
+        close();
+    }
+
+    function close() {
+        isOpen.value = false;
+        isExpanded.value = false;
+        query.value = "";
+        selectedIndex.value = 0;
+        clearSearchCache();
+    }
+
+    function open() {
+        isOpen.value = true;
+    }
+
+    function toggleExpanded() {
+        isExpanded.value = !isExpanded.value;
+    }
+
+    function onKeydown(e: KeyboardEvent) {
+        switch (e.key) {
+            case "ArrowDown":
+                e.preventDefault();
+                if (selectedIndex.value < results.value.length - 1) {
+                    selectedIndex.value++;
+                }
+                break;
+            case "ArrowUp":
+                e.preventDefault();
+                if (selectedIndex.value > 0) {
+                    selectedIndex.value--;
+                }
+                break;
+            case "Enter":
+                e.preventDefault();
+                if (results.value[selectedIndex.value]) {
+                    selectResult(results.value[selectedIndex.value]);
+                }
+                break;
+            case "Escape":
+                e.preventDefault();
+                if (isExpanded.value) {
+                    isExpanded.value = false;
+                } else {
+                    close();
+                }
+                break;
+        }
+    }
+
+    return {
+        query,
+        results,
+        isOpen,
+        isExpanded,
+        selectedIndex,
+        selectResult,
+        close,
+        open,
+        toggleExpanded,
+        onKeydown,
+    } as FuzzySearchState<T>;
+}

package/src/components/custom/search/index.ts

@@ -0,0 +1,7 @@
+export { default as FuzzySearch } from "./FuzzySearch.vue";
+export { default as SearchBar } from "./SearchBar.vue";
+export { useFuzzySearch } from "./composables/useFuzzySearch";
+export type { UseFuzzySearchOptions } from "./composables/useFuzzySearch";
+export { buildIndex, searchIndex, fuzzyMatch, clearSearchCache } from "./composables/fuzzySearchIndex";
+export type { SearchIndex } from "./composables/fuzzySearchIndex";
+export type { SearchableItem, SearchResult, FuzzySearchState } from "./composables/types";

package/src/components/custom/sidebar/ProgressiveSidebar.vue

@@ -0,0 +1,256 @@
+<script setup lang="ts">
+import { ref } from "vue";
+import { ChevronUp } from "lucide-vue-next";
+import type { SidebarState, SidebarSection } from "./types";
+
+const props = withDefaults(
+    defineProps<{
+        state: SidebarState;
+        mode?: "sticky" | "drawer";
+        renderTitle?: (title: string) => string;
+    }>(),
+    {
+        mode: "sticky",
+        renderTitle: (title: string) => title,
+    },
+);
+
+defineSlots<{
+    search?: () => any;
+}>();
+
+const sidebarNav = ref<HTMLElement | null>(null);
+defineExpose({ sidebarNav });
+</script>
+
+<template>
+    <aside class="progressive-sidebar" :class="`progressive-sidebar--${mode}`">
+        <nav ref="sidebarNav" class="sidebar-nav scrollbar-thin">
+            <slot name="search" />
+            <div class="sidebar-header">
+                <p class="sidebar-label">Contents</p>
+                <button
+                    class="sidebar-top-btn"
+                    @click="state.scrollToTop()"
+                    title="Scroll to top"
+                >
+                    <ChevronUp class="h-3 w-3" />
+                </button>
+            </div>
+            <ol class="sidebar-list">
+                <li v-for="(section, si) in state.sections" :key="section.id">
+                    <button
+                        :data-toc-id="section.id"
+                        @click="state.toggleSection(section.id)"
+                        class="sidebar-link"
+                        :class="{ 'is-active': state.activeRootId.value === section.id }"
+                    >
+                        <span v-html="renderTitle(section.title)" />
+                    </button>
+                    <!-- Subsections (animated expand) -->
+                    <div
+                        v-if="section.children"
+                        class="sidebar-sublist-wrapper"
+                        :class="{ 'is-expanded': state.isExpanded(section.id) }"
+                    >
+                        <ol class="sidebar-sublist">
+                            <li v-for="sub in section.children" :key="sub.id">
+                                <button
+                                    :data-toc-id="sub.id"
+                                    @click="state.navigateTo(sub.id)"
+                                    class="sidebar-link sidebar-sublink"
+                                    :class="{ 'is-active-sub': state.isActive(sub.id) || state.isInActiveChain(sub.id) }"
+                                >
+                                    <span v-html="renderTitle(sub.title)" />
+                                </button>
+                                <!-- Sub-subsections -->
+                                <ol
+                                    v-if="sub.children && state.isInActiveChain(sub.id)"
+                                    class="sidebar-subsublist"
+                                >
+                                    <li v-for="subsub in sub.children" :key="subsub.id">
+                                        <button
+                                            :data-toc-id="subsub.id"
+                                            @click="state.navigateTo(subsub.id)"
+                                            class="sidebar-link sidebar-subsublink"
+                                            :class="{ 'is-active-sub': state.isActive(subsub.id) }"
+                                        >
+                                            <span v-html="renderTitle(subsub.title)" />
+                                        </button>
+                                    </li>
+                                </ol>
+                            </li>
+                        </ol>
+                    </div>
+                </li>
+            </ol>
+        </nav>
+    </aside>
+</template>
+
+<style scoped>
+.progressive-sidebar {
+    --sidebar-top-inset: 1rem;
+    --sidebar-bottom-inset: 1.5rem;
+}
+
+.progressive-sidebar--sticky {
+    display: none;
+}
+
+@media (min-width: 1024px) {
+    .progressive-sidebar--sticky {
+        display: block;
+        position: sticky;
+        top: var(--sidebar-top-inset);
+        align-self: start;
+        min-height: 0;
+        max-height: calc(100dvh - var(--sidebar-top-inset) - var(--sidebar-bottom-inset));
+    }
+}
+
+.sidebar-nav {
+    overflow-y: auto;
+    overscroll-behavior: contain;
+    border-radius: var(--radius-xl);
+    background: var(--card);
+    max-height: calc(100dvh - var(--sidebar-top-inset) - var(--sidebar-bottom-inset));
+    scrollbar-gutter: stable;
+    scroll-padding-bottom: var(--sidebar-bottom-inset);
+    touch-action: pan-y;
+    padding: 0.625rem 0.625rem var(--sidebar-bottom-inset);
+    border: 2px solid color-mix(in srgb, var(--foreground) 15%, transparent);
+}
+
+.sidebar-header {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    margin-bottom: 0.5rem;
+    padding: 0 0.625rem;
+}
+
+.sidebar-label {
+    font-size: var(--type-small);
+    font-weight: 700;
+    text-transform: uppercase;
+    margin: 0;
+    letter-spacing: 0.08em;
+    color: color-mix(in srgb, var(--muted-foreground) 60%, transparent);
+}
+
+.sidebar-top-btn {
+    flex-shrink: 0;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    cursor: pointer;
+    width: 1.25rem;
+    height: 1.25rem;
+    border-radius: var(--radius-sm);
+    border: 1px solid color-mix(in srgb, var(--border) 40%, transparent);
+    background: none;
+    color: color-mix(in srgb, var(--muted-foreground) 45%, transparent);
+    transition: all var(--duration-fast) var(--ease-standard);
+}
+
+.sidebar-top-btn:hover {
+    color: var(--foreground);
+    border-color: var(--border);
+    background: color-mix(in srgb, var(--muted) 50%, transparent);
+}
+
+.sidebar-list {
+    list-style: none;
+    padding: 0;
+    margin: 0;
+    display: flex;
+    flex-direction: column;
+    gap: 1px;
+}
+
+.sidebar-link {
+    display: block;
+    width: 100%;
+    text-align: left;
+    background: none;
+    border: none;
+    cursor: pointer;
+    font-weight: 500;
+    font-size: 1rem;
+    line-height: 1.35;
+    padding: 0.28rem 0.625rem;
+    border-radius: var(--radius-md);
+    color: var(--muted-foreground);
+    transition:
+        color var(--duration-normal) var(--ease-out-expo),
+        background-color var(--duration-normal) var(--ease-out-expo),
+        font-weight var(--duration-fast) var(--ease-standard);
+}
+
+.sidebar-link:hover {
+    color: var(--foreground);
+    background: color-mix(in srgb, var(--muted) 50%, transparent);
+}
+
+.sidebar-link.is-active {
+    background: none;
+    font-weight: 600;
+    color: var(--primary);
+}
+
+.sidebar-link.is-active-sub {
+    font-weight: 600;
+    background: color-mix(in srgb, var(--muted) 40%, transparent);
+    color: var(--primary);
+}
+
+/* Animated subsection expand/collapse */
+.sidebar-sublist-wrapper {
+    display: grid;
+    opacity: 0;
+    grid-template-rows: 0fr;
+    transition:
+        grid-template-rows 0.4s var(--ease-out-expo),
+        opacity 0.3s var(--ease-out-expo);
+}
+
+.sidebar-sublist-wrapper.is-expanded {
+    opacity: 1;
+    grid-template-rows: 1fr;
+}
+
+.sidebar-sublist-wrapper > .sidebar-sublist {
+    overflow: hidden;
+}
+
+.sidebar-sublist {
+    list-style: none;
+    padding: 0 0 0 0.625rem;
+    margin: 0.0625rem 0 0.125rem;
+}
+
+.sidebar-sublink {
+    font-size: 0.78rem;
+    padding: 0.2rem 0.45rem;
+}
+
+.sidebar-subsublist {
+    list-style: none;
+    padding: 0 0 0 0.5rem;
+    margin: 0.03125rem 0 0.0625rem;
+}
+
+.sidebar-subsublink {
+    font-size: 0.72rem;
+    padding: 0.15rem 0.32rem;
+}
+
+/* Drawer mode */
+.progressive-sidebar--drawer .sidebar-nav {
+    max-height: 100%;
+    border: none;
+    border-radius: 0;
+    background: transparent;
+}
+</style>

package/src/components/custom/sidebar/composables/index.ts

@@ -0,0 +1,6 @@
+export { useScrollTracker } from "./useScrollTracker";
+export { useSidebarFollow } from "./useSidebarFollow";
+export type { SidebarFollowOptions } from "./useSidebarFollow";
+export { useSidebarState } from "./useSidebarState";
+export type { UseSidebarStateOptions } from "./useSidebarState";
+export { useTreeIndex, buildTreeIndex, isActive, isInActiveChain } from "./useTreeIndex";