@hiyve/utilities

Reusable utility components, hooks, and functions for Hiyve video conferencing applications.

Installation

npm install @hiyve/utilities
Copy

Quick Start

import {
  LiveClock,
  TooltipIconButton,
  ErrorBoundary,
  useContainerBreakpoint,
} from '@hiyve/utilities';

function Header() {
  const { isBelowBreakpoint, containerRef } = useContainerBreakpoint(800);

  return (
    <ErrorBoundary fallback={<div>Something went wrong</div>}>
      <header ref={containerRef}>
        {!isBelowBreakpoint && <LiveClock />}
        <TooltipIconButton tooltip="Copy" onClick={handleCopy}>
          <CopyIcon />
        </TooltipIconButton>
      </header>
    </ErrorBoundary>
  );
}
Copy

Components

LiveClock

Self-contained live time display that updates every second.

import { LiveClock } from '@hiyve/utilities';

<LiveClock variant="h6" />

<LiveClock
  variant="body1"
  updateInterval={5000}
  labels={{ formatTime: (date) => date.format('HH:mm:ss') }}
  colors={{ text: '#ffffff' }}
/>
Copy

TooltipIconButton

IconButton wrapper that correctly displays tooltips on disabled buttons.

import { TooltipIconButton } from '@hiyve/utilities';
import SaveIcon from '@mui/icons-material/Save';

<TooltipIconButton
  tooltip="Save changes"
  disabled={!hasChanges}
  onClick={handleSave}
>
  <SaveIcon />
</TooltipIconButton>
Copy

Extends all standard MUI IconButtonProps (except title).

ErrorBoundary

React error boundary that catches render errors in its child tree.

import { ErrorBoundary } from '@hiyve/utilities';

// Static fallback
<ErrorBoundary fallback={<div>Something went wrong</div>}>
  <MyComponent />
</ErrorBoundary>

// Render function fallback with error details and reset
<ErrorBoundary
  fallback={(error, reset) => (
    <div>
      <p>Error: {error.message}</p>
      <button onClick={reset}>Try Again</button>
    </div>
  )}
  onError={(error, errorInfo) => logToService(error)}
>
  <VideoGrid />
</ErrorBoundary>
Copy

When fallback is a function, it receives the caught Error and a reset function that clears the error state and re-renders the children.

Hooks

useContainerBreakpoint

Responsive container detection using ResizeObserver. Returns whether the container is below a given width threshold.

import { useContainerBreakpoint } from '@hiyve/utilities';

function ResponsivePanel() {
  const { isBelowBreakpoint, containerRef } = useContainerBreakpoint(600);

  return (
    <div ref={containerRef}>
      {isBelowBreakpoint ? <CompactView /> : <FullView />}
    </div>
  );
}
Copy

Signature: useContainerBreakpoint(breakpoint: number, options?: UseContainerBreakpointOptions)

Returns: UseContainerBreakpointResult

useDebounce

Delays updating a value until a specified time has passed since the last change. Useful for search inputs and API call throttling.

import { useDebounce } from '@hiyve/utilities';

function SearchComponent() {
  const [searchInput, setSearchInput] = useState('');
  const debouncedSearch = useDebounce(searchInput, 300);

  useEffect(() => {
    performSearch(debouncedSearch);
  }, [debouncedSearch]);

  return (
    <input
      value={searchInput}
      onChange={(e) => setSearchInput(e.target.value)}
    />
  );
}
Copy

Signature: useDebounce<T>(value: T, delay: number): T

Returns the debounced value.

useValidation

Form validation hook with built-in validator factories.

import { useValidation, validators } from '@hiyve/utilities';

function PollQuestionInput() {
  const [question, setQuestion] = useState('');
  const { error, validate, isValid, clearError } = useValidation(question, [
    validators.required('Question is required'),
    validators.maxLength(500, 'Question must be 500 characters or less'),
  ]);

  const handleSubmit = () => {
    if (validate()) {
      submitPoll(question);
    }
  };

  return (
    <TextField
      value={question}
      onChange={(e) => setQuestion(e.target.value)}
      error={!!error}
      helperText={error}
    />
  );
}
Copy

Signature: useValidation<T>(value: T, validators: Validator<T>[]): UseValidationResult

Built-in Validators

The validators object provides factory functions that return Validator functions:

usePersistedState

Persists state to localStorage with the same API as useState. Values survive page reloads and are automatically synchronized across browser tabs.

import { usePersistedState } from '@hiyve/utilities';

function JoinForm() {
  const [userName, setUserName] = usePersistedState('hiyve-userName', '');
  const [roomName, setRoomName] = usePersistedState('hiyve-roomName', '');

  return (
    <>
      <input value={userName} onChange={(e) => setUserName(e.target.value)} />
      <input value={roomName} onChange={(e) => setRoomName(e.target.value)} />
    </>
  );
}
Copy

Signature: usePersistedState<T>(key: string, defaultValue: T): [T, (value: T | ((prev: T) => T)) => void]

Returns a [value, setValue] tuple identical to useState. The setter supports both direct values and functional updates. Works in SSR environments by falling back to the default value when window is unavailable. Corrupted or unparseable stored values fall back to the default gracefully.

Utilities

throttle

Creates a throttled version of a function that executes at most once every wait milliseconds. The first call executes immediately; subsequent calls within the wait period are queued.

import { throttle } from '@hiyve/utilities';

const throttledUpdate = throttle((data) => {
  broadcastUpdate(data);
}, 50);

canvas.on('object:modified', () => throttledUpdate(canvas.toJSON()));

// Clean up
throttledUpdate.cancel();
Copy

Signature: throttle<T>(fn: T, wait: number): T & { cancel: () => void }

Returns a throttled function with a cancel() method to clear any pending execution.

Avatar Utilities

Functions for generating consistent user display elements (initials and colors).

import { getInitials, getUserColor, DEFAULT_AVATAR_PALETTE } from '@hiyve/utilities';

getInitials('John Doe');     // 'JD'
getInitials('jane_smith');   // 'JS'
getInitials('admin');        // 'AD'
getInitials('');             // '?'

getUserColor('user-123');                          // consistent color from default palette
getUserColor('user-123', ['#f00', '#0f0', '#00f']); // consistent color from custom palette
Copy

Retry Utilities

Async retry with exponential backoff, jitter, and customizable retry conditions.

import { withRetry, isNetworkErrorRetryable, sleep } from '@hiyve/utilities';

// Basic retry
const data = await withRetry(() => fetchData('/api/data'), {
  maxRetries: 3,
});

// Custom retry logic
const result = await withRetry(() => uploadFile(file), {
  maxRetries: 5,
  initialDelay: 500,
  isRetryable: isNetworkErrorRetryable,
  onRetry: (attempt, error, delay) => {
    console.log(`Retry ${attempt} after ${delay}ms`);
  },
});

// Standalone delay
await sleep(2000);
Copy

RetryOptions:

Debug Utilities

Namespaced debug logging with level filtering and global configuration.

import { createDebugLogger, configureDebug, isDebugEnabled } from '@hiyve/utilities';

// Enable debug logging at startup
configureDebug({ enabled: true });

// Create a scoped logger
const debug = createDebugLogger('hiyve:my-component');

debug.log('Component mounted');
debug.warn('Deprecated prop used');
debug.error('Failed to load data', error);

// Check enabled state
if (debug.enabled) {
  debug.log('Detailed info:', expensiveComputation());
}
Copy

DebugLogger interface:

DebugConfig options:

Error Formatting

Maps raw error messages to user-friendly strings using case-insensitive substring matching. Useful in onError callbacks to display clear, actionable messages to end users.

import { formatHiyveError } from '@hiyve/utilities';

<HiyveProvider
  onError={(err) => setError(formatHiyveError(err.message || String(err)))}
>
Copy

With custom messages that extend the defaults:

import { formatHiyveError, DEFAULT_HIYVE_ERROR_MESSAGES } from '@hiyve/utilities';

const friendly = formatHiyveError(error, {
  'rate limit': 'Too many requests. Please wait a moment and try again.',
});
Copy

Default mappings included:

Video Types & Layouts

Framework-agnostic types and layout algorithms shared between @hiyve/video-tile, @hiyve/video-grid, and their Angular counterparts. These are the single source of truth — the framework-specific packages re-export them for backward compatibility.

import {
  type OverlayPosition,
  type TilePosition,
  type MuteStatus,
  type MoodType,
  type MoodData,
  type BuiltInLayoutMode,
  type LayoutMode,
  getGridColumns,
  getGridClass,
  getPositionStyles,
  calculateSpeakerLayout,
  calculateSidebarLayout,
} from '@hiyve/utilities';
Copy

Angular / non-React consumers

Angular packages should import from the @hiyve/utilities/video subpath. This entry point is a standalone bundle (~2KB) with zero React or MUI dependencies:

import { type MuteStatus, getGridColumns } from '@hiyve/utilities/video';
Copy

Shared Types

Layout Functions

Types

All TypeScript interfaces and types are exported for use in custom implementations.

Defaults

Default configuration objects and merge helpers for component customization.

import { defaultLiveClockLabels, LiveClock } from '@hiyve/utilities';

// Override only the time format, keeping other defaults
<LiveClock
  labels={{
    ...defaultLiveClockLabels,
    formatTime: (date) => date.format('HH:mm:ss'),
  }}
/>
Copy

Features

• Zero/minimal external dependencies (MUI peer dependency for components)
• All utilities can be used independently
• Shared video types and layout algorithms for React and Angular packages
• Standalone @hiyve/utilities/video entry point with no React/MUI dependencies
• Built-in form validators for common patterns
• Retry with exponential backoff and jitter
• Scoped debug logging with level and namespace filtering
• Deterministic avatar colors for consistent user identification
• Error boundary with reset capability

Requirements

Peer dependencies (for component exports):

• react ^18.0.0
• @mui/material ^5.0.0 || ^6.0.0
• @mui/icons-material ^5.0.0 || ^6.0.0
• @emotion/react ^11.0.0
• @emotion/styled ^11.0.0

Non-component exports (hooks, utilities, avatar, debug, retry, throttle) have no peer dependency requirements beyond React.

The @hiyve/utilities/video subpath (video types and layout algorithms) has no peer dependencies at all and can be used from Angular or any other framework.

License

Proprietary - Hiyve SDK