@korso/shepherd-ui 0.2.0 → 0.2.1

package/README.md

@@ -1,47 +1,47 @@
-# @korso/shepherd-ui
-
-The Shepherd dashboard: an **auth-agnostic** React app (Vite) that renders the
-workspace landscape (crew, territory, active/done work, chat) and issues operator
-actions against the hub. "Auth-agnostic" means the core holds no notion of who
-the user is or how they authenticated — it renders coordination state and issues
-operator actions, leaving authentication to the layer in front of it.
-
-## Two build outputs
-
-One source tree, two Vite builds (`npm run build` runs both):
-
-- **`dist/lib`** (`build:lib`) — a component library for **Korso** to embed in
-  the hosted product. Exposes `<Dashboard/>`, `createShepherdClient`, the React
-  context (`ShepherdClientProvider` / `useShepherdClient`), and types via the `.`
-  export. It is **token-blind**: auth lives in the BFF in front of it. The
-  stylesheet is opt-in (`@korso/shepherd-ui/styles.css`), not auto-imported.
-- **`dist/selfhost`** (`build:app`) — a self-contained SPA the **hub serves**
-  verbatim via `@fastify/static` (the hub resolves `../../ui/dist/selfhost/`).
-  It bundles its own CSS and mounts the token-gated root.
-
-Both `dist/` outputs are gitignored; `npm run build` (root) and the hub Docker
-image regenerate them.
-
-## Two mounts
-
-- **Self-host (the Hub).** The Hub serves `<SelfHostApp/>` (the `./selfhost`
-  export, mounted by `src/main.tsx`). This is the **one** place a team token is
-  handled — the named exception to the auth-agnostic core: it prompts for the
-  `TEAM_TOKEN`, persists it, builds a same-origin client that sends
-  `Authorization: Bearer <token>`, and re-gates on a 401. The token gate lives
-  **only** here, never in the `.` export or `<Dashboard/>`.
-- **Hosted (Korso).** Korso imports `<Dashboard/>` + `createShepherdClient` from
-  the `.` export and supplies its own auth layer (the BFF). No token gate.
-
-## Development
-
-```
-npm -w @korso/shepherd-ui run dev    # Vite dev server for the self-host SPA
-```
-
-Other scripts: `build` (both outputs), `build:lib`, `build:app`, `type-check`
-(`tsc --noEmit`), `test` (Vitest, jsdom).
-
-## Phase note
-
-Korso-side consumption of the `dist/lib` library is **finalized in Phase 5**.
+# @korso/shepherd-ui
+
+The Shepherd dashboard: an **auth-agnostic** React app (Vite) that renders the
+workspace landscape (crew, territory, active/done work, chat) and issues operator
+actions against the hub. "Auth-agnostic" means the core holds no notion of who
+the user is or how they authenticated — it renders coordination state and issues
+operator actions, leaving authentication to the layer in front of it.
+
+## Two build outputs
+
+One source tree, two Vite builds (`npm run build` runs both):
+
+- **`dist/lib`** (`build:lib`) — a component library for **Korso** to embed in
+  the hosted product. Exposes `<Dashboard/>`, `createShepherdClient`, the React
+  context (`ShepherdClientProvider` / `useShepherdClient`), and types via the `.`
+  export. It is **token-blind**: auth lives in the BFF in front of it. The
+  stylesheet is opt-in (`@korso/shepherd-ui/styles.css`), not auto-imported.
+- **`dist/selfhost`** (`build:app`) — a self-contained SPA the **hub serves**
+  verbatim via `@fastify/static` (the hub resolves `../../ui/dist/selfhost/`).
+  It bundles its own CSS and mounts the token-gated root.
+
+Both `dist/` outputs are gitignored; `npm run build` (root) and the hub Docker
+image regenerate them.
+
+## Two mounts
+
+- **Self-host (the Hub).** The Hub serves `<SelfHostApp/>` (the `./selfhost`
+  export, mounted by `src/main.tsx`). This is the **one** place a team token is
+  handled — the named exception to the auth-agnostic core: it prompts for the
+  `TEAM_TOKEN`, persists it, builds a same-origin client that sends
+  `Authorization: Bearer <token>`, and re-gates on a 401. The token gate lives
+  **only** here, never in the `.` export or `<Dashboard/>`.
+- **Hosted (Korso).** Korso imports `<Dashboard/>` + `createShepherdClient` from
+  the `.` export and supplies its own auth layer (the BFF). No token gate.
+
+## Development
+
+```
+npm -w @korso/shepherd-ui run dev    # Vite dev server for the self-host SPA
+```
+
+Other scripts: `build` (both outputs), `build:lib`, `build:app`, `type-check`
+(`tsc --noEmit`), `test` (Vitest, jsdom).
+
+## Phase note
+
+Korso-side consumption of the `dist/lib` library is **finalized in Phase 5**.

package/dist/ShepherdRoot.js

@@ -1,76 +1,32 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useCallback, useEffect, useRef, useState } from "react";
+import { useCallback, useEffect, 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) => {
+    // Loads the workspace list and keeps the selection valid: a still-present
+    // selection is preserved (so a create/join refresh never yanks the user off
+    // their current workspace), otherwise it falls back to the first workspace.
+    const fetchWorkspaces = useCallback(async () => {
         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),
-            });
+            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]);
+        void fetchWorkspaces();
+    }, [fetchWorkspaces]);
     const workspaces = load.status === "ready" ? load.workspaces : [];
     const selected = workspaces.find((w) => w.id === selectedId) ?? null;
     if (load.status === "loading") {
@@ -80,9 +36,11 @@ export function ShepherdRoot({ hubUrl }) {
         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 })] }) }))] })] }));
+    // The Config tab's content. Rendered by <Dashboard> in its `config` panel.
+    // ConnectAgent only appears once a workspace is selected (nothing to connect
+    // an agent to otherwise).
+    const configSection = (_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 fetchWorkspaces();
+                }, onSelect: setSelectedId }), selected && _jsx(ConnectAgent, { workspaceId: selected.id, hubUrl: hubUrl })] }));
+    return (_jsx("div", { className: "shepherd-root", children: _jsx(Dashboard, { workspaceId: selected?.id, config: configSection, hasWorkspace: hasWorkspace }) }));
 }

package/dist/components/Dashboard.d.ts

@@ -1,4 +1,4 @@
-import type { ReactElement } from "react";
+import type { ReactElement, ReactNode } from "react";
 /** Props for {@link Dashboard}. The client comes from context. */
 export interface DashboardProps {
     /**
@@ -8,6 +8,20 @@ export interface DashboardProps {
      * aliases, so a no-id render is unchanged.
      */
     workspaceId?: string;
+    /**
+     * The hosted-shell management view. When supplied, a third `Config` tab is
+     * shown beside `Tasks`/`Chat` and this node renders in its panel. Omitting it
+     * (the self-host case) keeps the board a plain two-tab Tasks/Chat wallboard.
+     */
+    config?: ReactNode;
+    /**
+     * Whether the account currently belongs to a workspace. Only meaningful in the
+     * hosted shell (paired with {@link config}). When `false`, the Tasks/Chat
+     * panels show an {@link EmptyState} prompt instead of a board, the board does
+     * not poll, and the view lands on Config. Defaults to "yes" (self-host always
+     * has its implicit team workspace).
+     */
+    hasWorkspace?: boolean;
 }
 /**
  * The Shepherd wallboard shell. Composes {@link useLandscapePolling} (which reads
@@ -31,4 +45,4 @@ export interface DashboardProps {
  *
  * @returns The dashboard element.
  */
-export declare function Dashboard({ workspaceId }?: DashboardProps): ReactElement;
+export declare function Dashboard({ workspaceId, config, hasWorkspace, }?: DashboardProps): ReactElement;

package/dist/components/Dashboard.js

@@ -1,4 +1,4 @@
-import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
 import { useCallback, useEffect, useRef, useState } from "react";
 import { useLandscapePolling } from "../useLandscapePolling.js";
 import { defaultRepo, distinctRepos, matchesRepo } from "../logic.js";
@@ -8,6 +8,7 @@ import { ActiveList } from "./ActiveList.js";
 import { DoneList } from "./DoneList.js";
 import { Chat } from "./Chat.js";
 import { Composer } from "./Composer.js";
+import { EmptyState } from "../config/EmptyState.js";
 /**
  * localStorage keys + page size, ported verbatim from the state block of
  * packages/hub/public/app.js (POLL_MS lives in the hook).
@@ -126,9 +127,73 @@ function computeCounts(snapshot) {
  *
  * @returns The dashboard element.
  */
-export function Dashboard({ workspaceId } = {}) {
-    const { snapshot, status, lastUpdatedMs, refresh } = useLandscapePolling({ workspaceId });
-    const [activeTab, setActiveTab] = useState(() => (readStored(TAB_KEY) === "chat" ? "chat" : "tasks"));
+export function Dashboard({ workspaceId, config, hasWorkspace, } = {}) {
+    const hasConfig = config != null;
+    // Only the hosted shell with an explicit empty account suppresses the board;
+    // self-host (hasWorkspace undefined) always has its implicit team workspace.
+    const noWorkspace = hasWorkspace === false;
+    const { snapshot, status, lastUpdatedMs, refresh } = useLandscapePolling({
+        workspaceId,
+        // A no-workspace board has nothing to poll; keep it off the hub.
+        enabled: !noWorkspace,
+    });
+    const [activeTab, setActiveTab] = useState(() => {
+        // No workspace yet → land on Config, where create/join lives.
+        if (hasConfig && noWorkspace)
+            return "config";
+        const stored = readStored(TAB_KEY);
+        if (stored === "chat")
+            return "chat";
+        if (stored === "config" && hasConfig)
+            return "config";
+        return "tasks";
+    });
+    // The flat tab strip: Tasks/Chat always, Config only when the host supplies it.
+    const tabs = hasConfig
+        ? [
+            { id: "tasks", label: "Tasks" },
+            { id: "chat", label: "Chat" },
+            { id: "config", label: "Config" },
+        ]
+        : [
+            { id: "tasks", label: "Tasks" },
+            { id: "chat", label: "Chat" },
+        ];
+    // Roving-tabindex refs for the tablist: each tab registers 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 = tabs.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();
+        const target = tabs[next];
+        if (!target)
+            return;
+        onTab(target.id);
+        tabRefs.current[next]?.focus();
+    }, 
+    // `tabs` is rebuilt each render but its identity only matters by length,
+    // which is stable for a given `hasConfig`; `onTab` is stable.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+    [hasConfig]);
     // `null` = not yet chosen (derive a default on first render); "__all__" = All
     // repos; else a specific repo. Seeded from storage exactly like app.js.
     const [selectedRepo, setSelectedRepo] = useState(() => readStored(REPO_KEY));
@@ -205,5 +270,11 @@ export function Dashboard({ workspaceId } = {}) {
     // equals the `active` vital here (same filter), but doneCount is distinct.
     const activeCount = tasks.filter((t) => t.status === "active" && matchesRepo(t, effectiveRepo)).length;
     const doneCount = tasks.filter((t) => t.status !== "active" && matchesRepo(t, effectiveRepo)).length;
-    return (_jsxs("div", { id: "board", children: [_jsxs("header", { children: [_jsx("span", { className: "brand", children: "Shepherd" }), _jsx(RepoSelect, { repos: repos, counts: counts, selected: effectiveRepo, onSelect: onSelectRepo }), _jsxs("span", { className: "vitals", children: [_jsx("b", { id: "vitals-online", children: online }), " online · ", _jsx("b", { id: "vitals-active", children: active }), " active"] }), _jsx("span", { className: "grow" }), _jsx("span", { id: "status", className: "status" + (statusView.kind ? ` status--${statusView.kind}` : ""), children: statusView.text }), _jsx("span", { id: "freshness", className: "freshness", children: freshness }), _jsxs("nav", { className: "tabs", role: "tablist", "aria-label": "Dashboard views", children: [_jsx("button", { className: "tab" + (activeTab === "tasks" ? " tab--active" : ""), "data-tab": "tasks", type: "button", role: "tab", id: "tab-tasks", "aria-controls": "panel-tasks", "aria-selected": activeTab === "tasks", onClick: () => onTab("tasks"), children: "Tasks" }), _jsx("button", { className: "tab" + (activeTab === "chat" ? " tab--active" : ""), "data-tab": "chat", type: "button", role: "tab", id: "tab-chat", "aria-controls": "panel-chat", "aria-selected": activeTab === "chat", onClick: () => onTab("chat"), children: "Chat" })] })] }), _jsxs("section", { id: "panel-tasks", role: "tabpanel", "aria-labelledby": "tab-tasks", hidden: activeTab !== "tasks", children: [_jsx(Crew, { agents: agents, tasks: tasks, selectedRepo: effectiveRepo }), _jsxs("div", { className: "board", children: [_jsxs("div", { className: "col", children: [_jsxs("div", { className: "colhead", children: [_jsx("h2", { children: "Active" }), _jsx("span", { className: "n", id: "active-count", children: activeCount })] }), _jsx(ActiveList, { tasks: tasks, nowMs: nowMs, selectedRepo: effectiveRepo })] }), _jsx("div", { className: "board__rule" }), _jsxs("div", { className: "col", children: [_jsxs("div", { className: "colhead", children: [_jsx("h2", { children: "Done" }), _jsx("span", { className: "n", id: "done-count", children: doneCount })] }), _jsx(DoneList, { tasks: tasks, nowMs: nowMs, selectedRepo: effectiveRepo, doneShown: doneShown, onLoadMore: onLoadMore })] })] })] }), _jsx("section", { id: "panel-chat", role: "tabpanel", "aria-labelledby": "tab-chat", hidden: activeTab !== "chat", children: _jsxs("div", { className: "chat-wrap", children: [_jsx(Chat, { announcements: announcements, selectedRepo: effectiveRepo, nowMs: nowMs }), _jsx(Composer, { agents: agents, selectedRepo: effectiveRepo, workspaceId: workspaceId, onSent: refresh })] }) })] }));
+    // The poll-driven header chrome (repo filter, vitals, status, freshness) only
+    // makes sense for a live board — hide it on the Config tab and when there is
+    // no workspace to poll. The brand and the tab strip stay in every state.
+    const showBoardChrome = !noWorkspace && activeTab !== "config";
+    return (_jsxs("div", { id: "board", children: [_jsxs("header", { children: [_jsx("h1", { className: "brand", style: { margin: 0, font: "inherit" }, children: "Shepherd" }), showBoardChrome && (_jsxs(_Fragment, { children: [_jsx(RepoSelect, { repos: repos, counts: counts, selected: effectiveRepo, onSelect: onSelectRepo }), _jsxs("span", { className: "vitals", children: [_jsx("b", { id: "vitals-online", children: online }), " online · ", _jsx("b", { id: "vitals-active", children: active }), " active"] })] })), _jsx("span", { className: "grow" }), showBoardChrome && (_jsxs(_Fragment, { children: [_jsx("span", { id: "status", className: "status" + (statusView.kind ? ` status--${statusView.kind}` : ""), children: statusView.text }), _jsx("span", { id: "freshness", className: "freshness", children: freshness })] })), _jsx("nav", { className: "tabs", role: "tablist", "aria-label": "Shepherd views", children: tabs.map(({ id, label }, index) => (_jsx("button", { ref: (el) => {
+                                tabRefs.current[index] = el;
+                            }, className: "tab" + (activeTab === id ? " tab--active" : ""), "data-tab": id, type: "button", role: "tab", id: `tab-${id}`, "aria-controls": `panel-${id}`, "aria-selected": activeTab === id, tabIndex: activeTab === id ? 0 : -1, onClick: () => onTab(id), onKeyDown: (e) => onTabKeyDown(e, index), children: label }, id))) })] }), _jsx("section", { id: "panel-tasks", role: "tabpanel", "aria-labelledby": "tab-tasks", hidden: activeTab !== "tasks", children: noWorkspace ? (_jsx(EmptyState, { onGetStarted: () => onTab("config") })) : (_jsxs(_Fragment, { children: [_jsx(Crew, { agents: agents, tasks: tasks, selectedRepo: effectiveRepo }), _jsxs("div", { className: "board", children: [_jsxs("div", { className: "col", children: [_jsxs("div", { className: "colhead", children: [_jsx("h2", { children: "Active" }), _jsx("span", { className: "n", id: "active-count", children: activeCount })] }), _jsx(ActiveList, { tasks: tasks, nowMs: nowMs, selectedRepo: effectiveRepo })] }), _jsx("div", { className: "board__rule" }), _jsxs("div", { className: "col", children: [_jsxs("div", { className: "colhead", children: [_jsx("h2", { children: "Done" }), _jsx("span", { className: "n", id: "done-count", children: doneCount })] }), _jsx(DoneList, { tasks: tasks, nowMs: nowMs, selectedRepo: effectiveRepo, doneShown: doneShown, onLoadMore: onLoadMore })] })] })] })) }), _jsx("section", { id: "panel-chat", role: "tabpanel", "aria-labelledby": "tab-chat", hidden: activeTab !== "chat", children: noWorkspace ? (_jsx(EmptyState, { onGetStarted: () => onTab("config") })) : (_jsxs("div", { className: "chat-wrap", children: [_jsx(Chat, { announcements: announcements, selectedRepo: effectiveRepo, nowMs: nowMs }), _jsx(Composer, { agents: agents, selectedRepo: effectiveRepo, workspaceId: workspaceId, onSent: refresh })] })) }), hasConfig && (_jsx("section", { id: "panel-config", role: "tabpanel", "aria-labelledby": "tab-config", hidden: activeTab !== "config", children: config }))] }));
 }

package/dist/config/EmptyState.js

@@ -1,4 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useId } from "react";
 export function EmptyState({ title = "No workspace yet", children, onGetStarted, ctaLabel = "Go to Config", }) {
-    return (_jsxs("section", { className: "shepherd-empty-state", "aria-labelledby": "empty-state-heading", children: [_jsx("h2", { id: "empty-state-heading", children: title }), _jsx("p", { children: children ?? "Create a workspace or join one with an invite code to get started." }), onGetStarted && (_jsx("button", { type: "button", onClick: onGetStarted, children: ctaLabel }))] }));
+    // A per-instance id so two EmptyStates (e.g. the Tasks and Chat panels of a
+    // no-workspace board) never collide on a duplicate `empty-state-heading` id.
+    const headingId = useId();
+    return (_jsxs("section", { className: "shepherd-empty-state", "aria-labelledby": headingId, children: [_jsx("h2", { id: headingId, children: title }), _jsx("p", { children: children ?? "Create a workspace or join one with an invite code to get started." }), onGetStarted && (_jsx("button", { type: "button", onClick: onGetStarted, children: ctaLabel }))] }));
 }