@tuturuuu/ui 0.23.0 → 0.25.0

package/src/components/ui/chat/query-keys.ts

@@ -13,13 +13,19 @@ export const chatQueryKeys = {
     ] as const,
   conversations: (wsId: string, archived = 'active') =>
     [...chatQueryKeys.all(wsId), 'conversations', archived] as const,
-  conversationsInfinite: (wsId: string, archived = 'active', limit = 40) =>
+  conversationsInfinite: (
+    wsId: string,
+    archived = 'active',
+    limit = 40,
+    scope: 'all' | 'external' = 'all'
+  ) =>
     [
       ...chatQueryKeys.all(wsId),
       'conversations',
       archived,
       'infinite',
       limit,
+      scope,
     ] as const,
   directory: (wsId: string, query: string) =>
     [...chatQueryKeys.all(wsId), 'directory', query] as const,

package/src/components/ui/chat/selection.ts

@@ -8,7 +8,7 @@ type RouterLike = {
   replace: (href: string, options?: { scroll?: boolean }) => void;
 };
 
-export type ChatDetailsTarget = 'agent' | null;
+export type ChatDetailsTarget = 'agent' | 'external' | null;
 
 export function buildChatSelectionHref({
   conversationId,

package/src/components/ui/chat/utils.ts

@@ -5,9 +5,16 @@ import type {
   ChatUserProfile,
 } from '@tuturuuu/internal-api';
 
-export type ChatConversationScope = 'personal' | 'workspaces';
+export type ChatConversationScope = 'external' | 'personal' | 'workspaces';
 export type ChatConversationArchiveFilter = 'active' | 'all' | 'archived';
 
+export type ChatConversationDeliveryState =
+  | 'deleted'
+  | 'failed'
+  | 'seen'
+  | 'sending'
+  | 'sent';
+
 export const DEFAULT_CHAT_SCOPE: ChatConversationScope = 'personal';
 export const CHAT_CONVERSATION_TYPE_FILTERS = [
   'direct',
@@ -16,15 +23,54 @@ export const CHAT_CONVERSATION_TYPE_FILTERS = [
   'ai',
 ] as const satisfies ChatConversationType[];
 
+export type PendingChatSendRequest = {
+  fingerprint: string;
+  requestId: string;
+};
+
+export function resolvePendingChatSendRequest(
+  previous: PendingChatSendRequest | null,
+  payload: {
+    attachments: Array<{
+      filename: string;
+      path: string;
+      sizeBytes?: number | null;
+    }>;
+    content: string;
+  },
+  createRequestId: () => string
+): PendingChatSendRequest {
+  const fingerprint = JSON.stringify({
+    attachments: payload.attachments.map((attachment) => ({
+      filename: attachment.filename,
+      path: attachment.path,
+      sizeBytes: attachment.sizeBytes,
+    })),
+    content: payload.content,
+  });
+
+  return previous?.fingerprint === fingerprint
+    ? previous
+    : { fingerprint, requestId: createRequestId() };
+}
+
 export function normalizeChatConversationScope(
-  scope?: string | null
+  scope?: string | null,
+  fallback: ChatConversationScope = 'personal'
 ): ChatConversationScope {
-  return scope === 'workspaces' ? 'workspaces' : 'personal';
+  if (scope === 'external' || scope === 'personal' || scope === 'workspaces') {
+    return scope;
+  }
+  return fallback;
 }
 
 export function getChatConversationScope(
   conversation: Pick<ChatConversation, 'metadata' | 'type'>
 ): ChatConversationScope {
+  if (conversation.metadata?.externalChat === true) {
+    return 'external';
+  }
+
   if (conversation.metadata?.scope === 'personal') {
     return 'personal';
   }
@@ -48,6 +94,40 @@ export function getChatConversationScope(
   return 'workspaces';
 }
 
+export function getChatConversationQueueDetails(
+  conversation: Pick<
+    ChatConversation,
+    'latestMessage' | 'metadata' | 'updatedAt'
+  >
+) {
+  const latestMessage = conversation.latestMessage;
+  const phone = readNonEmptyString(conversation.metadata.phone);
+
+  return {
+    deliveryState: latestMessage
+      ? getChatConversationDeliveryState(latestMessage)
+      : null,
+    phone,
+    preview: latestMessage?.deletedAt
+      ? null
+      : (readNonEmptyString(latestMessage?.content) ??
+        readNonEmptyString(latestMessage?.attachments[0]?.filename)),
+    timestamp: latestMessage?.createdAt ?? conversation.updatedAt,
+  };
+}
+
+export function getChatConversationDeliveryState(
+  message: Pick<ChatMessage, 'deletedAt' | 'metadata'>
+): ChatConversationDeliveryState {
+  if (message.deletedAt) return 'deleted';
+
+  const status = readNonEmptyString(message.metadata.status)?.toLowerCase();
+  if (status && /fail|error|reject/u.test(status)) return 'failed';
+  if (status && /seen|read/u.test(status)) return 'seen';
+  if (status && /pending|queue|sending/u.test(status)) return 'sending';
+  return 'sent';
+}
+
 export function isChatConversation(value: unknown): value is ChatConversation {
   const conversation = value as Partial<ChatConversation> | null | undefined;
 
@@ -63,6 +143,8 @@ export function isChatConversation(value: unknown): value is ChatConversation {
 export function getChatConversationTypesForScope(
   scope: ChatConversationScope
 ): ChatConversationType[] {
+  if (scope === 'external') return ['channel'];
+
   return scope === 'personal'
     ? ['direct', 'group', 'channel', 'ai']
     : ['channel', 'ai'];
@@ -115,6 +197,35 @@ export function getChatInitials(profile?: ChatUserProfile | string | null) {
     .slice(0, 2);
 }
 
+export function getChatMessageSenderLabel(
+  message: Pick<ChatMessage, 'kind' | 'metadata' | 'sender'>,
+  fallback: { assistant: string; external: string; unknown: string }
+) {
+  const nativeDisplayName = readNonEmptyString(message.sender?.displayName);
+  if (nativeDisplayName) return nativeDisplayName;
+  if (message.kind === 'assistant') return fallback.assistant;
+
+  const externalSender = message.metadata?.externalSender;
+  if (isRecord(externalSender)) {
+    const displayName =
+      readNonEmptyString(externalSender.displayName) ??
+      readNonEmptyString(externalSender.name);
+    if (displayName) return displayName;
+  }
+
+  return message.metadata?.externalChat === true
+    ? fallback.external
+    : fallback.unknown;
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function readNonEmptyString(value: unknown) {
+  return typeof value === 'string' && value.trim() ? value.trim() : null;
+}
+
 export function getConversationTitle(
   conversation: ChatConversation,
   currentUserId: string,
@@ -237,6 +348,18 @@ export function isReadOnlyChatConversation(
   );
 }
 
+export function canPersistChatReadState({
+  externalChat,
+  hasMembership,
+  readOnly,
+}: {
+  externalChat: boolean;
+  hasMembership: boolean;
+  readOnly: boolean;
+}) {
+  return !readOnly && (hasMembership || externalChat);
+}
+
 export function getChatSelectionStorageKey(
   wsId: string,
   scope: ChatConversationScope

package/src/components/ui/custom/__tests__/workspace-select-helpers.test.ts

@@ -3,10 +3,82 @@ import { join } from 'node:path';
 import type { InternalApiWorkspaceSummary } from '@tuturuuu/types';
 import { describe, expect, it } from 'vitest';
 import {
+  buildWorkspaceSetupHandoffUrl,
   mergeWorkspaceSelectWorkspaces,
   normalizeWorkspaceSwitchPath,
+  resolveWorkspaceAvatarUrl,
 } from '../workspace-select-helpers';
 
+describe('buildWorkspaceSetupHandoffUrl', () => {
+  it('builds a localized Platform setup URL with an encoded satellite return', () => {
+    const handoffUrl = new URL(
+      buildWorkspaceSetupHandoffUrl({
+        locale: 'vi',
+        platformUrl: 'https://tuturuuu.com',
+        returnOrigin: 'https://tasks.tuturuuu.com',
+        returnPath: '/workspace-1/tasks?view=mine',
+        workspaceId: 'workspace-1',
+      })
+    );
+
+    expect(handoffUrl.pathname).toBe('/vi/workspace-1/workspace-setup');
+    expect(handoffUrl.searchParams.get('returnUrl')).toBe(
+      'https://tasks.tuturuuu.com/vi/workspace-1/tasks?view=mine'
+    );
+  });
+
+  it('does not duplicate an existing locale prefix', () => {
+    const handoffUrl = new URL(
+      buildWorkspaceSetupHandoffUrl({
+        locale: 'en',
+        platformUrl: 'http://platform.tuturuuu.localhost',
+        returnOrigin: 'http://meet.tuturuuu.localhost',
+        returnPath: '/en/workspace/workspace-1',
+        workspaceId: 'workspace-1',
+      })
+    );
+
+    expect(handoffUrl.searchParams.get('returnUrl')).toBe(
+      'http://meet.tuturuuu.localhost/en/workspace/workspace-1'
+    );
+  });
+
+  it('rejects a return path that changes the satellite origin', () => {
+    expect(() =>
+      buildWorkspaceSetupHandoffUrl({
+        locale: 'en',
+        platformUrl: 'https://tuturuuu.com',
+        returnOrigin: 'https://tasks.tuturuuu.com',
+        returnPath: 'https://evil.example/workspace-1',
+        workspaceId: 'workspace-1',
+      })
+    ).toThrow('Workspace return path must stay on the current app');
+  });
+});
+
+describe('resolveWorkspaceAvatarUrl', () => {
+  it('preserves a valid hosted avatar when an app provides a local fallback', () => {
+    expect(
+      resolveWorkspaceAvatarUrl(
+        'https://tuturuuu.com/media/logos/transparent.png',
+        {
+          rootWorkspaceLogoUrl: '/media/logos/transparent.png',
+        }
+      )
+    ).toBe('https://tuturuuu.com/media/logos/transparent.png');
+  });
+
+  it('uses the canonical root logo only when the root workspace has no avatar', () => {
+    expect(
+      resolveWorkspaceAvatarUrl(null, {
+        rootWorkspaceLogoUrl:
+          'https://tuturuuu.com/media/logos/transparent.png',
+      })
+    ).toBe('https://tuturuuu.com/media/logos/transparent.png');
+    expect(resolveWorkspaceAvatarUrl(null)).toBeNull();
+  });
+});
+
 describe('mergeWorkspaceSelectWorkspaces', () => {
   it('uses the current workspace fallback when the workspace list is unavailable', () => {
     const fallback: InternalApiWorkspaceSummary = {

package/src/components/ui/custom/onboarding-settings-panel.tsx

@@ -0,0 +1,131 @@
+'use client';
+
+import { MessageSquareText, Play, RotateCcw } from '@tuturuuu/icons';
+import { updateConnectedOnboardingProgress } from '@tuturuuu/internal-api/onboarding';
+import { Button } from '@tuturuuu/ui/button';
+import {
+  getLaunchableApp,
+  getLaunchableAppByHostname,
+  resolveLaunchableAppUrl,
+} from '@tuturuuu/utils/launchable-apps';
+import { useTranslations } from 'next-intl';
+import { useState } from 'react';
+
+function currentAppSlug() {
+  if (typeof window === 'undefined') return 'platform';
+  return (
+    getLaunchableAppByHostname(window.location.hostname)?.slug ?? 'platform'
+  );
+}
+
+function closeSettingsDialog() {
+  window.dispatchEvent(new Event('tuturuuu:settings-dialog-close-intent'));
+}
+
+export function OnboardingSettingsPanel() {
+  const t = useTranslations('onboarding_guide');
+  const [pending, setPending] = useState<'replay' | 'restart' | null>(null);
+
+  const replayApp = async () => {
+    const appSlug = currentAppSlug();
+    setPending('replay');
+    await updateConnectedOnboardingProgress({
+      dismissed_at: null,
+      replay_app: appSlug,
+    }).catch(() => null);
+    setPending(null);
+    closeSettingsDialog();
+    window.dispatchEvent(
+      new CustomEvent('tuturuuu:onboarding-replay', { detail: { appSlug } })
+    );
+  };
+
+  const restartJourney = async () => {
+    setPending('restart');
+    await updateConnectedOnboardingProgress({
+      completed_missions: [],
+      dismissed_at: null,
+      goals: [],
+      guidance_mode: 'standard',
+      journey_revision: 2,
+      persona: null,
+      replay_app: 'platform',
+    }).catch(() => null);
+
+    const platform = getLaunchableApp('platform');
+    if (!platform) return;
+    window.location.assign(
+      resolveLaunchableAppUrl({
+        app: platform,
+        currentOrigin: window.location.origin,
+        path: '/personal',
+        searchParams: { guide: 'platform' },
+      })
+    );
+  };
+
+  const shareFeedback = () => {
+    closeSettingsDialog();
+    window.dispatchEvent(
+      new CustomEvent('tuturuuu:report-problem-open-intent', {
+        detail: { context: `onboarding:${currentAppSlug()}` },
+      })
+    );
+  };
+
+  const actions = [
+    {
+      description: t('replay_app_description'),
+      icon: Play,
+      label: t('replay_app'),
+      onClick: replayApp,
+      pending: pending === 'replay',
+    },
+    {
+      description: t('restart_journey_description'),
+      icon: RotateCcw,
+      label: t('restart_journey'),
+      onClick: restartJourney,
+      pending: pending === 'restart',
+    },
+    {
+      description: t('feedback_description'),
+      icon: MessageSquareText,
+      label: t('feedback'),
+      onClick: shareFeedback,
+      pending: false,
+    },
+  ];
+
+  return (
+    <div className="space-y-3">
+      {actions.map((action) => (
+        <div
+          key={action.label}
+          className="flex flex-col gap-4 rounded-xl border p-4 sm:flex-row sm:items-center sm:justify-between"
+        >
+          <div className="flex gap-3">
+            <div className="grid size-9 shrink-0 place-items-center rounded-lg border bg-muted/40">
+              <action.icon className="size-4" />
+            </div>
+            <div>
+              <p className="font-medium text-sm">{action.label}</p>
+              <p className="mt-1 max-w-xl text-muted-foreground text-sm">
+                {action.description}
+              </p>
+            </div>
+          </div>
+          <Button
+            type="button"
+            variant="outline"
+            disabled={action.pending}
+            onClick={action.onClick}
+          >
+            <action.icon className="size-4" />
+            {action.label}
+          </Button>
+        </div>
+      ))}
+    </div>
+  );
+}

package/src/components/ui/custom/settings-dialog-shell.tsx

@@ -4,6 +4,7 @@ import {
   ArrowLeft,
   ChevronDown,
   ChevronRight,
+  Compass,
   Search,
   X,
 } from '@tuturuuu/icons';
@@ -63,6 +64,7 @@ import { useTranslations } from 'next-intl';
 import { parseAsString, useQueryState } from 'nuqs';
 import type { ComponentType, KeyboardEvent, ReactNode } from 'react';
 import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { OnboardingSettingsPanel } from './onboarding-settings-panel';
 import type { createSettingsSearchEngine } from './settings-dialog-search';
 import { loadSettingsSearchEngine } from './settings-dialog-search-loader';
 
@@ -158,17 +160,41 @@ export function SettingsDialogShell({
     })
   );
 
+  const extendedNavItems = useMemo<SettingsNavGroup[]>(
+    () => [
+      ...navItems,
+      {
+        label: t('onboarding_guide.title'),
+        items: [
+          {
+            name: 'onboarding_guide',
+            label: t('onboarding_guide.title'),
+            description: t('onboarding_guide.description'),
+            icon: Compass,
+            keywords: [
+              t('onboarding_guide.replay_app'),
+              t('onboarding_guide.restart_journey'),
+            ],
+          },
+        ],
+      },
+    ],
+    [navItems, t]
+  );
+
   const searchEngine = useMemo<SettingsSearchEngine | null>(
-    () => searchEngineFactory?.(navItems) ?? null,
-    [navItems, searchEngineFactory]
+    () => searchEngineFactory?.(extendedNavItems) ?? null,
+    [extendedNavItems, searchEngineFactory]
   );
 
   const allNavItems = useMemo(
-    () => searchEngine?.allItems ?? navItems.flatMap((group) => group.items),
-    [navItems, searchEngine]
+    () =>
+      searchEngine?.allItems ??
+      extendedNavItems.flatMap((group) => group.items),
+    [extendedNavItems, searchEngine]
   );
 
-  const activeGroup = navItems.find((group) =>
+  const activeGroup = extendedNavItems.find((group) =>
     group.items.some((item) => item.name === activeTab)
   );
 
@@ -209,8 +235,10 @@ export function SettingsDialogShell({
 
   const filteredNavItems = useMemo(
     () =>
-      searchQuery ? (searchEngine?.search(searchQuery) ?? navItems) : navItems,
-    [navItems, searchEngine, searchQuery]
+      searchQuery
+        ? (searchEngine?.search(searchQuery) ?? extendedNavItems)
+        : extendedNavItems,
+    [extendedNavItems, searchEngine, searchQuery]
   );
 
   const filteredEnabledItems = useMemo(
@@ -221,6 +249,11 @@ export function SettingsDialogShell({
       ),
     [filteredNavItems, searchEngine, searchQuery]
   );
+  const keyboardEnabledItems = useMemo(
+    () =>
+      filteredEnabledItems.filter((item) => item.name !== 'onboarding_guide'),
+    [filteredEnabledItems]
+  );
 
   const updateSearchQuery = useCallback(
     (value: string) => {
@@ -252,30 +285,30 @@ export function SettingsDialogShell({
 
   const changeActiveItem = useCallback(
     (targetIndex: number) => {
-      const targetItem = filteredEnabledItems[targetIndex];
+      const targetItem = keyboardEnabledItems[targetIndex];
       if (targetItem) selectActiveTab(targetItem.name);
     },
-    [filteredEnabledItems, selectActiveTab]
+    [keyboardEnabledItems, selectActiveTab]
   );
 
   const moveActiveItem = useCallback(
     (direction: 1 | -1) => {
-      if (filteredEnabledItems.length === 0) return;
+      if (keyboardEnabledItems.length === 0) return;
 
-      const currentIndex = filteredEnabledItems.findIndex(
+      const currentIndex = keyboardEnabledItems.findIndex(
         (item) => item.name === activeTab
       );
       const nextIndex =
         currentIndex === -1
           ? direction === 1
             ? 0
-            : filteredEnabledItems.length - 1
-          : (currentIndex + direction + filteredEnabledItems.length) %
-            filteredEnabledItems.length;
+            : keyboardEnabledItems.length - 1
+          : (currentIndex + direction + keyboardEnabledItems.length) %
+            keyboardEnabledItems.length;
 
       changeActiveItem(nextIndex);
     },
-    [activeTab, changeActiveItem, filteredEnabledItems]
+    [activeTab, changeActiveItem, keyboardEnabledItems]
   );
 
   const handleKeyboardNavigation = useCallback(
@@ -325,12 +358,12 @@ export function SettingsDialogShell({
 
       if (event.key === 'End') {
         event.preventDefault();
-        changeActiveItem(filteredEnabledItems.length - 1);
+        changeActiveItem(keyboardEnabledItems.length - 1);
       }
     },
     [
       changeActiveItem,
-      filteredEnabledItems.length,
+      keyboardEnabledItems.length,
       focusSearch,
       keyboardNavigation,
       moveActiveItem,
@@ -569,7 +602,11 @@ export function SettingsDialogShell({
                   <Separator />
                 </>
               )}
-              {children}
+              {activeTab === 'onboarding_guide' ? (
+                <OnboardingSettingsPanel />
+              ) : (
+                children
+              )}
             </div>
           </div>
         </main>

package/src/components/ui/custom/workspace-select-helpers.ts

@@ -1,5 +1,16 @@
 import type { InternalApiWorkspaceSummary } from '@tuturuuu/types';
 
+export function resolveWorkspaceAvatarUrl(
+  avatarUrl: string | null | undefined,
+  {
+    rootWorkspaceLogoUrl,
+  }: {
+    rootWorkspaceLogoUrl?: string;
+  } = {}
+) {
+  return avatarUrl || rootWorkspaceLogoUrl || null;
+}
+
 export function mergeWorkspaceSelectWorkspaces(
   workspaces: InternalApiWorkspaceSummary[] | undefined,
   currentWorkspaceFallback: InternalApiWorkspaceSummary | null | undefined
@@ -19,6 +30,45 @@ export function mergeWorkspaceSelectWorkspaces(
   return [...workspaceList, currentWorkspaceFallback];
 }
 
+export function buildWorkspaceSetupHandoffUrl({
+  locale,
+  platformUrl,
+  returnOrigin,
+  returnPath,
+  workspaceId,
+}: {
+  locale: string;
+  platformUrl: string;
+  returnOrigin: string;
+  returnPath: string;
+  workspaceId: string;
+}) {
+  const origin = new URL(returnOrigin).origin;
+  const returnUrl = new URL(returnPath, origin);
+
+  if (returnUrl.origin !== origin) {
+    throw new Error('Workspace return path must stay on the current app');
+  }
+
+  const localePrefix = `/${locale}`;
+  if (
+    returnUrl.pathname !== localePrefix &&
+    !returnUrl.pathname.startsWith(`${localePrefix}/`)
+  ) {
+    returnUrl.pathname = `${localePrefix}${
+      returnUrl.pathname.startsWith('/') ? '' : '/'
+    }${returnUrl.pathname}`;
+  }
+
+  const setupUrl = new URL(
+    `/${locale}/${encodeURIComponent(workspaceId)}/workspace-setup`,
+    platformUrl
+  );
+  setupUrl.searchParams.set('returnUrl', returnUrl.toString());
+
+  return setupUrl.toString();
+}
+
 export function normalizeWorkspaceSwitchPath(
   pathname: string,
   nextSlug: string