@lotics/ui 40.0.0 → 40.2.0

package/docs/catalog.md

@@ -1569,7 +1569,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   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
+  affordance beside them is both redundant and a claim about where it leads. A source it
+  cannot load is surfaced, never silent — a media element that fails paints an EMPTY BOX and
+  reports nothing, so an expired serving token is indistinguishable from a feature that never
+  produced a file; on error it renders a retryable notice filling the same box instead
+  (`mediaPlayer` locale slice, worded agnostically because the kit does not know whether it is
+  showing a recording, a clip or an attachment). Failure is remembered per SOURCE, so swapping
+  `src` presents the new one rather than inheriting the old one's error, and the retry remounts
+  the element — a re-render alone does not re-request the source. **`onError` reports the failure
+  with the HTTP STATUS**, not just the `MediaError`: a lapsed token, a missing file and an
+  unplayable codec all arrive as code 4, so the code alone cannot say which happened. The player
+  resolves the status by re-requesting the source, and only when an `onError` is supplied — the
+  kit carries no analytics, so the host decides whether the answer is worth a request. Native renders
   the `notAvailable` placeholder — playback there needs a native media dep the package does
   not carry.
 - **`media_player_types`** — `MediaPlayerProps`; types only.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "40.0.0",
+  "version": "40.2.0",
   "type": "module",
   "exports": {
     "./vite": {

package/src/locale.tsx

@@ -114,6 +114,12 @@ export interface LoticsLocale {
    *  (open/download/remove + the confirm), the gallery chrome (close, prev/next,
    *  rotate), and the preview captions (not-available / load-failed / password). */
   gallery: GalleryLabels;
+  /** `MediaPlayer`: the caption when a source will not load. Its own slice
+   *  rather than the `gallery` one, whose wording is "preview" — true of
+   *  `FilePreview` and wrong everywhere else the player is used, and a single
+   *  string cannot mean both. Agnostic on purpose: the kit does not know
+   *  whether it is showing a recording, a clip or an attachment. */
+  mediaPlayer: { loadFailed: string };
   /** `Avatar`: the fallback name (initials + a11y label) shown when no `name`. */
   avatar: { unknown: string };
   /** `BackButton` + `PopoverNavHeader`: the back-chevron's a11y name. */
@@ -306,6 +312,7 @@ export const en: LoticsLocale = {
     selectDateRange: "Select date range", selectDate: "Select date",
     clear: "Clear", done: "Done", placeholder: "All time",
   },
+  mediaPlayer: { loadFailed: "Failed to load media" },
   gallery: {
     close: "Close",
     previous: "Previous",
@@ -494,6 +501,7 @@ export const vi: LoticsLocale = {
     download: "Tải xuống",
     passwordProtected: "Tệp có mật khẩu — không xem trước được",
   },
+  mediaPlayer: { loadFailed: "Không tải được nội dung" },
   avatar: { unknown: "Không rõ" },
   nav: { back: "Quay lại" },
   chart: { noData: "Không có dữ liệu", total: "Tổng" },

package/src/media_player.web.tsx

@@ -1,4 +1,10 @@
+import { useState } from "react";
+import { StyleSheet, View } from "react-native";
+import { Button } from "./button";
+import { Icon } from "./icon";
+import { Text } from "./text";
 import { colors } from "./colors";
+import { useLoticsLocale } from "./locale";
 import type { MediaPlayerProps } from "./media_player_types";
 
 /**
@@ -17,16 +23,68 @@ import type { MediaPlayerProps } from "./media_player_types";
  * caller composes the box and this draws inside it.
  */
 export function MediaPlayer(props: MediaPlayerProps) {
-  const { src, kind, accessibilityLabel, testID } = props;
+  const { src, kind, accessibilityLabel, onError, testID } = props;
+  const l = useLoticsLocale();
+  // Bumped to REMOUNT the element on retry. Clearing the flag alone leaves the
+  // failed element in place, and a media element does not re-request its source
+  // just because it re-rendered.
+  const [attempt, setAttempt] = useState(0);
+  // The failed SOURCE, not a boolean: this component keeps its position when a
+  // caller swaps `src` (a gallery stepping to the next clip), and a boolean
+  // would carry the previous file's failure onto a file that was never tried.
+  const [failedSrc, setFailedSrc] = useState<string | null>(null);
+  const failed = failedSrc === src;
+
+  const handleError = (element: HTMLMediaElement) => {
+    setFailedSrc(src);
+    // Only probe when someone is listening — the host pays a request for the
+    // answer, so it is not spent when nothing reads it.
+    if (!onError) return;
+    const code = element.error?.code ?? null;
+    void resolveStatus(src).then((status) => onError({ status, code }));
+  };
+
+  /**
+   * A media element that cannot load its source renders an EMPTY BOX and says
+   * nothing — no pixel changes, no message, nothing to act on. An expired
+   * file-serving token was indistinguishable from "the feature never recorded
+   * anything", for a recording that was intact on disk the whole time. Whatever
+   * the cause, a failed load has to be visible and retryable.
+   */
+  if (failed) {
+    const notice = (
+      <View testID={testID ? `${testID}-error` : undefined} style={styles.error}>
+        <Icon name="circle-alert" size={20} color={colors.zinc["400"]} />
+        <Text size="sm" color="muted">
+          {l.mediaPlayer.loadFailed}
+        </Text>
+        <Button
+          title={l.errorState.retry}
+          color="secondary"
+          onPress={() => {
+            setFailedSrc(null);
+            setAttempt((n) => n + 1);
+          }}
+        />
+      </View>
+    );
+    // Video fills a box the caller sized, so the notice has to fill it too or
+    // the frame half-empties on failure. The wrapper is a flex container for
+    // exactly that reason — measured, `flex: 1` inside the default block box
+    // left the notice 50px tall in a 206px frame.
+    return kind === "video" ? <div style={videoWrapperStyle}>{notice}</div> : notice;
+  }
 
   if (kind === "audio") {
     return (
       <audio
+        key={attempt}
         data-testid={testID}
         aria-label={accessibilityLabel}
         controls
         preload="metadata"
         src={src}
+        onError={(e) => handleError(e.currentTarget)}
         style={audioStyle}
       />
     );
@@ -44,21 +102,52 @@ export function MediaPlayer(props: MediaPlayerProps) {
   return (
     <div style={videoWrapperStyle}>
       <video
+        key={attempt}
         data-testid={testID}
         aria-label={accessibilityLabel}
         controls
         preload="metadata"
         src={src}
+        onError={(e) => handleError(e.currentTarget)}
         style={videoStyle}
       />
     </div>
   );
 }
 
+const styles = StyleSheet.create({
+  error: {
+    flex: 1,
+    alignItems: "center",
+    justifyContent: "center",
+    gap: 8,
+    padding: 16,
+    borderRadius: 8,
+    backgroundColor: colors.zinc["100"],
+  },
+});
+
+/**
+ * The status behind a failed load. A media element never exposes it — every
+ * transport failure arrives as the same opaque `MediaError` — so the only way to
+ * tell an expired token from a broken file is to ask again and read the code.
+ * Null means even that could not be determined (offline, or a source this
+ * origin may not read), which is itself the useful answer.
+ */
+async function resolveStatus(src: string): Promise<number | null> {
+  try {
+    const res = await fetch(src, { method: "HEAD", credentials: "include" });
+    return res.status;
+  } catch {
+    return null;
+  }
+}
+
 // Inline rather than StyleSheet: these land on DOM elements, not RN views.
 const audioStyle = { width: "100%" } as const;
 const videoWrapperStyle = {
   position: "relative",
+  display: "flex",
   width: "100%",
   height: "100%",
   overflow: "hidden",

package/src/media_player_types.ts

@@ -1,3 +1,18 @@
+/**
+ * Why a source would not play.
+ *
+ * The media element's own `MediaError` is nearly useless on its own: a 401, a
+ * 404 and a genuinely unplayable codec all surface as code 4
+ * (`SRC_NOT_SUPPORTED`). The STATUS is what separates "the session lapsed" from
+ * "this file is broken", so the player resolves it before reporting.
+ */
+export interface MediaLoadFailure {
+  /** HTTP status of the source, or null when it could not be determined. */
+  status: number | null;
+  /** `MediaError.code` — 1 aborted, 2 network, 3 decode, 4 unsupported. */
+  code: number | null;
+}
+
 export interface MediaPlayerProps {
   /** Already-served URL for the media — signing/auth is the host's problem. */
   src: string;
@@ -9,5 +24,12 @@ export interface MediaPlayerProps {
   kind: "audio" | "video";
   /** Accessible name for the player. Required: an unlabelled one is a blank control. */
   accessibilityLabel: string;
+  /**
+   * Called once when a source fails to load. The player already SHOWS the
+   * failure; this is for the host to report it, because the kit carries no
+   * analytics of its own. Omit it and no status probe is performed — the work
+   * only happens when someone is listening.
+   */
+  onError?: (failure: MediaLoadFailure) => void;
   testID?: string;
 }