@lotics/ui 37.0.0 → 37.1.0

package/docs/catalog.md

@@ -1519,6 +1519,28 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   the sandboxed app iframe.
 - **`file_preview_types`** — `PreviewLabels` / `FilePreviewProps` / `GalleryLabels` — the
   shared label + prop contracts of the file-preview family; types only.
+- **`media_player`** — `MediaPlayer`: the ONE audio/video playback surface (`FilePreview`
+  composes it; so does the chat's recording message). Transport is the PLATFORM element's
+  — `controls preload="metadata"` — deliberately, because a hand-rolled scrub bar has to
+  re-earn keyboard access, screen-reader semantics, volume, speed, PiP, fullscreen and
+  captions that `<video>`/`<audio>` already get right. What it owns is what the element
+  does not: `kind` picks the element (never inferred from MIME — a screen recording holds
+  both streams and the CALLER decides whether this surface shows a picture), a REQUIRED
+  `accessibilityLabel`, and `objectFit: contain` so a capture letterboxes rather than
+  cropping evidence. It **fills its parent and carries no size of its own** — a lightbox
+  wants the modal's height, a chat bubble wants a fixed 16:9 box that will not resize when
+  metadata arrives, and a `fill`/`compact` prop to switch between them is exactly the
+  branching the kit forbids. Compose the box. Filling is done OUT OF FLOW (the video sits
+  absolutely inside a positioning wrapper the component owns) because a `<video>` is a
+  replaced element: once metadata loads it reports the source's intrinsic size, and any
+  ancestor sized by its content grows to match — with RN-web's `flexShrink: 0` default,
+  nothing pushes back, so a 720p capture measurably widened a 342px chat column to 367px
+  the moment it loaded. **Do not add your own fullscreen/expand control**: the native
+  transport already carries fullscreen, picture-in-picture and download, and a second
+  affordance beside them is both redundant and a claim about where it leads. Native renders
+  the `notAvailable` placeholder — playback there needs a native media dep the package does
+  not carry.
+- **`media_player_types`** — `MediaPlayerProps`; types only.
 - **`file_gallery_modal`** — `FileGalleryModal`: the FULL-SCREEN viewer — toolbar (filename
  , counter, download, optional `onOpenExternal`/`onRemove`, close-✕), prev/next, ESC,
   rotate (the 90° controls FLOAT as a pill on the image); on a phone the actions collapse

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "37.0.0",
+  "version": "37.1.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -39,6 +39,11 @@
       "default": "./src/file_preview.web.tsx"
     },
     "./file_preview_types": "./src/file_preview_types.ts",
+    "./media_player": {
+      "react-native": "./src/media_player.tsx",
+      "default": "./src/media_player.web.tsx"
+    },
+    "./media_player_types": "./src/media_player_types.ts",
     "./file_gallery_modal": "./src/file_gallery_modal.tsx",
     "./image_gallery": "./src/image_gallery.tsx",
     "./rotatable_image": "./src/rotatable_image.tsx",

package/src/file_preview.web.tsx

@@ -17,6 +17,7 @@ import { type FilePreviewProps, type PreviewLabels } from "./file_preview_types"
 import { useLoticsLocale } from "./locale";
 import { SpreadsheetView } from "./spreadsheet_view";
 import { RotatableImage } from "./rotatable_image";
+import { MediaPlayer } from "./media_player.web";
 import { downloadFileFromUrl } from "./download";
 import { colors } from "./colors";
 
@@ -56,13 +57,19 @@ export function FilePreview({ file, labels, onError, rotation, credentials }: Fi
     return <WordPreview file={file} labels={l} onError={onError} credentials={credentials} />;
   }
   if (isVideoMimeType(file.mimeType)) {
-    return <video controls preload="metadata" src={file.url} style={mediaElementStyle} />;
+    return (
+      <div style={videoFillStyle}>
+        <MediaPlayer src={file.url} kind="video" accessibilityLabel={file.filename} />
+      </div>
+    );
   }
   if (isAudioMimeType(file.mimeType)) {
     return (
       <div style={audioContainerStyle}>
         <MediaCard mimeType={file.mimeType} filename={file.filename} icon="music" size={160} />
-        <audio controls preload="metadata" src={file.url} style={audioElementStyle} />
+        <div style={audioElementStyle}>
+          <MediaPlayer src={file.url} kind="audio" accessibilityLabel={file.filename} />
+        </div>
       </div>
     );
   }
@@ -505,12 +512,7 @@ const pdfOverlayStyle: React.CSSProperties = {
   justifyContent: "center",
   pointerEvents: "none",
 };
-const mediaElementStyle: React.CSSProperties = {
-  width: "100%",
-  height: "100%",
-  backgroundColor: "rgba(10, 10, 10, 0.8)",
-  objectFit: "contain",
-};
+const videoFillStyle: React.CSSProperties = { width: "100%", height: "100%" };
 const audioContainerStyle: React.CSSProperties = {
   display: "flex",
   flexDirection: "column",

package/src/media_player.tsx

@@ -0,0 +1,36 @@
+import { StyleSheet, View } from "react-native";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { colors } from "./colors";
+import { useLoticsLocale } from "./locale";
+import type { MediaPlayerProps } from "./media_player_types";
+
+/**
+ * Native fallback. Playback needs a native media dependency this package does
+ * not carry, so it says so rather than rendering an inert box — the same choice
+ * `FilePreview` makes for the formats only its web variant can draw.
+ */
+export function MediaPlayer(props: MediaPlayerProps) {
+  const { kind, accessibilityLabel, testID } = props;
+  const l = useLoticsLocale().gallery;
+  return (
+    <View testID={testID} accessibilityLabel={accessibilityLabel} style={styles.placeholder}>
+      <Icon name={kind === "video" ? "monitor" : "music"} size={20} color={colors.zinc["400"]} />
+      <Text size="sm" color="muted">
+        {l.notAvailable}
+      </Text>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  placeholder: {
+    flexDirection: "row",
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 8,
+    padding: 16,
+    borderRadius: 8,
+    backgroundColor: colors.zinc["100"],
+  },
+});

package/src/media_player.web.tsx

@@ -0,0 +1,76 @@
+import { colors } from "./colors";
+import type { MediaPlayerProps } from "./media_player_types";
+
+/**
+ * Playback surface for one audio or video source.
+ *
+ * Transport is the PLATFORM's, deliberately. A hand-rolled play/pause/scrub bar
+ * would have to re-earn keyboard access, screen-reader semantics, volume, speed,
+ * picture-in-picture, fullscreen, download and captions — all of which the
+ * native element already does correctly, and which callers should NOT duplicate
+ * with a control of their own.
+ *
+ * It FILLS its parent rather than carrying a size. A lightbox wants the video to
+ * take the modal's height; a chat bubble wants a 16:9 box that does not resize
+ * when metadata arrives. Those are the caller's boxes, and a `fill`/`compact`
+ * prop to switch between them is the branching this codebase forbids — so the
+ * caller composes the box and this draws inside it.
+ */
+export function MediaPlayer(props: MediaPlayerProps) {
+  const { src, kind, accessibilityLabel, testID } = props;
+
+  if (kind === "audio") {
+    return (
+      <audio
+        data-testid={testID}
+        aria-label={accessibilityLabel}
+        controls
+        preload="metadata"
+        src={src}
+        style={audioStyle}
+      />
+    );
+  }
+
+  // A `<video>` is a REPLACED element: once metadata loads it reports the
+  // source's intrinsic size as its content size, and any ancestor sized by its
+  // content grows to match. React-native-web views default to `flexShrink: 0`,
+  // so nothing pushes back — a 1280x720 capture measurably widened a 342px chat
+  // column to 367px the moment it loaded, breaking the very "does not resize"
+  // promise above. Taking the media OUT OF FLOW is what makes filling safe, and
+  // it lives here rather than in each caller because a caller cannot see the
+  // intrinsic size that causes it. The wrapper carries the positioning context
+  // so the media cannot escape to some unrelated positioned ancestor.
+  return (
+    <div style={videoWrapperStyle}>
+      <video
+        data-testid={testID}
+        aria-label={accessibilityLabel}
+        controls
+        preload="metadata"
+        src={src}
+        style={videoStyle}
+      />
+    </div>
+  );
+}
+
+// Inline rather than StyleSheet: these land on DOM elements, not RN views.
+const audioStyle = { width: "100%" } as const;
+const videoWrapperStyle = {
+  position: "relative",
+  width: "100%",
+  height: "100%",
+  overflow: "hidden",
+} as const;
+const videoStyle = {
+  position: "absolute",
+  inset: 0,
+  width: "100%",
+  height: "100%",
+  display: "block",
+  // Letterbox rather than crop or stretch: a screen capture is evidence, and a
+  // cropped one silently hides part of what was on screen.
+  objectFit: "contain",
+  backgroundColor: colors.zinc["900"],
+} as const;

package/src/media_player_types.ts

@@ -0,0 +1,13 @@
+export interface MediaPlayerProps {
+  /** Already-served URL for the media — signing/auth is the host's problem. */
+  src: string;
+  /**
+   * Which element to render. Not inferred from the MIME type on purpose: a
+   * screen recording carries both streams in one file, and the caller — not the
+   * container format — decides whether this surface is showing a picture.
+   */
+  kind: "audio" | "video";
+  /** Accessible name for the player. Required: an unlabelled one is a blank control. */
+  accessibilityLabel: string;
+  testID?: string;
+}