@hachej/boring-data-explorer 0.1.13

package/README.md

@@ -0,0 +1,272 @@
+# @hachej/boring-data-explorer
+
+<div align="center">
+
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+</div>
+
+Searchable, faceted data tables for the workbench. The headless primitive that `data-catalog` and other explorer-style plugins build on top of.
+
+```bash
+git clone https://github.com/hachej/boring-ui.git && cd boring-ui && pnpm install
+```
+
+> **Note:** This plugin is workspace-private (`"private": true`) — install from source within the monorepo.
+
+---
+
+## TL;DR
+
+**The Problem**: You have data — customers, invoices, logs, metrics — and you want users to search, filter, and explore it inside an agent app. But building faceted tables with virtualization, paging, and selection from scratch is tedious.
+
+**The Solution**: `@hachej/boring-data-explorer` provides a controlled `<DataExplorer>` component + `useExplorerState` hook + an `ExplorerDataSource` adapter contract. You implement `search(args)` (and optionally `fetchFacets(args)`) against any backend. The component handles the rest.
+
+### Why Use @hachej/boring-data-explorer?
+
+| Feature | What It Does |
+|---------|--------------|
+| **`<DataExplorer>` component** | Search box, faceted filters, virtualized rows, row selection, drag-and-drop payload |
+| **`useExplorerState` hook** | Manages query, facets, paging, and selection state |
+| **Adapter contract** | `search(args)` + optional `fetchFacets(args)` — implement once, plug any backend (SQL, REST, in-memory, gRPC) |
+| **Agent-driven** | Rows expose a `DragPayload`; the agent can open any row via surface resolver |
+| **Headless + styled** | Use the hook alone for custom UI, or mount the full component out of the box |
+
+---
+
+## Quick Example
+
+```tsx
+import { DataExplorer, useExplorerState } from "@hachej/boring-data-explorer/front"
+import type { ExplorerDataSource, SearchArgs, SearchResult } from "@hachej/boring-data-explorer/shared"
+
+// 1. Implement the adapter against your backend
+const customersSource: ExplorerDataSource = {
+  async search({ query, filters, limit, offset, signal }): Promise<SearchResult> {
+    const res = await fetch(`/api/customers?q=${query}&limit=${limit}&offset=${offset}`, { signal })
+    const { items, total } = await res.json()
+    return { items, total, hasMore: offset + items.length < total }
+  },
+}
+
+// 2. Mount the explorer
+export function CustomersPane() {
+  const state = useExplorerState({ source: customersSource, pageSize: 50 })
+  return <DataExplorer state={state} />
+}
+```
+
+The result is a sortable, filterable table — users can search, filter by facets, select rows, and drag rows into other panels.
+
+---
+
+## Adapter Contract
+
+```ts
+// Explorer item shape rendered by the DataExplorer
+export type ExplorerItem = {
+  id: string
+  title: string
+  subtitle?: string          // muted second line (truncates with title)
+  group?: string             // group key — matches a facet value for grouping
+  leading?: Badge            // leading mono chip (e.g. type code)
+  trailing?: Badge[]         // trailing chips for status flags
+  meta?: string              // right-aligned plain text (e.g. "1.2M")
+}
+
+export type Badge = {
+  code: string               // 1-4 char mono code rendered as a chip
+  tooltip?: string
+}
+
+// Search arguments from the explorer to your adapter
+export type SearchArgs = {
+  query: string
+  filters: Record<string, string[]>   // active facet filters
+  group?: { key: string; value: string }  // scope to single group (paging inside a group)
+  limit: number
+  offset: number
+  signal?: AbortSignal
+}
+
+// Search result your adapter returns
+export type SearchResult = {
+  items: ExplorerItem[]
+  total: number               // total count for the current scope (query + filters + optional group)
+  hasMore: boolean            // whether there are more pages
+}
+
+// Facets — optional. When omitted, the explorer renders flat (no facet popover)
+export type Facets = Record<string, FacetValue[]>
+export type FacetValue = { value: string; count: number }
+
+export type FacetsArgs = {
+  filters: Record<string, string[]>
+  signal?: AbortSignal
+}
+
+// The adapter contract
+export interface ExplorerDataSource {
+  search(args: SearchArgs): Promise<SearchResult>
+  fetchFacets?(args: FacetsArgs): Promise<Facets>   // optional
+}
+```
+
+Implement against **any backend**. The component doesn't care whether data comes from SQL, REST, Elasticsearch, or a JSON file.
+
+### Static Data Adapter
+
+```tsx
+import type { ExplorerDataSource, ExplorerItem } from "@hachej/boring-data-explorer/shared"
+
+const entries: ExplorerItem[] = [
+  { id: "customers", title: "Customers", subtitle: "Customer records", leading: { code: "tbl" } },
+  { id: "invoices", title: "Invoices", subtitle: "Invoice records", leading: { code: "tbl" }, group: "finance" },
+]
+
+const adapter: ExplorerDataSource = {
+  async search({ query, limit, offset }) {
+    const normalized = query.trim().toLowerCase()
+    const matched = normalized
+      ? entries.filter((entry) => `${entry.title} ${entry.subtitle ?? ""}`.toLowerCase().includes(normalized))
+      : entries
+    const items = matched.slice(offset, offset + limit)
+    return { items, total: matched.length, hasMore: offset + items.length < matched.length }
+  },
+}
+```
+
+---
+
+## Installation
+
+```bash
+# From source (workspace-only — not published to npm)
+cd boring-ui/plugins/data-explorer && pnpm install && pnpm build
+```
+
+---
+
+## Package Surfaces
+
+| Import | Environment | What You Get |
+|--------|-------------|--------------|
+| `@hachej/boring-data-explorer` | Browser | `<DataExplorer>`, `useExplorerState`, all types re-exported |
+| `@hachej/boring-data-explorer/front` | Browser | Same as top-level (explicit subpath) |
+| `@hachej/boring-data-explorer/shared` | Any | `ExplorerDataSource`, `ExplorerItem`, `Facets`, `SearchArgs`, `DragPayload`, `Badge` — no React deps |
+| `@hachej/boring-data-explorer/testing` | Browser | Test utilities and mock data sources |
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────┐
+│     <DataExplorer>         │
+│  ┌───┬─────┬─────────────┐ │
+│  │ 🔍 │ Facets │ Results │ │
+│  └───┴─────┴─────────────┘ │
+│  ┌───┐ ┌───────────────┐  │
+│  │ ← │ │ 1..25 of 430  │  │
+│  └───┘ └───────────────┘  │
+└──────────────┬─────────────┘
+               │ source.search(args)
+               │ source.fetchFacets?(args)
+┌──────────────▼─────────────┐
+│    ExplorerDataSource      │
+│  (your adapter impl)       │
+│                            │
+│  search({ query, filters,  │
+│          limit, offset })  │
+│                            │
+│  fetchFacets?({ filters }) │
+└──────────────┬─────────────┘
+               │
+┌──────────────▼─────────────┐
+│   Any Backend              │
+│   PostgreSQL · REST API    │
+│   Elasticsearch · In-memory│
+│   gRPC · whatever          │
+└────────────────────────────┘
+```
+
+---
+
+## How @hachej/boring-data-explorer Compares
+
+| Feature | @hachej/boring-data-explorer | AG Grid | TanStack Table | Build your own |
+|---------|------------------------------|---------|----------------|----------------|
+| Built-in search + facets | ✅ One hook | ⚠️ Filter only | ❌ DIY | ❌ |
+| Backend adapter contract | ✅ `search` + `fetchFacets` | ❌ In-memory | ⚠️ Sorting/filtering | ❌ |
+| Drag-and-drop payload | ✅ `DragPayload` type | ⚠️ Add-on | ❌ | ❌ |
+| Agent integration | ✅ Surface resolver | ❌ | ❌ | ❌ |
+| Virtualized rows | ✅ | ✅ | ⚠️ Manual | ❌ |
+| Complexity | ✅ ~10 lines to mount | ❌ Heavy API | ⚠️ Complex API | ❌ Weeks |
+
+**When to use @hachej/boring-data-explorer:**
+- You want a fast, searchable table with facet filters in a boring-ui workbench
+- You're building a data catalog plugin for an agent app
+- You need drag-and-drop from table rows to other panels
+
+**When it might not fit:**
+- You need enterprise-grade data grids (use AG Grid or TanStack Table)
+- You need editable cells, pivot tables, or group-by aggregations
+- You're building outside of a boring-ui workspace (you'd need the layout shell)
+
+---
+
+## Troubleshooting
+
+| Error | Cause | Fix |
+|-------|-------|-----|
+| No rows showing | `search()` returned empty items | Check your backend query — log the response |
+| Facets empty | `fetchFacets()` not implemented | Add the optional `fetchFacets` method to your adapter |
+| Infinite loading loop | `useExplorerState` deps changing every render | Memoize your `source` object or move it outside the component |
+| Drag not working | Row has no `DragPayload` | Pass `getDragPayload` prop to `<DataExplorer>` |
+| Wrong source selected | Adapter returns the wrong item ids or payload | Check your adapter's `search()` mapping |
+
+---
+
+## Limitations
+
+- **Workspace-private** — `"private": true` in package.json. Not published to npm. Install from source within the monorepo.
+- **Not an enterprise data grid** — No cell editing, pivot tables, or group-by. It's a search-and-filter primitive, not AG Grid.
+- **No built-in data fetching** — You implement `search()` and optionally `fetchFacets()`. The adapter doesn't cache or debounce.
+- **Requires boring-ui workspace chrome** — The component assumes it's mounted inside a workspace panel layout. Standalone use is possible but you lose the drag-to-panel behavior.
+- **No column customization UI** — Column shape is derived from `ExplorerItem` (title / subtitle / leading / trailing / meta) — no arbitrary column projection.
+
+---
+
+## FAQ
+
+**Q: What's the difference between `data-explorer` and `data-catalog`?**  
+A: `data-explorer` is the primitive — a single table you mount wherever. `data-catalog` is a higher-level plugin: it puts a sidebar tab listing data sources, and clicking a source opens the explorer table.
+
+**Q: Can I use this without the boring-ui workspace?**  
+A: Yes. `<DataExplorer>` and `useExplorerState` are standalone React exports. You'll just lose the drag-to-panel integration since there's no workbench to receive the payload.
+
+**Q: How do I customize the table columns?**  
+A: Columns are derived from `ExplorerItem` fields: `title` (primary), `subtitle` (secondary), `leading` (mono chip), `trailing` (status badges), `meta` (right-aligned text). There is no per-column projection API.
+
+**Q: Does it support server-side pagination?**  
+A: Yes — `search()` receives `limit` and `offset`. Your backend can return a slice. `total` and `hasMore` drive the pager.
+
+**Q: Can I use this for non-tabular data?**  
+A: Yes — map any data shape (GraphQL results, CSV rows, API responses) to `ExplorerItem[]`. The adapter is backend-agnostic.
+
+---
+
+## Used by
+
+- **[`@hachej/boring-data-catalog`](../data-catalog/README.md)** — configurable catalog tab listing multiple data sources
+- Any plugin that needs a faceted, searchable table inside a workbench panel
+
+---
+
+*About Contributions:* Please don't take this the wrong way, but I do not accept outside contributions for any of my projects. I simply don't have the mental bandwidth to review anything, and it's my name on the thing, so I'm responsible for any problems it causes; thus, the risk-reward is highly asymmetric from my perspective. I'd also have to worry about other "stakeholders," which seems unwise for tools I mostly make for myself for free. Feel free to submit issues, and even PRs if you want to illustrate a proposed fix, but know I won't merge them directly. Instead, I'll have Claude or Codex review submissions via `gh` and independently decide whether and how to address them. Bug reports in particular are welcome. Sorry if this offends, but I want to avoid wasted time and hurt feelings. I understand this isn't in sync with the prevailing open-source ethos that seeks community contributions, but it's the only way I can move at this velocity and keep my sanity.
+
+---
+
+## License
+
+MIT

package/dist/front/index.d.ts

@@ -0,0 +1,79 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+import { ExplorerDataSource, FacetConfig, ExplorerItem, DragPayload, Facets } from '../shared/index.js';
+export { Badge, FacetValue, FacetsArgs, SearchArgs, SearchResult } from '../shared/index.js';
+
+type DataExplorerProps = {
+    adapter: ExplorerDataSource;
+    /** Facets shown in the toolbar popover. Adapter must implement fetchFacets for this to work. */
+    facets?: FacetConfig[];
+    /** Single grouping axis (must match a facet key). When set, renders tree mode. */
+    groupBy?: string;
+    /** Activated when a row is clicked, double-clicked, or Enter-pressed. */
+    onActivate?: (row: ExplorerItem) => void;
+    /** Returning a payload makes rows draggable. */
+    getDragPayload?: (row: ExplorerItem) => DragPayload | null | undefined;
+    /** Empty state shown when the top-level result has no rows and no query/filters. */
+    emptyState?: ReactNode;
+    searchPlaceholder?: string;
+    /** Hide the search input. Default true. */
+    searchable?: boolean;
+    /**
+     * Controlled query. When set, the toolbar's search input is hidden and the
+     * caller is responsible for supplying (and debouncing) the query value.
+     * Useful when an outer chrome already owns a search box.
+     */
+    query?: string;
+    /** Called when the toolbar search changes. Use with `query` for controlled per-tab search. */
+    onQueryChange?: (query: string) => void;
+    /** Page size and debounce — passed through to useExplorerState. */
+    pageSize?: number;
+    debounceMs?: number;
+    className?: string;
+};
+declare function DataExplorer({ adapter, facets: facetConfigs, groupBy, onActivate, getDragPayload, emptyState, searchPlaceholder, searchable, query, onQueryChange, pageSize, debounceMs, className, }: DataExplorerProps): react_jsx_runtime.JSX.Element;
+
+type UseExplorerStateOptions = {
+    adapter: ExplorerDataSource;
+    /** Facets shown in the toolbar popover. Adapter must implement fetchFacets. */
+    facets?: FacetConfig[];
+    /** Facet key used as the single grouping axis (tree mode). */
+    groupBy?: string;
+    /** Page size for both top-level and per-group pagination. */
+    pageSize?: number;
+    /** Debounce window (ms) applied to setQuery. */
+    debounceMs?: number;
+    /**
+     * Controlled query. When set, the hook bypasses internal debounce and
+     * `setQuery` becomes a no-op — the caller owns the value (and any debounce
+     * the caller wants to apply). Searches re-run when this prop changes.
+     */
+    query?: string;
+};
+type GroupState = {
+    items: ExplorerItem[];
+    total: number;
+    hasMore: boolean;
+    loading: boolean;
+};
+declare function useExplorerState(options: UseExplorerStateOptions): {
+    query: string;
+    filters: Record<string, string[]>;
+    facets: Facets | null;
+    topItems: ExplorerItem[];
+    topTotal: number;
+    topHasMore: boolean;
+    loading: boolean;
+    getGroup: (value: string) => GroupState;
+    isExpanded: (value: string) => boolean;
+    setQuery: (q: string) => void;
+    toggleFilter: (key: string, value: string) => void;
+    clearFilters: () => void;
+    expandGroup: (value: string) => void;
+    collapseGroup: (value: string) => void;
+    loadMoreTop: () => void;
+    loadMoreGroup: (value: string) => void;
+};
+type UseExplorerStateReturn = ReturnType<typeof useExplorerState>;
+
+export { DataExplorer, type DataExplorerProps, DragPayload, ExplorerDataSource, ExplorerItem, FacetConfig, Facets, type UseExplorerStateOptions, type UseExplorerStateReturn, useExplorerState };

package/dist/front/index.js

@@ -0,0 +1,696 @@
+// src/front/DataExplorer.tsx
+import { useMemo } from "react";
+import { ChevronRightIcon, ChevronDownIcon, FilterIcon, SearchIcon, XIcon } from "lucide-react";
+
+// src/front/utils.ts
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+
+// src/front/DataExplorer.tsx
+import { Button, Chip as UiChip, ChipButton, EmptyState, Input, Spinner, Toolbar as UiToolbar } from "@hachej/boring-ui-kit";
+import { Popover, PopoverTrigger, PopoverContent } from "@hachej/boring-ui-kit";
+
+// src/front/useExplorerState.ts
+import { useCallback, useEffect, useReducer, useRef } from "react";
+var EMPTY_GROUP = { items: [], total: 0, hasMore: false, loading: false };
+function reducer(state, action) {
+  switch (action.type) {
+    case "setPendingQuery":
+      return { ...state, pendingQuery: action.query };
+    case "applyQuery":
+      return {
+        ...state,
+        query: action.query,
+        pendingQuery: action.query,
+        topItems: [],
+        topTotal: 0,
+        topHasMore: false,
+        topOffset: 0,
+        expanded: {},
+        groups: {}
+      };
+    case "setFilters":
+      return {
+        ...state,
+        filters: action.filters,
+        topItems: [],
+        topTotal: 0,
+        topHasMore: false,
+        topOffset: 0,
+        expanded: {},
+        groups: {}
+      };
+    case "expandGroup":
+      return { ...state, expanded: { ...state.expanded, [action.value]: true } };
+    case "collapseGroup":
+      return { ...state, expanded: { ...state.expanded, [action.value]: false } };
+    case "topResolved":
+      return {
+        ...state,
+        topItems: action.append ? [...state.topItems, ...action.items] : action.items,
+        topTotal: action.total,
+        topHasMore: action.hasMore,
+        topOffset: action.offset + action.items.length
+      };
+    case "groupResolved": {
+      const prev = state.groups[action.value] ?? EMPTY_GROUP;
+      return {
+        ...state,
+        groups: {
+          ...state.groups,
+          [action.value]: {
+            items: action.append ? [...prev.items, ...action.items] : action.items,
+            total: action.total,
+            hasMore: action.hasMore,
+            loading: false
+          }
+        }
+      };
+    }
+    case "groupLoading": {
+      const prev = state.groups[action.value] ?? EMPTY_GROUP;
+      return {
+        ...state,
+        groups: { ...state.groups, [action.value]: { ...prev, loading: action.loading } }
+      };
+    }
+    case "facetsResolved":
+      return { ...state, facets: action.facets };
+    case "loading":
+      return { ...state, loading: action.loading };
+  }
+}
+var INITIAL = {
+  query: "",
+  pendingQuery: "",
+  filters: {},
+  topItems: [],
+  topTotal: 0,
+  topHasMore: false,
+  topOffset: 0,
+  expanded: {},
+  groups: {},
+  facets: null,
+  loading: false
+};
+function isAbortError(err) {
+  return err instanceof DOMException && err.name === "AbortError";
+}
+function useExplorerState(options) {
+  const {
+    adapter,
+    facets: facetConfigs,
+    groupBy,
+    pageSize = 50,
+    debounceMs = 200,
+    query: controlledQuery
+  } = options;
+  const isControlled = controlledQuery !== void 0;
+  const [state, dispatch] = useReducer(reducer, INITIAL);
+  const stateRef = useRef(state);
+  stateRef.current = state;
+  const adapterRef = useRef(adapter);
+  adapterRef.current = adapter;
+  const optsRef = useRef({ pageSize, groupBy, hasFacets: !!facetConfigs?.length });
+  optsRef.current = { pageSize, groupBy, hasFacets: !!facetConfigs?.length };
+  const topController = useRef(null);
+  const groupControllers = useRef(/* @__PURE__ */ new Map());
+  const facetController = useRef(null);
+  const debounceTimer = useRef(null);
+  const mounted = useRef(true);
+  const runTopSearch = useCallback(
+    async (args) => {
+      topController.current?.abort();
+      const ctrl = new AbortController();
+      topController.current = ctrl;
+      dispatch({ type: "loading", loading: true });
+      const searchArgs = {
+        query: args.query,
+        filters: args.filters,
+        offset: args.offset,
+        limit: optsRef.current.pageSize,
+        signal: ctrl.signal
+      };
+      try {
+        const result = await adapterRef.current.search(searchArgs);
+        if (!mounted.current || ctrl.signal.aborted) return;
+        dispatch({
+          type: "topResolved",
+          items: result.items,
+          total: result.total,
+          hasMore: result.hasMore,
+          offset: args.offset,
+          append: args.append
+        });
+      } catch (err) {
+        if (isAbortError(err)) return;
+        console.error("DataExplorer: search failed", err);
+      } finally {
+        if (mounted.current && topController.current === ctrl) {
+          dispatch({ type: "loading", loading: false });
+        }
+      }
+    },
+    []
+  );
+  const runGroupSearch = useCallback(
+    async (args) => {
+      const groupKey = optsRef.current.groupBy;
+      if (!groupKey) return;
+      groupControllers.current.get(args.groupValue)?.abort();
+      const ctrl = new AbortController();
+      groupControllers.current.set(args.groupValue, ctrl);
+      dispatch({ type: "groupLoading", value: args.groupValue, loading: true });
+      const searchArgs = {
+        query: args.query,
+        filters: args.filters,
+        group: { key: groupKey, value: args.groupValue },
+        offset: args.offset,
+        limit: optsRef.current.pageSize,
+        signal: ctrl.signal
+      };
+      try {
+        const result = await adapterRef.current.search(searchArgs);
+        if (!mounted.current || ctrl.signal.aborted) return;
+        dispatch({
+          type: "groupResolved",
+          value: args.groupValue,
+          items: result.items,
+          total: result.total,
+          hasMore: result.hasMore,
+          append: args.append
+        });
+      } catch (err) {
+        if (isAbortError(err)) return;
+        console.error("DataExplorer: group search failed", err);
+        if (mounted.current) {
+          dispatch({ type: "groupLoading", value: args.groupValue, loading: false });
+        }
+      }
+    },
+    []
+  );
+  const runFetchFacets = useCallback(async (filters) => {
+    if (!optsRef.current.hasFacets) return;
+    const fetchFacets = adapterRef.current.fetchFacets;
+    if (!fetchFacets) return;
+    facetController.current?.abort();
+    const ctrl = new AbortController();
+    facetController.current = ctrl;
+    try {
+      const facets = await fetchFacets({ filters, signal: ctrl.signal });
+      if (!mounted.current || ctrl.signal.aborted) return;
+      dispatch({ type: "facetsResolved", facets });
+    } catch (err) {
+      if (isAbortError(err)) return;
+      console.error("DataExplorer: fetchFacets failed", err);
+    }
+  }, []);
+  const refreshScope = useCallback(
+    (query, filters) => {
+      void runTopSearch({ query, filters, offset: 0, append: false });
+      void runFetchFacets(filters);
+    },
+    [runTopSearch, runFetchFacets]
+  );
+  const isControlledRef = useRef(isControlled);
+  isControlledRef.current = isControlled;
+  const setQuery = useCallback(
+    (q) => {
+      if (isControlledRef.current) return;
+      dispatch({ type: "setPendingQuery", query: q });
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+      debounceTimer.current = setTimeout(() => {
+        dispatch({ type: "applyQuery", query: q });
+        refreshScope(q, stateRef.current.filters);
+      }, debounceMs);
+    },
+    [debounceMs, refreshScope]
+  );
+  const toggleFilter = useCallback(
+    (key, value) => {
+      const current = stateRef.current.filters[key] ?? [];
+      const next = current.includes(value) ? current.filter((v) => v !== value) : [...current, value];
+      const nextFilters = { ...stateRef.current.filters };
+      if (next.length) nextFilters[key] = next;
+      else delete nextFilters[key];
+      dispatch({ type: "setFilters", filters: nextFilters });
+      refreshScope(stateRef.current.query, nextFilters);
+    },
+    [refreshScope]
+  );
+  const clearFilters = useCallback(() => {
+    dispatch({ type: "setFilters", filters: {} });
+    refreshScope(stateRef.current.query, {});
+  }, [refreshScope]);
+  const expandGroup = useCallback(
+    (value) => {
+      const isLoaded = (stateRef.current.groups[value]?.items.length ?? 0) > 0;
+      dispatch({ type: "expandGroup", value });
+      if (!isLoaded) {
+        void runGroupSearch({
+          groupValue: value,
+          query: stateRef.current.query,
+          filters: stateRef.current.filters,
+          offset: 0,
+          append: false
+        });
+      }
+    },
+    [runGroupSearch]
+  );
+  const collapseGroup = useCallback((value) => {
+    dispatch({ type: "collapseGroup", value });
+  }, []);
+  const loadMoreTop = useCallback(() => {
+    const s = stateRef.current;
+    if (!s.topHasMore) return;
+    void runTopSearch({
+      query: s.query,
+      filters: s.filters,
+      offset: s.topOffset,
+      append: true
+    });
+  }, [runTopSearch]);
+  const loadMoreGroup = useCallback(
+    (value) => {
+      const s = stateRef.current;
+      const g = s.groups[value];
+      if (!g?.hasMore) return;
+      void runGroupSearch({
+        groupValue: value,
+        query: s.query,
+        filters: s.filters,
+        offset: g.items.length,
+        append: true
+      });
+    },
+    [runGroupSearch]
+  );
+  useEffect(() => {
+    mounted.current = true;
+    const initialQuery = isControlledRef.current ? controlledQuery ?? "" : "";
+    if (initialQuery) {
+      dispatch({ type: "applyQuery", query: initialQuery });
+    }
+    refreshScope(initialQuery, {});
+    return () => {
+      mounted.current = false;
+      if (debounceTimer.current) clearTimeout(debounceTimer.current);
+      topController.current?.abort();
+      facetController.current?.abort();
+      for (const ctrl of groupControllers.current.values()) ctrl.abort();
+      groupControllers.current.clear();
+    };
+  }, []);
+  const lastControlledQuery = useRef(controlledQuery);
+  useEffect(() => {
+    if (!isControlled) return;
+    if (lastControlledQuery.current === controlledQuery) return;
+    lastControlledQuery.current = controlledQuery;
+    const next = controlledQuery ?? "";
+    dispatch({ type: "applyQuery", query: next });
+    refreshScope(next, stateRef.current.filters);
+  }, [isControlled, controlledQuery, refreshScope]);
+  const getGroup = useCallback(
+    (value) => state.groups[value] ?? EMPTY_GROUP,
+    [state.groups]
+  );
+  const isExpanded = useCallback(
+    (value) => !!state.expanded[value],
+    [state.expanded]
+  );
+  return {
+    query: state.pendingQuery,
+    filters: state.filters,
+    facets: state.facets,
+    topItems: state.topItems,
+    topTotal: state.topTotal,
+    topHasMore: state.topHasMore,
+    loading: state.loading,
+    getGroup,
+    isExpanded,
+    setQuery,
+    toggleFilter,
+    clearFilters,
+    expandGroup,
+    collapseGroup,
+    loadMoreTop,
+    loadMoreGroup
+  };
+}
+
+// src/front/DataExplorer.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+function DataExplorer({
+  adapter,
+  facets: facetConfigs,
+  groupBy,
+  onActivate,
+  getDragPayload,
+  emptyState = "No results",
+  searchPlaceholder = "Search\u2026",
+  searchable = true,
+  query,
+  onQueryChange,
+  pageSize,
+  debounceMs,
+  className
+}) {
+  const state = useExplorerState({
+    adapter,
+    facets: facetConfigs,
+    groupBy,
+    pageSize,
+    debounceMs,
+    query
+  });
+  const isControlled = query !== void 0;
+  const showSearch = searchable && (!isControlled || !!onQueryChange);
+  const setToolbarQuery = isControlled && onQueryChange ? onQueryChange : state.setQuery;
+  const hasQuery = (query ?? state.query ?? "").length > 0;
+  const hasFilters = Object.values(state.filters).some((v) => v.length > 0);
+  const treeMode = !!groupBy && !hasQuery && !hasFilters;
+  const filterCount = Object.values(state.filters).reduce((n, v) => n + v.length, 0);
+  const groupEntries = useMemo(() => {
+    if (!treeMode || !groupBy) return [];
+    const config = facetConfigs?.find((f) => f.key === groupBy);
+    const values = state.facets?.[groupBy] ?? [];
+    const ordered = [...values];
+    if (config?.order?.length) {
+      const orderIdx = (v) => {
+        const i = config.order.indexOf(v);
+        return i === -1 ? Number.MAX_SAFE_INTEGER : i;
+      };
+      ordered.sort((a, b) => orderIdx(a.value) - orderIdx(b.value));
+    }
+    return ordered.map((v) => ({
+      value: v.value,
+      count: v.count,
+      label: config?.formatValue ? config.formatValue(v.value) : v.value
+    }));
+  }, [treeMode, groupBy, facetConfigs, state.facets]);
+  const showEmpty = !state.loading && !treeMode && state.topItems.length === 0 && state.query.length === 0 && !hasFilters;
+  return /* @__PURE__ */ jsxs("div", { className: cn("flex h-full flex-col", className), "data-slot": "data-explorer", children: [
+    showSearch || facetConfigs?.length ? /* @__PURE__ */ jsx(
+      Toolbar,
+      {
+        searchable: showSearch,
+        searchPlaceholder,
+        query: state.query,
+        onQueryChange: setToolbarQuery,
+        facetConfigs,
+        facets: state.facets,
+        filters: state.filters,
+        filterCount,
+        onToggleFilter: state.toggleFilter,
+        onClearFilters: state.clearFilters,
+        total: treeMode ? null : state.topTotal
+      }
+    ) : null,
+    /* @__PURE__ */ jsx("div", { className: "flex-1 overflow-y-auto", "data-slot": "data-explorer-list", children: showEmpty ? /* @__PURE__ */ jsx("div", { className: "flex h-full items-center justify-center px-4 py-8", children: /* @__PURE__ */ jsx(EmptyState, { className: "min-h-0 border-0", description: emptyState }) }) : treeMode ? /* @__PURE__ */ jsx(
+      TreeList,
+      {
+        entries: groupEntries,
+        isExpanded: state.isExpanded,
+        getGroup: state.getGroup,
+        onExpand: state.expandGroup,
+        onCollapse: state.collapseGroup,
+        onLoadMoreGroup: state.loadMoreGroup,
+        onActivate,
+        getDragPayload
+      }
+    ) : /* @__PURE__ */ jsx(
+      FlatList,
+      {
+        items: state.topItems,
+        hasMore: state.topHasMore,
+        loading: state.loading,
+        onLoadMore: state.loadMoreTop,
+        onActivate,
+        getDragPayload
+      }
+    ) })
+  ] });
+}
+function Toolbar({
+  searchable,
+  searchPlaceholder,
+  query,
+  onQueryChange,
+  facetConfigs,
+  facets,
+  filters,
+  filterCount,
+  onToggleFilter,
+  onClearFilters,
+  total
+}) {
+  return /* @__PURE__ */ jsxs(UiToolbar, { className: "border-b border-border/60 px-2 py-1.5", children: [
+    total != null ? /* @__PURE__ */ jsx("span", { className: "px-1 font-mono text-[10.5px] uppercase tracking-[0.05em] text-muted-foreground/80", children: total.toLocaleString() }) : null,
+    /* @__PURE__ */ jsx("div", { className: "flex-1" }),
+    searchable ? /* @__PURE__ */ jsxs(Popover, { children: [
+      /* @__PURE__ */ jsxs(
+        PopoverTrigger,
+        {
+          "aria-label": "Search",
+          className: cn(
+            "inline-flex h-7 items-center gap-1 rounded-sm px-1.5 text-[11px] text-muted-foreground transition-colors hover:bg-muted/60 hover:text-foreground",
+            query.length > 0 && "bg-muted text-foreground"
+          ),
+          children: [
+            /* @__PURE__ */ jsx(SearchIcon, { size: 12 }),
+            query.length > 0 ? /* @__PURE__ */ jsx("span", { className: "max-w-20 truncate text-[11px]", children: query }) : null
+          ]
+        }
+      ),
+      /* @__PURE__ */ jsxs(PopoverContent, { side: "right", align: "start", sideOffset: 8, className: "w-64 p-3", children: [
+        /* @__PURE__ */ jsx(
+          Input,
+          {
+            "aria-label": "Search",
+            autoFocus: true,
+            placeholder: searchPlaceholder,
+            value: query,
+            onChange: (e) => onQueryChange(e.target.value),
+            className: "h-8 rounded-sm text-[12.5px]"
+          }
+        ),
+        query.length > 0 ? /* @__PURE__ */ jsxs(Button, { type: "button", variant: "ghost", size: "xs", onClick: () => onQueryChange(""), className: "mt-2 gap-1 text-[11px] text-muted-foreground hover:text-foreground", children: [
+          /* @__PURE__ */ jsx(XIcon, { size: 11 }),
+          " Clear search"
+        ] }) : null
+      ] })
+    ] }) : null,
+    facetConfigs?.length ? /* @__PURE__ */ jsxs(Popover, { children: [
+      /* @__PURE__ */ jsxs(
+        PopoverTrigger,
+        {
+          "aria-label": "Filters",
+          className: cn(
+            "inline-flex h-7 items-center gap-1 rounded-sm px-1.5 text-[11px] text-muted-foreground transition-colors hover:bg-muted/60 hover:text-foreground",
+            filterCount > 0 && "bg-muted text-foreground"
+          ),
+          children: [
+            /* @__PURE__ */ jsx(FilterIcon, { size: 12 }),
+            filterCount > 0 ? /* @__PURE__ */ jsx("span", { className: "font-mono text-[10px]", children: filterCount }) : null
+          ]
+        }
+      ),
+      /* @__PURE__ */ jsxs(
+        PopoverContent,
+        {
+          side: "right",
+          align: "start",
+          sideOffset: 8,
+          className: "w-64 space-y-3 p-3 text-[12px]",
+          children: [
+            facetConfigs.map((config) => /* @__PURE__ */ jsx(
+              FacetSection,
+              {
+                config,
+                values: facets?.[config.key] ?? [],
+                selected: filters[config.key] ?? [],
+                onToggle: onToggleFilter
+              },
+              config.key
+            )),
+            filterCount > 0 ? /* @__PURE__ */ jsxs(Button, { type: "button", variant: "ghost", size: "xs", onClick: onClearFilters, className: "gap-1 text-[11px] text-muted-foreground hover:text-foreground", children: [
+              /* @__PURE__ */ jsx(XIcon, { size: 11 }),
+              " Clear all"
+            ] }) : null
+          ]
+        }
+      )
+    ] }) : null
+  ] });
+}
+function FacetSection({
+  config,
+  values,
+  selected,
+  onToggle
+}) {
+  if (!values.length) return null;
+  const ordered = config.order ? [...values].sort((a, b) => {
+    const ia = config.order.indexOf(a.value);
+    const ib = config.order.indexOf(b.value);
+    return (ia === -1 ? 999 : ia) - (ib === -1 ? 999 : ib);
+  }) : values;
+  return /* @__PURE__ */ jsxs("div", { className: "space-y-1.5", children: [
+    /* @__PURE__ */ jsx("div", { className: "font-mono text-[10px] uppercase tracking-[0.06em] text-muted-foreground", children: config.label }),
+    /* @__PURE__ */ jsx("div", { className: "flex flex-wrap gap-1", children: ordered.map((v) => {
+      const active = selected.includes(v.value);
+      const label = config.formatValue ? config.formatValue(v.value) : v.value;
+      return /* @__PURE__ */ jsxs(
+        ChipButton,
+        {
+          type: "button",
+          selected: active,
+          onClick: () => onToggle(config.key, v.value),
+          className: "gap-1 rounded-sm text-[11px]",
+          children: [
+            label,
+            /* @__PURE__ */ jsx("span", { className: "font-mono text-[10px] text-muted-foreground/80", children: v.count.toLocaleString() })
+          ]
+        },
+        v.value
+      );
+    }) })
+  ] });
+}
+function FlatList({
+  items,
+  hasMore,
+  loading,
+  onLoadMore,
+  onActivate,
+  getDragPayload
+}) {
+  return /* @__PURE__ */ jsxs("ul", { className: "flex flex-col px-1 py-1", children: [
+    items.map((row) => /* @__PURE__ */ jsx(
+      Row,
+      {
+        row,
+        onActivate,
+        getDragPayload
+      },
+      row.id
+    )),
+    hasMore ? /* @__PURE__ */ jsx("li", { className: "px-3 py-2", children: /* @__PURE__ */ jsx(Button, { type: "button", variant: "ghost", size: "xs", onClick: onLoadMore, disabled: loading, className: "w-full justify-start text-[11px] text-muted-foreground hover:text-foreground", children: loading ? "Loading\u2026" : "Load more" }) }) : null
+  ] });
+}
+function TreeList({
+  entries,
+  isExpanded,
+  getGroup,
+  onExpand,
+  onCollapse,
+  onLoadMoreGroup,
+  onActivate,
+  getDragPayload
+}) {
+  return /* @__PURE__ */ jsx("ul", { className: "flex flex-col py-1", children: entries.map((entry) => {
+    const expanded = isExpanded(entry.value);
+    const group = getGroup(entry.value);
+    return /* @__PURE__ */ jsxs("li", { children: [
+      /* @__PURE__ */ jsxs(
+        Button,
+        {
+          type: "button",
+          variant: "ghost",
+          size: "sm",
+          "aria-expanded": expanded,
+          onClick: () => expanded ? onCollapse(entry.value) : onExpand(entry.value),
+          className: "group mx-1 h-auto w-[calc(100%-0.5rem)] justify-start gap-1.5 px-1.5 py-1 text-left hover:bg-muted/40",
+          children: [
+            expanded ? /* @__PURE__ */ jsx(ChevronDownIcon, { size: 11, className: "text-muted-foreground/80" }) : /* @__PURE__ */ jsx(ChevronRightIcon, { size: 11, className: "text-muted-foreground/80" }),
+            /* @__PURE__ */ jsx("span", { className: "text-[12.5px] font-medium text-foreground", children: entry.label }),
+            /* @__PURE__ */ jsx("span", { className: "ml-auto font-mono text-[10.5px] text-muted-foreground/80", children: entry.count.toLocaleString() })
+          ]
+        }
+      ),
+      expanded ? /* @__PURE__ */ jsxs("ul", { className: "flex flex-col", children: [
+        group.items.map((row) => /* @__PURE__ */ jsx(
+          Row,
+          {
+            row,
+            indent: true,
+            onActivate,
+            getDragPayload
+          },
+          row.id
+        )),
+        group.loading && group.items.length === 0 ? /* @__PURE__ */ jsxs("li", { className: "flex items-center gap-1.5 pl-7 pr-3 py-1.5 text-[11px] text-muted-foreground/80", children: [
+          /* @__PURE__ */ jsx(Spinner, { className: "size-3" }),
+          "Loading\u2026"
+        ] }) : null,
+        group.hasMore ? /* @__PURE__ */ jsx("li", { className: "pl-7 pr-3 py-1", children: /* @__PURE__ */ jsx(Button, { type: "button", variant: "ghost", size: "xs", onClick: () => onLoadMoreGroup(entry.value), disabled: group.loading, className: "text-[11px] text-muted-foreground hover:text-foreground", children: group.loading ? "Loading\u2026" : "Load more" }) }) : null
+      ] }) : null
+    ] }, entry.value);
+  }) });
+}
+function Row({
+  row,
+  indent,
+  onActivate,
+  getDragPayload
+}) {
+  const interactive = !!onActivate;
+  const payload = getDragPayload?.(row);
+  const draggable = !!payload;
+  const handleKeyDown = (e) => {
+    if (!interactive) return;
+    if (e.key === "Enter" || e.key === " ") {
+      e.preventDefault();
+      onActivate?.(row);
+    }
+  };
+  const handleDragStart = (e) => {
+    if (!payload) return;
+    e.dataTransfer.setData(payload.mimeType, payload.value);
+    e.dataTransfer.setData("text/plain", payload.value);
+    e.dataTransfer.effectAllowed = "copy";
+  };
+  return /* @__PURE__ */ jsxs(
+    "li",
+    {
+      ...interactive ? { role: "button", tabIndex: 0, onClick: () => onActivate?.(row), onKeyDown: handleKeyDown } : {},
+      ...draggable ? { draggable: true, onDragStart: handleDragStart } : {},
+      className: cn(
+        "group mx-1 flex items-start gap-2 rounded-md px-1.5 py-1",
+        "transition-colors duration-120 ease-[cubic-bezier(0.22,1,0.36,1)]",
+        interactive && "cursor-pointer hover:bg-foreground/5",
+        indent && "pl-7"
+      ),
+      title: row.title,
+      children: [
+        row.leading ? /* @__PURE__ */ jsx(BadgeChip, { badge: row.leading }) : null,
+        /* @__PURE__ */ jsxs("span", { className: "flex min-w-0 flex-1 flex-col", children: [
+          /* @__PURE__ */ jsx("span", { className: "truncate text-[12.5px] font-medium leading-tight text-foreground", children: row.title }),
+          row.subtitle ? /* @__PURE__ */ jsx("span", { className: "truncate text-[11.5px] leading-snug text-muted-foreground/85", children: row.subtitle }) : null
+        ] }),
+        row.trailing?.length ? /* @__PURE__ */ jsx("span", { className: "flex shrink-0 items-center gap-1", children: row.trailing.map((b, i) => /* @__PURE__ */ jsx(BadgeChip, { badge: b }, i)) }) : null,
+        row.meta ? /* @__PURE__ */ jsx("span", { className: "shrink-0 self-center font-mono text-[10.5px] text-muted-foreground/80", children: row.meta }) : null
+      ]
+    }
+  );
+}
+function BadgeChip({ badge }) {
+  return /* @__PURE__ */ jsx(
+    UiChip,
+    {
+      "aria-hidden": "true",
+      title: badge.tooltip,
+      className: "mt-[1px] h-[16px] min-w-[24px] rounded-[3px] border-0 bg-muted/60 px-1 font-mono text-[9.5px] uppercase tracking-[0.06em] text-muted-foreground group-hover:text-foreground",
+      children: badge.code
+    }
+  );
+}
+export {
+  DataExplorer,
+  useExplorerState
+};

package/dist/shared/index.d.ts

@@ -0,0 +1,73 @@
+/**
+ * DataExplorer shared types — no runtime deps.
+ *
+ * Importable from BOTH front and server bundles without dragging in
+ * platform-specific code.
+ */
+type Badge = {
+    /** 1–4 char mono code rendered as a chip. */
+    code: string;
+    tooltip?: string;
+};
+type ExplorerItem = {
+    id: string;
+    title: string;
+    /** Optional muted second line (truncates with title). */
+    subtitle?: string;
+    /** Group key — must match one of the facet values for `groupBy`. */
+    group?: string;
+    /** Leading mono chip (e.g. type code, frequency). */
+    leading?: Badge;
+    /** Trailing mono chips for status flags (e.g. [D] derived, [LIVE]). */
+    trailing?: Badge[];
+    /** Right-aligned plain text for numeric metadata (e.g. "1.2M", "2.4s"). */
+    meta?: string;
+};
+type FacetValue = {
+    value: string;
+    count: number;
+};
+type Facets = Record<string, FacetValue[]>;
+type FacetConfig = {
+    /** Filter key sent to the adapter (e.g. "frequency"). */
+    key: string;
+    /** Display label (e.g. "Frequency"). */
+    label: string;
+    /** Explicit display order; unknown values go after in adapter order. */
+    order?: string[];
+    /** Display formatter for raw values (e.g. "M" → "Monthly"). */
+    formatValue?: (value: string) => string;
+};
+type SearchArgs = {
+    query: string;
+    filters: Record<string, string[]>;
+    /** Scope to a single group's value (only set when paginating inside a group). */
+    group?: {
+        key: string;
+        value: string;
+    };
+    limit: number;
+    offset: number;
+    signal?: AbortSignal;
+};
+type SearchResult = {
+    items: ExplorerItem[];
+    /** Total count for the current scope (query + filters + optional group). */
+    total: number;
+    hasMore: boolean;
+};
+type FacetsArgs = {
+    filters: Record<string, string[]>;
+    signal?: AbortSignal;
+};
+type ExplorerDataSource = {
+    search(args: SearchArgs): Promise<SearchResult>;
+    /** Optional. When omitted, the explorer renders flat (no facet popover). */
+    fetchFacets?(args: FacetsArgs): Promise<Facets>;
+};
+type DragPayload = {
+    mimeType: string;
+    value: string;
+};
+
+export type { Badge, DragPayload, ExplorerDataSource, ExplorerItem, FacetConfig, FacetValue, Facets, FacetsArgs, SearchArgs, SearchResult };

package/dist/testing/index.d.ts

@@ -0,0 +1,6 @@
+import { ExplorerDataSource } from '../shared/index.js';
+
+declare function createMockSeriesAdapter(): ExplorerDataSource;
+declare function createMockTablesAdapter(): ExplorerDataSource;
+
+export { createMockSeriesAdapter, createMockTablesAdapter };

package/dist/testing/index.js

@@ -0,0 +1,159 @@
+// src/front/storybookAdapters.ts
+var wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+function makeAdapter(rows, extractFacets, opts = {}) {
+  const latency = opts.latencyMs ?? 80;
+  const matchFilters = (row, filters) => {
+    const facetValues = extractFacets(row);
+    for (const [key, vs] of Object.entries(filters)) {
+      if (!vs.length) continue;
+      if (!vs.includes(facetValues[key] ?? "")) return false;
+    }
+    return true;
+  };
+  return {
+    async search(args) {
+      await wait(latency);
+      let pool = rows;
+      if (args.group) {
+        pool = pool.filter((r) => extractFacets(r)[args.group.key] === args.group.value);
+      }
+      if (args.query) {
+        const q = args.query.toLowerCase();
+        pool = pool.filter(
+          (r) => r.id.toLowerCase().includes(q) || r.title.toLowerCase().includes(q) || (r.subtitle?.toLowerCase().includes(q) ?? false)
+        );
+      }
+      pool = pool.filter((r) => matchFilters(r, args.filters));
+      const slice = pool.slice(args.offset, args.offset + args.limit);
+      return {
+        items: slice,
+        total: pool.length,
+        hasMore: args.offset + slice.length < pool.length
+      };
+    },
+    async fetchFacets(args) {
+      await wait(latency / 2);
+      const pool = rows.filter((r) => matchFilters(r, args.filters));
+      const facets = {};
+      for (const row of pool) {
+        const values = extractFacets(row);
+        for (const [key, value] of Object.entries(values)) {
+          if (!facets[key]) facets[key] = [];
+          const entry = facets[key].find((e) => e.value === value);
+          if (entry) entry.count += 1;
+          else facets[key].push({ value, count: 1 });
+        }
+      }
+      return facets;
+    }
+  };
+}
+var FREQ_LABELS = {
+  D: "Daily",
+  W: "Weekly",
+  M: "Monthly",
+  Q: "Quarterly",
+  SA: "Semiannual",
+  A: "Annual"
+};
+var FREQ_DISTRIBUTION = [
+  { code: "D", n: 120 },
+  { code: "W", n: 60 },
+  { code: "M", n: 240 },
+  { code: "Q", n: 90 },
+  { code: "SA", n: 30 },
+  { code: "A", n: 60 }
+];
+var SERIES_NAMES = [
+  "Real GDP",
+  "Nominal GDP",
+  "Personal Consumption",
+  "Industrial Production",
+  "Capacity Utilization",
+  "Unemployment Rate",
+  "Initial Claims",
+  "Nonfarm Payrolls",
+  "CPI All Urban",
+  "Core CPI",
+  "PCE Price Index",
+  "Federal Funds Rate",
+  "10-Year Treasury",
+  "30-Year Mortgage",
+  "Crude Oil WTI",
+  "Brent Crude",
+  "S&P 500",
+  "Trade Weighted Dollar",
+  "Retail Sales",
+  "Housing Starts"
+];
+function generateSeriesRows() {
+  const rows = [];
+  let i = 0;
+  for (const { code, n } of FREQ_DISTRIBUTION) {
+    for (let k = 0; k < n; k++) {
+      const baseName = SERIES_NAMES[(i + k) % SERIES_NAMES.length];
+      const idx = i + k;
+      const id = `${code}${String(idx).padStart(4, "0")}`;
+      const derived = idx % 13 === 0;
+      rows.push({
+        id,
+        title: `${baseName}${k > SERIES_NAMES.length ? ` v${k}` : ""}`,
+        subtitle: `${FREQ_LABELS[code]} \xB7 seasonally adjusted`,
+        group: code,
+        leading: { code, tooltip: FREQ_LABELS[code] },
+        trailing: derived ? [{ code: "D", tooltip: "Derived series" }] : void 0
+      });
+    }
+    i += n;
+  }
+  return rows;
+}
+function createMockSeriesAdapter() {
+  const rows = generateSeriesRows();
+  return makeAdapter(
+    rows,
+    (row) => ({
+      frequency: row.group ?? "",
+      source: row.trailing?.some((b) => b.code === "D") ? "derived" : "fred"
+    }),
+    { latencyMs: 60 }
+  );
+}
+var TABLE_DEFS = [
+  { schema: "public", name: "users", kind: "TBL", rows: "1.2M" },
+  { schema: "public", name: "events", kind: "TBL", rows: "84M" },
+  { schema: "public", name: "sessions", kind: "TBL", rows: "240k" },
+  { schema: "public", name: "active_users", kind: "VW", rows: "\u2014" },
+  { schema: "public", name: "live_orders", kind: "STR", rows: "live" },
+  { schema: "analytics", name: "daily_revenue", kind: "MAT", rows: "365" },
+  { schema: "analytics", name: "weekly_cohort", kind: "MAT", rows: "52" },
+  { schema: "analytics", name: "session_funnel", kind: "VW", rows: "\u2014" },
+  { schema: "billing", name: "invoices", kind: "TBL", rows: "412k" },
+  { schema: "billing", name: "subscriptions", kind: "TBL", rows: "38k" },
+  { schema: "billing", name: "open_invoices", kind: "VW", rows: "\u2014" },
+  { schema: "audit", name: "access_log", kind: "TBL", rows: "16M" },
+  { schema: "audit", name: "auth_events", kind: "STR", rows: "live" }
+];
+function createMockTablesAdapter() {
+  const rows = TABLE_DEFS.map((t) => ({
+    id: `${t.schema}.${t.name}`,
+    title: t.name,
+    subtitle: t.schema,
+    group: t.schema,
+    leading: { code: t.kind },
+    trailing: t.kind === "STR" ? [{ code: "LIVE" }] : void 0,
+    meta: t.rows
+  }));
+  return makeAdapter(
+    rows,
+    (row) => ({
+      schema: row.group ?? "",
+      kind: row.leading?.code ?? ""
+    }),
+    { latencyMs: 40 }
+  );
+}
+export {
+  createMockSeriesAdapter,
+  createMockTablesAdapter
+};

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@hachej/boring-data-explorer",
+  "version": "0.1.13",
+  "type": "module",
+  "private": false,
+  "license": "MIT",
+  "description": "Data explorer plugin primitive and shared explorer contracts for Boring workspace plugins.",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/hachej/boring-ui"
+  },
+  "homepage": "https://github.com/hachej/boring-ui",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/front/index.d.ts",
+      "import": "./dist/front/index.js"
+    },
+    "./front": {
+      "types": "./dist/front/index.d.ts",
+      "import": "./dist/front/index.js"
+    },
+    "./shared": {
+      "types": "./dist/shared/index.d.ts",
+      "import": "./dist/shared/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "pnpm --filter @hachej/boring-ui-kit build && tsc --noEmit",
+    "test": "pnpm --filter @hachej/boring-ui-kit build && vitest run --passWithNoTests",
+    "lint": "pnpm run typecheck",
+    "clean": "rm -rf dist .tsbuildinfo"
+  },
+  "peerDependencies": {
+    "react": "^18.0.0 || ^19.0.0",
+    "react-dom": "^18.0.0 || ^19.0.0"
+  },
+  "dependencies": {
+    "@hachej/boring-ui-kit": "workspace:*",
+    "clsx": "^2.1.1",
+    "lucide-react": "^1.8.0",
+    "tailwind-merge": "^3.5.0"
+  },
+  "devDependencies": {
+    "@testing-library/jest-dom": "^6.9.1",
+    "@testing-library/react": "^16.3.2",
+    "@testing-library/user-event": "^14.6.1",
+    "@types/react": "^19.0.0",
+    "@types/react-dom": "^19.0.0",
+    "@vitejs/plugin-react": "^4.0.0",
+    "jsdom": "^29.0.2",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}