@lotics/ui 39.0.0 → 40.2.0

package/AGENTS.md

@@ -30,7 +30,11 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
 - **Responsive layout measures the CONTAINER, not the screen.** `useContainerSize()` reports the
   nearest `SizeBoundary`; wrap one around any region whose width stops tracking its parent's, and
   `Dialog`/`Drawer`/popover bodies already are boundaries so their contents get the panel
-  rather than the region they were opened from. `useScreenSize()` answers a question about the DEVICE — is there a keyboard
+  rather than the region they were opened from. The overlay's OWN presentation is not one of
+  these questions and is not yours to answer: `PopoverContent` reads the screen itself and takes
+  no prop, because it fills the viewport whatever box opened it — handing it a container width is
+  how a narrow column on a wide display opened a full-bleed phone sheet.
+  `useScreenSize()` answers a question about the DEVICE — is there a keyboard
   worth a shortcut hint, are these touch targets — and reaching for it to decide SPACE is how a
   panel a few hundred pixels wide lays its contents out for the whole display. (A component that
   needs a number rather than a bucket — how many columns fit — measures its own box; `Table`

package/MIGRATION.md

@@ -4,6 +4,35 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 40.0.0 — `PopoverContent` decides its own presentation; `small` is gone
+
+`PopoverContent` took a `small` prop meaning "render as a bottom sheet". It now asks
+`useScreenSize()` itself. **Delete the prop** — passing it is a type error.
+
+```diff
+- <PopoverContent small={small}>
++ <PopoverContent>
+```
+
+**Why the prop had to go rather than be defaulted.** A popover is an overlay: it fills the
+viewport regardless of which box it was opened from, so the only input is how wide that
+viewport is — and there is exactly one right answer per viewport. Every caller had to
+supply it by hand, and the two ways to get it wrong both shipped: one passed
+`useContainerSize()` — the width of the *column* holding the trigger — so a narrow chat
+column on a 1728px display opened a full-bleed modal sheet; another passed nothing and so
+never became a sheet on a real phone. Leaving the prop as an override would have kept both
+mistakes writable.
+
+**What changes for a NARROW-VIEWPORT host.** The rule is the viewport, not the device, so a
+surface that is a few hundred pixels wide on a desktop — a browser side panel, an embedded
+frame — now gets the bottom sheet where a popover that passed nothing was previously always
+anchored. If that is wrong for your surface, argue it as a change to the threshold or to what
+the rule reads, for every consumer at once; do not reach for a per-instance override.
+
+If you were computing `small` only to feed this prop, drop the hook call too. `useScreenSize`
+remains exported for its real uses — deciding whether a surface is a `Dialog` or a `Popover`
+at all, sizing touch targets, showing a keyboard shortcut.
+
 ## 39.0.0 — `PageHeader.leading` is `trailing`, and it renders AFTER the title
 
 38.0.0 shipped `leading`, a slot before the title. It is now **`trailing`**, in the same

package/docs/catalog.md

@@ -1247,8 +1247,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   control both dismisses this popover AND activates that control in one click; clicking outside,
   scrolling an ancestor, or Escape dismisses. Interactions inside a layer the popover opened
   from within (a nested popover, an `Alert` confirm, a full-screen Modal like the file preview)
-  never dismiss it — clicks, scrolls, and Escape belong to that layer until it closes. Only the
-  `small` (bottom-sheet) presentation is modal (scrim). `PopoverContent` already insets its
+  never dismiss it — clicks, scrolls, and Escape belong to that layer until it closes. In a
+  NARROW VIEWPORT (`small`, under 768) it presents instead as a modal bottom sheet (scrim, close
+  button, slide-up) — decided by `PopoverContent` itself off the screen size, with nothing to pass
+  and no way to answer it differently: an overlay fills the viewport whatever box it was opened
+  from, so the width of the column holding the trigger is never the question. The viewport, not
+  the device — a few-hundred-pixel side panel on a desktop gets the sheet too.
+  `PopoverContent` already insets its
   body 12px — put content directly in it, NEVER add your own padding `View` (that double-pads);
   title/actions go in `PopoverHeader` / `PopoverFooter`. **A fixed width is the `width` PROP,
   never `style`**: `style` reaches only the BODY, and the panel is `max-content`, so a width set
@@ -1564,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.
@@ -1786,8 +1802,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   width crosses a threshold — a height-only change (the mobile soft keyboard) and a resize
   inside one bucket both return the identical value. Correct only for
   questions about the device rather than the space: is there a keyboard to show a shortcut
-  for, are these touch-sized targets, and an overlay deciding whether it is a full-screen
-  sheet. Everything spatial wants `useContainerSize`.
+  for, are these touch-sized targets, and whether a surface is a `Dialog` on a phone and a
+  `Popover` otherwise. A popover's own anchored-vs-sheet presentation is NOT one of them —
+  `PopoverContent` reads this itself and takes no prop. Everything spatial wants
+  `useContainerSize`.
 - **`use_async_fn`** — `useAsyncFn`: wrap an async function into a manual-trigger mutation —
   `[run, {loading, data, error}]`, unmount-safe, the error lands in state AND rethrows; the
   pending-state engine for a submit/download/upload action.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "39.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;
 }

package/src/popover.tsx

@@ -13,6 +13,7 @@ import { MIN_CONTROL_WIDTH } from "./control_surface";
 import { IconButton } from "./icon_button";
 import { Portal } from "./portal";
 import { SizeBoundary } from "./size_boundary";
+import { useScreenSize } from "./use_screen_size";
 import { Divider } from "./divider";
 import { useOverlayScope } from "./overlay_scope";
 import {
@@ -209,8 +210,6 @@ export interface PopoverContentProps {
    * both.
    */
   width?: number;
-  /** When true, renders as bottom sheet on small screens (close button, slide-up animation) */
-  small?: boolean;
   /** Accessible name for the bottom-sheet close button. Defaults to the locale's `overlay.close` ("Close" / "Đóng"). */
   closeLabel?: string;
   /** When true (default), the popover moves focus into its content on open and
@@ -230,10 +229,26 @@ export function PopoverContent(props: PopoverContentProps) {
     contentContainerStyle,
     disableBodyScroll,
     width,
-    small = false,
     closeLabel = locale.overlay.close,
     manageFocus = true,
   } = props;
+  // The VIEWPORT, never the container, and never a caller's opinion of either.
+  // A popover is an overlay: it fills the viewport regardless of the box it was
+  // opened from, so the only input to "anchored or bottom sheet" is how wide
+  // that viewport is — under `small` (<768) the sheet wins.
+  //
+  // This was a `small` prop and every caller answered it by hand. One answered
+  // with `useContainerSize()`, the width of whatever column held the trigger, so
+  // a narrow chat column on a desktop opened a full-bleed sheet; another passed
+  // nothing and never became a sheet on a real phone. Reading it here is the
+  // only way neither can be written again.
+  //
+  // Note this is the viewport and NOT "is this a phone": a browser side panel is
+  // a few hundred pixels of a desktop and gets the sheet too. That is the rule
+  // behaving as defined rather than a bug, but it is the reason a surface that
+  // wants a different presentation must change the RULE here, for everyone, and
+  // never re-introduce a per-caller override.
+  const { small } = useScreenSize();
   const { open, onOpenChange, triggerRef, side, align, offset, inheritTriggerWidth } =
     usePopoverContext();