@lotics/ui 37.0.0 → 38.0.0

package/MIGRATION.md

@@ -4,6 +4,34 @@ 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.
 
+## 38.0.0 — the `lg` avatar is a control (40), not a size (48)
+
+`AVATAR_PX.lg` was 48 and `AVATAR_TEXT.lg` was `lg` type. They are now **40** and `md`
+type. Every `size="lg"` avatar — `Avatar`, `MemberChip`, `GroupAvatar` — renders 8px
+smaller. Nothing to pass; there is no way to ask for 48.
+
+**Why.** The scale's whole argument is that a rung quotes a number the system already
+owns, which is why `md` is `CONTROL_CONTENT_HEIGHT` (28). `lg` quoted nothing. It is
+the rung for an avatar that stands in a band **on its own** — an account menu beside a
+row of icon buttons — and those are `CONTROL_HEIGHT`, so at 48 the avatar was the one
+item in the row that visibly got out. 40 is that number.
+
+**If a surface genuinely needs a bigger person figure**, it is not in a control band,
+and `xl` (72) is the rung for it. If neither fits, the surface is setting its own row
+height and should say so rather than reaching for an avatar rung to do it.
+
+### `PageHeader` gained `leading`, and its title now wraps instead of overflowing
+
+`leading` is additive — a control rendered immediately BEFORE the title, for something
+that changes what is AROUND the content (a side-panel toggle, a back arrow), as opposed
+to `actions`, which act on the content itself.
+
+The behaviour change to check: a title too long for the row used to keep its intrinsic
+width and push `actions` clean off the row — measured at 417px outside a 480px header.
+It now wraps, and `actions` hold their place. **If you worked around this** by shortening
+a title, hiding the CTA at narrow widths, or capping the header's width, that workaround
+is now what is distorting the layout — drop it.
+
 ## 37.0.0 — `PageContent`'s side gutter is a token, and responsive
 
 `PageContent` padded `16` at every width. It now uses `pagePad` from

package/docs/catalog.md

@@ -76,20 +76,23 @@ inline: a picker option, an assignee, a `select_member` value. Pure: resolve the
 your directory and pass `name` / `image`; never hand-roll `Avatar` + `Text`. (`MemberSelect`
 renders these per option.)
 
-**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 28 / 48 / 72
+**Size is a RUNG, never a pixel count** — `sm | md | lg | xl` = 24 / 28 / 40 / 72
 (`@lotics/ui/avatar_size`, shared by `Avatar`, `MemberChip` and `GroupAvatar`). Default `md`.
 The number was removed because the same concept had drifted to eleven different values across
 the product and its apps, so one person looked different on every screen. Pick by density:
 `sm` for a dense row or inline cell, `md` for a control band, register or list (the default),
 `lg` for a prominent row or the account menu, `xl` for a profile's own header.
 
-**`md` is `CONTROL_CONTENT_HEIGHT`** (28) — the largest rung a 40px control band seats without
-growing, and the height `InlineButton` and a `md` `IconButton` already used to sit inside a
-field. An avatar is the tallest thing in whatever row holds it, so a rung that overshoots
-doesn't look slightly big, it RESIZES the control: at the old 36 the same member chip measured
-46 in a `Select` trigger, 50 in an inline editor and 54 in an `InlineSlot`, because each
-surface had picked its own inset with no number to pick it from. Put nothing taller than `md`
-in a control — a bigger avatar belongs in a row that sets its own height.
+**Both middle rungs quote `control_surface`, and which one you want depends on whether the
+avatar is IN a control or IS one.** `md` is `CONTROL_CONTENT_HEIGHT` (28) — the largest rung a
+40px control band seats without growing, and the height `InlineButton` and a `md` `IconButton`
+already used to sit inside a field. An avatar is the tallest thing in whatever row holds it, so
+a rung that overshoots doesn't look slightly big, it RESIZES the control: at the old 36 the same
+member chip measured 46 in a `Select` trigger, 50 in an inline editor and 54 in an `InlineSlot`,
+because each surface had picked its own inset with no number to pick it from. Put nothing taller
+than `md` in a control. `lg` is `CONTROL_HEIGHT` (40) — the avatar that stands in a band on its
+own, an account menu beside a row of icon buttons, so it measures what they do. Anything bigger
+belongs in a row that sets its own height.
 
 **`sm` shows ONE initial; every larger rung shows two** — two letters are not legible at 24px.
 That is the practical reason not to reach for `sm` by reflex: on a real roster a single letter
@@ -517,7 +520,14 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   useSeparator` inserts and what menus/popovers put between option groups.
 - **`container`** — `Container`: centers content at a max width (`ContainerSize` sm|md|lg,
   `CONTAINER_SIZES`).
-- **`page_header`** — `PageHeader`: the page's title band; `actions` puts page-level CTAs on the title row (right-aligned), while `left`/`right` form a separate nav row above.
+- **`page_header`** — `PageHeader`: the page's title band. `actions` puts page-level CTAs on
+  the title row (right-aligned) and `leading` puts a control immediately BEFORE the title;
+  `left`/`right` form a separate nav row above. Split `leading` from `actions` by what the
+  control acts on: `actions` do something to the page's CONTENT (create, sort, export),
+  `leading` changes what is AROUND it (a side-panel toggle, a back arrow). A panel toggle
+  filed under `actions` reads as a peer of "create one of these". Under a title too long
+  for the row the TITLE gives way and wraps while `actions` keep their width — a wrapped
+  title is merely taller, a CTA pushed off the row is unreachable.
 - **`page_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
   region — a centred column with optional `title`/`titleRight`/`description`, `header`/`footer`
   slots and `fullscreen`. **Reach for it before hand-rolling a screen shell**: a scroller, a
@@ -1519,6 +1529,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": "38.0.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/avatar_size.ts

@@ -28,6 +28,13 @@ export type AvatarSize = "sm" | "md" | "lg" | "xl";
  * trigger, 50 in an inline editor and 54 in an `InlineSlot` — three heights for
  * one control band, because each surface had picked its own inset and none of
  * them had a number to pick it FROM.
+ *
+ * The same argument fixes the rung ABOVE it. An avatar that stands on its own in
+ * a band — an account menu next to a row of icon buttons — is not a child of a
+ * control, it IS one, so its number is `CONTROL_HEIGHT` (40), not a size picked
+ * for looking prominent. Both live rungs therefore quote `control_surface`; only
+ * `sm` (too small for two letters) and `xl` (a profile header, in no band at all)
+ * are free.
  */
 export const AVATAR_PX: Record<AvatarSize, number> = {
   /** Dense rows and inline chips — one initial, because two do not fit. */
@@ -35,8 +42,12 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
   /** The default: a 40px control band, a register, a list — anywhere a person is
    *  a row. Equals `CONTROL_CONTENT_HEIGHT` (`control_surface`). */
   md: 28,
-  /** Prominent rows, the account menu. */
-  lg: 48,
+  /** An avatar that IS a control rather than one sitting inside a control — the
+   *  account-menu trigger in a top bar, a prominent row's leading figure. Equals
+   *  `CONTROL_HEIGHT` (`control_surface`), so it lines up with the icon buttons
+   *  beside it. It was 48, which anchored to nothing: the bar's other controls
+   *  are 40, and a 48px circle among them reads as the one thing that got out. */
+  lg: 40,
   /** A profile's own header. */
   xl: 72,
 };
@@ -51,13 +62,17 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
  *
  *   sm  12 on 24 = 50%
  *   md  12 on 28 = 43%
- *   lg  20 on 48 = 42%
+ *   lg  16 on 40 = 40%
  *   xl  32 on 72 = 44%
  *
- * The two-letter rungs sit within 2 points of each other, so an avatar reads the
- * same at every size rather than growing emptier as it grows — `lg` was on `md`
- * type (16 on 48 = 33%) and was visibly the thin one. `sm` runs richer by design:
- * one letter in a small circle needs the weight.
+ * The two-letter rungs sit within 4 points of each other, so an avatar reads the
+ * same at every size rather than growing emptier as it grows — `lg` at 48 was on
+ * `md` type (16 on 48 = 33%) and was visibly the thin one. `sm` runs richer by
+ * design: one letter in a small circle needs the weight.
+ *
+ * `lg` keeps `md` type now that the circle is 40, and the next rung up would be
+ * worse in the other direction: `lg` type is 20, which on 40 is 50% — the fattest
+ * of the two-letter rungs, and the same defect this table was written to fix.
  *
  * `md` shares `sm`'s rung and is NOT the odd one out for it: the same 12px reads
  * as 50% of a 24px circle holding one letter and 43% of a 28px circle holding
@@ -68,7 +83,7 @@ export const AVATAR_PX: Record<AvatarSize, number> = {
 export const AVATAR_TEXT: Record<AvatarSize, TextSize> = {
   sm: "xs", // 12 on 24 — one letter, so it carries a larger share of the circle
   md: "xs", // 12 on 28
-  lg: "lg", // 20 on 48
+  lg: "md", // 16 on 40
   xl: "xxl", // 32 on 72
 };
 

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;
+}

package/src/page_header.tsx

@@ -5,29 +5,70 @@ import { ReactNode } from "react";
 interface PageHeaderProps {
   title: string;
   description?: string | null;
+  /** The nav row ABOVE the title — breadcrumbs, a back control, row-level status. */
   left?: ReactNode;
+  /** The nav row ABOVE the title, right-aligned. */
   right?: ReactNode;
+  /**
+   * A control that belongs to the TITLE, rendered immediately before it on the
+   * title row — a panel toggle, a back arrow into the page you came from.
+   *
+   * The distinction from `actions` is what the control acts ON, not where it
+   * looks best. `actions` are things you do to the page's CONTENT (create, sort,
+   * export) and collect at the right, where a scanning eye reaches them last;
+   * `leading` changes what is AROUND the content, and belongs against the title
+   * it frames. Putting a panel toggle in `actions` files it with the CTAs and
+   * makes the reader parse "open a side panel" as a peer of "create one of
+   * these".
+   */
+  leading?: ReactNode;
   /** Page-level actions (CTAs), rendered on the title row, right-aligned —
    *  distinct from `left`/`right`, which form a separate nav row above. */
   actions?: ReactNode;
 }
 
 export function PageHeader(props: PageHeaderProps) {
-  const { title, description, left, right, actions } = props;
+  const { title, description, left, right, leading, actions } = props;
 
   const hasNav = !!left || !!right;
 
-  const titleRow = actions ? (
-    <View style={{ flexDirection: "row", alignItems: "center", justifyContent: "space-between", gap: 12 }}>
-      <Text size="xxl" weight="semibold">
-        {title}
-      </Text>
+  // ONE shape, whichever slots are filled. Branching the row on `leading` gave
+  // the title two different behaviours under a long string — shrinking when a
+  // panel toggle happened to be present and overflowing when it was not — which
+  // is a layout law decided by an unrelated prop.
+  //
+  // The title is what gives way; `actions` keep their width, because a CTA
+  // pushed off the row is unreachable while a wrapped title is merely taller.
+  // Both halves of the pair are required: a React Native `View`/`Text` does NOT
+  // shrink by default (`flexShrink: 0`, unlike the web), and `flexShrink` alone
+  // then floors the item at its MIN-CONTENT width — the longest word — so
+  // `minWidth: 0` is what lets it actually wrap. `DetailRow`'s spread value is
+  // the same pair for the same reason.
+  const titleRow = (
+    <View
+      style={{
+        flexDirection: "row",
+        alignItems: "center",
+        justifyContent: "space-between",
+        gap: 12,
+      }}
+    >
+      <View
+        style={{
+          flexDirection: "row",
+          alignItems: "center",
+          gap: 8,
+          flexShrink: 1,
+          minWidth: 0,
+        }}
+      >
+        {leading}
+        <Text size="xxl" weight="semibold" style={{ flexShrink: 1, minWidth: 0 }}>
+          {title}
+        </Text>
+      </View>
       {actions}
     </View>
-  ) : (
-    <Text size="xxl" weight="semibold">
-      {title}
-    </Text>
   );
 
   return (