@nextclaw/ui 0.13.1 → 0.13.3

package/src/features/side-dock/components/side-dock.tsx

@@ -0,0 +1,117 @@
+import { AppWindow, BookOpen, Boxes, Plus } from 'lucide-react';
+import type { LucideIcon } from 'lucide-react';
+import type { SideDockManager } from '@/features/side-dock/managers/side-dock.manager';
+import { SIDE_DOCK_BUILT_IN_ITEMS } from '@/features/side-dock/configs/side-dock-built-in-items.config';
+import { useSideDockStore } from '@/features/side-dock/stores/side-dock.store';
+import type {
+  SideDockIconName,
+  SideDockItem,
+  SideDockItemIcon,
+} from '@/features/side-dock/types/side-dock.types';
+import { mergeSideDockItems } from '@/features/side-dock/utils/side-dock-item.utils';
+import {
+  useDocBrowser,
+  type DocBrowserTab,
+} from '@/shared/components/doc-browser/doc-browser-context';
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipProvider,
+  TooltipTrigger,
+} from '@/shared/components/ui/tooltip';
+import { t } from '@/shared/lib/i18n';
+import { cn } from '@/shared/lib/utils';
+
+type SideDockProps = {
+  manager: SideDockManager;
+};
+
+const SIDE_DOCK_ICON_COMPONENTS: Record<SideDockIconName, LucideIcon> = {
+  apps: Boxes,
+  docs: BookOpen,
+  'new-tab': Plus,
+  'service-apps': AppWindow,
+};
+
+function SideDockItemIconView({ icon }: { icon: SideDockItemIcon }) {
+  if (icon.type === 'url') {
+    return <img src={icon.url} alt="" className="h-5 w-5 rounded object-cover" />;
+  }
+
+  const Icon = SIDE_DOCK_ICON_COMPONENTS[icon.name];
+  return <Icon className="h-5 w-5" aria-hidden="true" />;
+}
+
+function SideDockButton({
+  active,
+  item,
+  onOpen,
+}: {
+  active: boolean;
+  item: SideDockItem;
+  onOpen: (item: SideDockItem) => void;
+}) {
+  const label = t(item.labelKey);
+
+  return (
+    <Tooltip>
+      <TooltipTrigger asChild>
+        <button
+          type="button"
+          aria-label={label}
+          title={label}
+          data-side-dock-item-id={item.id}
+          onClick={() => onOpen(item)}
+          className={cn(
+            'flex h-10 w-10 shrink-0 items-center justify-center rounded-lg text-muted-foreground transition-colors',
+            'hover:bg-primary/10 hover:text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring',
+            active
+              ? 'bg-primary/10 text-primary'
+              : 'bg-transparent',
+          )}
+        >
+          <SideDockItemIconView icon={item.icon} />
+        </button>
+      </TooltipTrigger>
+      <TooltipContent side="left">{label}</TooltipContent>
+    </Tooltip>
+  );
+}
+
+function isSideDockItemActive(
+  item: SideDockItem,
+  isDocBrowserOpen: boolean,
+  currentTab?: DocBrowserTab,
+): boolean {
+  if (!isDocBrowserOpen || !currentTab) {
+    return false;
+  }
+  if (currentTab.currentUrl === item.target.uri) {
+    return true;
+  }
+  return item.id === 'docs' && currentTab.kind === 'docs';
+}
+
+export function SideDock({ manager }: SideDockProps) {
+  const pinnedItems = useSideDockStore((state) => state.pinnedItems);
+  const { currentTab, isOpen } = useDocBrowser();
+  const items = mergeSideDockItems(SIDE_DOCK_BUILT_IN_ITEMS, pinnedItems);
+
+  return (
+    <TooltipProvider delayDuration={250}>
+      <aside
+        data-testid="side-dock"
+        className="z-30 flex h-full w-14 shrink-0 flex-col items-center gap-1 border-l border-border/60 bg-background/95 px-2 py-3"
+      >
+        {items.map((item) => (
+          <SideDockButton
+            key={item.id}
+            active={isSideDockItemActive(item, isOpen, currentTab)}
+            item={item}
+            onOpen={manager.openItem}
+          />
+        ))}
+      </aside>
+    </TooltipProvider>
+  );
+}

package/src/features/side-dock/configs/side-dock-built-in-items.config.ts

@@ -0,0 +1,43 @@
+import {
+  RIGHT_PANEL_APPS_URL,
+  RIGHT_PANEL_HOME_URL,
+  RIGHT_PANEL_SERVICE_APPS_URL,
+} from '@/features/right-panel-resources';
+import type { SideDockItem } from '@/features/side-dock/types/side-dock.types';
+
+export const SIDE_DOCK_DOCS_URL = 'nextclaw://docs';
+
+export const SIDE_DOCK_BUILT_IN_ITEMS: SideDockItem[] = [
+  {
+    builtIn: true,
+    icon: { type: 'builtin', name: 'apps' },
+    id: 'apps',
+    labelKey: 'appsTitle',
+    removable: false,
+    target: { type: 'right-panel-resource', uri: RIGHT_PANEL_APPS_URL },
+  },
+  {
+    builtIn: true,
+    icon: { type: 'builtin', name: 'service-apps' },
+    id: 'service-apps',
+    labelKey: 'serviceAppsTitle',
+    removable: false,
+    target: { type: 'right-panel-resource', uri: RIGHT_PANEL_SERVICE_APPS_URL },
+  },
+  {
+    builtIn: true,
+    icon: { type: 'builtin', name: 'docs' },
+    id: 'docs',
+    labelKey: 'docBrowserHelp',
+    removable: false,
+    target: { type: 'right-panel-resource', uri: SIDE_DOCK_DOCS_URL },
+  },
+  {
+    builtIn: true,
+    icon: { type: 'builtin', name: 'new-tab' },
+    id: 'new-tab',
+    labelKey: 'docBrowserHomeTitle',
+    removable: false,
+    target: { type: 'right-panel-resource', uri: RIGHT_PANEL_HOME_URL },
+  },
+];

package/src/features/side-dock/index.ts

@@ -0,0 +1,10 @@
+export { SideDock } from '@/features/side-dock/components/side-dock';
+export { SideDockManager } from '@/features/side-dock/managers/side-dock.manager';
+export type {
+  SideDockIconName,
+  SideDockItem,
+  SideDockItemIcon,
+  SideDockItemId,
+  SideDockItemTarget,
+  SideDockPinnedItem,
+} from '@/features/side-dock/types/side-dock.types';

package/src/features/side-dock/managers/side-dock.manager.test.ts

@@ -0,0 +1,62 @@
+import { beforeEach, describe, expect, it, vi } from 'vitest';
+import { SideDockManager } from '@/features/side-dock/managers/side-dock.manager';
+import { useSideDockStore } from '@/features/side-dock/stores/side-dock.store';
+import type { SideDockItem } from '@/features/side-dock/types/side-dock.types';
+import type { DocBrowserManager } from '@/shared/components/doc-browser/managers/doc-browser.manager';
+
+const customItem: SideDockItem = {
+  builtIn: false,
+  icon: { type: 'builtin', name: 'docs' },
+  id: 'custom-docs',
+  labelKey: 'docBrowserHelp',
+  removable: true,
+  target: { type: 'right-panel-resource', uri: 'nextclaw://docs/custom' },
+};
+
+describe('SideDockManager', () => {
+  beforeEach(() => {
+    window.localStorage.clear();
+    useSideDockStore.getState().setPinnedItems([]);
+  });
+
+  it('opens right panel resource items through DocBrowserManager', () => {
+    const open = vi.fn();
+    const manager = new SideDockManager({ open } as unknown as DocBrowserManager);
+
+    manager.openItem(customItem);
+
+    expect(open).toHaveBeenCalledWith('nextclaw://docs/custom');
+  });
+
+  it('pins removable items and keeps built-in items immutable', () => {
+    const manager = new SideDockManager({ open: vi.fn() } as unknown as DocBrowserManager);
+
+    manager.pinItem(customItem, '2026-06-02T00:00:00.000Z');
+    manager.pinItem({ ...customItem, builtIn: true, id: 'built-in-copy', removable: false });
+
+    expect(useSideDockStore.getState().pinnedItems).toEqual([
+      {
+        createdAt: '2026-06-02T00:00:00.000Z',
+        icon: { type: 'builtin', name: 'docs' },
+        id: 'custom-docs',
+        labelKey: 'docBrowserHelp',
+        target: { type: 'right-panel-resource', uri: 'nextclaw://docs/custom' },
+      },
+    ]);
+  });
+
+  it('unpins and reorders pinned items', () => {
+    const manager = new SideDockManager({ open: vi.fn() } as unknown as DocBrowserManager);
+
+    manager.pinItem(customItem, '2026-06-02T00:00:00.000Z');
+    manager.pinItem({
+      ...customItem,
+      id: 'custom-apps',
+      target: { type: 'right-panel-resource', uri: 'nextclaw://apps/custom' },
+    }, '2026-06-02T00:00:01.000Z');
+    manager.reorderPinnedItems(['custom-apps', 'custom-docs']);
+    manager.unpinItem('custom-docs');
+
+    expect(useSideDockStore.getState().pinnedItems.map((item) => item.id)).toEqual(['custom-apps']);
+  });
+});

package/src/features/side-dock/managers/side-dock.manager.ts

@@ -0,0 +1,58 @@
+import { SIDE_DOCK_BUILT_IN_ITEMS } from '@/features/side-dock/configs/side-dock-built-in-items.config';
+import { useSideDockStore } from '@/features/side-dock/stores/side-dock.store';
+import type { SideDockItem, SideDockPinnedItem } from '@/features/side-dock/types/side-dock.types';
+import {
+  createPinnedSideDockItem,
+  mergeSideDockItems,
+} from '@/features/side-dock/utils/side-dock-item.utils';
+import type { DocBrowserManager } from '@/shared/components/doc-browser/managers/doc-browser.manager';
+
+export class SideDockManager {
+  constructor(private readonly docBrowserManager: DocBrowserManager) {}
+
+  readonly getItems = (): SideDockItem[] => mergeSideDockItems(
+    SIDE_DOCK_BUILT_IN_ITEMS,
+    useSideDockStore.getState().pinnedItems,
+  );
+
+  readonly openItem = (item: Pick<SideDockItem, 'target'>): void => {
+    if (item.target.type === 'right-panel-resource') {
+      this.docBrowserManager.open(item.target.uri);
+    }
+  };
+
+  readonly pinItem = (item: SideDockItem, createdAt: string = new Date().toISOString()): void => {
+    if (!item.removable) {
+      return;
+    }
+    this.setPinnedItems((items) => {
+      if (items.some((pinnedItem) => pinnedItem.id === item.id || pinnedItem.target.uri === item.target.uri)) {
+        return items;
+      }
+      return [...items, createPinnedSideDockItem(item, createdAt)];
+    });
+  };
+
+  readonly unpinItem = (itemId: string): void => {
+    this.setPinnedItems((items) => items.filter((item) => item.id !== itemId));
+  };
+
+  readonly reorderPinnedItems = (itemIds: string[]): void => {
+    this.setPinnedItems((items) => {
+      const itemsById = new Map(items.map((item) => [item.id, item]));
+      const orderedItems = itemIds
+        .map((id) => itemsById.get(id))
+        .filter((item): item is SideDockPinnedItem => item !== undefined);
+      const orderedIds = new Set(orderedItems.map((item) => item.id));
+      const remainingItems = items.filter((item) => !orderedIds.has(item.id));
+      return [...orderedItems, ...remainingItems];
+    });
+  };
+
+  private readonly setPinnedItems = (
+    updater: (items: SideDockPinnedItem[]) => SideDockPinnedItem[],
+  ): void => {
+    const { pinnedItems, setPinnedItems } = useSideDockStore.getState();
+    setPinnedItems(updater(pinnedItems));
+  };
+}

package/src/features/side-dock/stores/side-dock.store.ts

@@ -0,0 +1,42 @@
+import { create } from 'zustand';
+import { createJSONStorage, persist } from 'zustand/middleware';
+import type { SideDockPinnedItem } from '@/features/side-dock/types/side-dock.types';
+import { normalizeSideDockPinnedItems } from '@/features/side-dock/utils/side-dock-item.utils';
+
+const SIDE_DOCK_STORAGE_KEY = 'nextclaw.side-dock.state';
+const SIDE_DOCK_STORAGE_VERSION = 1;
+
+type SideDockStore = {
+  pinnedItems: SideDockPinnedItem[];
+  setPinnedItems: (items: SideDockPinnedItem[]) => void;
+};
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object';
+}
+
+export const useSideDockStore = create<SideDockStore>()(
+  persist(
+    (set) => ({
+      pinnedItems: [],
+      setPinnedItems: (items) => set({ pinnedItems: normalizeSideDockPinnedItems(items) }),
+    }),
+    {
+      name: SIDE_DOCK_STORAGE_KEY,
+      version: SIDE_DOCK_STORAGE_VERSION,
+      storage: createJSONStorage(() => window.localStorage),
+      partialize: (state) => ({
+        pinnedItems: state.pinnedItems,
+      }),
+      merge: (persistedState, currentState) => {
+        const pinnedItems = isRecord(persistedState)
+          ? normalizeSideDockPinnedItems(persistedState.pinnedItems)
+          : [];
+        return {
+          ...currentState,
+          pinnedItems,
+        };
+      },
+    },
+  ),
+);

package/src/features/side-dock/types/side-dock.types.ts

@@ -0,0 +1,29 @@
+export type SideDockItemId = string;
+
+export type SideDockItemTarget = {
+  type: 'right-panel-resource';
+  uri: string;
+};
+
+export type SideDockIconName = 'apps' | 'docs' | 'new-tab' | 'service-apps';
+
+export type SideDockItemIcon =
+  | { type: 'builtin'; name: SideDockIconName }
+  | { type: 'url'; url: string };
+
+export type SideDockItem = {
+  builtIn: boolean;
+  icon: SideDockItemIcon;
+  id: SideDockItemId;
+  labelKey: string;
+  removable: boolean;
+  target: SideDockItemTarget;
+};
+
+export type SideDockPinnedItem = {
+  createdAt: string;
+  icon: SideDockItemIcon;
+  id: SideDockItemId;
+  labelKey: string;
+  target: SideDockItemTarget;
+};

package/src/features/side-dock/utils/side-dock-item.utils.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import type { SideDockItem } from '@/features/side-dock/types/side-dock.types';
+import {
+  mergeSideDockItems,
+  normalizeSideDockPinnedItem,
+  normalizeSideDockPinnedItems,
+} from '@/features/side-dock/utils/side-dock-item.utils';
+
+const builtInItem: SideDockItem = {
+  builtIn: true,
+  icon: { type: 'builtin', name: 'apps' },
+  id: 'apps',
+  labelKey: 'appsTitle',
+  removable: false,
+  target: { type: 'right-panel-resource', uri: 'nextclaw://apps' },
+};
+
+describe('side-dock-item utils', () => {
+  it('normalizes persisted pinned items and drops malformed entries', () => {
+    const items = normalizeSideDockPinnedItems([
+      {
+        createdAt: '2026-06-02T00:00:00.000Z',
+        icon: { type: 'builtin', name: 'docs' },
+        id: 'docs-custom',
+        labelKey: 'docBrowserHelp',
+        target: { type: 'right-panel-resource', uri: 'nextclaw://docs' },
+      },
+      {
+        createdAt: '2026-06-02T00:00:00.000Z',
+        icon: { type: 'builtin', name: 'unknown' },
+        id: 'bad-icon',
+        labelKey: 'bad',
+        target: { type: 'right-panel-resource', uri: 'nextclaw://bad' },
+      },
+    ]);
+
+    expect(items).toEqual([
+      {
+        createdAt: '2026-06-02T00:00:00.000Z',
+        icon: { type: 'builtin', name: 'docs' },
+        id: 'docs-custom',
+        labelKey: 'docBrowserHelp',
+        target: { type: 'right-panel-resource', uri: 'nextclaw://docs' },
+      },
+    ]);
+  });
+
+  it('rejects invalid single pinned item payloads', () => {
+    expect(normalizeSideDockPinnedItem({ id: 'missing-fields' })).toBeNull();
+    expect(normalizeSideDockPinnedItem(null)).toBeNull();
+  });
+
+  it('keeps built-ins first and ignores pinned duplicates', () => {
+    const items = mergeSideDockItems(
+      [builtInItem],
+      [
+        {
+          createdAt: '2026-06-02T00:00:00.000Z',
+          icon: { type: 'builtin', name: 'docs' },
+          id: 'docs-custom',
+          labelKey: 'docBrowserHelp',
+          target: { type: 'right-panel-resource', uri: 'nextclaw://docs' },
+        },
+        {
+          createdAt: '2026-06-02T00:00:00.000Z',
+          icon: { type: 'builtin', name: 'apps' },
+          id: 'apps-copy',
+          labelKey: 'appsTitle',
+          target: { type: 'right-panel-resource', uri: 'nextclaw://apps' },
+        },
+      ],
+    );
+
+    expect(items.map((item) => item.id)).toEqual(['apps', 'docs-custom']);
+    expect(items[1]?.removable).toBe(true);
+  });
+});

package/src/features/side-dock/utils/side-dock-item.utils.ts

@@ -0,0 +1,126 @@
+import type {
+  SideDockIconName,
+  SideDockItem,
+  SideDockItemIcon,
+  SideDockPinnedItem,
+} from '@/features/side-dock/types/side-dock.types';
+
+const SIDE_DOCK_BUILTIN_ICON_NAMES: SideDockIconName[] = [
+  'apps',
+  'docs',
+  'new-tab',
+  'service-apps',
+];
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return !!value && typeof value === 'object';
+}
+
+function isSideDockIconName(value: unknown): value is SideDockIconName {
+  return SIDE_DOCK_BUILTIN_ICON_NAMES.includes(value as SideDockIconName);
+}
+
+function normalizeSideDockIcon(value: unknown): SideDockItemIcon | null {
+  if (!isRecord(value) || typeof value.type !== 'string') {
+    return null;
+  }
+
+  if (value.type === 'builtin' && isSideDockIconName(value.name)) {
+    return {
+      type: 'builtin',
+      name: value.name,
+    };
+  }
+
+  if (value.type === 'url' && typeof value.url === 'string' && value.url.trim().length > 0) {
+    return {
+      type: 'url',
+      url: value.url.trim(),
+    };
+  }
+
+  return null;
+}
+
+export function normalizeSideDockPinnedItem(value: unknown): SideDockPinnedItem | null {
+  if (
+    !isRecord(value)
+    || typeof value.id !== 'string'
+    || value.id.trim().length === 0
+    || typeof value.labelKey !== 'string'
+    || value.labelKey.trim().length === 0
+    || typeof value.createdAt !== 'string'
+    || value.createdAt.trim().length === 0
+    || !isRecord(value.target)
+    || value.target.type !== 'right-panel-resource'
+    || typeof value.target.uri !== 'string'
+    || value.target.uri.trim().length === 0
+  ) {
+    return null;
+  }
+
+  const icon = normalizeSideDockIcon(value.icon);
+  if (!icon) {
+    return null;
+  }
+
+  return {
+    createdAt: value.createdAt,
+    icon,
+    id: value.id.trim(),
+    labelKey: value.labelKey.trim(),
+    target: {
+      type: 'right-panel-resource',
+      uri: value.target.uri.trim(),
+    },
+  };
+}
+
+export function normalizeSideDockPinnedItems(value: unknown): SideDockPinnedItem[] {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+
+  const itemsById = new Map<string, SideDockPinnedItem>();
+  value.forEach((item) => {
+    const normalized = normalizeSideDockPinnedItem(item);
+    if (normalized) {
+      itemsById.set(normalized.id, normalized);
+    }
+  });
+  return Array.from(itemsById.values());
+}
+
+export function createPinnedSideDockItem(item: SideDockItem, createdAt: string): SideDockPinnedItem {
+  return {
+    createdAt,
+    icon: item.icon,
+    id: item.id,
+    labelKey: item.labelKey,
+    target: item.target,
+  };
+}
+
+export function createSideDockItemFromPinnedItem(item: SideDockPinnedItem): SideDockItem {
+  return {
+    builtIn: false,
+    icon: item.icon,
+    id: item.id,
+    labelKey: item.labelKey,
+    removable: true,
+    target: item.target,
+  };
+}
+
+export function mergeSideDockItems(
+  builtInItems: SideDockItem[],
+  pinnedItems: SideDockPinnedItem[],
+): SideDockItem[] {
+  const seenIds = new Set(builtInItems.map((item) => item.id));
+  const seenUris = new Set(builtInItems.map((item) => item.target.uri));
+  const customItems = pinnedItems
+    .filter((item) => !seenIds.has(item.id) && !seenUris.has(item.target.uri))
+    .map(createSideDockItemFromPinnedItem);
+
+  return [...builtInItems, ...customItems];
+}

package/src/platforms/desktop/components/desktop-app-shell.tsx

@@ -21,6 +21,7 @@ type DesktopAppShellProps = {
   isDocBrowserOpen: boolean;
   docBrowserMode: "floating" | "docked";
   docBrowserRenderers?: DocBrowserCustomTabRenderers;
+  sideDock?: React.ReactNode;
   children: React.ReactNode;
 };
 
@@ -30,6 +31,7 @@ export function DesktopAppShell({
   isDocBrowserOpen,
   docBrowserMode,
   docBrowserRenderers = {},
+  sideDock,
   children,
 }: DesktopAppShellProps) {
   const isMainRoute = isMainWorkspaceRoute(pathname);
@@ -68,6 +70,7 @@ export function DesktopAppShell({
               <DocBrowser customTabRenderers={docBrowserRenderers} />
             </Suspense>
           ) : null}
+          {sideDock}
         </div>
       </div>
       {showMobileBottomNav ? <MobileBottomNav /> : null}