@hiyve/react-collaboration

Chat, polls, Q&A, and file management components for Hiyve.

Installation

npx @hiyve/cli login
npm install @hiyve/react-collaboration
Copy

Quick Start

import { ChatPanel, PollsWindow, QAPanel, FileManager } from '@hiyve/react-collaboration';
import { HiyveProvider } from '@hiyve/react';

function CollaborationSidebar() {
  return (
    <HiyveProvider generateRoomToken={generateRoomToken}>
      <ChatPanel maxHeight={400} />
      <PollsWindow />
      <QAPanel />
      <FileManager />
    </HiyveProvider>
  );
}
Copy

Components

Chat

Chat Hub

Polls

Q&A

File Manager

File Session Host

FileSessionHost is the unified host for opening a file in the right editor. Pair it with editors from @hiyve/react-notes, @hiyve/react-clips, @hiyve/react-assignments, and @hiyve/react-whiteboard to host them inside a sidebar tab or as a fullscreen modal.

import { FileSessionHost } from '@hiyve/react-collaboration';
import { NoteEditor } from '@hiyve/react-notes';
import { Whiteboard } from '@hiyve/react-whiteboard';
import { ClipComposition } from '@hiyve/react-clips';
import { AssignmentEditor } from '@hiyve/react-assignments';
import { Folder as FolderIcon } from '@mui/icons-material';

const editors = {
  note: NoteEditor,
  whiteboard: Whiteboard,
  'clip-composition': ClipComposition,
  assignment: AssignmentEditor,
};

function NotesTab() {
  const [openFile, setOpenFile] = useState(null);

  return (
    <FileSessionHost
      variant="inline"
      file={openFile}
      onClose={() => setOpenFile(null)}
      onFileOpen={setOpenFile}
      editors={editors}
      emptyState={{
        icon: <FolderIcon />,
        filterFileType: 'note',
        onCreate: () => openCreateDialog(),
      }}
      onError={(error) => console.error(error)}
    />
  );
}
Copy

FileSessionHost Props

FileSessionEmptyStateConfig

Room File Scope

<FileCacheProvider>
  <RoomFileScope>
    <FileManager />
  </RoomFileScope>
</FileCacheProvider>
Copy

RoomFileScope Props

useRoomFileScope Hook

Returns the current room file scope context, or null when not inside a RoomFileScope.

Public Files

FileManager supports a public file pool alongside the user's own private files — a read-only library many users can browse and copy from. Pass scopesAvailable, activeScope, onScopeChange, publicFiles, and onCopyPublicToPrivate to enable it.

Access is gated by two roles on the user's identity profile:

When both roles are present, FileManager renders a scope selector at the top. When only one is available, the selector is hidden and that scope is shown. When neither is set, an empty state is shown.

In the public-files scope the FileManager hides destructive actions (delete, rename, share, move, upload, create folder). When the user copies or drags a public file, your onCopyPublicToPrivate callback is invoked and the file is added to the user's private library; the original is untouched.

Wiring it up

import { useUser, useHasRole, ROLE_PRIVATE_FILES, ROLE_PUBLIC_FILES } from '@hiyve/react-identity';
import { useUserFiles, usePublicFiles } from '@hiyve/react';
import { FileManager, type FileScope } from '@hiyve/react-collaboration';
import { useMemo, useState, useCallback, useEffect } from 'react';

function Library() {
  const { user } = useUser();
  const userId = user?.email;

  const hasPrivate = useHasRole(ROLE_PRIVATE_FILES);
  const hasPublic = useHasRole(ROLE_PUBLIC_FILES);
  const scopesAvailable = useMemo<FileScope[]>(
    () => [
      ...(hasPrivate ? ['private-files' as const] : []),
      ...(hasPublic ? ['public-files' as const] : []),
    ],
    [hasPrivate, hasPublic],
  );

  const [activeScope, setActiveScope] = useState<FileScope>('private-files');
  useEffect(() => {
    if (scopesAvailable.length && !scopesAvailable.includes(activeScope)) {
      setActiveScope(scopesAvailable[0]);
    }
  }, [scopesAvailable, activeScope]);

  const { files: publicFiles, copyToPrivate } = usePublicFiles({
    userId,
    enabled: Boolean(userId && hasPublic && activeScope === 'public-files'),
  });

  const { fetchUserFiles } = useUserFiles();
  const handleCopyPublicToPrivate = useCallback(
    async (fileId: string, opts?: { location?: string }) => {
      const created = await copyToPrivate(fileId, opts);
      if (userId) void fetchUserFiles(userId);
      return created;
    },
    [copyToPrivate, fetchUserFiles, userId],
  );

  return (
    <FileManager
      scopesAvailable={scopesAvailable}
      activeScope={activeScope}
      onScopeChange={setActiveScope}
      publicFiles={publicFiles}
      onCopyPublicToPrivate={handleCopyPublicToPrivate}
      // …other props as normal
    />
  );
}
Copy

Related components

FileScopeSelector Props

Room Analysis Viewer

RoomAnalysisViewerProps accepts analysisData, optional videoUrl, recordingId, region/marker props, currentUserId, and an sx override. Use it inside a FileViewer overlay or as a standalone display when surfacing post-meeting analytics.

File Comments

FileCommentsPanel displays a controlled list of comments with an inline composer. Pair it with any file-viewer surface (or your own host) by feeding comments and wiring onAddComment.

import { FileCommentsPanel } from '@hiyve/react-collaboration';

<FileCommentsPanel
  fileId={fileId}
  localUserId={currentUserId}
  comments={comments}
  onAddComment={(text) => addComment(fileId, text)}
  onDeleteComment={(id) => deleteComment(id)}
  onEditComment={(id, text) => editComment(id, text)}
/>
Copy

FileCommentsPanel Props (FileCommentsPanelProps):

FileCommentList and FileCommentInput are also exported for split layouts (read-only feeds, custom composer placement). Defaults: defaultFileCommentsPanelLabels, defaultFileCommentsPanelIcons, buildDefaultFileCommentsPanelColors(theme), defaultFileCommentsPanelStyles. Merge functions: mergeFileCommentsPanelLabels, mergeFileCommentsPanelIcons, mergeFileCommentsPanelColors, mergeFileCommentsPanelStyles. The FILE_COMMENTS_CONFIG constant exposes default character limits.

Thumbnails

The file-manager exposes a thumbnail layer for previews. Use the useThumbnail hook to fetch a cached thumbnail for a file:

import { useThumbnail } from '@hiyve/react-collaboration';

const { src, status } = useThumbnail({ file, size: 96 });
Copy

To customize how thumbnails are produced, register your own generators alongside the built-ins:

import {
  defaultThumbnailGenerators,
  resolveThumbnailGenerator,
  type ThumbnailGenerator,
} from '@hiyve/react-collaboration';

const myGenerator: ThumbnailGenerator = async (ctx) => /* return data URL */;
const generators = [myGenerator, ...defaultThumbnailGenerators];
Copy

Cache primitives (getCachedThumb, setCachedThumb, hasCachedThumb, clearCachedThumb, clearThumbnailCache, queueThumbnailTask) and low-level URL helpers (generateImageThumbnailFromUrl, generateVideoThumbnailFromUrl) are exported for advanced integrations. Built-ins: imageThumbnailGenerator, videoThumbnailGenerator, textPreviewThumbnailGenerator, placeholderThumbnailGenerator.

The text-preview built-in renders a content-first tile for document-style files. Resource types with a known saved shape get a structured preview — poll and Q&A session files show their question list with a count label, titled rich-text documents (notes, assignments) show the title and body text plus a due-date label when present, and summary/analysis files show the overview text. Other JSON documents fall back to a readable-text excerpt that filters out ids, timestamps, and other machine noise.

Theme color builders

Use these factories to derive defaulted color objects from a MUI Theme:

All three accept an optional ThemeColorTokens argument to override individual tokens before defaults are applied.

Session Common

Predicates

ChatPanel Props

ChatMessageList Props

ChatInput Props

ChatHub Props

Quick Start: Multi-Channel Chat

import { ChatHub } from '@hiyve/react-collaboration';

const channels = [
  { id: 'general', name: 'General', unreadCount: 3, lastMessagePreview: 'Hello!' },
  { id: 'design', name: 'Design Team', unreadCount: 0 },
];

function MultiChannelChat() {
  const [activeId, setActiveId] = useState<string | null>('general');
  const [messages, setMessages] = useState<ChatMessage[]>([]);

  return (
    <ChatHub
      channels={channels}
      activeChannelId={activeId}
      messages={messages}
      localUserId="user-123"
      onChannelSelect={setActiveId}
      onSend={(content) => handleSendMessage(activeId, content)}
      channelListProps={{ showSearch: true }}
    />
  );
}
Copy

ChatChannelList Props

PollsWindow Props

QAPanel Props

FileManager Props

FileCacheProvider Props

Room mode (default): Place inside HiyveProvider. Automatically manages the file cache when a room is joined.

Library mode: Provide the files prop and on* callbacks to use without HiyveProvider.

FileViewer Props

MediaFileViewer Props

Enhanced media player for audio/video files. Requires @hiyve/react-media-player.

FileIcon Props

RoomSummaryViewer Props

Dialog Props

CreateFolderDialog

RenameFileDialog

DeleteConfirmDialog

FileSharingDialog

Hooks

Polls

Q&A

File Manager

Session

Utilities

Polls

Q&A

File Manager

File Reference Utilities

Utilities for discovering file references when sharing files that link to other files (e.g., a clip composition referencing audio clips). Built-in extractors handle clip-composition and assignment resource types.

import {
  registerFileReferenceExtractor,
  hasFileReferences,
  extractFileReferences,
} from '@hiyve/react-collaboration';

// Register a custom extractor for playlist files
const cleanup = registerFileReferenceExtractor('playlist', (content) => {
  const playlist = content as { tracks?: Array<{ fileId: string }> };
  return (playlist.tracks ?? []).map(t => t.fileId);
});

// Check and extract references
if (hasFileReferences('playlist')) {
  const referencedIds = extractFileReferences('playlist', parsedContent);
}

// Unregister when done
cleanup();
Copy

Constants

Customization

Every component supports customization through labels, icons, colors, and styles props. Pass a partial object to override only the values you need.

Chat

import { ChatPanel, buildDefaultChatPanelColors } from '@hiyve/react-collaboration';
// `buildDefaultChatPanelColors(theme)` is a theme-aware factory; pass the MUI Theme:
// const colors = buildDefaultChatPanelColors(useTheme());

<ChatPanel
  labels={{
    title: 'Mensajes',
    placeholder: 'Escribe un mensaje...',
    emptyState: 'Sin mensajes',
  }}
  colors={{
    headerBackground: '#f5f5f5',
    containerBackground: '#ffffff',
    localMessageBackground: '#1976d2',
  }}
  styles={{
    avatarSize: 28,
    messageBorderRadius: 16,
  }}
/>
Copy

Chat defaults and merge functions:

Chat Hub

import { ChatHub, defaultChatHubColors } from '@hiyve/react-collaboration';

<ChatHub
  channels={channels}
  activeChannelId={activeId}
  messages={messages}
  localUserId="user-123"
  onChannelSelect={setActiveId}
  onSend={handleSend}
  labels={{ emptyStateMessage: 'Selecciona una conversacion' }}
  colors={{ subtitleColor: '#888' }}
  channelListProps={{
    labels: { title: 'Conversaciones', searchPlaceholder: 'Buscar...' },
  }}
/>
Copy

Chat Hub defaults and merge functions:

Polls

import { PollsWindow, defaultPollsWindowLabels } from '@hiyve/react-collaboration';

<PollsWindow
  labels={{
    createPoll: 'Neue Umfrage',
    vote: 'Abstimmen',
  }}
  colors={{
    primary: '#7c3aed',
  }}
/>
Copy

Polls defaults and merge functions:

Q&A

import { QAPanel, defaultQAPanelLabels } from '@hiyve/react-collaboration';

<QAPanel
  labels={{
    askQuestion: 'Poser une question',
    answer: 'Repondre',
  }}
  icons={{
    upvote: <MyUpvoteIcon />,
  }}
/>
Copy

Q&A defaults and merge functions:

File Manager

import {
  FileManager,
  defaultFileManagerLabels,
  defaultFileIcons,
} from '@hiyve/react-collaboration';

<FileManager
  labels={{
    upload: 'Subir archivo',
    newFolder: 'Nueva carpeta',
  }}
/>
Copy

File Manager defaults and merge functions:

Note: The unprefixed names (defaultLabels, mergeLabels, defaultIcons, mergeIcons, defaultColors, mergeColors, defaultStyles, mergeStyles) are deprecated. Use the prefixed defaultFileManager* / mergeFileManager* names shown above. | defaultFileIcons | mergeFileIcons | | defaultFileIconColors | mergeFileIconColors | | defaultViewerLabels | -- | | defaultViewerColors | -- | | defaultViewerStyles | -- | | defaultMediaFileViewerLabels | mergeMediaFileViewerLabels | | defaultMediaFileViewerColors | mergeMediaFileViewerColors | | defaultCreateFolderLabels | -- | | defaultRenameLabels | -- | | defaultDeleteLabels | -- | | defaultShareLabels | -- | | defaultRoomSummaryLabels | -- | | defaultRoomSummaryColors | -- |

Session Common

Namespaced Constants

Some constant names are shared across the polls and Q&A domains. They are exported with domain prefixes to avoid conflicts:

Advanced: Data Message Types

These constants are available for consumers building custom poll or Q&A integrations outside of the provided components (e.g., custom UIs that send and receive poll/Q&A data messages directly).

File Reference Utilities

Utilities for discovering and resolving file references when files link to other files (e.g., a clip composition referencing audio clips). Built-in extractors handle clip-composition and assignment resource types. Register custom extractors for additional resource types.

Key Types

Requirements

• @hiyve/react (^2.0.0) -- components must be rendered inside HiyveProvider
• @hiyve/rtc-client -- WebRTC client (provided by HiyveProvider)
• @hiyve/utilities (^1.0.0)
• @mui/material (^5.0.0 || ^6.0.0) and @mui/icons-material
• @emotion/react (^11.0.0) and @emotion/styled (^11.0.0)
• react (^18.0.0)
• dayjs (^1.11.0) -- optional, used for date formatting in file manager
• @hiyve/react-media-player (^1.0.0) -- optional, enables enhanced media playback in MediaFileViewer

License

Proprietary - Hiyve SDK