@ksp-gonogo/kerbcast-react 1.7.0 → 1.8.0

package/dist/FeedActionBar.d.ts

@@ -0,0 +1,133 @@
+/**
+ * FeedActionBar: the shared top-right action row rendered by BOTH
+ * `CameraFeed` and `KerbalFaceFeed`, so a single overflow engine serves every
+ * feed surface (part cams, crew faces, and any future host).
+ *
+ * Partition rule (issue #6 UI spec): stateful toggles (their at-rest state
+ * must stay visible, e.g. auto-track, the coming REC) are PRIMARY and always
+ * inline. Non-stateful actions (quality, PiP, fullscreen, plain consumer
+ * actions) are overflow-eligible: they collapse into a ⋮ menu ONLY once the
+ * row is genuinely crowded (total enabled >= 4 AND >= 2 non-stateful
+ * eligible): a single item never collapses, since that would cost a click
+ * to reach the one control that exists. Order is stable (an explicit `order`
+ * wins, otherwise entries keep the relative position their caller gave them)
+ * so chips don't reflow as buttons enable/disable around them.
+ *
+ * Close/remove is a THIRD category: `pinnedTrailing`. It is never
+ * overflow-eligible, never counted toward the overflow threshold, and always
+ * renders last (to the right of the ⋮ trigger itself), so dismissing a
+ * feed always stays a single, persistent, rightmost click. Bar order is:
+ * [stateful primaries] … [⋮ overflow, non-stateful] [pinned trailing close].
+ *
+ * Deliberately minimal: an entry is just (id, label, stateful?, order?,
+ * pinnedTrailing?, render). The interactive node itself (icon, aria
+ * attributes, onClick, any submenu it opens) is built by the caller
+ * (CameraFeed / KerbalFaceFeed) exactly as before; this component only
+ * decides WHERE it goes.
+ */
+/**
+ * A consumer-supplied action rendered into a feed's action bar. Lets a host
+ * page (e.g. the sidecar's spotlight toggle) inject controls without the
+ * library knowing what they do.
+ */
+export interface FeedAction {
+    /** Stable identity for the React key. */
+    id: string;
+    /** Accessible label; used for aria-label, the native tooltip, and the overflow-menu row's visible text. */
+    label: string;
+    /** Icon node, sized by the action bar (~14px). */
+    icon: React.ReactNode;
+    /** Toggle state: renders the button highlighted and sets aria-pressed. */
+    active?: boolean;
+    onClick: () => void;
+    /**
+     * Whether this action is a stateful toggle: stays PRIMARY / always
+     * inline so its at-rest state is visible, never collapses into the ⋮
+     * overflow. Defaults to `active !== undefined`. Override when a
+     * tri-state/menu-driven action's "active" isn't a plain boolean, or to force
+     * a boolean toggle to be overflow-eligible anyway.
+     */
+    stateful?: boolean;
+    /**
+     * Stable sort key for the action bar (lower sorts first). Actions without
+     * an explicit order keep their natural (array) position; this exists so a
+     * consumer can pin an action to a specific slot instead. Chips never
+     * reflow as buttons enable/disable; this is what keeps that stable.
+     */
+    order?: number;
+    /**
+     * Marks this as the bar's pinned-trailing (close/remove) slot: it is NEVER
+     * overflow-eligible, is excluded entirely from the overflow-threshold count
+     * (both the total and the non-stateful-eligible count), and always renders
+     * last (to the right of the ⋮ trigger), so dismissing a feed is always a
+     * single, persistent, rightmost click. `CameraFeed`'s `trailingActions`
+     * prop sets this automatically; a `KerbalFaceFeed`/`actions`-only consumer
+     * sets it explicitly on its close action.
+     */
+    pinnedTrailing?: boolean;
+}
+interface Partitionable {
+    stateful?: boolean;
+    order?: number;
+    pinnedTrailing?: boolean;
+}
+/**
+ * Sort a list of action-bar entries into (primary, overflow, pinnedTrailing).
+ * `entries` must already be filtered down to the currently-enabled set:
+ * this function has no notion of "disabled", only "present".
+ *
+ * `pinnedTrailing` entries (close/remove) are pulled out FIRST and excluded
+ * entirely from the overflow-threshold count. Both the total and the
+ * non-stateful-eligible count run only over the remaining entries, then
+ * always returned as their own group, to be rendered last (see
+ * `FeedActionBar`, which places them after the ⋮ trigger).
+ */
+export declare function partitionActionBarEntries<T extends Partitionable>(entries: readonly T[]): {
+    primary: T[];
+    overflow: T[];
+    pinnedTrailing: T[];
+};
+/**
+ * One slot in the bar. `render` produces the actual interactive element
+ * (unchanged whether it lands inline or inside the overflow menu) so callers
+ * keep full control of refs / aria attributes / submenus; FeedActionBar only
+ * decides placement and, in the overflow menu, adds the visible label.
+ */
+export interface FeedActionBarEntry {
+    id: string;
+    label: string;
+    stateful?: boolean;
+    order?: number;
+    pinnedTrailing?: boolean;
+    render: () => React.ReactNode;
+}
+/**
+ * Adapt a plain consumer/public `FeedAction` (id/label/icon/active/onClick,
+ * plus the optional stateful?/order?/pinnedTrailing? flags) into a bar entry,
+ * rendered as the standard icon button. `stateful` defaults to
+ * `active !== undefined` per the #6 spec (stateful toggles, meaning
+ * `active !== undefined`, stay primary).
+ */
+export declare function feedActionToEntry(action: FeedAction): FeedActionBarEntry;
+export interface FeedActionBarProps {
+    /** Non-partitioned content rendered before the partitioned entries (e.g. the camera step buttons). */
+    leading?: React.ReactNode;
+    entries: FeedActionBarEntry[];
+    /** Forwarded to the root row; lets a host `styled(FeedActionBar)` override layout (e.g. KerbalFaceFeed's smaller, always-visible bar). */
+    className?: string;
+}
+/**
+ * Shared top-right action row. Renders `leading`, then the partitioned
+ * entries: stateful ones always inline, non-stateful ones inline until the
+ * row is crowded enough to warrant a ⋮ overflow menu, then the pinned
+ * trailing (close/remove) entries: always last, to the right of the ⋮.
+ */
+export declare function FeedActionBar({ leading, entries, className }: FeedActionBarProps): import("react").JSX.Element | null;
+/** Icon-button shared by every action-bar entry (built-in or consumer). */
+export declare const OverlayIconButton: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "$active"> & {
+    $active?: boolean;
+}, never> & Partial<Pick<import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").ButtonHTMLAttributes<HTMLButtonElement>, HTMLButtonElement>, "$active"> & {
+    $active?: boolean;
+}, never>>> & string;
+export declare const ActionBarRow: import("styled-components/dist/types").IStyledComponentBase<"web", import("styled-components").FastOmit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never> & Partial<Pick<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, never>>> & string;
+export {};

package/dist/FeedActionBar.js

@@ -0,0 +1,225 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * FeedActionBar: the shared top-right action row rendered by BOTH
+ * `CameraFeed` and `KerbalFaceFeed`, so a single overflow engine serves every
+ * feed surface (part cams, crew faces, and any future host).
+ *
+ * Partition rule (issue #6 UI spec): stateful toggles (their at-rest state
+ * must stay visible, e.g. auto-track, the coming REC) are PRIMARY and always
+ * inline. Non-stateful actions (quality, PiP, fullscreen, plain consumer
+ * actions) are overflow-eligible: they collapse into a ⋮ menu ONLY once the
+ * row is genuinely crowded (total enabled >= 4 AND >= 2 non-stateful
+ * eligible): a single item never collapses, since that would cost a click
+ * to reach the one control that exists. Order is stable (an explicit `order`
+ * wins, otherwise entries keep the relative position their caller gave them)
+ * so chips don't reflow as buttons enable/disable around them.
+ *
+ * Close/remove is a THIRD category: `pinnedTrailing`. It is never
+ * overflow-eligible, never counted toward the overflow threshold, and always
+ * renders last (to the right of the ⋮ trigger itself), so dismissing a
+ * feed always stays a single, persistent, rightmost click. Bar order is:
+ * [stateful primaries] … [⋮ overflow, non-stateful] [pinned trailing close].
+ *
+ * Deliberately minimal: an entry is just (id, label, stateful?, order?,
+ * pinnedTrailing?, render). The interactive node itself (icon, aria
+ * attributes, onClick, any submenu it opens) is built by the caller
+ * (CameraFeed / KerbalFaceFeed) exactly as before; this component only
+ * decides WHERE it goes.
+ */
+import { Fragment, useId } from "react";
+import { createPortal } from "react-dom";
+import styled from "styled-components";
+import { usePortalMenu } from "./menuPositioning";
+// ---------------------------------------------------------------------------
+// Partition logic (pure, unit-tested independently of any rendering)
+// ---------------------------------------------------------------------------
+const OVERFLOW_MIN_TOTAL = 4;
+const OVERFLOW_MIN_NON_STATEFUL = 2;
+/**
+ * Sort a list of action-bar entries into (primary, overflow, pinnedTrailing).
+ * `entries` must already be filtered down to the currently-enabled set:
+ * this function has no notion of "disabled", only "present".
+ *
+ * `pinnedTrailing` entries (close/remove) are pulled out FIRST and excluded
+ * entirely from the overflow-threshold count. Both the total and the
+ * non-stateful-eligible count run only over the remaining entries, then
+ * always returned as their own group, to be rendered last (see
+ * `FeedActionBar`, which places them after the ⋮ trigger).
+ */
+export function partitionActionBarEntries(entries) {
+    const sorted = [...entries].sort((a, b) => (a.order ?? Number.POSITIVE_INFINITY) - (b.order ?? Number.POSITIVE_INFINITY));
+    const pinnedTrailing = sorted.filter((e) => e.pinnedTrailing);
+    const overflowable = sorted.filter((e) => !e.pinnedTrailing);
+    const nonStateful = overflowable.filter((e) => !e.stateful);
+    const overflowActive = overflowable.length >= OVERFLOW_MIN_TOTAL && nonStateful.length >= OVERFLOW_MIN_NON_STATEFUL;
+    if (!overflowActive) {
+        return { primary: overflowable, overflow: [], pinnedTrailing };
+    }
+    return {
+        primary: overflowable.filter((e) => e.stateful),
+        overflow: nonStateful,
+        pinnedTrailing,
+    };
+}
+/**
+ * Adapt a plain consumer/public `FeedAction` (id/label/icon/active/onClick,
+ * plus the optional stateful?/order?/pinnedTrailing? flags) into a bar entry,
+ * rendered as the standard icon button. `stateful` defaults to
+ * `active !== undefined` per the #6 spec (stateful toggles, meaning
+ * `active !== undefined`, stay primary).
+ */
+export function feedActionToEntry(action) {
+    return {
+        id: action.id,
+        label: action.label,
+        stateful: action.stateful ?? action.active !== undefined,
+        order: action.order,
+        pinnedTrailing: action.pinnedTrailing,
+        render: () => (_jsx(OverlayIconButton, { type: "button", "aria-label": action.label, "aria-pressed": action.active ?? undefined, title: action.label, "$active": action.active ?? false, onClick: action.onClick, children: action.icon }, action.id)),
+    };
+}
+// ---------------------------------------------------------------------------
+// The bar itself
+// ---------------------------------------------------------------------------
+const OVERFLOW_MENU_MAX_WIDTH = 200;
+const OVERFLOW_MENU_MAX_HEIGHT = 240;
+/**
+ * Shared top-right action row. Renders `leading`, then the partitioned
+ * entries: stateful ones always inline, non-stateful ones inline until the
+ * row is crowded enough to warrant a ⋮ overflow menu, then the pinned
+ * trailing (close/remove) entries: always last, to the right of the ⋮.
+ */
+export function FeedActionBar({ leading, entries, className }) {
+    const { primary, overflow, pinnedTrailing } = partitionActionBarEntries(entries);
+    const menuId = useId();
+    const overflowMenu = usePortalMenu({
+        maxWidth: OVERFLOW_MENU_MAX_WIDTH,
+        maxHeight: OVERFLOW_MENU_MAX_HEIGHT,
+        align: "end",
+    });
+    const closeOverflowMenu = overflowMenu.close;
+    if (!leading && entries.length === 0)
+        return null;
+    return (_jsxs(ActionBarRow, { className: className, children: [leading, primary.map((e) => (_jsx(Fragment, { children: e.render() }, e.id))), overflow.length > 0 && (_jsx(OverlayIconButton, { ref: overflowMenu.triggerRef, type: "button", "aria-label": "More actions", "aria-haspopup": "menu", "aria-expanded": overflowMenu.open, "aria-controls": menuId, title: "More actions", "$active": overflowMenu.open, onClick: overflowMenu.toggle, children: _jsx(MoreIcon, {}) })), overflow.length > 0 &&
+                overflowMenu.open &&
+                overflowMenu.position &&
+                createPortal(_jsx(OverflowMenu, { ref: overflowMenu.menuRef, id: menuId, role: "menu", "aria-label": "More actions", style: overflowMenu.position, children: overflow.map((e) => (
+                    // The wrapping row's onClick fires in the BUBBLE phase, after
+                    // the entry's own button click handler, so this closes the
+                    // menu once the action has actually fired rather than
+                    // pre-empting it.
+                    _jsxs(OverflowMenuItem, { onClick: closeOverflowMenu, children: [e.render(), _jsx(OverflowMenuItemLabel, { "aria-hidden": "true", children: e.label })] }, e.id))) }), document.body), pinnedTrailing.map((e) => (_jsx(Fragment, { children: e.render() }, e.id)))] }));
+}
+// ---------------------------------------------------------------------------
+// Icons
+// ---------------------------------------------------------------------------
+/* Overflow trigger: vertical ellipsis (three dots). */
+function MoreIcon() {
+    return (_jsxs("svg", { viewBox: "0 0 16 16", width: 14, height: 14, fill: "currentColor", stroke: "none", "aria-hidden": "true", children: [_jsx("circle", { cx: "8", cy: "3", r: "1.4" }), _jsx("circle", { cx: "8", cy: "8", r: "1.4" }), _jsx("circle", { cx: "8", cy: "13", r: "1.4" })] }));
+}
+// ---------------------------------------------------------------------------
+// Styled components
+// ---------------------------------------------------------------------------
+/** Icon-button shared by every action-bar entry (built-in or consumer). */
+export const OverlayIconButton = styled.button `
+  position: relative;
+  width: 24px;
+  height: 24px;
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: 0;
+  /* Active-toggle fill (quality / tracking / PiP / fullscreen / custom actions
+     all share this button). Its own token so a consumer can recolour just the
+     action-row highlight without touching the general accent; defaults to
+     --kerbcast-accent, so the sidecar web page (which maps its accent onto that)
+     is unchanged. */
+  background: ${(p) => p.$active
+    ? "var(--kerbcast-action-active, var(--kerbcast-accent, #00ff88))"
+    : "rgba(0, 0, 0, 0.5)"};
+  border: 1px solid
+    ${(p) => p.$active
+    ? "var(--kerbcast-action-active, var(--kerbcast-accent, #00ff88))"
+    : "rgba(255, 255, 255, 0.3)"};
+  border-radius: 3px;
+  color: ${(p) => (p.$active ? "#000" : "#fff")};
+  cursor: pointer;
+  transition: background 0.12s, border-color 0.12s, color 0.12s;
+
+  @media (hover: hover) {
+    &:hover {
+      background: ${(p) => p.$active
+    ? "var(--kerbcast-action-active, var(--kerbcast-accent, #00ff88))"
+    : "rgba(0, 0, 0, 0.7)"};
+      border-color: rgba(255, 255, 255, 0.6);
+    }
+  }
+
+  &:focus-visible {
+    outline: 2px solid var(--kerbcast-accent, #00ff88);
+    outline-offset: 2px;
+  }
+
+  &:disabled {
+    opacity: 0.4;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+`;
+/* Top-right cluster of overlay controls (custom actions + built-ins + overflow). */
+export const ActionBarRow = styled.div `
+  position: absolute;
+  top: 6px;
+  right: 8px;
+  z-index: 3;
+  display: flex;
+  align-items: center;
+  gap: 4px;
+  opacity: 0;
+  pointer-events: none;
+  transition: opacity 0.15s;
+
+  @media (prefers-reduced-motion: reduce) {
+    transition: none;
+  }
+`;
+/* The ⋮ overflow dropdown: same portal/anchor contract as CameraFeed's other
+   menus (fixed position set inline from the trigger rect) so tile clipping
+   cannot cut it off. */
+const OverflowMenu = styled.div `
+  position: fixed;
+  z-index: 1000;
+  min-width: 140px;
+  max-width: min(200px, calc(100vw - 16px));
+  max-height: min(40vh, 240px);
+  display: flex;
+  flex-direction: column;
+  padding: 4px;
+  gap: 2px;
+  background: rgba(0, 0, 0, 0.85);
+  border: 1px solid rgba(255, 255, 255, 0.3);
+  border-radius: 4px;
+  overflow-x: hidden;
+  overflow-y: auto;
+`;
+const OverflowMenuItem = styled.div `
+  display: flex;
+  align-items: center;
+  gap: 8px;
+  padding: 2px 4px;
+  border-radius: 3px;
+
+  @media (hover: hover) {
+    &:hover {
+      background: rgba(255, 255, 255, 0.1);
+    }
+  }
+`;
+const OverflowMenuItemLabel = styled.span `
+  font-size: 11px;
+  letter-spacing: 0.04em;
+  color: #fff;
+  white-space: nowrap;
+`;

package/dist/KerbalFaceFeed.d.ts

@@ -16,7 +16,7 @@
  * wrapper supplies one, so declarative controls compose the same way they do
  * on `CameraFeed`.
  */
-import { FeedAction, CameraStreamHook } from "./CameraFeed";
+import { CameraStreamHook, FeedAction } from "./CameraFeed";
 /**
  * Coarse presentation state a wrapper reacts to for its own fallback/badge:
  * - `live`: a stream is bound and playing.

package/dist/KerbalFaceFeed.js

@@ -19,6 +19,7 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  */
 import { useEffect, useRef } from "react";
 import styled from "styled-components";
+import { FeedActionBar, feedActionToEntry } from "./FeedActionBar";
 import { useKerbcastStream } from "./hooks/useKerbcastStream";
 import { useKerbcastCameras } from "./hooks/useKerbcastCameras";
 import { useReportDisplaySize } from "./hooks/useReportDisplaySize";
@@ -59,26 +60,18 @@ const OverlayLayer = styled.div `
   position: absolute;
   inset: 0;
 `;
-const ActionBar = styled.div `
-  position: absolute;
+/*
+ * The shared FeedActionBar is hover-revealed by default (CameraFeed's larger
+ * frame fades it in on hover/focus). A tiny face tile has no such affordance,
+ * so this override keeps the original always-visible, corner-hugging look;
+ * layout/button styling (flex row, gap, the shared OverlayIconButton) still
+ * comes from FeedActionBar itself.
+ */
+const KerbalActionBarRow = styled(FeedActionBar) `
   top: 4px;
   right: 4px;
-  display: flex;
-  gap: 4px;
-  z-index: 2;
-`;
-const ActionButton = styled.button `
-  display: inline-flex;
-  align-items: center;
-  justify-content: center;
-  width: 22px;
-  height: 22px;
-  padding: 0;
-  border: none;
-  border-radius: 3px;
-  cursor: pointer;
-  color: #fff;
-  background: ${(p) => (p.$active ? "rgba(255,255,255,0.28)" : "rgba(0,0,0,0.45)")};
+  opacity: 1;
+  pointer-events: auto;
 `;
 export function KerbalFaceFeed({ flightId, size, reportSize = true, actions, showActions = true, children, onFeedStateChange, showStandby = true, useStream, }) {
     // Match CameraFeed: the built-in hook (which acquires/releases the
@@ -114,5 +107,5 @@ export function KerbalFaceFeed({ flightId, size, reportSize = true, actions, sho
     useEffect(() => {
         notify.current?.(state);
     }, [state]);
-    return (_jsxs(Frame, { ref: frameRef, "$size": size, "data-testid": "kerbal-face-feed", "data-feed-state": state, children: [_jsx(Face, { ref: videoRef, autoPlay: true, playsInline: true, muted: true, controls: false }), state === "destroyed" && _jsx(DestroyedScrim, {}), showStandby && state !== "live" && (_jsx(StandbyLayer, { children: _jsx(StandbyIcon, { size: Math.round((size ?? 96) * 0.32) }) })), showActions && actions && actions.length > 0 && (_jsx(ActionBar, { children: actions.map((a) => (_jsx(ActionButton, { type: "button", "aria-label": a.label, title: a.label, "aria-pressed": a.active, "$active": a.active, onClick: a.onClick, children: a.icon }, a.id))) })), children && _jsx(OverlayLayer, { children: children })] }));
+    return (_jsxs(Frame, { ref: frameRef, "$size": size, "data-testid": "kerbal-face-feed", "data-feed-state": state, children: [_jsx(Face, { ref: videoRef, autoPlay: true, playsInline: true, muted: true, controls: false }), state === "destroyed" && _jsx(DestroyedScrim, {}), showStandby && state !== "live" && (_jsx(StandbyLayer, { children: _jsx(StandbyIcon, { size: Math.round((size ?? 96) * 0.32) }) })), showActions && actions && actions.length > 0 && (_jsx(KerbalActionBarRow, { entries: actions.map(feedActionToEntry) })), children && _jsx(OverlayLayer, { children: children })] }));
 }

package/dist/RecordingsTray.d.ts

@@ -0,0 +1,37 @@
+/**
+ * RecordingsTray: a presentational drawer over the client-side recordings
+ * store (`useRecordings()`). Lists finished single clips and grouped SETS,
+ * with a play/preview, a download, and a discard per clip; a group also gets
+ * a download-all + a discard-set. Recording is client-local and in-memory (no
+ * sidecar, no server state), so this is where an operator saves a clip before
+ * a page reload discards it. The tray shows a quiet reminder of that.
+ *
+ * Deliberately dumb: it owns no recording logic, only formatting and the
+ * per-clip object-URL lifecycle (create on first render, revoke on discard or
+ * unmount). Starting/stopping recordings is CameraFeed's REC control (or a
+ * host's own REC+ grouped flow); this component only ever reads the store and
+ * calls its discard/discardGroup actions.
+ *
+ * Every `RecordingHandle` (standalone or a grouped member) carries its own
+ * `flightId`, so camera names come straight off the clip, with no dependency
+ * on the store's transient `active` list. That matters because the tray
+ * commonly mounts after a recording has already finished (its `active` entry
+ * long gone by then). A host supplies the flightId -> label step via
+ * `cameraLabel` (e.g. `buildCameraLabeler(useKerbcastCameras())`, the same
+ * labeller CameraFeed uses) so this stays decoupled from any particular
+ * camera registry; omit it for a plain "Camera <flightId>" fallback.
+ */
+export interface RecordingsTrayProps {
+    /**
+     * Resolve a flightId to a display label for a clip's camera name. Omit for
+     * a plain "Camera <flightId>" fallback.
+     */
+    cameraLabel?: (flightId: number) => string;
+    /** Forwarded to the root panel; lets a host lay out/size the tray. */
+    className?: string;
+}
+/**
+ * The shared drawer. Requires a `KerbcastProvider` ancestor (it calls
+ * `useRecordings()` directly, same requirement as `CameraFeed`).
+ */
+export declare function RecordingsTray({ cameraLabel, className }: RecordingsTrayProps): import("react").JSX.Element;