@camstack/ui-library 0.1.39 → 0.1.40

package/dist/composites/step-tree-master.d.ts

@@ -0,0 +1,28 @@
+import { PipelineSchema, PipelineSlot } from '@camstack/types';
+export type StepDotState = 'inherit' | 'on' | 'off' | 'na';
+export interface StepTreeNode {
+    readonly addonId: string;
+    readonly addonName: string;
+    readonly slot: PipelineSlot;
+    readonly inputClasses: readonly string[];
+    readonly outputClasses: readonly string[];
+    readonly children: readonly StepTreeNode[];
+}
+export interface StepTreeMasterProps {
+    readonly tree: readonly StepTreeNode[];
+    readonly selectedAddonId: string | null;
+    readonly onSelect: (addonId: string) => void;
+    readonly agentDots?: Readonly<Record<string, readonly {
+        readonly agentNodeId: string;
+        readonly state: StepDotState;
+    }[]>>;
+    readonly className?: string;
+}
+export declare function StepTreeMaster({ tree, selectedAddonId, onSelect, agentDots, className, }: StepTreeMasterProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Helper: build a StepTreeNode[] from a `PipelineSchema` by chaining on
+ * `inputClasses` ⇔ `outputClasses` compatibility. Mirrors the orchestrator
+ * resolver's `buildTreeFromAddons` logic but yields names only (display
+ * layer). Addons in the audio-classifier slot become separate roots.
+ */
+export declare function buildStepTreeFromSchema(schema: PipelineSchema): readonly StepTreeNode[];

package/dist/composites/stream-panel.d.ts

@@ -0,0 +1,143 @@
+import { ReactNode } from 'react';
+import { SignalingResult, ClientStreamHints } from './camera-stream-player';
+import { DeviceDetections } from '../hooks/use-device-detections';
+/**
+ * Discriminated WebRTC target — same shape as the backend cap. Kept
+ * locally on the StreamChoice so consumers don't need to import from
+ * `@camstack/types` to render a panel.
+ */
+export type StreamChoiceTarget = {
+    readonly kind: 'adaptive';
+} | {
+    readonly kind: 'profile';
+    readonly profile: 'high' | 'mid' | 'low';
+} | {
+    readonly kind: 'cam-stream';
+    readonly camStreamId: string;
+};
+export interface StreamChoice {
+    /**
+     * Stable identifier for React keys, dropdown values, and the
+     * player's `streamKey` prop. Opaque to the panel — typical values:
+     * `'adaptive'`, `'profile:high'`, `'stream:native:main'`.
+     */
+    readonly id: string;
+    /** Display label (e.g. "Adaptive", "HIGH (3840×2160)", "Native main"). */
+    readonly label: string;
+    /** Structured WebRTC target — passed verbatim to `createSession`. */
+    readonly target: StreamChoiceTarget;
+    /** Live broker status (null if unavailable). */
+    readonly status?: string | null;
+    /** Input FPS from camera (null if unavailable). */
+    readonly inputFps?: number | null;
+    /** Decoded FPS (null if unavailable). */
+    readonly decodeFps?: number | null;
+    /** Bitrate in kbps (null if unavailable). */
+    readonly bitrateKbps?: number | null;
+}
+export interface StreamStats {
+    readonly status: string;
+    readonly inputFps: number;
+    readonly decodeFps: number;
+    readonly uptimeMs: number;
+}
+export interface StreamPanelProps {
+    readonly serverUrl: string;
+    readonly createSession: (target: StreamChoiceTarget, hints?: ClientStreamHints) => Promise<SignalingResult>;
+    readonly sendAnswer: (sessionId: string, sdpAnswer: string) => Promise<void>;
+    readonly closeSession?: (sessionId: string) => Promise<void>;
+    /** Available streams. If omitted or single entry, no dropdown shown. */
+    readonly streams?: readonly StreamChoice[];
+    /** Currently active StreamChoice id. Defaults to first stream. */
+    readonly activeStreamId?: string;
+    /** Called when user selects a different stream (StreamChoice id). */
+    readonly onStreamChange?: (id: string) => void;
+    readonly deviceName?: string;
+    /** Pipeline phase from useDeviceDetections (e.g. "active", "watching") */
+    readonly phase?: string;
+    /** Pipeline metrics from useDeviceWebrtc. If provided, overrides phase and adds detection fps. */
+    readonly pipelineMetrics?: {
+        phase: string;
+        detectionFps: number;
+        avgInferenceMs: number;
+    } | null;
+    /** Detection data from useDeviceDetections hook. If omitted, no overlays. */
+    readonly detections?: DeviceDetections;
+    /** Initial state for detection overlay (default: true) */
+    readonly defaultShowDetections?: boolean;
+    /** Initial state for motion overlay (default: false) */
+    readonly defaultShowMotion?: boolean;
+    readonly streamStats?: StreamStats;
+    /** Auto-play on mount (default: true) */
+    readonly autoPlay?: boolean;
+    /** Show play/stop toggle + snapshot preview when stopped (default: false) */
+    readonly showPlayStop?: boolean;
+    /** Snapshot source URL (data: URI). Only used when showPlayStop=true. */
+    readonly snapshotSrc?: string | null;
+    /** Whether snapshot is currently loading */
+    readonly snapshotLoading?: boolean;
+    /** Callback to refresh snapshot */
+    readonly onRefreshSnapshot?: () => void;
+    /** Show stream stats in header (fps, uptime) (default: false) */
+    readonly showStreamStats?: boolean;
+    readonly children?: ReactNode;
+    /**
+     * Extra overlay node composited on top of the video, alongside the
+     * built-in detection overlay. Used by callers to layer device-scoped
+     * controls (PTZOverlay, AudioPTT, ...) without forking the panel.
+     */
+    readonly extraOverlay?: ReactNode;
+    /**
+     * Whether the device supports PTZ. When true, the header shows a
+     * "PTZ" toggle next to detect/motion.
+     */
+    readonly ptzAvailable?: boolean;
+    /**
+     * Controlled visibility of the PTZ overlay. Drives both the
+     * header button highlight and (combined with `ptzOverlay`) overlay
+     * rendering. Caller computes the final value (e.g. OR with an
+     * external "force on" surface like a floating PTZ panel) and
+     * passes it down here.
+     */
+    readonly ptzShown?: boolean;
+    /**
+     * Overlay rendered ON the live video when `ptzShown` is true.
+     * Typically a `<PTZOverlay controls={...} mode="overlay" />` from
+     * ui-library. Combined with `extraOverlay` in the player overlay
+     * slot — both render together when active.
+     */
+    readonly ptzOverlay?: ReactNode;
+    /**
+     * Notified when the user clicks the in-header PTZ toggle. The
+     * caller updates its source of truth for `ptzShown`. No-op if
+     * omitted (button stays inert).
+     */
+    readonly onPtzToggle?: () => void;
+    /**
+     * Whether the device supports two-way audio (intercom). When true,
+     * the header shows an "Intercom" toggle next to detect/motion that
+     * lets the operator open the floating intercom panel without leaving
+     * the stream view.
+     */
+    readonly intercomAvailable?: boolean;
+    /**
+     * Controlled visibility of the intercom panel — drives the button's
+     * highlight state. The caller (which owns the floating-panel state)
+     * passes `true` while its intercom panel is open.
+     */
+    readonly intercomShown?: boolean;
+    /**
+     * Notified when the user clicks the in-header intercom toggle. The
+     * caller flips its panel state. No-op if omitted (button inert).
+     */
+    readonly onIntercomToggle?: () => void;
+    /**
+     * When true, drops the panel's outer rounded card chrome (border,
+     * rounded corners, background). Use when embedding into another
+     * surface that already provides framing — e.g. the device-detail
+     * left-column hero where the panel is one row of a larger card.
+     */
+    readonly chromeless?: boolean;
+    readonly className?: string;
+}
+export declare function StreamPanel({ serverUrl, createSession, sendAnswer, closeSession, streams, activeStreamId: controlledStreamId, onStreamChange, deviceName, phase, pipelineMetrics, detections, defaultShowDetections, defaultShowMotion, streamStats, autoPlay, showPlayStop, snapshotSrc, snapshotLoading, onRefreshSnapshot, showStreamStats, children, extraOverlay, ptzAvailable, ptzShown, ptzOverlay, onPtzToggle, intercomAvailable, intercomShown, onIntercomToggle, chromeless, className, }: StreamPanelProps): import("react/jsx-runtime").JSX.Element;

package/dist/composites/version-badge.d.ts

@@ -0,0 +1,24 @@
+import { default as React } from 'react';
+export type SemanticBadgeVariant = 'success' | 'warning' | 'danger' | 'info' | 'neutral';
+export interface SemanticBadgeProps {
+    children: React.ReactNode;
+    variant?: SemanticBadgeVariant;
+    /** Use monospace font (good for versions, codes) */
+    mono?: boolean;
+    className?: string;
+}
+/**
+ * General-purpose badge with semantic color variants.
+ * Solid background with dark text for maximum contrast.
+ */
+export declare function SemanticBadge({ children, variant, mono, className }: SemanticBadgeProps): import("react/jsx-runtime").JSX.Element;
+export interface VersionBadgeProps {
+    version: string;
+    preRelease?: boolean;
+    className?: string;
+}
+/**
+ * Version badge — auto-detects pre-release versions.
+ * Stable = success (green), Pre-release = warning (amber).
+ */
+export declare function VersionBadge({ version, preRelease, className }: VersionBadgeProps): import("react/jsx-runtime").JSX.Element;

package/dist/composites/widget-slot.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+import { WidgetProps } from '../contexts/widget-registry.js';
+export interface WidgetSlotProps {
+    /** `<addonId>/<stableId>` — the public widget identifier. */
+    readonly widgetId: string;
+    /** Host context — picked up by metadata `requires` validation. Defaults to `'device-tab'`. */
+    readonly host?: WidgetProps['host'];
+    /** Forwarded to widget. */
+    readonly config?: Readonly<Record<string, unknown>>;
+    /** Forwarded to widget. */
+    readonly deviceId?: number;
+    readonly integrationId?: string;
+    /** Stable instance id — defaults to `widgetId` for non-dashboard hosts (single mount per page). */
+    readonly instanceId?: string;
+    /** Dashboard sizing — placeholder for v1. */
+    readonly size?: WidgetProps['size'];
+    readonly columns?: number;
+    readonly rows?: number;
+}
+export declare function WidgetSlot(props: WidgetSlotProps): ReactNode;

package/dist/contexts/custom-field-renderers.d.ts

@@ -0,0 +1,26 @@
+import { ComponentType, ReactNode } from 'react';
+import { ConfigField } from '@camstack/types';
+/**
+ * Props shape every custom renderer receives. Keep it congruent with
+ * the built-in `case` branches so the dispatcher in `config-form-field`
+ * can pass arguments uniformly.
+ */
+export interface CustomFieldRendererProps {
+    readonly field: ConfigField;
+    readonly value: unknown;
+    readonly onChange: (value: unknown) => void;
+    readonly disabled?: boolean;
+}
+export type CustomFieldRenderer = ComponentType<CustomFieldRendererProps>;
+export type CustomFieldRendererMap = Readonly<Record<string, CustomFieldRenderer>>;
+export interface CustomFieldRenderersProviderProps {
+    readonly renderers: CustomFieldRendererMap;
+    readonly children: ReactNode;
+}
+export declare function CustomFieldRenderersProvider({ renderers, children, }: CustomFieldRenderersProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Look up a registered renderer by `field.type`. Returns null when no
+ * renderer is registered — caller falls back to its built-in handling
+ * (or renders nothing).
+ */
+export declare function useCustomFieldRenderer(type: string): CustomFieldRenderer | null;

package/dist/contexts/device-context.d.ts

@@ -0,0 +1,20 @@
+import { ReactNode } from 'react';
+/**
+ * Cached device snapshot. Loose-typed (`Record<string, unknown>`) at
+ * the boundary because the wire shape lives in different places
+ * depending on the caller — DeviceDetail reads from
+ * `deviceManager.list`, `addon-admin-ui` from a hand-loaded subset.
+ * Renderers narrow the fields they actually need.
+ */
+export type DeviceSnapshot = Readonly<Record<string, unknown>>;
+export interface DeviceContextProviderProps {
+    readonly deviceId: number;
+    /** Optional cached device snapshot — readers narrow the fields they need. */
+    readonly device?: DeviceSnapshot;
+    readonly children: ReactNode;
+}
+export declare function DeviceContextProvider({ deviceId, device, children }: DeviceContextProviderProps): import("react/jsx-runtime").JSX.Element;
+/** @returns the device id of the current page subtree, or null if outside any provider. */
+export declare function useDeviceId(): number | null;
+/** @returns the cached device snapshot, or null when no snapshot is provided. */
+export declare function useDeviceSnapshot(): DeviceSnapshot | null;

package/dist/contexts/player-overlays.d.ts

@@ -0,0 +1,56 @@
+import { ReactNode } from 'react';
+export interface PlayerOverlayLayer {
+    readonly id: string;
+    /** Lower = bottom. Built-in layers (PTZ overlay, detection overlay)
+     *  are drawn at order 0; addon-contributed layers should pick a
+     *  higher value (e.g. 100) to land on top. */
+    readonly order: number;
+    readonly node: ReactNode;
+}
+export interface PlayerToolbarButton {
+    readonly id: string;
+    /** Lower = leftmost in the toolbar cluster. */
+    readonly order: number;
+    /** Icon node — typically a `<svg>` or lucide-react icon. The host
+     *  renders it inside a button shell; the icon component is
+     *  responsible for its own sizing (h-3 w-3 by convention). */
+    readonly icon: ReactNode;
+    /** Visible label on wider breakpoints; collapses to icon-only on
+     *  narrow widths. */
+    readonly label: string;
+    /** Title/tooltip for the rendered button. Defaults to `label`. */
+    readonly title?: string;
+    /** Controlled active state — drives the highlight (primary tint). */
+    readonly active: boolean;
+    /** Tone variant for the inactive state. `'primary'` reads as a
+     *  call-to-action (e.g. "Snapshot"); `'default'` is a neutral
+     *  toggle. */
+    readonly tone?: 'default' | 'primary';
+    /** Disable the button when the host is mid-transition. */
+    readonly disabled?: boolean;
+    readonly onClick: () => void;
+}
+export interface PlayerOverlaysProviderProps {
+    readonly children: ReactNode;
+}
+export declare function PlayerOverlaysProvider({ children }: PlayerOverlaysProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Snapshot of registered layers ordered by `order` (asc, ties resolved
+ *  by insertion order of the underlying Map). Returns `[]` outside a
+ *  provider. */
+export declare function usePlayerOverlayLayers(): readonly PlayerOverlayLayer[];
+/** Snapshot of registered toolbar buttons, ordered by `order` (asc). */
+export declare function usePlayerToolbarButtons(): readonly PlayerToolbarButton[];
+/**
+ * Register an overlay layer for the lifetime of the calling component.
+ * Re-registers on every render with the latest spec; auto-unregisters
+ * on unmount. Pass `null` to skip registration when the layer is
+ * conditionally enabled (the hook still runs every render — keeps
+ * react-hook order stable across spec === null toggles).
+ *
+ * Callers that build the spec inline should memoise it (`useMemo`)
+ * to avoid re-registering on every parent render — context-write
+ * effects depend on referential equality of the spec object.
+ */
+export declare function usePlayerOverlayLayer(spec: PlayerOverlayLayer | null): void;
+/** Same shape as `usePlayerOverlayLayer`, scoped to toolbar buttons. */
+export declare function usePlayerToolbarButton(spec: PlayerToolbarButton | null): void;

package/dist/contexts/system-context.d.ts

@@ -0,0 +1,19 @@
+import { ReactNode } from 'react';
+import { System } from '@camstack/sdk';
+export interface SystemProviderProps {
+    readonly system: System;
+    readonly children: ReactNode;
+}
+export declare function SystemProvider({ system, children }: SystemProviderProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * Read the active `System` instance from the surrounding `<SystemProvider>`.
+ * Throws when no provider is mounted — every hook in this directory
+ * relies on the system, so a clear error beats a silent null.
+ */
+export declare function useSystem(): System;
+/**
+ * Variant that returns `null` instead of throwing — useful for
+ * components that need to render before the provider is set up
+ * (boot-time splash screens etc.).
+ */
+export declare function useOptionalSystem(): System | null;

package/dist/contexts/widget-registry.d.ts

@@ -0,0 +1,68 @@
+import { ComponentType, ReactNode } from 'react';
+/** Standard props every addon-contributed widget receives. */
+export interface WidgetProps {
+    /** Stable id of THIS widget instance (form-builder field key, dashboard slot UUID, etc.). */
+    readonly instanceId: string;
+    /** Host where this widget is rendered. */
+    readonly host: 'device-tab' | 'dashboard' | 'integration-detail';
+    /** Form/dashboard-supplied props. Shape depends on the widget. */
+    readonly config?: Readonly<Record<string, unknown>>;
+    /** Provided when host has a device context. */
+    readonly deviceId?: number;
+    /** Provided when host has an integration context. */
+    readonly integrationId?: string;
+    /** Dashboard sizing hints (placeholder for v1 — widget can ignore). */
+    readonly size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    readonly columns?: number;
+    readonly rows?: number;
+}
+/** Public registry surface. */
+export interface WidgetRegistry {
+    /**
+     * Returns the resolved widget component for `<addonId>/<stableId>`,
+     * or `undefined` when the widget id is unknown to the registry, or
+     * `null` while the bundle is still loading.
+     */
+    resolve(widgetId: string): ComponentType<WidgetProps> | null | undefined;
+    /** Metadata lookup — used by `<WidgetSlot>` to validate `requires`. */
+    metadata(widgetId: string): WidgetMetadataEntry | undefined;
+    /** Every contributed widget. Used by host pickers (e.g. dashboard
+     *  add-widget modal) to enumerate the available widgets. */
+    listAll(): readonly WidgetMetadataEntry[];
+}
+/** One enriched-aggregator entry exposed to consumers. */
+export interface WidgetMetadataEntry {
+    readonly widgetId: string;
+    readonly addonId: string;
+    readonly stableId: string;
+    readonly label: string;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly remoteName: string;
+    readonly bundleUrl: string;
+    readonly hosts: readonly ('device-tab' | 'dashboard' | 'integration-detail')[];
+    readonly requires: {
+        readonly deviceContext: boolean;
+        readonly integrationContext: boolean;
+    };
+    readonly defaultSize: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+    readonly allowedSizes: readonly ('xs' | 'sm' | 'md' | 'lg' | 'xl')[];
+    readonly defaultColumns: number;
+    readonly defaultRows: number;
+}
+export interface WidgetRegistryProviderProps {
+    readonly children: ReactNode;
+}
+export declare function WidgetRegistryProvider({ children }: WidgetRegistryProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Returns the registered widget component, `null` while loading, or `undefined` if unknown. */
+export declare function useWidget(widgetId: string): ComponentType<WidgetProps> | null | undefined;
+/** Returns the metadata entry for a widget, or `undefined` if unknown. */
+export declare function useWidgetMetadata(widgetId: string): WidgetMetadataEntry | undefined;
+/** Returns every contributed widget — host pickers (dashboard
+ *  add-widget modal, settings UI palette) consume this to enumerate
+ *  the registry. Filter on the call site by `metadata.hosts.includes()`. */
+export declare function useAllWidgets(): readonly WidgetMetadataEntry[];
+/** Read the registry instance — throws when no provider is mounted. */
+export declare function useWidgetRegistry(): WidgetRegistry;
+/** Variant returning `null` when no provider is mounted — for boot splash etc. */
+export declare function useOptionalWidgetRegistry(): WidgetRegistry | null;

package/dist/contexts/zone-editing.d.ts

@@ -0,0 +1,59 @@
+import { ReactNode } from 'react';
+export type ZoneDrawingKind = 'polygon' | 'tripwire';
+export interface ZoneDraftPoint {
+    readonly x: number;
+    readonly y: number;
+}
+export interface ZoneDraft {
+    readonly id: string;
+    readonly kind: ZoneDrawingKind;
+    readonly name: string;
+    readonly color: string;
+    readonly points: ReadonlyArray<ZoneDraftPoint>;
+}
+export interface ZoneEditingState {
+    /** Whether the zone editor overlay is active. When `true` the
+     *  Konva Stage intercepts clicks; when `false` clicks pass
+     *  through to the underlying player. */
+    readonly editing: boolean;
+    /** Active drawing kind. `null` means "select / drag existing
+     *  zones". Setting a non-null value triggers a fresh polygon /
+     *  tripwire creation on the next click. */
+    readonly drawingKind: ZoneDrawingKind | null;
+    /** Currently-selected zone id (for highlight + ZoneForm). */
+    readonly selectedZoneId: string | null;
+    /** In-flight draft snapshot of the zone being edited. `null` while
+     *  no edit session is active — read-only browse mode. */
+    readonly editingDraft: ZoneDraft | null;
+}
+export interface ZoneEditingActions {
+    setEditing(editing: boolean): void;
+    setDrawingKind(kind: ZoneDrawingKind | null): void;
+    setSelectedZoneId(id: string | null): void;
+    /** Start a new polygon/tripwire — convenience for "Add zone"
+     *  buttons that should both unlock the overlay AND select the
+     *  shape kind in one click. */
+    startDrawing(kind: ZoneDrawingKind): void;
+    /** Exit edit mode — clears the drawing kind + selection + any
+     *  in-flight draft. Called when the Detection tab is torn down. */
+    exitEditing(): void;
+    /** Snapshot a zone into the draft and enter unified edit mode.
+     *  If a different draft is already active it is discarded. */
+    enterDraft(draft: ZoneDraft): void;
+    /** Patch the active draft. No-op when no draft is active. */
+    updateDraft(patch: Partial<Omit<ZoneDraft, 'id' | 'kind'>>): void;
+    /** Throw the draft away. Caller is expected to refresh from
+     *  upstream zone state (operator chose Discard or navigated away). */
+    discardDraft(): void;
+}
+interface ZoneEditingContextValue extends ZoneEditingState, ZoneEditingActions {
+}
+export interface ZoneEditingProviderProps {
+    readonly children: ReactNode;
+}
+export declare function ZoneEditingProvider({ children }: ZoneEditingProviderProps): import("react/jsx-runtime").JSX.Element;
+/** Read + drive the zone-editing state. Returns `null` outside a
+ *  provider so callers that mount in pages without zones (e.g. a
+ *  shared hero on a non-camera device) can no-op gracefully. */
+export declare function useZoneEditing(): ZoneEditingContextValue | null;
+export {};