@hiyve/react-assignments

Assignment editor with activity tracking for Hiyve -- rich text editing, due dates, time estimates, status management, per-user activity sessions, and cloud persistence.

Installation

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

Quick Start

import { AssignmentEditor } from '@hiyve/react-assignments';
import { HiyveProvider } from '@hiyve/react';

function TeamAssignment() {
  return (
    <HiyveProvider generateRoomToken={generateRoomToken}>
      <AssignmentEditor
        title="Sprint Task"
        enableAutoSave
        onSave={(assignment) => console.log('Saved:', assignment.id)}
        onStatusChange={(status) => console.log('Status:', status)}
      />
    </HiyveProvider>
  );
}
Copy

Components

CreateAssignmentDialog Props

import { CreateAssignmentDialog } from '@hiyve/react-assignments';

<CreateAssignmentDialog
  open={showDialog}
  onClose={() => setShowDialog(false)}
  onCreate={(fileId, fileName, fileData) => {
    console.log('Created:', fileId);
    setShowDialog(false);
  }}
  defaultName="Design Review"
/>
Copy

Hooks

Utilities

AssignmentEditor Props

Imperative Handle (Ref)

AssignmentEditor exposes a ref for external control:

import { useRef } from 'react';
import { AssignmentEditor, type AssignmentEditorRef } from '@hiyve/react-assignments';

function AssignmentsPanel() {
  const editorRef = useRef<AssignmentEditorRef>(null);

  return (
    <div>
      <button
        onClick={() => editorRef.current?.save()}
        disabled={editorRef.current?.isSaving}
      >
        Save Now
      </button>
      <AssignmentEditor ref={editorRef} enableAutoSave />
    </div>
  );
}
Copy

The ref provides: save(), isSaving, hasUnsavedChanges, lastSaved, and fileId. File attachments are now managed inline via embed nodes (see Embedding Files).

Using Hooks Directly

For custom editor UIs, use the hooks independently:

import { useAssignmentEditor, useAssignmentPersistence, useActivityTracker } from '@hiyve/react-assignments';

function CustomAssignmentEditor() {
  const { editor, content, isEmpty, getHTML, focus } = useAssignmentEditor({
    placeholder: 'Describe the assignment details...',
    onUpdate: (content) => console.log('Changed'),
  });

  const { startSession, endSession, currentSession } = useActivityTracker({
    userId: currentUser.id,
  });

  // Render your own UI around the editor instance
}
Copy

AssignmentViewer

Render an existing AssignmentFile (or just a JSONContent body) read-only — no toolbar, no editing, but with full embed support:

import { AssignmentViewer } from '@hiyve/react-assignments';

<AssignmentViewer
  assignment={loadedAssignment}
  resolveFile={async (fileId) => ({ url: await getSignedUrl(fileId) })}
  onOpenEmbed={(embed) => openPreviewModal(embed.fileId)}
  onActivityTick={(elapsedSeconds) => trackTimeSpent(elapsedSeconds)}
/>
Copy

Embedding Files

Inline file references are rendered through the assignment-embed TipTap node. Wrap your editor / viewer in <EmbedProvider> to wire the file picker + resolver:

import { AssignmentEditor, EmbedProvider } from '@hiyve/react-assignments';

<EmbedProvider
  pickEmbed={async () => openFilePickerDialog()}
  resolveFile={async (fileId) => ({ url: await getSignedUrl(fileId) })}
  onOpenEmbed={(embed) => openPreviewModal(embed.fileId)}
>
  <AssignmentEditor enableFileEmbeds title="Sprint Task" />
</EmbedProvider>
Copy

The provider takes:

• pickEmbed: EmbedPickerCallback — opens your file picker; resolves to a PickedEmbed (or null to cancel).
• resolveFile: EmbedFileResolver — turns a fileId into a ResolvedEmbedFile (URL + metadata) for rendering.
• onOpenEmbed?: EmbedOpenCallback — invoked when an embed card is clicked.

For lower-level integration, AssignmentEmbedNode and AssignmentEmbedView are exported directly so they can be added to a custom TipTap configuration. The full set of embed kinds is exposed as ALL_EMBED_KINDS.

Activity Tracking

Track per-user work sessions with timers, progress, and notes. Use createAssignmentFile() to mint a new assignment with sensible defaults:

import { useState, useEffect } from 'react';
import { AssignmentEditor, createAssignmentFile, type AssignmentFile } from '@hiyve/react-assignments';

function AssignmentScreen({ client, currentUserId }: { client: AssignmentFileClient; currentUserId: string }) {
  const [assignment, setAssignment] = useState<AssignmentFile>();

  useEffect(() => {
    createAssignmentFile(client, {
      name: 'Design Review',
      ownerId: currentUserId,
    }).then(({ fileData }) => setAssignment(fileData));
  }, [client, currentUserId]);

  if (!assignment) return null;

  return (
    <AssignmentEditor
      title="Design Review"
      showMetadata
      showTabs
      enableActivityTracking
      initialAssignment={assignment}
      onStatusChange={(status) => console.log('Status:', status)}
    />
  );
}
Copy

The Activity tab shows individual session controls. The Activity Dashboard tab displays aggregate stats including active users, total time spent, and average progress.

Activity Utilities

import {
  calculateTotalTime,
  formatDuration,
  getActivityStats,
  getStatusColor,
} from '@hiyve/react-assignments';

const totalMinutes = calculateTotalTime(userActivity.sessions);
const display = formatDuration(totalMinutes); // "2h 30m"
const stats = getActivityStats(userActivities);
const color = getStatusColor('in_progress');
Copy

Session Management

For full file-management workflows (create, load, switch between saved assignments) use FileSessionHost from @hiyve/react-collaboration with AssignmentEditor registered as the editor for the assignment resource type. See @hiyve/react-collaboration for details.

Customization

All visual aspects of the editor are customizable through labels, icons, colors, and styles props. Pass a partial object -- unspecified keys use defaults.

Labels (i18n)

import { AssignmentEditor } from '@hiyve/react-assignments';

<AssignmentEditor
  labels={{
    title: 'Tarea',
    placeholder: 'Escribe tu tarea...',
    save: 'Guardar',
    saving: 'Guardando...',
    saved: 'Guardado',
    bold: 'Negrita',
    italic: 'Cursiva',
    dueDate: 'Fecha limite',
    status: 'Estado',
  }}
/>
Copy

Icons

import { AssignmentEditor } from '@hiyve/react-assignments';
import { FaBold, FaItalic } from 'react-icons/fa';

<AssignmentEditor
  icons={{
    bold: <FaBold />,
    italic: <FaItalic />,
  }}
/>
Copy

Colors

import { AssignmentEditor, buildDefaultAssignmentEditorColors } from '@hiyve/react-assignments';
import { useTheme } from '@mui/material';

// Light theme override — derive defaults from the current MUI theme
function ThemedAssignment() {
  const theme = useTheme();
  const baseColors = buildDefaultAssignmentEditorColors(theme);

  return (
    <AssignmentEditor
      colors={{
        ...baseColors,
        headerBackground: '#f5f5f5',
        editorBackground: '#ffffff',
        editorText: '#212121',
        toolbarBackground: '#fafafa',
        toolbarButtonActive: '#1976d2',
      }}
    />
  );
}
Copy

Styles

import { AssignmentEditor } from '@hiyve/react-assignments';

// Compact layout
<AssignmentEditor
  styles={{
    toolbarButtonSize: 28,
    editorPadding: 12,
    editorFontSize: '0.875rem',
    borderRadius: 8,
  }}
/>
Copy

Defaults and merge functions:

Features

• Rich text formatting (bold, italic, strikethrough, highlight, code)
• Headings (H1, H2, H3)
• Lists (bullet, numbered, task/checkbox)
• Tables with full editing
• Assignment metadata: due date, time estimates, status, user assignment
• Per-user activity tracking with session timer and notes
• Team activity dashboard with stats and progress overview
• Inline file embeds via the assignment-embed node and EmbedProvider
• Auto-save to file storage with debouncing
• Undo/redo history
• Read-only mode with ownership-based access control
• Read-only viewer (AssignmentViewer) for displaying assignments without editing
• Dark theme

Constants

Key Types

Assignment Status Values

type AssignmentStatus = 'not_started' | 'in_progress' | 'on_hold' | 'completed';
Copy

Requirements

• @hiyve/react (^2.0.0) -- components must be rendered inside HiyveProvider
• @hiyve/react-collaboration (^1.0.0) -- optional, for hosting AssignmentEditor inside FileSessionHost
• @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)

Rich text editor dependencies are bundled with the package -- no separate installation needed.

License

Proprietary - Hiyve SDK