@korso/shepherd-ui 0.1.0 → 0.2.0

package/dist/ShepherdProvider.d.ts

@@ -0,0 +1,12 @@
+import type { ReactNode } from "react";
+import type { ShepherdClient, ShepherdClientConfig } from "./client.js";
+export interface ShepherdProviderProps {
+    /** A pre-built client. Mutually exclusive with `config`. */
+    client?: ShepherdClient;
+    /** Config to build a client from, when one is not supplied directly. */
+    config?: ShepherdClientConfig;
+    children: ReactNode;
+}
+export declare function ShepherdProvider({ client, config, children }: ShepherdProviderProps): import("react").JSX.Element;
+/** Access the ShepherdClient from context. Throws if used outside a provider. */
+export declare function useShepherdClient(): ShepherdClient;

package/dist/ShepherdProvider.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, useMemo } from "react";
+import { createShepherdClient } from "./client.js";
+// ---------------------------------------------------------------------------
+// ShepherdProvider — supplies a ShepherdClient to the view tree via context.
+//
+// Auth-agnostic: the provider takes either a ready-made `client` or a `config`
+// (baseUrl + optional getAuthHeader) and builds one. It imports no auth library.
+// ---------------------------------------------------------------------------
+const ShepherdContext = createContext(null);
+export function ShepherdProvider({ client, config, children }) {
+    // Memoise on STABLE PRIMITIVE deps (baseUrl + getAuthHeader) rather than the
+    // whole `config` object. A consumer passing an inline `config={{ … }}` mints a
+    // new object every render; keying on it would rebuild the client each render and
+    // re-fire every client-dep effect (e.g. re-subscribing useLandscape's 5s poll).
+    // A directly-supplied `client` still takes precedence.
+    const baseUrl = config?.baseUrl;
+    const getAuthHeader = config?.getAuthHeader;
+    const value = useMemo(() => {
+        if (client)
+            return client;
+        return createShepherdClient({ baseUrl: baseUrl ?? "", getAuthHeader });
+    }, [client, baseUrl, getAuthHeader]);
+    return _jsx(ShepherdContext.Provider, { value: value, children: children });
+}
+/** Access the ShepherdClient from context. Throws if used outside a provider. */
+export function useShepherdClient() {
+    const client = useContext(ShepherdContext);
+    if (!client) {
+        throw new Error("useShepherdClient must be used within a <ShepherdProvider>.");
+    }
+    return client;
+}

package/dist/ShepherdProvider.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ShepherdProvider.test.js

@@ -0,0 +1,47 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { render, renderHook, act } from "@testing-library/react";
+import { ShepherdProvider, useShepherdClient } from "./ShepherdProvider.js";
+// ---------------------------------------------------------------------------
+// ShepherdProvider — supplies the client via context. Covers the throw-outside-
+// provider guard and the stable-deps memoisation (P2.5): an inline `config`
+// object must not rebuild the client every render.
+// ---------------------------------------------------------------------------
+describe("useShepherdClient", () => {
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    it("throws a clear error when used outside a <ShepherdProvider>", () => {
+        // Silence the expected React error-boundary console noise.
+        const spy = vi.spyOn(console, "error").mockImplementation(() => { });
+        expect(() => renderHook(() => useShepherdClient())).toThrow(/must be used within a <ShepherdProvider>/);
+        spy.mockRestore();
+    });
+    it("returns the same client across renders when config props are stable", () => {
+        const getAuthHeader = () => "Bearer t";
+        const baseUrl = "https://hub.example.com";
+        function wrapper({ children }) {
+            // A NEW inline config object each render — identity changes every time.
+            return (_jsx(ShepherdProvider, { config: { baseUrl, getAuthHeader }, children: children }));
+        }
+        const { result, rerender } = renderHook(() => useShepherdClient(), { wrapper });
+        const first = result.current;
+        rerender();
+        // Memoised on primitive deps (baseUrl + getAuthHeader), so the client is
+        // stable even though the `config` object identity changed.
+        expect(result.current).toBe(first);
+    });
+    it("prefers a directly-supplied client over config", () => {
+        const client = { baseUrl: "x" };
+        const config = { baseUrl: "ignored" };
+        let seen;
+        function Probe() {
+            seen = useShepherdClient();
+            return null;
+        }
+        act(() => {
+            render(_jsx(ShepherdProvider, { client: client, config: config, children: _jsx(Probe, {}) }));
+        });
+        expect(seen).toBe(client);
+    });
+});

package/dist/ShepherdRoot.d.ts

@@ -0,0 +1,9 @@
+export interface ShepherdRootProps {
+    /**
+     * The DIRECT Hub URL embedded in the agent install command (planning decision
+     * #2: the headless agent connects straight to the Hub, not the BFF). Defaults
+     * to the client's baseUrl, which is correct for self-host.
+     */
+    hubUrl?: string;
+}
+export declare function ShepherdRoot({ hubUrl }: ShepherdRootProps): import("react").JSX.Element;

package/dist/ShepherdRoot.js

@@ -0,0 +1,88 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback, useEffect, useRef, useState } from "react";
+import { Dashboard } from "./components/Dashboard.js";
+import { Workspaces } from "./config/Workspaces.js";
+import { ConnectAgent } from "./config/ConnectAgent.js";
+import { EmptyState } from "./config/EmptyState.js";
+import { useShepherdClient } from "./context.js";
+import { describeError } from "./client.js";
+const VIEWS = [
+    { id: "board", label: "Board" },
+    { id: "config", label: "Config" },
+];
+export function ShepherdRoot({ hubUrl }) {
+    const client = useShepherdClient();
+    const [load, setLoad] = useState({ status: "loading" });
+    const [selectedId, setSelectedId] = useState(null);
+    const [view, setView] = useState("board");
+    // Roving-tabindex refs for the tablist: each tab button registers itself by
+    // index so arrow/Home/End navigation can move DOM focus to the target tab.
+    const tabRefs = useRef([]);
+    // WAI-ARIA "tabs with automatic activation": Arrow keys (wrap-around),
+    // Home, End change the active view AND move focus to the matching tab.
+    const onTabKeyDown = useCallback((e, index) => {
+        const last = VIEWS.length - 1;
+        let next = null;
+        switch (e.key) {
+            case "ArrowRight":
+                next = index === last ? 0 : index + 1;
+                break;
+            case "ArrowLeft":
+                next = index === 0 ? last : index - 1;
+                break;
+            case "Home":
+                next = 0;
+                break;
+            case "End":
+                next = last;
+                break;
+            default:
+                return;
+        }
+        e.preventDefault();
+        setView(VIEWS[next].id);
+        tabRefs.current[next]?.focus();
+    }, []);
+    // The landing view (Config vs Board) is decided exactly once, on the first
+    // resolved list (isInitial), so a later refresh (after create/join) never
+    // re-routes the user off whatever tab they're on.
+    const fetchWorkspaces = useCallback(async (isInitial) => {
+        try {
+            const res = await client.listWorkspaces();
+            setLoad({ status: "ready", workspaces: res.workspaces });
+            // Keep the current selection if it still exists; else pick the first.
+            setSelectedId((prev) => prev && res.workspaces.some((w) => w.id === prev)
+                ? prev
+                : (res.workspaces[0]?.id ?? null));
+            if (isInitial) {
+                setView(res.workspaces.length === 0 ? "config" : "board");
+            }
+        }
+        catch (err) {
+            setLoad({
+                status: "error",
+                message: describeError(err),
+            });
+        }
+    }, [client]);
+    // Initial load + landing decision (runs once on mount).
+    useEffect(() => {
+        void fetchWorkspaces(true);
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, []);
+    const refresh = useCallback(() => fetchWorkspaces(false), [fetchWorkspaces]);
+    const workspaces = load.status === "ready" ? load.workspaces : [];
+    const selected = workspaces.find((w) => w.id === selectedId) ?? null;
+    if (load.status === "loading") {
+        return (_jsx("div", { className: "shepherd-root", children: _jsx("p", { role: "status", children: "Loading\u2026" }) }));
+    }
+    if (load.status === "error") {
+        return (_jsx("div", { className: "shepherd-root", children: _jsx("p", { role: "alert", children: load.message }) }));
+    }
+    const hasWorkspace = workspaces.length > 0;
+    return (_jsxs("div", { className: "shepherd-root", children: [_jsxs("header", { children: [_jsx("h1", { className: "brand", style: { margin: 0, font: "inherit" }, children: "Shepherd" }), _jsx("nav", { className: "tabs", role: "tablist", "aria-label": "Shepherd views", children: VIEWS.map(({ id, label }, index) => (_jsx("button", { ref: (el) => {
+                                tabRefs.current[index] = el;
+                            }, type: "button", role: "tab", id: `tab-${id}`, "aria-controls": `panel-${id}`, "aria-selected": view === id, tabIndex: view === id ? 0 : -1, onClick: () => setView(id), onKeyDown: (e) => onTabKeyDown(e, index), children: label }, id))) })] }), _jsxs("main", { children: [view === "board" && (_jsx("div", { role: "tabpanel", id: "panel-board", "aria-labelledby": "tab-board", tabIndex: 0, children: hasWorkspace && selected ? (_jsx(Dashboard, { workspaceId: selected.id })) : (_jsx(EmptyState, { onGetStarted: () => setView("config") })) })), view === "config" && (_jsx("div", { role: "tabpanel", id: "panel-config", "aria-labelledby": "tab-config", tabIndex: 0, children: _jsxs("section", { className: "shepherd-config", "aria-labelledby": "config-heading", children: [_jsx("h2", { id: "config-heading", children: "Configuration" }), _jsx(Workspaces, { workspaces: workspaces, selected: selected, onChanged: () => {
+                                        void refresh();
+                                    }, onSelect: setSelectedId }), selected && _jsx(ConnectAgent, { workspaceId: selected.id, hubUrl: hubUrl })] }) }))] })] }));
+}

package/dist/ShepherdRoot.routing.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ShepherdRoot.routing.test.js

@@ -0,0 +1,61 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describe, it, expect, vi, beforeEach } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { ShepherdProvider } from "./ShepherdProvider.js";
+import { ShepherdRoot } from "./ShepherdRoot.js";
+import { makeMockClient } from "./test/mockClient.js";
+// ---------------------------------------------------------------------------
+// ShepherdRoot — routing / landing + empty-state gating (Task 6.3).
+//
+// The route guard keys off listWorkspaces() being empty:
+//   - no workspace  → land on Config; Tasks/Chat render an EmptyState prompt.
+//   - >= 1 workspace → land on Tasks for the first (selected) workspace.
+// ---------------------------------------------------------------------------
+const WS = { id: "ws_1", slug: "acme", name: "Acme", role: "admin" };
+describe("ShepherdRoot routing / landing", () => {
+    let client;
+    beforeEach(() => {
+        client = makeMockClient();
+    });
+    function renderRoot() {
+        return render(_jsx(ShepherdProvider, { client: client, children: _jsx(ShepherdRoot, { hubUrl: "https://hub.example.run.app" }) }));
+    }
+    it("lands on Tasks when the account has at least one workspace", async () => {
+        client.listWorkspaces = vi.fn().mockResolvedValue({ workspaces: [WS] });
+        renderRoot();
+        await waitFor(() => expect(screen.getByRole("tab", { name: "Tasks" })).toHaveAttribute("aria-selected", "true"));
+        expect(screen.getByRole("heading", { name: "Tasks" })).toBeInTheDocument();
+    });
+    it("passes the selected workspaceId into the Tasks view", async () => {
+        client.listWorkspaces = vi.fn().mockResolvedValue({ workspaces: [WS] });
+        renderRoot();
+        await waitFor(() => expect(screen.getByTestId("tasks-workspace-id")).toHaveTextContent("ws_1"));
+    });
+    it("lands on Config when the account has no workspace", async () => {
+        client.listWorkspaces = vi.fn().mockResolvedValue({ workspaces: [] });
+        renderRoot();
+        await waitFor(() => expect(screen.getByRole("tab", { name: "Config" })).toHaveAttribute("aria-selected", "true"));
+    });
+    it("shows an EmptyState (not an error) on Tasks when there is no workspace", async () => {
+        client.listWorkspaces = vi.fn().mockResolvedValue({ workspaces: [] });
+        renderRoot();
+        // Wait for the load to resolve (Config becomes active).
+        await waitFor(() => expect(screen.getByRole("tab", { name: "Config" })).toHaveAttribute("aria-selected", "true"));
+        await userEvent.click(screen.getByRole("tab", { name: "Tasks" }));
+        // The empty-state prompt renders, never a hard wall / crash.
+        expect(screen.getByRole("heading", { name: /no workspace yet|get started/i })).toBeInTheDocument();
+        // The real wallboard scaffold heading is NOT present.
+        expect(screen.queryByTestId("tasks-workspace-id")).not.toBeInTheDocument();
+    });
+    it("shows a loading indicator before the workspace list resolves", async () => {
+        let resolve;
+        client.listWorkspaces = vi.fn().mockReturnValue(new Promise((r) => {
+            resolve = r;
+        }));
+        renderRoot();
+        expect(screen.getByText(/loading/i)).toBeInTheDocument();
+        resolve({ workspaces: [WS] });
+        await waitFor(() => expect(screen.getByRole("heading", { name: "Tasks" })).toBeInTheDocument());
+    });
+});

package/dist/ShepherdRoot.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/ShepherdRoot.test.js

@@ -0,0 +1,37 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, waitFor } from "@testing-library/react";
+import { userEvent } from "@testing-library/user-event";
+import { ShepherdProvider } from "./ShepherdProvider.js";
+import { ShepherdRoot } from "./ShepherdRoot.js";
+import { makeMockClient } from "./test/mockClient.js";
+// Proves the jsdom + Testing Library harness works for downstream tasks: mount
+// the shell inside the provider and confirm the three-view tab skeleton renders
+// and switches. Task 6.3 made the shell async (it lands after listWorkspaces()
+// resolves), so we inject a mock client with a workspace and wait for the load.
+describe("ShepherdRoot", () => {
+    const WS = { id: "ws_1", slug: "acme", name: "Acme", role: "admin" };
+    function renderRoot() {
+        const client = makeMockClient({
+            listWorkspaces: vi.fn().mockResolvedValue({ workspaces: [WS] }),
+        });
+        return render(_jsx(ShepherdProvider, { client: client, children: _jsx(ShepherdRoot, {}) }));
+    }
+    it("mounts and shows the three-view tab shell", async () => {
+        renderRoot();
+        expect(await screen.findByRole("tab", { name: "Tasks" })).toBeInTheDocument();
+        expect(screen.getByRole("tab", { name: "Chat" })).toBeInTheDocument();
+        expect(screen.getByRole("tab", { name: "Config" })).toBeInTheDocument();
+    });
+    it("defaults to the Tasks view when a workspace exists", async () => {
+        renderRoot();
+        await waitFor(() => expect(screen.getByRole("tab", { name: "Tasks" })).toHaveAttribute("aria-selected", "true"));
+        expect(screen.getByRole("heading", { name: "Tasks" })).toBeInTheDocument();
+    });
+    it("switches to the Config view when its tab is clicked", async () => {
+        renderRoot();
+        await userEvent.click(await screen.findByRole("tab", { name: "Config" }));
+        expect(screen.getByRole("tab", { name: "Config" })).toHaveAttribute("aria-selected", "true");
+        expect(screen.getByRole("heading", { name: "Config" })).toBeInTheDocument();
+    });
+});