@appsocom/react 0.0.0-stage → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Appsotech Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,33 @@
-# Temporary Holding Version
+# @appsocom/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React hooks and components for [Appsocom Live](https://live.appsocom.com) video calls: a complete call screen in one component, or the pieces and hooks to build your own.
+
+```bash
+npm install @appsocom/react @appsocom/client
+```
+
+```tsx
+import { VideoConference } from "@appsocom/react";
+import "@appsocom/react/styles.css";
+
+<VideoConference url="https://api.appsocom.dev" token={token} onLeft={(reason) => console.log(reason)} />
+```
+
+`VideoConference` shows a pre-join screen (camera preview, mic level, device pickers, blur and noise suppression), then the grid, controls and chat. Use `prejoin={false}` to join straight away, `chat={false}` to hide chat, and `layout="grid" | "focus"` to pick a layout.
+
+Build your own from `SfuRoom`, `VideoGrid`, `ParticipantTile`, `ControlBar`, `DeviceSelect`, `PreJoin`, `ChatPanel`, `ConnectionBanner` and `VideoTrack`, with hooks such as `useParticipants`, `useLocalParticipant`, `useActiveSpeakers`, `useChat` and `useRaisedHands`.
+
+```tsx
+<SfuRoom url={url} token={token}>
+  <MyGrid />
+</SfuRoom>
+
+function MyGrid() {
+  const participants = useParticipants();
+  return participants.map((p) => <ParticipantTile key={p.id} participant={p} />);
+}
+```
+
+Guide: [UI kits](https://docs.appsocom.dev/ui-kits)
+
+Docs: [docs.appsocom.dev](https://docs.appsocom.dev) · License: MIT

package/dist/components.d.ts

@@ -0,0 +1,157 @@
+/**
+ * Ready-made web UI for sfukit: video grid, participant tiles, control bar,
+ * device pickers, prejoin screen and an all-in-one <VideoConference>.
+ * Styles: import "@appsocom/react/styles.css" (theme with CSS variables), or
+ * style the `sfk-*` classes yourself.
+ */
+import { type CSSProperties, type ReactNode } from "react";
+import { type JoinOptions, type Room } from "@appsocom/client";
+import type { LessonState, Participant } from "@appsocom/protocol";
+declare const paths: Record<string, string>;
+export declare function Icon({ name, size }: {
+    name: keyof typeof paths | string;
+    size?: number;
+}): import("react").JSX.Element;
+/** A <video> showing one track. Muted by default (audio is played by the room). */
+export declare function VideoTrack({ track, mirror, fit, className, style, }: {
+    track: MediaStreamTrack | null | undefined;
+    mirror?: boolean;
+    fit?: "cover" | "contain";
+    className?: string;
+    style?: CSSProperties;
+}): import("react").JSX.Element;
+/** Live audio level of a track, 0..1 (for mic meters). */
+export declare function useAudioLevel(track: MediaStreamTrack | null | undefined): number;
+/** Cameras, mics or speakers, kept up to date as devices are plugged in. */
+export declare function useMediaDevices(kind: MediaDeviceKind): MediaDeviceInfo[];
+export interface ParticipantTileProps {
+    /** A remote participant. Leave out (with `local`) for your own tile. */
+    participant?: Participant;
+    local?: boolean;
+    /** Camera (default) or their screen share. */
+    source?: "camera" | "screen";
+    /** Moderators get a menu on remote tiles (mute, stop camera, let present, remove). Default true. */
+    moderation?: boolean;
+    /** Receive this video only while the tile is on screen. Default true. */
+    subscribeWhenVisible?: boolean;
+    className?: string;
+    children?: ReactNode;
+}
+/** One participant: video (or initials), name, mic state, speaking ring, quality, role, hand. */
+export declare function ParticipantTile({ participant, local, source, moderation, subscribeWhenVisible, className, children, }: ParticipantTileProps): import("react").JSX.Element | null;
+export interface VideoGridProps {
+    /** "auto" (default): spotlight a screen share or the moderator's spotlight, otherwise a grid. "speaker": active speaker large. */
+    layout?: "auto" | "grid" | "speaker";
+    /** Show your own tile. Default true. */
+    includeLocal?: boolean;
+    /** Receive video only for tiles on screen. Default true. */
+    subscribeWhenVisible?: boolean;
+    className?: string;
+}
+/** Everyone's video, laid out to fit. Screen shares and spotlighted people get the big spot. */
+export declare function VideoGrid({ layout, includeLocal, subscribeWhenVisible, className }: VideoGridProps): import("react").JSX.Element;
+/**
+ * A <select> of cameras, mics or speakers. Inside a room, picking one switches
+ * the room's device; outside (prejoin), pass value/onChange.
+ */
+export declare function DeviceSelect({ kind, value, onChange, label, className, }: {
+    kind: MediaDeviceKind;
+    value?: string;
+    onChange?: (deviceId: string, device: MediaDeviceInfo | undefined) => void;
+    label?: string;
+    className?: string;
+}): import("react").JSX.Element | null;
+export interface ControlBarProps {
+    /** Which buttons to show. All default to true (shown when your permissions allow). */
+    controls?: Partial<Record<"mic" | "camera" | "screen" | "blur" | "noise" | "devices" | "hand" | "chat" | "leave", boolean>>;
+    /** Called after leaving. */
+    onLeave?: () => void;
+    /** Called when the chat button is pressed (if you show a chat panel). */
+    onToggleChat?: () => void;
+    className?: string;
+    children?: ReactNode;
+}
+/** Mic, camera, screen share, blur, noise suppression, devices, raise hand, leave. */
+export declare function ControlBar({ controls, onLeave, onToggleChat, className, children }: ControlBarProps): import("react").JSX.Element;
+/** Data-saver picker (rendered inside the ControlBar's devices popover too). */
+export declare function DataSaverSelect({ label, className }: {
+    label?: string;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** "12.4 MB used · about 85 MB per hour". Renders nothing until there's a reading. */
+export declare function DataUsageMeter({ className }: {
+    className?: string;
+}): import("react").JSX.Element | null;
+/** "Reconnecting…" banner while the room or media connection is down, or a note while on audio fallback. */
+export declare function ConnectionBanner(): import("react").JSX.Element | null;
+/** Simple chat panel (room.chat / room.sendChat). */
+export declare function ChatPanel({ className }: {
+    className?: string;
+}): import("react").JSX.Element;
+export interface PreJoinChoices {
+    name: string;
+    audio: boolean;
+    video: boolean;
+    audioDeviceId?: string;
+    videoDeviceId?: string;
+    backgroundBlur: boolean;
+    noiseSuppression: boolean;
+}
+export interface PreJoinProps {
+    onSubmit: (choices: PreJoinChoices) => void;
+    /** Ask for a display name. Default false (names usually come from the token). */
+    askName?: boolean;
+    defaults?: Partial<PreJoinChoices>;
+    joinLabel?: string;
+    /** Show blur / noise suppression toggles when supported. Default true. */
+    showEffects?: boolean;
+    className?: string;
+}
+/** Camera preview, mic level, device pickers and on/off toggles before joining. */
+export declare function PreJoin({ onSubmit, askName, defaults, joinLabel, showEffects, className }: PreJoinProps): import("react").JSX.Element;
+export interface SfuRoomProps extends Omit<JoinOptions, "url" | "token"> {
+    url: string;
+    token: string;
+    /** Device choices from <PreJoin> (applied once joined). */
+    audioDeviceId?: string;
+    videoDeviceId?: string;
+    audioOutputDeviceId?: string;
+    /** Shown while joining. */
+    connecting?: ReactNode;
+    /** Shown if joining fails (default: the error message). */
+    renderError?: (error: Error) => ReactNode;
+    onJoined?: (room: Room) => void;
+    onLeft?: (reason: string) => void;
+    onError?: (error: Error) => void;
+    children?: ReactNode;
+}
+/** Joins a room while mounted and provides it to the hooks/components inside. */
+export declare function SfuRoom(props: SfuRoomProps): import("react").JSX.Element;
+export interface VideoConferenceProps extends Omit<SfuRoomProps, "children"> {
+    /** Show <PreJoin> first. Default true. */
+    prejoin?: boolean;
+    /** Show a chat panel toggle. Default true. */
+    chat?: boolean;
+    layout?: VideoGridProps["layout"];
+    className?: string;
+}
+/** The whole call UI in one component: prejoin → grid + controls + chat. */
+export declare function VideoConference({ prejoin, chat, layout, className, ...roomProps }: VideoConferenceProps): import("react").JSX.Element;
+/** A readable version of simple TeX for the board (x^2 → x², \\frac{a}{b} → a⁄b). */
+export declare function texToText(tex: string): string;
+/** The AI teacher's whiteboard (16:10, scales to its width). */
+export declare function LessonWhiteboard({ lesson, className }: {
+    lesson: LessonState;
+    className?: string;
+}): import("react").JSX.Element;
+/** The current slide of an AI lesson (nothing when none is shown). */
+export declare function LessonSlideView({ lesson, className }: {
+    lesson: LessonState;
+    className?: string;
+}): import("react").JSX.Element | null;
+/** A one-line status for an AI lesson: section, who's speaking, timer. */
+export declare function LessonStatusBar({ lesson, names }: {
+    lesson: LessonState;
+    names?: (userId: string) => string;
+}): import("react").JSX.Element;
+export {};