@nextclaw/ui 0.14.1 → 0.14.2

package/src/features/chat/features/input/input-surface-plugins/__tests__/panel-app-reference-plugin.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, it } from 'vitest';
+import { resolveChatInputSurfaceState } from '@nextclaw/agent-chat-ui';
+import { createPanelAppReferenceInputSurfacePlugin, PANEL_APP_REFERENCE_TRIGGER_SPEC } from '@/features/chat/features/input/input-surface-plugins/panel-app-reference-plugin.utils';
+import type { PanelAppEntryView } from '@/shared/lib/api';
+
+function createPanelApp(overrides: Partial<PanelAppEntryView> & Pick<PanelAppEntryView, 'appId' | 'title'>): PanelAppEntryView {
+  return {
+    id: overrides.id ?? overrides.appId,
+    appId: overrides.appId,
+    fileName: overrides.fileName ?? `${overrides.appId}.panel.html`,
+    kind: overrides.kind ?? 'single-file',
+    title: overrides.title,
+    description: overrides.description,
+    contentPath: overrides.contentPath ?? `/panels/${overrides.appId}.panel.html`,
+    createdAt: overrides.createdAt ?? '2026-06-18T00:00:00.000Z',
+    updatedAt: overrides.updatedAt ?? '2026-06-18T00:00:00.000Z',
+    sizeBytes: overrides.sizeBytes ?? 100,
+    favorite: overrides.favorite ?? false,
+    clientDeclared: overrides.clientDeclared ?? false,
+    clientGranted: overrides.clientGranted ?? false,
+    lastOpenedAt: overrides.lastOpenedAt,
+    openCount: overrides.openCount ?? 0,
+  };
+}
+
+describe('panel app reference input surface plugin', () => {
+  it('returns panel app reference items for @ trigger queries', () => {
+    const plugin = createPanelAppReferenceInputSurfacePlugin({
+      itemTexts: {
+        appIdLabel: 'App ID',
+        fileLabel: 'File',
+        noDescriptionLabel: 'No description',
+        subtitle: 'Panel App',
+      },
+      menuTexts: {
+        loadingLabel: 'Loading',
+        sectionLabel: 'Panel Apps',
+        emptyLabel: 'Empty',
+        hintLabel: 'Type @',
+        itemHintLabel: 'Enter to reference',
+      },
+    });
+
+    const state = resolveChatInputSurfaceState({
+      plugins: [plugin],
+      trigger: {
+        ...PANEL_APP_REFERENCE_TRIGGER_SPEC,
+        query: 'task',
+        start: 0,
+        end: 5,
+      },
+      data: {
+        isPanelAppsLoading: false,
+        isSkillsLoading: false,
+        panelApps: [
+          createPanelApp({
+            appId: 'task-board',
+            title: 'Task Board',
+            description: 'Track tasks',
+          }),
+        ],
+        recentSkillValues: [],
+        skillRecords: [],
+      },
+    });
+
+    expect(state.panel?.items).toEqual([
+      expect.objectContaining({
+        key: 'panel-app:task-board',
+        title: 'Task Board',
+        tokenKind: 'panel_app',
+        tokenKey: 'task-board',
+        value: 'task-board',
+      }),
+    ]);
+  });
+});

package/src/features/chat/features/input/input-surface-plugins/__tests__/slash-command-plugin.test.ts

@@ -0,0 +1,108 @@
+import { describe, expect, it, vi } from 'vitest';
+import { resolveChatInputSurfaceState } from '@nextclaw/agent-chat-ui';
+import { createSlashCommandInputSurfacePlugin } from '@/features/chat/features/input/input-surface-plugins/slash-command-plugin.utils';
+
+function createPlugin(onSelectCommand = vi.fn()) {
+  return createSlashCommandInputSurfacePlugin({
+    commands: [
+      {
+        key: 'side-chat',
+        title: 'Side chat',
+        description: 'Open side chat',
+        detailLines: ['Creates a child session on first send'],
+        keywords: ['side', 'chat'],
+        onSelect: onSelectCommand,
+      },
+    ],
+    itemTexts: {
+      noSkillDescription: 'No description',
+      slashSkillScopeLabel: 'Scope',
+      slashSkillSpecLabel: 'Spec',
+      slashSkillSubtitle: 'Skill',
+    },
+    labels: {
+      commandHintLabel: 'Run command',
+      commandSectionLabel: 'Commands',
+      commandSubtitle: 'Command',
+      skillHintLabel: 'Add skill',
+      skillSectionLabel: 'Skills',
+    },
+    menuTexts: {
+      emptyLabel: 'No result',
+      hintLabel: 'Type /',
+      itemHintLabel: 'Select item',
+      loadingLabel: 'Loading',
+      sectionLabel: 'Slash',
+    },
+    onSelectSkill: vi.fn(),
+  });
+}
+
+describe('createSlashCommandInputSurfacePlugin', () => {
+  it('places command items before skill items in the slash panel', () => {
+    const state = resolveChatInputSurfaceState({
+      data: {
+        isPanelAppsLoading: false,
+        isSkillsLoading: false,
+        panelApps: [],
+        recentSkillValues: [],
+        skillRecords: [
+          {
+            key: 'web-search',
+            label: 'Web Search',
+            description: 'Search web',
+          },
+        ],
+      },
+      plugins: [createPlugin()],
+      trigger: {
+        key: 'slash',
+        marker: '/',
+        query: '',
+        start: 0,
+        end: 1,
+      },
+    });
+
+    expect(state.panel?.items.map((item) => item.key)).toEqual([
+      'command:side-chat',
+      'skill:web-search',
+    ]);
+    expect(state.panel?.items[0]).toMatchObject({
+      sectionKey: 'commands',
+      sectionLabel: 'Commands',
+      hintLabel: 'Run command',
+    });
+    expect(state.panel?.items[1]).toMatchObject({
+      sectionKey: 'skills',
+      sectionLabel: 'Skills',
+      hintLabel: 'Add skill',
+    });
+  });
+
+  it('runs a command item through the panel selection handler', () => {
+    const onSelectCommand = vi.fn();
+    const state = resolveChatInputSurfaceState({
+      data: {
+        isPanelAppsLoading: false,
+        isSkillsLoading: false,
+        panelApps: [],
+        recentSkillValues: [],
+        skillRecords: [],
+      },
+      plugins: [createPlugin(onSelectCommand)],
+      trigger: {
+        key: 'slash',
+        marker: '/',
+        query: 'side',
+        start: 0,
+        end: 5,
+      },
+    });
+
+    const item = state.panel?.items[0];
+    expect(item?.key).toBe('command:side-chat');
+    state.panel?.onSelectItem?.(item!);
+    expect(onSelectCommand).toHaveBeenCalledTimes(1);
+  });
+});

package/src/features/chat/features/input/input-surface-plugins/chat-input-product-plugin-adapters.types.ts

@@ -0,0 +1,10 @@
+import type { ChatSkillRecord } from '@/features/chat/types/chat-input-bar.types';
+import type { PanelAppEntryView } from '@/shared/lib/api';
+
+export type ChatInputProductPluginData = {
+  isPanelAppsLoading: boolean;
+  isSkillsLoading: boolean;
+  panelApps: readonly PanelAppEntryView[];
+  recentSkillValues: readonly string[];
+  skillRecords: readonly ChatSkillRecord[];
+};

package/src/features/chat/features/input/input-surface-plugins/input-surface-search.utils.ts

@@ -0,0 +1,108 @@
+const INPUT_SURFACE_MATCH_SCORE = {
+  exactId: 1200,
+  exactLabel: 1150,
+  prefixId: 1000,
+  prefixLabel: 950,
+  prefixToken: 900,
+  containsId: 800,
+  containsLabel: 760,
+  containsDescription: 500,
+  subsequence: 300,
+  fallback: 1,
+} as const;
+
+export type InputSurfaceSearchCandidate = {
+  id: string;
+  label: string;
+  description?: string;
+  aliases?: readonly string[];
+};
+
+export function normalizeInputSurfaceSearchText(value: string | null | undefined): string {
+  return (value ?? '').trim().toLowerCase();
+}
+
+export function buildInputSurfaceRecentOrderIndex(values: readonly string[]): Map<string, number> {
+  return new Map(values.map((value, index) => [value, index] as const));
+}
+
+function isSubsequenceMatch(query: string, target: string): boolean {
+  if (!query || !target) {
+    return false;
+  }
+  let pointer = 0;
+  for (const char of target) {
+    if (char === query[pointer]) {
+      pointer += 1;
+      if (pointer >= query.length) {
+        return true;
+      }
+    }
+  }
+  return false;
+}
+
+export function scoreInputSurfaceSearchCandidate(
+  candidate: InputSurfaceSearchCandidate,
+  query: string,
+): number {
+  const normalizedQuery = normalizeInputSurfaceSearchText(query);
+  if (!normalizedQuery) {
+    return INPUT_SURFACE_MATCH_SCORE.fallback;
+  }
+
+  const id = normalizeInputSurfaceSearchText(candidate.id);
+  const label = normalizeInputSurfaceSearchText(candidate.label || candidate.id);
+  const description = normalizeInputSurfaceSearchText(candidate.description);
+  const aliases = (candidate.aliases ?? []).map(normalizeInputSurfaceSearchText).filter(Boolean);
+  const labelTokens = label.split(/[\s/_-]+/).filter(Boolean);
+  const idCandidates = [id, ...aliases];
+
+  if (idCandidates.some((value) => value === normalizedQuery)) {
+    return INPUT_SURFACE_MATCH_SCORE.exactId;
+  }
+  if (label === normalizedQuery) {
+    return INPUT_SURFACE_MATCH_SCORE.exactLabel;
+  }
+  if (idCandidates.some((value) => value.startsWith(normalizedQuery))) {
+    return INPUT_SURFACE_MATCH_SCORE.prefixId;
+  }
+  if (label.startsWith(normalizedQuery)) {
+    return INPUT_SURFACE_MATCH_SCORE.prefixLabel;
+  }
+  if (labelTokens.some((token) => token.startsWith(normalizedQuery))) {
+    return INPUT_SURFACE_MATCH_SCORE.prefixToken;
+  }
+  if (idCandidates.some((value) => value.includes(normalizedQuery))) {
+    return INPUT_SURFACE_MATCH_SCORE.containsId;
+  }
+  if (label.includes(normalizedQuery)) {
+    return INPUT_SURFACE_MATCH_SCORE.containsLabel;
+  }
+  if (description.includes(normalizedQuery)) {
+    return INPUT_SURFACE_MATCH_SCORE.containsDescription;
+  }
+  if (
+    isSubsequenceMatch(normalizedQuery, label) ||
+    idCandidates.some((value) => isSubsequenceMatch(normalizedQuery, value))
+  ) {
+    return INPUT_SURFACE_MATCH_SCORE.subsequence;
+  }
+  return 0;
+}
+
+export function resolveInputSurfaceMatchTier(score: number): number {
+  if (score >= INPUT_SURFACE_MATCH_SCORE.exactLabel) {
+    return 4;
+  }
+  if (score >= INPUT_SURFACE_MATCH_SCORE.prefixToken) {
+    return 3;
+  }
+  if (score >= INPUT_SURFACE_MATCH_SCORE.containsLabel) {
+    return 2;
+  }
+  if (score > 0) {
+    return 1;
+  }
+  return 0;
+}

package/src/features/chat/features/input/input-surface-plugins/panel-app-reference-plugin.utils.ts

@@ -0,0 +1,108 @@
+import {
+  createInputSurfaceReferenceTokenPlugin,
+  type ChatInputSurfaceItem,
+  type ChatInputSurfaceMenuTexts,
+  type ChatInputSurfacePlugin,
+  type ChatInputSurfaceTriggerSpec,
+} from '@nextclaw/agent-chat-ui';
+import type { ChatInputProductPluginData } from './chat-input-product-plugin-adapters.types';
+import type { PanelAppEntryView } from '@/shared/lib/api';
+import {
+  scoreInputSurfaceSearchCandidate,
+  resolveInputSurfaceMatchTier,
+} from './input-surface-search.utils';
+
+export const PANEL_APP_REFERENCE_TRIGGER_SPEC: ChatInputSurfaceTriggerSpec = {
+  key: 'panel-app-reference',
+  marker: '@',
+};
+
+function getPanelAppActivityTime(entry: PanelAppEntryView): number {
+  return Date.parse(entry.lastOpenedAt ?? entry.updatedAt) || 0;
+}
+
+function buildPanelAppReferenceItems(params: {
+  entries: readonly PanelAppEntryView[];
+  query: string;
+  texts: {
+    appIdLabel: string;
+    fileLabel: string;
+    noDescriptionLabel: string;
+    subtitle: string;
+  };
+}): ChatInputSurfaceItem[] {
+  const collator = new Intl.Collator(undefined, { sensitivity: 'base', numeric: true });
+  return params.entries
+    .map((entry, order) => ({
+      entry,
+      order,
+      score: scoreInputSurfaceSearchCandidate(
+        {
+          id: entry.appId,
+          label: entry.title || entry.appId,
+          description: entry.description,
+          aliases: [entry.id, entry.fileName],
+        },
+        params.query,
+      ),
+    }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => {
+      const leftTier = resolveInputSurfaceMatchTier(left.score);
+      const rightTier = resolveInputSurfaceMatchTier(right.score);
+      if (rightTier !== leftTier) {
+        return rightTier - leftTier;
+      }
+      if (left.entry.favorite !== right.entry.favorite) {
+        return left.entry.favorite ? -1 : 1;
+      }
+      const rightActivity = getPanelAppActivityTime(right.entry);
+      const leftActivity = getPanelAppActivityTime(left.entry);
+      if (rightActivity !== leftActivity) {
+        return rightActivity - leftActivity;
+      }
+      if (right.score !== left.score) {
+        return right.score - left.score;
+      }
+      const labelCompare = collator.compare(left.entry.title || left.entry.appId, right.entry.title || right.entry.appId);
+      return labelCompare || left.order - right.order;
+    })
+    .map(({ entry }) => ({
+      key: `panel-app:${entry.appId}`,
+      title: entry.title || entry.appId,
+      subtitle: params.texts.subtitle,
+      description: (entry.description ?? '').trim() || params.texts.noDescriptionLabel,
+      detailLines: [
+        `${params.texts.appIdLabel}: ${entry.appId}`,
+        `${params.texts.fileLabel}: ${entry.fileName}`,
+      ],
+      tokenKind: 'panel_app',
+      tokenKey: entry.appId,
+      value: entry.appId,
+    }));
+}
+
+export function createPanelAppReferenceInputSurfacePlugin(params: {
+  itemTexts: {
+    appIdLabel: string;
+    fileLabel: string;
+    noDescriptionLabel: string;
+    subtitle: string;
+  };
+  menuTexts: ChatInputSurfaceMenuTexts;
+}): ChatInputSurfacePlugin<ChatInputProductPluginData> {
+  return createInputSurfaceReferenceTokenPlugin({
+    key: 'panel-app-reference',
+    trigger: PANEL_APP_REFERENCE_TRIGGER_SPEC,
+    tokenKind: 'panel_app',
+    texts: params.menuTexts,
+    getIsLoading: ({ data }) => data.isPanelAppsLoading,
+    getRecords: ({ data }) => data.panelApps,
+    getItems: ({ records, query }) =>
+      buildPanelAppReferenceItems({
+        entries: records,
+        query,
+        texts: params.itemTexts,
+      }),
+  });
+}

package/src/features/chat/features/input/input-surface-plugins/slash-command-plugin.utils.ts

@@ -0,0 +1,161 @@
+import {
+  CHAT_INPUT_SURFACE_SLASH_TRIGGER_SPEC,
+  createInputSurfaceTriggeredPanelPlugin,
+  type ChatInputSurfaceItem,
+  type ChatInputSurfaceMenuTexts,
+  type ChatInputSurfacePlugin,
+} from '@nextclaw/agent-chat-ui';
+import { buildChatSlashItems } from '@/features/chat/features/input/utils/chat-input-bar.utils';
+import type { ChatInputProductPluginData } from './chat-input-product-plugin-adapters.types';
+import type { ChatInputBarAdapterTexts } from '@/features/chat/types/chat-input-bar.types';
+import {
+  resolveInputSurfaceMatchTier,
+  scoreInputSurfaceSearchCandidate,
+} from './input-surface-search.utils';
+
+const SLASH_COMMAND_SECTION_KEY = 'commands';
+const SLASH_SKILL_SECTION_KEY = 'skills';
+
+export type ChatSlashCommandDescriptor = {
+  key: string;
+  title: string;
+  description: string;
+  detailLines?: readonly string[];
+  keywords?: readonly string[];
+  onSelect: () => void;
+};
+
+function buildSlashCommandItems(params: {
+  commands: readonly ChatSlashCommandDescriptor[];
+  query: string;
+  texts: {
+    commandHintLabel: string;
+    commandSubtitle: string;
+    commandSectionLabel: string;
+  };
+}): ChatInputSurfaceItem[] {
+  const collator = new Intl.Collator(undefined, { sensitivity: 'base', numeric: true });
+  return params.commands
+    .map((command, order) => ({
+      command,
+      order,
+      score: scoreInputSurfaceSearchCandidate(
+        {
+          id: command.key,
+          label: command.title,
+          description: command.description,
+          aliases: command.keywords,
+        },
+        params.query,
+      ),
+    }))
+    .filter((entry) => entry.score > 0)
+    .sort((left, right) => {
+      const leftTier = resolveInputSurfaceMatchTier(left.score);
+      const rightTier = resolveInputSurfaceMatchTier(right.score);
+      if (rightTier !== leftTier) {
+        return rightTier - leftTier;
+      }
+      if (right.score !== left.score) {
+        return right.score - left.score;
+      }
+      return collator.compare(left.command.title, right.command.title) || left.order - right.order;
+    })
+    .map(({ command }) => ({
+      key: `command:${command.key}`,
+      title: command.title,
+      subtitle: params.texts.commandSubtitle,
+      description: command.description,
+      detailLines: [...(command.detailLines ?? [])],
+      hintLabel: params.texts.commandHintLabel,
+      sectionKey: SLASH_COMMAND_SECTION_KEY,
+      sectionLabel: params.texts.commandSectionLabel,
+    }));
+}
+
+function buildSlashSkillItems(params: {
+  data: ChatInputProductPluginData;
+  itemTexts: Pick<
+    ChatInputBarAdapterTexts,
+    'slashSkillSubtitle' | 'slashSkillSpecLabel' | 'slashSkillScopeLabel' | 'noSkillDescription'
+  >;
+  skillHintLabel: string;
+  skillSectionLabel: string;
+  query: string;
+}): ChatInputSurfaceItem[] {
+  const {
+    data,
+    itemTexts,
+    query,
+    skillHintLabel,
+    skillSectionLabel,
+  } = params;
+  return buildChatSlashItems(
+    [...data.skillRecords],
+    query,
+    itemTexts,
+    [...data.recentSkillValues],
+  ).map((item) => ({
+    ...item,
+    hintLabel: skillHintLabel,
+    sectionKey: SLASH_SKILL_SECTION_KEY,
+    sectionLabel: skillSectionLabel,
+  }));
+}
+
+export function createSlashCommandInputSurfacePlugin(params: {
+  commands: readonly ChatSlashCommandDescriptor[];
+  menuTexts: ChatInputSurfaceMenuTexts;
+  itemTexts: Pick<
+    ChatInputBarAdapterTexts,
+    'slashSkillSubtitle' | 'slashSkillSpecLabel' | 'slashSkillScopeLabel' | 'noSkillDescription'
+  >;
+  labels: {
+    commandHintLabel: string;
+    commandSectionLabel: string;
+    commandSubtitle: string;
+    skillHintLabel: string;
+    skillSectionLabel: string;
+  };
+  onSelectSkill?: (skillRef: string) => void;
+}): ChatInputSurfacePlugin<ChatInputProductPluginData> {
+  return createInputSurfaceTriggeredPanelPlugin({
+    key: 'slash-command',
+    trigger: CHAT_INPUT_SURFACE_SLASH_TRIGGER_SPEC,
+    resolvePanel: (context) => {
+      const { data, trigger } = context;
+      return {
+        isLoading: data.isSkillsLoading,
+        items: [
+          ...buildSlashCommandItems({
+            commands: params.commands,
+            query: trigger.query,
+            texts: {
+              commandHintLabel: params.labels.commandHintLabel,
+              commandSectionLabel: params.labels.commandSectionLabel,
+              commandSubtitle: params.labels.commandSubtitle,
+            },
+          }),
+          ...buildSlashSkillItems({
+            data,
+            itemTexts: params.itemTexts,
+            query: trigger.query,
+            skillHintLabel: params.labels.skillHintLabel,
+            skillSectionLabel: params.labels.skillSectionLabel,
+          }),
+        ],
+        onSelectItem: (item) => {
+          if (item.key.startsWith('command:')) {
+            params.commands.find((command) => item.key === `command:${command.key}`)?.onSelect();
+            return;
+          }
+          const skillRef = item.tokenKey ?? item.value;
+          if (skillRef) {
+            params.onSelectSkill?.(skillRef);
+          }
+        },
+        texts: params.menuTexts,
+      };
+    },
+  });
+}

package/src/features/chat/features/input/utils/__tests__/chat-composer-state.utils.test.ts

@@ -1,5 +1,5 @@
 import { createChatComposerTextNode, createChatComposerTokenNode } from '@nextclaw/agent-chat-ui';
-import { deriveNcpMessagePartsFromComposer } from '../chat-composer-state.utils';
+import { deriveNcpMessagePartsFromComposer } from '@/features/chat/features/input/utils/chat-composer-state.utils';
 
 describe('deriveNcpMessagePartsFromComposer', () => {
   it('preserves interleaved text and image token order while serializing skill tokens inline', () => {
@@ -68,6 +68,27 @@ describe('deriveNcpMessagePartsFromComposer', () => {
     ]);
   });
 
+  it('serializes panel app tokens as inline panel app references', () => {
+    expect(
+      deriveNcpMessagePartsFromComposer(
+        [
+          createChatComposerTextNode('review '),
+          createChatComposerTokenNode({
+            tokenKind: 'panel_app',
+            tokenKey: 'task-board',
+            label: 'Task Board'
+          })
+        ],
+        []
+      )
+    ).toEqual([
+      {
+        type: 'text',
+        text: 'review @panel-app:task-board'
+      }
+    ]);
+  });
+
   it('preserves uploaded attachment references when the attachment has a server uri', () => {
     const parts = deriveNcpMessagePartsFromComposer(
       [

package/src/features/chat/features/input/utils/__tests__/chat-inline-token.utils.test.ts

@@ -1,10 +1,11 @@
 import { createChatComposerTextNode, createChatComposerTokenNode } from '@nextclaw/agent-chat-ui';
 import {
+  buildInlineTokensFromTextProtocol,
   buildInlineSkillTokensFromComposer,
   CHAT_UI_INLINE_TOKENS_METADATA_KEY,
   readInlineTokensFromMetadata,
-  splitTextByInlineTokens
-} from '../chat-inline-token.utils';
+  resolveInlineTokensForText
+} from '@/features/chat/features/input/utils/chat-inline-token.utils';
 
 describe('chat-inline-token utils', () => {
   it('builds ordered inline skill tokens from composer nodes', () => {
@@ -60,9 +61,9 @@ describe('chat-inline-token utils', () => {
     ]);
   });
 
-  it('splits text into inline text and token fragments', () => {
+  it('merges metadata tokens with pure text protocol tokens', () => {
     expect(
-      splitTextByInlineTokens('please use $weather now', [
+      resolveInlineTokensForText('please use $weather and @panel-app:task-board', [
         {
           kind: 'skill',
           key: 'weather',
@@ -71,17 +72,29 @@ describe('chat-inline-token utils', () => {
         }
       ])
     ).toEqual([
-      { type: 'text', text: 'please use ' },
       {
-        type: 'token',
-        token: {
-          kind: 'skill',
-          key: 'weather',
-          label: 'Weather',
-          rawText: '$weather'
-        }
+        kind: 'skill',
+        key: 'weather',
+        label: 'Weather',
+        rawText: '$weather'
       },
-      { type: 'text', text: ' now' }
+      {
+        kind: 'panel_app',
+        key: 'task-board',
+        label: 'task-board',
+        rawText: '@panel-app:task-board'
+      }
+    ]);
+  });
+
+  it('builds inline panel app tokens from pure text protocol', () => {
+    expect(buildInlineTokensFromTextProtocol('review @panel-app:task-board now')).toEqual([
+      {
+        kind: 'panel_app',
+        key: 'task-board',
+        label: 'task-board',
+        rawText: '@panel-app:task-board'
+      }
     ]);
   });
 });