@nextclaw/ui 0.23.0 → 0.24.0-beta.0

package/src/features/projects/components/project-work-items.test.tsx

@@ -0,0 +1,78 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { ProjectObservationSnapshot } from "@nextclaw/client-sdk";
+import { ProjectWorkItems } from "./project-work-items";
+
+const reference = {
+  kind: "ai-report" as const,
+  label: "AI report",
+  observedAt: "2026-08-30T00:00:00.000Z",
+  sessionId: "session-1",
+};
+
+function createSnapshot(): ProjectObservationSnapshot {
+  return {
+    asOf: reference.observedAt,
+    project: { name: "Demo", rootPath: "/tmp/demo", context: [] },
+    sources: [],
+    workflows: [{
+      id: "research",
+      label: "Research",
+      stages: [{ id: "draft", label: "Draft" }],
+      reference,
+    }],
+    runs: [],
+    workItems: [{
+      id: "report",
+      name: "Write the report",
+      status: "active",
+      workflowId: "research",
+      stageId: "draft",
+      updatedAt: reference.observedAt,
+      reference,
+    }],
+    artifactCategories: [], artifacts: [], signals: [], requests: [], activity: [], skills: [], diagnostics: [],
+    dataQuality: "complete",
+  };
+}
+
+describe("ProjectWorkItems", () => {
+  it("switches list, board, and gantt over one snapshot without fabricating a schedule", () => {
+    render(
+      <ProjectWorkItems
+        hasProjectSessions
+        snapshot={createSnapshot()}
+        shouldOfferObservationSetup={false}
+        onStartObservationSetup={vi.fn()}
+        onStartProjectWork={vi.fn()}
+      />,
+    );
+    expect(screen.getByText("Write the report")).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: /Board|看板/ }));
+    expect(screen.getByText("Draft")).toBeTruthy();
+    expect(screen.getByText("Write the report")).toBeTruthy();
+
+    fireEvent.click(screen.getByRole("button", { name: /Gantt|甘特图/ }));
+    expect(screen.getByText(/No schedule markers|没有 schedule Marker/)).toBeTruthy();
+  });
+
+  it("offers an ordinary project conversation before rendering empty view controls", () => {
+    const onStartProjectWork = vi.fn();
+    render(
+      <ProjectWorkItems
+        hasProjectSessions={false}
+        snapshot={{ ...createSnapshot(), workItems: [] }}
+        shouldOfferObservationSetup={false}
+        onStartObservationSetup={vi.fn()}
+        onStartProjectWork={onStartProjectWork}
+      />,
+    );
+
+    expect(screen.queryByRole("group", { name: /Work item views|工作项视图/ })).toBeNull();
+    fireEvent.click(
+      screen.getByRole("button", { name: /Start project work|开始项目工作/ }),
+    );
+    expect(onStartProjectWork).toHaveBeenCalledOnce();
+  });
+});

package/src/features/projects/components/project-work-items.tsx

@@ -0,0 +1,272 @@
+import { useState } from "react";
+import type {
+  ObservedWorkItem,
+  ProjectObservationSnapshot,
+} from "@nextclaw/client-sdk";
+import { Button } from "@/shared/components/ui/button";
+import { t } from "@/shared/lib/i18n";
+import {
+  createProjectBoardColumns,
+  getScheduledWorkItems,
+  getUnstagedWorkItems,
+  type ProjectWorkView,
+} from "@/features/projects/presenters/project-home.presenter";
+import { ProjectEmptyState } from "./project-section";
+import { ProjectRuns } from "./project-runs";
+
+function WorkItemCard({
+  item,
+  onSelect,
+}: {
+  item: ObservedWorkItem;
+  onSelect: () => void;
+}) {
+  return (
+    <button
+      type="button"
+      className="w-full rounded-xl bg-card p-3 text-left text-sm shadow-sm hover:bg-[var(--interaction-hover)] focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-border"
+      onClick={onSelect}
+    >
+      <span className="block font-medium">{item.name}</span>
+      <span className="mt-1 block text-xs text-muted-foreground">
+        {item.reference.label} · {t(`projectsStatus_${item.status}`)}
+      </span>
+    </button>
+  );
+}
+
+function ProjectWorkItemsEmptyState({
+  hasProjectSessions,
+  onStartObservationSetup,
+  onStartProjectWork,
+  shouldOfferObservationSetup,
+}: {
+  hasProjectSessions: boolean;
+  onStartObservationSetup: () => void;
+  onStartProjectWork: () => void;
+  shouldOfferObservationSetup: boolean;
+}) {
+  const messageKey = shouldOfferObservationSetup
+    ? "projectsWorkNeedsSetup"
+    : hasProjectSessions
+      ? "projectsWorkNoReports"
+      : "projectsWorkNoSessions";
+  return (
+    <div className="min-w-0">
+      <ProjectEmptyState>{t(messageKey)}</ProjectEmptyState>
+      <Button
+        size="sm"
+        variant="outline"
+        onClick={
+          shouldOfferObservationSetup
+            ? onStartObservationSetup
+            : onStartProjectWork
+        }
+      >
+        {t(
+          shouldOfferObservationSetup
+            ? "projectsObservationSetupAction"
+            : "projectsStartProjectWork",
+        )}
+      </Button>
+    </div>
+  );
+}
+
+export function ProjectWorkItems({
+  hasProjectSessions,
+  onStartObservationSetup,
+  onStartProjectWork,
+  snapshot,
+  shouldOfferObservationSetup,
+}: {
+  hasProjectSessions: boolean;
+  onStartObservationSetup: () => void;
+  onStartProjectWork: () => void;
+  snapshot: ProjectObservationSnapshot;
+  shouldOfferObservationSetup: boolean;
+}) {
+  const [view, setView] = useState<ProjectWorkView>("list");
+  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const selected =
+    snapshot.workItems.find((item) => item.id === selectedId) ?? null;
+  const columns = createProjectBoardColumns(
+    snapshot.workflows,
+    snapshot.workItems,
+  );
+  const unstaged = getUnstagedWorkItems(snapshot.workItems);
+  const scheduled = getScheduledWorkItems(snapshot.workItems);
+  return (
+    <section className="min-w-0" aria-label={t("projectsWork")}>
+      {(snapshot.runs?.length ?? 0) > 0 ? (
+        <div className="mb-5">
+          <h2 className="mb-2 text-sm font-semibold">{t("projectsAiActivity")}</h2>
+          <ProjectRuns snapshot={snapshot} />
+        </div>
+      ) : null}
+      {snapshot.workItems.length === 0 ? (
+        <ProjectWorkItemsEmptyState
+          hasProjectSessions={hasProjectSessions}
+          onStartObservationSetup={onStartObservationSetup}
+          onStartProjectWork={onStartProjectWork}
+          shouldOfferObservationSetup={shouldOfferObservationSetup}
+        />
+      ) : (
+      <>
+      <div
+        className="mb-4 flex flex-wrap gap-1"
+        role="group"
+        aria-label={t("projectsWorkViews")}
+      >
+        {(["list", "board", "gantt"] as const).map((key) => (
+          <Button
+            key={key}
+            size="sm"
+            variant={view === key ? "secondary" : "ghost"}
+            aria-pressed={view === key}
+            onClick={() => setView(key)}
+          >
+            {t(`projectsWork${key[0].toUpperCase()}${key.slice(1)}`)}
+          </Button>
+        ))}
+      </div>
+      {view === "list" ? (
+        <div className="space-y-2">
+          {snapshot.workItems.map((item) => (
+            <WorkItemCard
+              key={item.id}
+              item={item}
+              onSelect={() => setSelectedId(item.id)}
+            />
+          ))}
+        </div>
+      ) : null}
+      {view === "board" ? (
+        columns.length ? (
+          <div className="grid min-w-0 gap-3 md:grid-cols-2 xl:grid-cols-4">
+            {columns.map((column) => (
+              <section
+                key={column.id}
+                className="min-w-0 rounded-xl bg-muted/35 p-3"
+              >
+                <h3 className="mb-3 text-xs font-semibold">{column.label}</h3>
+                <div className="space-y-2">
+                  {column.items.map((item) => (
+                    <WorkItemCard
+                      key={item.id}
+                      item={item}
+                      onSelect={() => setSelectedId(item.id)}
+                    />
+                  ))}
+                  {!column.items.length ? (
+                    <p className="py-3 text-xs text-muted-foreground">
+                      {t("projectsNoData")}
+                    </p>
+                  ) : null}
+                </div>
+              </section>
+            ))}
+            {unstaged.length ? (
+              <section className="min-w-0 rounded-xl bg-muted/35 p-3">
+                <h3 className="mb-3 text-xs font-semibold">
+                  {t("projectsUnstaged")}
+                </h3>
+                <div className="space-y-2">
+                  {unstaged.map((item) => (
+                    <WorkItemCard
+                      key={item.id}
+                      item={item}
+                      onSelect={() => setSelectedId(item.id)}
+                    />
+                  ))}
+                </div>
+              </section>
+            ) : null}
+          </div>
+        ) : (
+          <ProjectEmptyState>
+            {t("projectsBoardNeedsWorkflow")}
+          </ProjectEmptyState>
+        )
+      ) : null}
+      {view === "gantt" ? (
+        scheduled.length ? (
+          <div className="overflow-x-auto rounded-xl border border-border/60">
+            <div className="min-w-[42rem] divide-y divide-border/60">
+              {scheduled.map((item) => (
+                <button
+                  key={item.id}
+                  type="button"
+                  className="grid w-full grid-cols-[minmax(12rem,1fr)_9rem_9rem] gap-3 px-4 py-3 text-left text-sm hover:bg-[var(--interaction-hover)]"
+                  onClick={() => setSelectedId(item.id)}
+                >
+                  <span className="truncate font-medium">{item.name}</span>
+                  <span>{item.schedule?.start ?? "—"}</span>
+                  <span>{item.schedule?.end ?? "—"}</span>
+                </button>
+              ))}
+            </div>
+          </div>
+        ) : (
+          <ProjectEmptyState>
+            {t("projectsGanttNeedsSchedule")}
+          </ProjectEmptyState>
+        )
+      ) : null}
+      {selected ? (
+        <aside
+          className="mt-4 rounded-xl border border-border/60 bg-muted/25 p-4"
+          aria-label={t("projectsWorkDetails")}
+        >
+          <div className="flex items-start justify-between gap-3">
+            <div>
+              <h3 className="font-semibold">{selected.name}</h3>
+              <p className="mt-1 text-xs text-muted-foreground">
+                {selected.id} · {selected.reference.label}
+              </p>
+            </div>
+            <Button
+              size="sm"
+              variant="ghost"
+              onClick={() => setSelectedId(null)}
+            >
+              {t("projectsCloseDetails")}
+            </Button>
+          </div>
+          <dl className="mt-3 grid gap-2 text-sm sm:grid-cols-2">
+            <div>
+              <dt className="text-xs text-muted-foreground">
+                {t("projectsStatus")}
+              </dt>
+              <dd>{t(`projectsStatus_${selected.status}`)}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">
+                {t("projectsStage")}
+              </dt>
+              <dd>{selected.stageId ?? t("projectsNoData")}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">
+                {t("projectsUpdated")}
+              </dt>
+              <dd>{selected.updatedAt}</dd>
+            </div>
+            <div>
+              <dt className="text-xs text-muted-foreground">
+                {t("projectsSchedule")}
+              </dt>
+              <dd>
+                {selected.schedule
+                  ? `${selected.schedule.start ?? "—"} → ${selected.schedule.end ?? "—"}`
+                  : t("projectsNoData")}
+              </dd>
+            </div>
+          </dl>
+        </aside>
+      ) : null}
+      </>
+      )}
+    </section>
+  );
+}

package/src/features/projects/hooks/use-project-observation.test.tsx

@@ -0,0 +1,93 @@
+import { act, renderHook, waitFor } from "@testing-library/react";
+import type { ReactNode } from "react";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { NcpEventType } from "@nextclaw/ncp";
+import { eventKeys, type ProjectObservationSnapshot } from "@nextclaw/client-sdk";
+import { EventBus } from "@nextclaw/shared";
+import { afterEach, describe, expect, it, vi } from "vitest";
+import { nextclawClient } from "@/shared/lib/api";
+import { useProjectObservation } from "./use-project-observation";
+
+const mocks = vi.hoisted(() => ({ getObservation: vi.fn() }));
+
+vi.mock("@/shared/lib/api", () => ({
+  nextclawClient: {
+    eventBus: new EventBus(),
+    projects: { getObservation: mocks.getObservation },
+  },
+}));
+
+const observedAt = "2026-08-31T00:00:00.000Z";
+const snapshot: ProjectObservationSnapshot = {
+  asOf: observedAt,
+  project: { name: "Demo", rootPath: "/tmp/demo", context: [] },
+  sources: [],
+  workflows: [],
+  runs: [{
+    sessionId: "session-1",
+    state: "running",
+    updatedAt: observedAt,
+    reference: {
+      kind: "system-record",
+      label: "Session run",
+      observedAt,
+      sessionId: "session-1",
+    },
+  }],
+  workItems: [],
+  artifactCategories: [],
+  artifacts: [],
+  signals: [],
+  requests: [],
+  activity: [],
+  skills: [],
+  diagnostics: [],
+  dataQuality: "complete",
+};
+
+afterEach(() => {
+  vi.useRealTimers();
+  mocks.getObservation.mockReset();
+});
+
+describe("useProjectObservation", () => {
+  it("refreshes only for the active project's session lifecycle", async () => {
+    mocks.getObservation.mockResolvedValue(snapshot);
+    const queryClient = new QueryClient({
+      defaultOptions: { queries: { retry: false } },
+    });
+    const wrapper = ({ children }: { children: ReactNode }) => (
+      <QueryClientProvider client={queryClient}>{children}</QueryClientProvider>
+    );
+    const { result } = renderHook(
+      () => useProjectObservation("project-1", "/tmp/demo"),
+      { wrapper },
+    );
+    await waitFor(() => expect(result.current.data).toEqual(snapshot));
+
+    act(() => {
+      nextclawClient.eventBus.emit(eventKeys.sessionSummaryUpsert, {
+        summary: {
+          sessionId: "other-session",
+          messageCount: 0,
+          updatedAt: observedAt,
+          metadata: { project_root: "/tmp/other" },
+        },
+      });
+    });
+    await new Promise((resolve) => setTimeout(resolve, 150));
+    expect(mocks.getObservation).toHaveBeenCalledTimes(1);
+
+    act(() => {
+      nextclawClient.eventBus.emit(eventKeys.ncpEvent, {
+        type: NcpEventType.MessageTextDelta,
+        payload: {
+          sessionId: "session-1",
+          messageId: "assistant-1",
+          delta: '[nextclaw.project/v1 id=wi_7km4q2x9dn name="Live work" stage=exploration]',
+        },
+      });
+    });
+    await waitFor(() => expect(mocks.getObservation).toHaveBeenCalledTimes(2));
+  });
+});

package/src/features/projects/hooks/use-project-observation.ts

@@ -0,0 +1,85 @@
+import { useEffect } from "react";
+import { useQuery, useQueryClient } from "@tanstack/react-query";
+import { NcpEventType, type NcpEndpointEvent } from "@nextclaw/ncp";
+import { eventKeys, type ProjectObservationSnapshot } from "@nextclaw/client-sdk";
+import { nextclawClient } from "@/shared/lib/api";
+
+export const projectObservationQueryKey = (projectId: string) => [
+  "project-observation",
+  projectId,
+] as const;
+
+const REFRESHING_NCP_EVENTS = new Set<NcpEventType>([
+  NcpEventType.MessageTextEnd,
+  NcpEventType.MessageTextDelta,
+  NcpEventType.MessageCompleted,
+  NcpEventType.MessageFailed,
+  NcpEventType.MessageAbort,
+  NcpEventType.RunStarted,
+  NcpEventType.RunFinished,
+  NcpEventType.RunError,
+]);
+
+const readNcpEventSessionId = (event: NcpEndpointEvent): string | null => {
+  if (!("payload" in event) || !event.payload || typeof event.payload !== "object" || !("sessionId" in event.payload)) {
+    return null;
+  }
+  const { sessionId } = event.payload;
+  return typeof sessionId === "string" && sessionId.trim() ? sessionId.trim() : null;
+};
+
+const readProjectRoot = (metadata: Record<string, unknown> | undefined): string | null => {
+  const value = metadata?.project_root ?? metadata?.projectRoot;
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+};
+
+export function useProjectObservation(projectId: string | null, projectRoot: string | null) {
+  const queryClient = useQueryClient();
+  useEffect(() => {
+    if (!projectId || !projectRoot) return;
+    const queryKey = projectObservationQueryKey(projectId);
+    let refreshTimer: ReturnType<typeof setTimeout> | null = null;
+    const scheduleRefresh = () => {
+      if (refreshTimer) return;
+      refreshTimer = setTimeout(() => {
+        refreshTimer = null;
+        void queryClient.invalidateQueries({ queryKey, exact: true });
+      }, 100);
+    };
+    const hasObservedSession = (sessionId: string): boolean => {
+      const snapshot = queryClient.getQueryData<ProjectObservationSnapshot>(queryKey);
+      return Boolean(
+        snapshot?.runs?.some((run) => run.sessionId === sessionId)
+        || snapshot?.workItems.some((item) => item.reference.sessionId === sessionId)
+        || snapshot?.activity.some((activity) => activity.reference.sessionId === sessionId),
+      );
+    };
+    const unsubscribers = [
+      nextclawClient.eventBus.on(eventKeys.ncpEvent, (event) => {
+        if (!REFRESHING_NCP_EVENTS.has(event.type)) return;
+        const sessionId = readNcpEventSessionId(event);
+        if (sessionId && hasObservedSession(sessionId)) scheduleRefresh();
+      }),
+      nextclawClient.eventBus.on(eventKeys.sessionRunStatus, ({ sessionKey }) => {
+        if (hasObservedSession(sessionKey)) scheduleRefresh();
+      }),
+      nextclawClient.eventBus.on(eventKeys.sessionSummaryUpsert, ({ summary }) => {
+        if (readProjectRoot(summary.metadata) === projectRoot) scheduleRefresh();
+      }),
+      nextclawClient.eventBus.on(eventKeys.sessionSummaryDelete, ({ sessionKey }) => {
+        if (hasObservedSession(sessionKey)) scheduleRefresh();
+      }),
+    ];
+    return () => {
+      if (refreshTimer) clearTimeout(refreshTimer);
+      for (const unsubscribe of unsubscribers) unsubscribe();
+    };
+  }, [projectId, projectRoot, queryClient]);
+
+  return useQuery({
+    queryKey: projectObservationQueryKey(projectId ?? ""),
+    enabled: Boolean(projectId),
+    staleTime: 5_000,
+    queryFn: async () => await nextclawClient.projects.getObservation(projectId!),
+  });
+}

package/src/features/projects/index.ts

@@ -0,0 +1,2 @@
+/** Public UI boundary for Projects. */
+export { ProjectsPage } from "./pages/project-home-page";