feat(plugin): add sidebar view examples and ref actions

Keep sidebar layout and gestures inside the plugin while routing entity handles to their owning hosts. Examples cover empty projects, pinned workspaces, task sections, nested agents and device-local label folders.
2026-11-06 08:24:46 +00:00 · 2026-11-06 09:22:19 +01:00
parent dc309586f0
commit 62bd21214b
34 changed files with 1254 additions and 85 deletions
@@ -0,0 +1,34 @@
+import type { PluginAgentSnapshot } from "@getpaseo/plugin";
+import { ScrollView, View } from "react-native";
+import { useAgents, type PluginSidebarViewProps } from "@getpaseo/plugin/client";
+import { AgentRow, Heading } from "./rows";
+export function agentTask(agent: PluginAgentSnapshot) {
+  if (agent.attentionReason === "permission") return "Respond";
+  if (agent.requiresAttention || agent.status === "error") return "Review";
+  if (agent.status === "running" || agent.status === "initializing") return "Wait";
+  return "Start";
+}
+function Task({ title, view }: { title: string; view: PluginSidebarViewProps }) {
+  const agents = useAgents({
+    where: (item) => agentTask(item) === title,
+    orderBy: ["lastActivityAt", "desc"],
+  });
+  return (
+    <View>
+      <Heading title={title} view={view} />
+      {agents.map((reference) => (
+        <AgentRow key={reference.key} reference={reference} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Agents(view: PluginSidebarViewProps) {
+  return (
+    <ScrollView>
+      <Task title="Respond" view={view} />
+      <Task title="Review" view={view} />
+      <Task title="Wait" view={view} />
+      <Task title="Start" view={view} />
+    </ScrollView>
+  );
+}
@@ -0,0 +1,191 @@
+import { useMutation } from "@tanstack/react-query";
+import { useCallback, useMemo, useState } from "react";
+import { Pressable, ScrollView, Text, View } from "react-native";
+import {
+  usePaseo,
+  useSettings,
+  useWorkspaces,
+  type WorkspaceRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { folders } from "../shared/preferences";
+import { Heading, WorkspaceRow } from "./rows";
+interface Move {
+  reference: WorkspaceRef;
+  from: string | null;
+}
+function folderLabel(key: string): string | null {
+  return key === "unlabelled" ? null : key.slice("label:".length);
+}
+function Movable({
+  reference,
+  folder,
+  view,
+  select,
+}: {
+  reference: WorkspaceRef;
+  folder: string | null;
+  view: PluginSidebarViewProps;
+  select: (move: Move) => void;
+}) {
+  const pick = useCallback(() => select({ reference, from: folder }), [select, reference, folder]);
+  return (
+    <View>
+      <WorkspaceRow reference={reference} view={view} onLongPress={pick} />
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Move workspace ${reference.id}`}
+        onPress={pick}
+      >
+        <Heading title="Move…" view={view} />
+      </Pressable>
+    </View>
+  );
+}
+export function Labels(view: PluginSidebarViewProps) {
+  const paseo = usePaseo();
+  const settings = useSettings(folders);
+  const [selected, select] = useState<Move | null>(null);
+  const groups = useWorkspaces({
+    orderBy: "name",
+    groupBy: (item) =>
+      item.labels.length ? item.labels.map((label) => `label:${label}`) : ["unlabelled"],
+  });
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, paddingHorizontal: 12 }),
+    [view.theme],
+  );
+  const move = useMutation({
+    mutationFn: async (destination: string | null) => {
+      if (!selected) return;
+      const workspace = paseo.workspaces.ref(selected.reference);
+      // Add first: if adding fails the workspace keeps its original folder.
+      if (destination && destination !== selected.from)
+        await workspace.setLabel(destination, { assigned: true });
+      if (selected.from && selected.from !== destination)
+        await workspace.setLabel(selected.from, { assigned: false });
+      select(null);
+    },
+  });
+  const toggle = useCallback(
+    (folder: string) => {
+      if (settings.status !== "ready") return;
+      void settings.save(
+        {
+          collapsed: settings.values.collapsed.includes(folder)
+            ? settings.values.collapsed.filter((item) => item !== folder)
+            : [...settings.values.collapsed, folder],
+        },
+        settings.revision,
+      );
+    },
+    [settings],
+  );
+  const cancel = useCallback(() => select(null), []);
+  if (settings.status === "loading") return <Text style={style}>Loading folders…</Text>;
+  if (settings.status !== "ready")
+    return (
+      <View>
+        <Text style={style}>{settings.error}</Text>
+        <Pressable accessibilityRole="button" onPress={settings.reload}>
+          <Heading title="Reload folders" view={view} />
+        </Pressable>
+        {settings.status === "invalid" ? (
+          <Pressable accessibilityRole="button" onPress={settings.reset}>
+            <Heading title="Reset folders" view={view} />
+          </Pressable>
+        ) : null}
+      </View>
+    );
+  return (
+    <ScrollView>
+      {selected ? (
+        <View>
+          <Text style={style}>Choose a destination folder</Text>
+          <Pressable accessibilityRole="button" onPress={cancel}>
+            <Heading title="Cancel move" view={view} />
+          </Pressable>
+        </View>
+      ) : (
+        <Text style={style}>Long press a workspace or choose Move…</Text>
+      )}
+      {move.error ? <Text style={style}>{move.error.message}</Text> : null}
+      {Array.from(
+        new Set(["label:Inbox", "label:Later", "unlabelled", ...groups.map((group) => group.key)]),
+      ).map((folder) => (
+        <Folder
+          key={folder}
+          folder={folder}
+          view={view}
+          selected={!!selected}
+          pending={move.isPending}
+          move={move.mutate}
+          collapsed={settings.values.collapsed.includes(folder)}
+          toggle={toggle}
+        >
+          {groups
+            .find((group) => group.key === folder)
+            ?.items.map((reference) => (
+              <Movable
+                key={reference.key}
+                reference={reference}
+                folder={folderLabel(folder)}
+                view={view}
+                select={select}
+              />
+            ))}
+        </Folder>
+      ))}
+      {settings.saveError ? <Text style={style}>{settings.saveError}</Text> : null}
+    </ScrollView>
+  );
+}
+function Folder({
+  folder,
+  view,
+  selected,
+  pending,
+  move,
+  collapsed,
+  toggle,
+  children,
+}: {
+  folder: string;
+  view: PluginSidebarViewProps;
+  selected: boolean;
+  pending: boolean;
+  move: (folder: string | null) => void;
+  collapsed: boolean;
+  toggle: (folder: string) => void;
+  children: import("react").ReactNode;
+}) {
+  const toggleFolder = useCallback(() => toggle(folder), [toggle, folder]);
+  const label = folderLabel(folder);
+  const title = label ?? "Unlabelled";
+  const destination = useCallback(() => move(label), [move, label]);
+  return (
+    <View>
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`Toggle ${title}`}
+        onPress={toggleFolder}
+      >
+        <Heading title={`${collapsed ? "▸" : "▾"} ${title}`} view={view} />
+      </Pressable>
+      {selected ? (
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel={label === null ? "Remove current label" : `Move to ${title}`}
+          disabled={pending}
+          onPress={destination}
+        >
+          <Heading
+            title={label === null ? "Remove current label" : `Move to ${title}`}
+            view={view}
+          />
+        </Pressable>
+      ) : null}
+      {collapsed ? null : children}
+    </View>
+  );
+}
@@ -0,0 +1,109 @@
+import { ScrollView, View } from "react-native";
+import {
+  useProjects,
+  useWorkspaces,
+  useAgents,
+  useAgent,
+  type AgentRef,
+  type WorkspaceRef,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+import { AgentRow, ProjectHeading, WorkspaceRow } from "./rows";
+const indent = { paddingLeft: 12 };
+function AgentTree({ reference, view }: { reference: AgentRef; view: PluginSidebarViewProps }) {
+  const agent = useAgent(reference);
+  const children = useAgents({
+    where: (item) =>
+      item.parentAgent?.key === reference.key && item.workspace.key === agent?.workspace.key,
+    orderBy: "createdAt",
+  });
+  return (
+    <View>
+      <AgentRow reference={reference} view={view} />
+      <View style={indent}>
+        {children.map((child) => (
+          <AgentTree key={child.key} reference={child} view={view} />
+        ))}
+      </View>
+    </View>
+  );
+}
+function RootWithParent({
+  reference,
+  parent,
+  workspace,
+  view,
+}: {
+  reference: AgentRef;
+  parent: AgentRef;
+  workspace: WorkspaceRef;
+  view: PluginSidebarViewProps;
+}) {
+  const parents = useAgents({
+    where: (item) => item.ref.key === parent.key && item.workspace.key === workspace.key,
+  });
+  return parents.length > 0 ? null : <AgentTree reference={reference} view={view} />;
+}
+function Root({
+  reference,
+  workspace,
+  view,
+}: {
+  reference: AgentRef;
+  workspace: WorkspaceRef;
+  view: PluginSidebarViewProps;
+}) {
+  const agent = useAgent(reference);
+  if (!agent) return null;
+  return agent.parentAgent ? (
+    <RootWithParent
+      reference={reference}
+      parent={agent.parentAgent}
+      workspace={workspace}
+      view={view}
+    />
+  ) : (
+    <AgentTree reference={reference} view={view} />
+  );
+}
+function Workspace({ reference, view }: { reference: WorkspaceRef; view: PluginSidebarViewProps }) {
+  const agents = useAgents({
+    where: (item) => item.workspace.key === reference.key,
+    orderBy: "createdAt",
+  });
+  return (
+    <View>
+      <WorkspaceRow reference={reference} view={view} />
+      <View style={indent}>
+        {agents.map((agent) => (
+          <Root key={agent.key} reference={agent} workspace={reference} view={view} />
+        ))}
+      </View>
+    </View>
+  );
+}
+function Project({ reference, view }: { reference: ProjectRef; view: PluginSidebarViewProps }) {
+  const workspaces = useWorkspaces({
+    where: (item) => item.project.key === reference.key,
+    orderBy: "name",
+  });
+  return (
+    <View>
+      <ProjectHeading reference={reference} view={view} />
+      {workspaces.map((workspace) => (
+        <Workspace key={workspace.key} reference={workspace} view={view} />
+      ))}
+    </View>
+  );
+}
+export function Nested(view: PluginSidebarViewProps) {
+  const projects = useProjects({ orderBy: "displayName" });
+  return (
+    <ScrollView>
+      {projects.map((reference) => (
+        <Project key={reference.key} reference={reference} view={view} />
+      ))}
+    </ScrollView>
+  );
+}
@@ -0,0 +1,139 @@
+import { useCallback, useMemo } from "react";
+import { Pressable, Text, View } from "react-native";
+import {
+  useWorkspace,
+  useAgent,
+  useProject,
+  type WorkspaceRef,
+  type AgentRef,
+  type ProjectRef,
+  type PluginSidebarViewProps,
+} from "@getpaseo/plugin/client";
+
+export function Heading({ title, view }: { title: string; view: PluginSidebarViewProps }) {
+  const style = useMemo(
+    () => ({
+      color: view.theme.colors.foregroundMuted,
+      fontSize: 11,
+      paddingHorizontal: 12,
+      paddingTop: 12,
+      paddingBottom: 4,
+    }),
+    [view.theme],
+  );
+  return (
+    <Text accessibilityRole="header" style={style}>
+      {title}
+    </Text>
+  );
+}
+export function WorkspaceRow({
+  reference,
+  view,
+  onLongPress,
+}: {
+  reference: WorkspaceRef;
+  view: PluginSidebarViewProps;
+  onLongPress?: () => void;
+}) {
+  const workspace = useWorkspace(reference);
+  const open = useCallback(
+    () => view.navigation.openWorkspace(reference),
+    [view.navigation, reference],
+  );
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12, lineHeight: 16 }),
+    [view.theme],
+  );
+  const detail = useMemo(
+    () => ({ color: view.theme.colors.foregroundMuted, fontSize: 11 }),
+    [view.theme],
+  );
+  const background = useMemo(
+    () => ({
+      ...rowStyle,
+      backgroundColor:
+        view.active.workspace?.key === reference.key ? view.theme.colors.surface2 : undefined,
+    }),
+    [view.active.workspace, view.theme, reference],
+  );
+  if (!workspace) return null;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Open ${workspace.title ?? workspace.name}`}
+      onPress={open}
+      onLongPress={onLongPress}
+      style={background}
+    >
+      <Text numberOfLines={1} style={style}>
+        {workspace.title ?? workspace.name}
+      </Text>
+      <Text numberOfLines={1} style={detail}>
+        {workspace.indicatorLabel}
+      </Text>
+    </Pressable>
+  );
+}
+export function AgentRow({
+  reference,
+  view,
+}: {
+  reference: AgentRef;
+  view: PluginSidebarViewProps;
+}) {
+  const agent = useAgent(reference);
+  const open = useCallback(
+    () => view.navigation.openAgent(reference),
+    [view.navigation, reference],
+  );
+  const style = useMemo(
+    () => ({ color: view.theme.colors.foreground, fontSize: 12 }),
+    [view.theme],
+  );
+  if (!agent) return null;
+  return (
+    <Pressable
+      accessibilityRole="button"
+      accessibilityLabel={`Open agent ${agent.title ?? agent.provider}`}
+      onPress={open}
+      style={rowStyle}
+    >
+      <Text numberOfLines={1} style={style}>
+        {agent.title ?? agent.provider}
+      </Text>
+    </Pressable>
+  );
+}
+export function ProjectHeading({
+  reference,
+  view,
+}: {
+  reference: ProjectRef;
+  view: PluginSidebarViewProps;
+}) {
+  const project = useProject(reference);
+  const open = useCallback(
+    () => view.navigation.openProject(reference),
+    [view.navigation, reference],
+  );
+  if (!project) return null;
+  return (
+    <View>
+      <Heading title={project.displayName} view={view} />
+      <Pressable
+        accessibilityRole="button"
+        accessibilityLabel={`New workspace in ${project.displayName}`}
+        onPress={open}
+      >
+        <Heading title="+ New workspace" view={view} />
+      </Pressable>
+    </View>
+  );
+}
+const rowStyle = {
+  minHeight: 28,
+  paddingHorizontal: 12,
+  paddingVertical: 4,
+  justifyContent: "center",
+} as const;
@@ -1,54 +1,37 @@
-import { useCallback, useMemo } from "react";
+import { ScrollView, View } from "react-native";
 import {
-  useWorkspace,
+  useProjects,
  useWorkspaces,
-  type WorkspaceRef,
+  type ProjectRef,
  type PluginSidebarViewProps,
 } from "@getpaseo/plugin/client";
-import { Pressable, ScrollView, Text } from "react-native";
-
-function WorkspaceRow({
-  reference,
-  view,
-}: {
-  reference: WorkspaceRef;
-  view: PluginSidebarViewProps;
-}) {
-  const workspace = useWorkspace(reference);
-  const open = useCallback(
-    () => view.navigation.openWorkspace(reference),
-    [view.navigation, reference],
-  );
-  const textStyle = useMemo(
-    () => ({ color: view.theme.colors.foreground, fontSize: 12, lineHeight: 16 }),
-    [view.theme],
-  );
-  const labelStyle = useMemo(
-    () => ({ color: view.theme.colors.foregroundMuted, fontSize: 11 }),
-    [view.theme],
-  );
-  if (!workspace) return null;
+import { Heading, ProjectHeading, WorkspaceRow } from "./rows";
+function Project({ reference, view }: { reference: ProjectRef; view: PluginSidebarViewProps }) {
+  const workspaces = useWorkspaces({
+    where: (item) => item.project.key === reference.key && !item.pinnedAt,
+    orderBy: "name",
+  });
  return (
-    <Pressable
-      accessibilityRole="button"
-      accessibilityLabel={`Open ${workspace.name}`}
-      onPress={open}
-      style={rowStyle}
-    >
-      <Text style={textStyle}>{workspace.title ?? workspace.name}</Text>
-      <Text style={labelStyle}>{workspace.indicatorLabel}</Text>
-    </Pressable>
+    <View>
+      <ProjectHeading reference={reference} view={view} />
+      {workspaces.map((workspace) => (
+        <WorkspaceRow key={workspace.key} reference={workspace} view={view} />
+      ))}
+    </View>
  );
 }
 export function Workspaces(view: PluginSidebarViewProps) {
-  const workspaces = useWorkspaces({ orderBy: "name" });
+  const projects = useProjects({ orderBy: "displayName" });
+  const pinned = useWorkspaces({ where: (item) => !!item.pinnedAt, orderBy: "name" });
  return (
    <ScrollView>
-      {workspaces.map((reference) => (
+      {pinned.length ? <Heading title="Pinned" view={view} /> : null}
+      {pinned.map((reference) => (
        <WorkspaceRow key={reference.key} reference={reference} view={view} />
      ))}
+      {projects.map((reference) => (
+        <Project key={reference.key} reference={reference} view={view} />
+      ))}
    </ScrollView>
  );
 }
-
-const rowStyle = { minHeight: 28, paddingHorizontal: 12, justifyContent: "center" } as const;
@@ -1,10 +1,16 @@
 import type { PluginClientContext } from "@getpaseo/plugin/client";
 import { Workspaces } from "./client/workspaces";
-
+import { Agents } from "./client/agents";
+import { Nested } from "./client/nested";
+import { Labels } from "./client/labels";
 export default function contribute(client: PluginClientContext) {
-  return client.addSidebarView({
-    id: "workspaces",
-    title: "Example workspaces",
-    Component: Workspaces,
-  });
+  const cleanups = [
+    client.addSidebarView({ id: "workspaces", title: "Example workspaces", Component: Workspaces }),
+    client.addSidebarView({ id: "agents", title: "Example agents", Component: Agents }),
+    client.addSidebarView({ id: "nested", title: "Example nested agents", Component: Nested }),
+    client.addSidebarView({ id: "labels", title: "Example label folders", Component: Labels }),
+  ];
+  return () => {
+    for (const cleanup of cleanups) void cleanup();
+  };
 }
@@ -0,0 +1,8 @@
+import { defineSettings } from "@getpaseo/plugin";
+import { z } from "zod";
+export const folders = defineSettings({
+  id: "folders",
+  scope: "device",
+  version: 1,
+  schema: z.object({ collapsed: z.array(z.string()).default([]) }),
+});