@ai-matrx/capture 0.0.0 → 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,342 @@
+import * as React from 'react';
+import React__default from 'react';
+
+/**
+ * features/capture-camera/ — EXTRACTION SOURCE for the `@ai-matrx/capture`
+ * package (aidream/apps/shared/capture). Everything outside `host/` must stay
+ * free of app imports beyond React, lucide-react and `cn` — those are the
+ * documented substitution points when this directory is mirrored into the
+ * package (icons → inlined SVGs, cn → tailwind-merge), exactly like
+ * `@ai-matrx/media` was extracted from `features/files`.
+ *
+ * The package is the OPINIONATED iPhone-style camera chrome: translucent
+ * top/bottom bars over a full-bleed feed, the two-tap options grid, zoom
+ * pills, shutter, VIDEO·PHOTO·UPLOAD mode selector, recents thumb, flip
+ * button, rule-of-thirds grid, countdown timer, and the iOS-style sheet.
+ * It renders and orchestrates UI state ONLY — the host injects the engine
+ * (stream + capture callbacks) and everything persisted (upload, gallery,
+ * thumbnails). No fetch, no storage, no getUserMedia in this layer.
+ */
+
+/** The two persistent capture modes; Upload is an immediate action. */
+type CaptureCameraMode = "photo" | "video";
+/** Timer options genuinely supported (a countdown before the shutter). */
+type CaptureTimerSetting = 0 | 3 | 10;
+/** Output aspect for photo capture (center-cropped from the full sensor). */
+type CaptureAspect = "full" | "4:3" | "1:1" | "16:9";
+/**
+ * THE CLOUD LAW of this package: cloud integration is WHAT the system does,
+ * not an optional add-on. Every `CameraCapture` REQUIRES this port — the
+ * type system refuses a camera with no cloud. How the host fulfills it
+ * (fileHandler, a client SDK, a domain uploader) is injected; that it is
+ * fulfilled is not negotiable.
+ */
+interface CaptureCloudPort {
+    /** Content of the bottom-left recents thumbnail (latest cloud/session
+     *  media). Null renders the placeholder — the button still opens the
+     *  library. */
+    recentsThumb: React.ReactNode;
+    /** Opens the host's cloud media library (tiled gallery). */
+    onOpenLibrary: () => void;
+    /** Persists an edited image produced by the edit sheet. */
+    onSaveEdited: (blob: Blob, suggestedName: string) => void;
+}
+/**
+ * The engine port — everything the chrome needs from the host's camera
+ * runtime. The host owns lease acquisition/release, capture and recording;
+ * the chrome never touches getUserMedia.
+ */
+interface CaptureCameraEngine {
+    /** Live stream for the preview, or null while connecting/blocked. */
+    stream: MediaStream | null;
+    /** The preview <video> element ref the host's capture path reads from. */
+    videoRef: React.RefObject<HTMLVideoElement | null>;
+    /** Camera unavailable: permission denied or unsupported. */
+    blocked: null | {
+        reason: "permission-denied" | "not-supported";
+    };
+    /** Take a photo NOW (any timer countdown already elapsed). The chrome's
+     *  current aspect setting rides along; the host center-crops the full
+     *  sensor frame to it ("full" = untouched). */
+    onCapturePhoto: (opts?: {
+        aspect?: CaptureAspect;
+    }) => void;
+    /** Start / stop video recording. */
+    onStartRecording: () => void;
+    onStopRecording: () => void;
+    recording: boolean;
+    /** Elapsed recording seconds (host-owned monotonic clock). */
+    recordElapsedSeconds: number;
+    /** Open the device files picker (the Upload lane). */
+    onUpload: () => void;
+    /** Flip to the next camera; null hides the flip button. */
+    onFlipCamera: (() => void) | null;
+}
+/** One tile in the two-tap options grid. */
+interface CaptureOptionTile {
+    id: string;
+    label: string;
+    icon: React.ReactNode;
+    /** Highlight state (iPhone: yellow when engaged/auto). */
+    active?: boolean;
+    /** Small value read-out under the icon (e.g. "3s", "4:3"). */
+    valueLabel?: string;
+    disabled?: boolean;
+    onPress: () => void;
+}
+/**
+ * Slot-based extensibility — how domain layers (e.g. commerce intake) attach
+ * their own affordances without forking the chrome. Typed slots, not a plugin
+ * registry, on purpose.
+ */
+interface CaptureCameraSlots {
+    /** Extra buttons in the top bar, before the options-grid button. */
+    topBarTrailing?: React.ReactNode;
+    /** Center of the top bar (e.g. current-item label + count). */
+    topBarCenter?: React.ReactNode;
+    /** Honesty chips under the top bar (QR confirmation, etc.). */
+    statusChips?: React.ReactNode;
+    /** Rows rendered inside the bottom bar ABOVE the mode selector
+     *  (filmstrip, notes/voice row, process button…). */
+    aboveModeSelector?: React.ReactNode;
+    /** A compact action pinned right of the mode selector (Next/Break). */
+    modeRowTrailing?: React.ReactNode;
+    /** Extra tiles appended to the options grid. */
+    optionTiles?: CaptureOptionTile[];
+    /** Extra entries in the mode row after UPLOAD (e.g. SCAN). Selecting one
+     *  is an immediate host action — the chrome keeps its current mode. */
+    extraModes?: {
+        id: string;
+        label: string;
+        onSelect: () => void;
+    }[];
+    /** Free overlays rendered above everything (sheets, pagers). */
+    overlays?: React.ReactNode;
+}
+
+/**
+ * CaptureSheet — the iOS-style system sheet used over the camera: a light,
+ * heavily-rounded card sliding over the lower portion of the screen with a
+ * circular ✕ close top-right; content is an icon + bold title + body text
+ * with a filled primary action and a tinted secondary one. `variant="busy"`
+ * is the transient state (small spinner + label, like the OS "Connecting…"
+ * sheet). Deliberately light-on-dark regardless of app theme — it mirrors
+ * the OS presentation over camera chrome.
+ *
+ * Package source (`@ai-matrx/capture`) — presentational only.
+ */
+
+interface CaptureSheetAction {
+    label: string;
+    onPress: () => void;
+    kind?: "primary" | "secondary";
+}
+interface CaptureSheetProps {
+    open: boolean;
+    onClose: () => void;
+    /** Standard content sheet by default; "busy" renders spinner + label. */
+    variant?: "content" | "busy";
+    icon?: React__default.ReactNode;
+    title?: string;
+    body?: React__default.ReactNode;
+    actions?: CaptureSheetAction[];
+    /** The busy variant's label ("Connecting…"). */
+    busyLabel?: string;
+}
+declare function CaptureSheet({ open, onClose, variant, icon, title, body, actions, busyLabel, }: CaptureSheetProps): React__default.JSX.Element | null;
+
+/**
+ * CameraCapture — the opinionated iPhone-style camera surface, assembled.
+ *
+ * Layout (matching the iOS Camera app):
+ * - Full-bleed live feed with a semi-transparent near-black bar across the
+ *   top and bottom — controls read clearly while the feed shows through.
+ * - Top bar: close (host-provided), center slot, torch, host extras, and the
+ *   grid button revealing the two-tap OptionsGridPanel.
+ * - Over the feed's bottom edge: real zoom pills (only when the track
+ *   reports a zoom range).
+ * - Bottom bar: injected rows → VIDEO·PHOTO·UPLOAD mode selector → recents
+ *   thumb · shutter · flip.
+ * - Overlays: rule-of-thirds grid, timer countdown, recording chip, blocked
+ *   sheet (iOS system-sheet presentation).
+ *
+ * The chrome owns UI state only (options panel, grid, timer, countdown).
+ * Capture behavior, streams and persistence come from the injected
+ * `CaptureCameraEngine`; domain features attach through `CaptureCameraSlots`.
+ *
+ * Package source (`@ai-matrx/capture`).
+ */
+
+interface CameraCaptureProps {
+    engine: CaptureCameraEngine;
+    /** THE CLOUD LAW: the cloud port is REQUIRED — a camera with no cloud
+     *  library/persistence is not a valid instance of this system. */
+    cloud: CaptureCloudPort;
+    mode: CaptureCameraMode;
+    onModeChange: (mode: CaptureCameraMode) => void;
+    /** The live preview element (host wires its runtime's `CameraPreview`). */
+    preview: React__default.ReactNode;
+    /** Close affordance top-left; omitted = no close button. */
+    onClose?: () => void;
+    /** Body + actions for the camera-blocked iOS-style sheet. */
+    blockedSheet?: {
+        body: React__default.ReactNode;
+        actions: CaptureSheetAction[];
+    };
+    /** Hide all chrome except honesty chips (host renders its own toggle). */
+    controlsHidden?: boolean;
+    shutterDisabled?: boolean;
+    slots?: CaptureCameraSlots;
+}
+declare function CameraCapture({ engine, cloud, mode, onModeChange, preview, onClose, blockedSheet, controlsHidden, shutterDisabled, slots, }: CameraCaptureProps): React__default.JSX.Element;
+
+/**
+ * CountdownOverlay — the big centered timer digits (iPhone timer capture):
+ * one large white numeral per second, scaling in as it changes.
+ *
+ * Package source (`@ai-matrx/capture`) — presentational only.
+ */
+
+declare function CountdownOverlay({ seconds }: {
+    seconds: number | null;
+}): React__default.JSX.Element | null;
+
+/**
+ * GridOverlay — the rule-of-thirds composition grid over the viewfinder.
+ * Genuinely supported (pure CSS), toggled from the options grid.
+ *
+ * Package source (`@ai-matrx/capture`) — presentational only.
+ */
+
+declare function GridOverlay({ visible }: {
+    visible: boolean;
+}): React__default.JSX.Element | null;
+
+/**
+ * ImageEditSheet — instant in-browser image editing, core to the package
+ * (THE CLOUD LAW's sibling: capture without instant edit is half a system).
+ * v1 covers the basics that belong in the browser — crop (free + 1:1, 4:3,
+ * 16:9 presets), rotate 90°, flip — full-screen dark chrome in the iOS
+ * editing style: Cancel/Save top bar, the image letterboxed center, a
+ * draggable/resizable crop frame with corner handles, tool row bottom.
+ * Heavier AI edits ride host-injected actions, not this sheet.
+ *
+ * Output is a JPEG re-encode of the ORIGINAL pixels (rotation/flip/crop
+ * applied on canvas) — never a screenshot of the preview.
+ *
+ * Package source (`@ai-matrx/capture`) — browser canvas only, no app deps.
+ */
+
+interface ImageEditSheetProps {
+    open: boolean;
+    /** Source image URL (object URL or resolvable src). */
+    src: string | null;
+    onClose: () => void;
+    /** Receives the edited JPEG. The host persists it (cloud port). */
+    onSave: (blob: Blob) => void;
+}
+declare function ImageEditSheet({ open, src, onClose, onSave, }: ImageEditSheetProps): React__default.JSX.Element | null;
+
+/**
+ * ModeSelector — the iPhone mode row: uppercase, letter-spaced labels in a
+ * horizontal band; the ACTIVE mode sits in a dark pill with the iOS camera
+ * yellow. VIDEO and PHOTO are persistent modes; UPLOAD is an immediate
+ * action (opens the host's picker) and never takes the active state — it is
+ * our third lane in the slot the iPhone layout leaves open next to PHOTO.
+ *
+ * Package source (`@ai-matrx/capture`) — presentational only.
+ */
+
+interface ModeSelectorProps {
+    mode: CaptureCameraMode;
+    onModeChange: (mode: CaptureCameraMode) => void;
+    onUpload: () => void;
+    /** Locks mode switching (while recording). */
+    modeDisabled?: boolean;
+    uploadDisabled?: boolean;
+    /** Host-injected extra entries after UPLOAD (e.g. SCAN) — immediate
+     *  actions, never the active mode. */
+    extraModes?: {
+        id: string;
+        label: string;
+        onSelect: () => void;
+    }[];
+}
+declare function ModeSelector({ mode, onModeChange, onUpload, modeDisabled, uploadDisabled, extraModes, }: ModeSelectorProps): React__default.JSX.Element;
+
+/**
+ * OptionsGridPanel — the iPhone two-tap options surface: tapping the grid
+ * button dims the viewfinder and reveals a rounded dark panel pinned to the
+ * bottom holding a grid of circular toggle buttons with uppercase labels
+ * (one tap to reveal, one tap to act). This is NOT a drawer — no drag
+ * handle, no route; tapping the scrim or the grid button again closes it.
+ *
+ * Tiles are injected (`CaptureOptionTile[]`) so hosts and domain extensions
+ * add their own toggles without touching the panel.
+ *
+ * Package source (`@ai-matrx/capture`) — presentational only.
+ */
+
+interface OptionsGridPanelProps {
+    open: boolean;
+    onClose: () => void;
+    tiles: CaptureOptionTile[];
+}
+declare function OptionsGridPanel({ open, onClose, tiles, }: OptionsGridPanelProps): React__default.JSX.Element | null;
+
+/**
+ * ShutterButton — the iPhone shutter: a thin white ring with a filled inner
+ * circle. Photo = white fill; video idle = red circle; video recording = the
+ * inner shape morphs to a small red rounded square (the iOS stop affordance).
+ * Press feedback is a scale-down of the INNER fill only, like iOS.
+ *
+ * Package source (`@ai-matrx/capture`) — presentational only.
+ */
+
+interface ShutterButtonProps {
+    mode: CaptureCameraMode;
+    recording: boolean;
+    disabled?: boolean;
+    onPress: () => void;
+}
+declare function ShutterButton({ mode, recording, disabled, onPress, }: ShutterButtonProps): React__default.JSX.Element;
+
+/**
+ * ZoomRow — the iPhone zoom pills floating over the bottom of the feed:
+ * small translucent circles, the active factor in a slightly larger circle
+ * with yellow text and an "×" suffix. Rendered ONLY when the host reports a
+ * real zoom range (track capabilities) — we never fake unsupported zoom.
+ *
+ * Package source (`@ai-matrx/capture`) — presentational only.
+ */
+
+interface ZoomRowProps {
+    /** Available zoom factors in ascending order (e.g. [1, 2, 4]). */
+    options: number[];
+    /** The currently applied factor (nearest option is highlighted). */
+    value: number;
+    onSelect: (factor: number) => void;
+}
+declare function ZoomRow({ options, value, onSelect }: ZoomRowProps): React__default.JSX.Element | null;
+
+interface TrackControls {
+    torchSupported: boolean;
+    torchOn: boolean;
+    toggleTorch: () => void;
+    /** ≥2 entries when the track reports a usable zoom range, else []. */
+    zoomOptions: number[];
+    zoom: number;
+    setZoom: (factor: number) => void;
+    /** Exposure compensation — only when the hardware reports a range. */
+    exposureSupported: boolean;
+    exposure: number;
+    exposureRange: {
+        min: number;
+        max: number;
+        step: number;
+    } | null;
+    setExposure: (value: number) => void;
+}
+declare function useTrackControls(stream: MediaStream | null): TrackControls;
+
+export { CameraCapture, type CameraCaptureProps, type CaptureAspect, type CaptureCameraEngine, type CaptureCameraMode, type CaptureCameraSlots, type CaptureCloudPort, type CaptureOptionTile, CaptureSheet, type CaptureSheetAction, type CaptureSheetProps, type CaptureTimerSetting, CountdownOverlay, GridOverlay, ImageEditSheet, type ImageEditSheetProps, ModeSelector, type ModeSelectorProps, OptionsGridPanel, type OptionsGridPanelProps, ShutterButton, type ShutterButtonProps, type TrackControls, ZoomRow, type ZoomRowProps, useTrackControls };