@texturehq/edges-explore

Curated primitives for map / list / detail "Explore" experiences built on Edges.

This package is the shared interaction model that dashboard Explore and CommonGrid Explore will eventually consume. Primitives are promoted one at a time through the lab canvas at apps/edges/lab/explore-framework; only promoted primitives ship on the public surface.

Toolbar chrome

import { ExploreToolbar, ExploreToolbarPrimary, ExploreToolbarChips,
  ExploreToolbarActions } from "@texturehq/edges-explore/toolbar";

<ExploreToolbar aria-label="Explore controls">
  <ExploreToolbarPrimary><MyStatus /></ExploreToolbarPrimary>
  <ExploreToolbarChips><MyChips /></ExploreToolbarChips>
  <ExploreToolbarActions><MyActions /></ExploreToolbarActions>
</ExploreToolbar>

All regions accept normal div attributes, children and className. Regions are optional. Primary can also contain Chips to group status and chips as one flexible left region. The outer container drives wrapping below 640px, independent of the viewport. Actions wrap within available width; Chips scroll horizontally, including when keyboard focus enters an item. Long status content should wrap or truncate within the primary region. No feature-specific props or Dashboard variables are required. Include the package source/dist in your Tailwind v4 sources.

ExploreToolbarOverflow accepts child slots plus renderOverflow(hiddenCount). It measures actual slot and affordance widths and collapses excess slots. Supply a labelled button that opens the omitted content; the package never decides what the items mean or how to reveal them. If a focused item becomes hidden on resize, focus moves to the overflow control. Without collapse behavior, use the scrollable ExploreToolbarChips region. Standard Tab order remains intact: the outer element uses a labelled group, not the ARIA toolbar roving-tabindex pattern.

Dashboard owns chip appearance and construction, result counts, saved views, filters, time travel and actions. See the Explore Framework canvas toolbar fixture for isolated desktop, empty, many-item and constrained-width examples.

Status

ExplorePanel is the first curated primitive. Other modules in src/ (layers, layout, modes, selection, states, tooltips, dashboard-compat) are reference material being refined in the canvas — they are not exposed on the package's public exports yet. Promoting a primitive means: graduate it in the canvas, add a manifest entry in src/manifest.ts, and re-add its subpath in package.json + tsup.config.ts.

Installation

{
  "dependencies": {
    "@texturehq/edges-explore": "workspace:*"
  }
}

Usage

For a full-page Explore experience with deep linking + browser back/forward, use useUrlExploreRouteStack — the in-memory stack is the source of truth, with the URL as its persisted form. The URL only feeds the stack at mount and on popstate; user-initiated mutations flow stack → URL:

import { ExplorePanel, useUrlExploreRouteStack } from "@texturehq/edges-explore";
import { useRouter, useSearchParams } from "next/navigation";
import { useCallback, useEffect, useState } from "react";

type Route =
  | { type: "overview"; id: "overview" }
  | { type: "site"; id: string; payload: { siteId: string } };

const parse = (params: URLSearchParams): Route[] => {
  const stack: Route[] = [{ type: "overview", id: "overview" }];
  const siteId = params.get("siteId");
  if (siteId) stack.push({ type: "site", id: `site:${siteId}`, payload: { siteId } });
  return stack;
};

const serialize = (routes: Route[]): URLSearchParams => {
  const params = new URLSearchParams();
  for (const route of routes) {
    if (route.type === "site") params.set("siteId", route.payload.siteId);
  }
  return params;
};

function ExploreSidebar() {
  const router = useRouter();
  const searchParams = useSearchParams();
  const stack = useUrlExploreRouteStack<Route>({
    parse: useCallback(parse, []),
    serialize: useCallback(serialize, []),
    initialSearch: searchParams?.toString(),
  });
  const [expanded, setExpanded] = useState(false);

  // Sync stack changes back to the URL.
  useEffect(() => {
    const next = stack.serializedSearch;
    const current = window.location.search.replace(/^\?/, "");
    if (next !== current) router.replace(next ? `?${next}` : window.location.pathname, { scroll: false });
  }, [stack.serializedSearch, router]);

  const routeLabel = (route: Route) =>
    route.type === "overview" ? "Overview" : `Site ${route.payload.siteId}`;

  return (
    <ExplorePanel
      current={stack.current}
      previous={stack.previous}
      getRouteLabel={routeLabel}
      onBack={stack.back}
      onClose={() => stack.replace(null)}
      isExpanded={expanded}
      onToggleExpanded={() => setExpanded((v) => !v)}
    >
      <RouteBody route={stack.current} />
    </ExplorePanel>
  );
}

For embedded contexts (modals, canvas demos, etc.) where there's no URL to bind to, use useExploreRouteStack instead — same controller shape, in-memory state, accepts an initialRoute.

The panel is a flex sibling — wrap it next to your map column for push behavior (map shrinks to make room), or render it absolutely-positioned over the map for overlay. That choice belongs to the parent layout, not the primitive.

Public exports

| Subpath | Exports | Purpose | | --- | --- | --- | | . | re-exports of ./panel and ./routes | Convenience barrel | | ./panel | ExplorePanel, ExplorePanelProps, width constants | Right-edge info panel with route-stack header and animated transitions | | ./routes | ExploreRouteDescriptor, useUrlExploreRouteStack (URL-backed), useExploreRouteStack (in-memory), pure reducers (pushExploreRoute, pushDeeperExploreRoute, popExploreRoute, replaceExploreRoute) | Headless route-stack primitives the panel drives off | | ./manifest | explorePrimitivesManifest, ExplorePrimitiveEntry | Prompt/tool-friendly catalog of what's promoted |

Dependency rules

@texturehq/edges-explore may depend on @texturehq/edges, React, and small package-local helpers. It must not depend on:

• apps/dashboard
• CommonGrid app code
• @texturehq/edges-entity-surfaces
• private API clients or app data hooks

If a primitive needs to know what a "site", "device", "alert", "utility", or "power plant" is, it does not belong in this package. Pass that content through slots or keep it in an entity-surface package/app.

Scripts

yarn lint
yarn typecheck
yarn test
yarn build

Panel and route convergence

ExplorePanel accepts getRouteKey for consumer-defined identity and getRouteLabel for labels. headerActions inserts arbitrary route-owned content into the standard header. The default collapsed width is 380px; controlled customWidth affects collapsed mode only, with 320–900px drag bounds capped at 90% of the viewport. Expanded width is 800px. Mobile retains the responsive 88vw width. onResizeStart, onResize, and onResizeEnd report drag lifetime; cancellation, close, expansion, capture loss and unmount finish the drag using its last width and restore document styles. Arrow keys resize by 16px (Shift: 64px). Content and header remain mounted through the 240ms close window.

Both useExploreRouteStack and useUrlExploreRouteStack expose:

• reset(routes): replace the full route path after an external navigation.
• navigateTo(route): truncate descendants of an existing key and refresh its payload, otherwise append.
• removeRoutes(types): remove matching families anywhere; use getRouteType for custom families.
• removeRouteByKey(key): remove the first exact identity from the stack.

Pure counterparts are navigateToExploreRoute, removeExploreRoutes, and removeExploreRouteByKey, exported from /routes and the root. Removals preserve array identity when nothing matches. push deduplicates the top and replaces family peers; pushDeeper preserves same-family ancestors. Back preserves the root by default; closeOnRootBack: true allows back to close the final route (also supported by popExploreRoute). For path-backed consumers, seed useExploreRouteStack with initialRoutes so a deep link has its full route path on the first render. initialRoutes takes precedence over initialRoute. Keep path parsing, query options, and browser history writes in the consuming app. The package never interprets consumer route payloads.