@lotics/ui 36.0.0 → 37.1.0

package/MIGRATION.md

@@ -4,6 +4,33 @@ 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.
 
+## 37.0.0 — `PageContent`'s side gutter is a token, and responsive
+
+`PageContent` padded `16` at every width. It now uses `pagePad` from
+`@lotics/ui/spacing` — **16 on a phone, 32 wider**. Nothing to pass; the only visible
+change is that a wide page breathes where it used to sit 16px off the chrome.
+
+```ts
+import { pagePad } from "@lotics/ui/spacing";
+pagePad(small); // SPACE.md | SPACE.xl
+```
+
+**Why a token rather than a prop.** A screen that cannot use this shell — one with a
+rail, a side panel, or a scroller it must hold a ref to — still has to land on the
+same left edge, and a list and the record it opens are one reading column seen twice:
+a gutter that differs between them slides the content sideways as the reader crosses.
+Left to each app this lands on hand-picked numbers; the case that prompted this had
+14 and 28, one of them not even a multiple of 4, against a scale whose own doc says
+that reads as broken.
+
+It is also COUPLED to `ROW_WASH_BLEED`: a register row bleeds its wash outward to
+`pagePad − ROW_WASH_BLEED`. Two numbers that must be read together should not live in
+two repositories.
+
+**If you hand-roll a page shell, import `pagePad` instead of choosing.** And check
+whether `PageContent` would do — it carries the centred `maxWidth` column and the
+title band most screens re-type by hand.
+
 ## 36.0.0 — seven components stopped announcing English; their strings moved to the pack
 
 **Nothing to change if you pass a shipped pack** (`en` / `vi`) — both carry every

package/docs/catalog.md

@@ -418,7 +418,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   scales and `getCssVariables()` — an OPT-IN serializer to `--lotics-*` CSS variables for
   hand-rolled plain DOM/CSS (nothing injects them automatically; `@lotics/ui` components
   don't need them).
-- **`spacing`** — the `SPACE` scale + `SpaceToken`.
+- **`spacing`** — the `SPACE` scale + `SpaceToken`, and **`pagePad(small)`** — the page's
+  side gutter (`SPACE.md` on a phone, `SPACE.xl` wider). `PageContent` applies it; a screen
+  that cannot use that shell — one with a rail, a side panel or its own scroller — imports it
+  rather than picking a number, because a list and the record it opens are one reading column
+  seen twice and must not shift sideways between them. It is also COUPLED to `ROW_WASH_BLEED`:
+  a register row bleeds its wash outward to `pagePad − ROW_WASH_BLEED`, so the two are read
+  together and neither belongs to the app.
 - **`control_surface`** — `CONTROL_HEIGHT` (40), `CONTROL_CONTENT_HEIGHT` (28 — the tallest
   FIXED-height node a 40px band seats, 6 per side of air; what `InlineButton` and a `md`
   `IconButton` already used, now named so an avatar or any other child lands on it too. Text
@@ -513,7 +519,13 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   `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_content`** — `PageContent` + `PAGE_SIZES`: the page's padded, width-capped content
-  region.
+  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
+  centred `maxWidth` column and a title band re-typed per screen is how two pages of one app end
+  up on different gutters. Its side padding is `pagePad` (`@lotics/ui/spacing`), so a screen that
+  genuinely cannot use it — one with a rail, a side panel, or a scroller it must hold a ref to —
+  still lands on the same edge by importing that token. It OWNS its `ScrollView` and exposes no
+  scroll props, which is the real limit on adoption.
 - **`accordion`** — `Accordion` + `AccordionHeader`/`AccordionTitle`/`AccordionMeta`:
   expandable section rows.
 - **`tabs`** — `Tabs`: switch between content sections; WAI-ARIA tablist + roving tabindex;
@@ -1507,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": "36.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;
+}

package/src/page_content.tsx

@@ -4,6 +4,7 @@ import { colors } from "@lotics/ui/colors";
 import { Spacer } from "@lotics/ui/spacer";
 import { ReactNode } from "react";
 import { useContainerSize } from "@lotics/ui/size_boundary";
+import { pagePad } from "@lotics/ui/spacing";
 
 interface PageContentProps {
   children: ReactNode;
@@ -26,6 +27,10 @@ export function PageContent(props: PageContentProps) {
   const screenSize = useContainerSize();
 
   const maxWidth = !screenSize.small && size ? PAGE_SIZES[size] : undefined;
+  // The gutter is a TOKEN, not this component's own number — a screen that cannot
+  // use this shell (one with a rail, a side panel, its own scroller) still has to
+  // land on the same edge, and it can only do that if the number has one home.
+  const pad = pagePad(screenSize.small);
 
   if (fullscreen) {
     return (
@@ -33,7 +38,7 @@ export function PageContent(props: PageContentProps) {
         {!!header && (
           <View
             style={{
-              paddingHorizontal: 16,
+              paddingHorizontal: pad,
               paddingTop: 16,
               width: "100%",
             }}
@@ -51,7 +56,7 @@ export function PageContent(props: PageContentProps) {
       {!!header && (
         <View
           style={{
-            paddingHorizontal: 16,
+            paddingHorizontal: pad,
             paddingTop: 16,
             maxWidth,
             width: "100%",
@@ -73,7 +78,7 @@ export function PageContent(props: PageContentProps) {
             maxWidth,
             width: "100%",
             marginHorizontal: "auto",
-            paddingHorizontal: 16,
+            paddingHorizontal: pad,
           }}
         >
           <View
@@ -101,19 +106,25 @@ export function PageContent(props: PageContentProps) {
         </View>
       </ScrollView>
       {!!footer && (
-        <View
-          style={{
-            borderTopWidth: 1,
-            borderTopColor: colors.border,
-            padding: 16,
-            paddingBottom: 24,
-          }}
-        >
+        // The RULE spans the page; the CONTENT sits on the body's column. Those
+        // are two different widths, which is why they are two elements.
+        <View style={{ borderTopWidth: 1, borderTopColor: colors.border }}>
+          {/* ONE box carries the cap AND the gutter, exactly as the body's does.
+              Split across two — the padding outside, the cap inside — they
+              compute different edges the moment a cap is in play and the viewport
+              is wider than it: the body's content starts `pad` inside a centred
+              1280 box, while the footer's starts wherever 1280 centres inside a
+              padded full-width box. That put a footer's totals 32px off the column
+              they total, and it is invisible at phone width, where nothing is
+              capped. */}
           <View
             style={{
               maxWidth,
               width: "100%",
               marginHorizontal: "auto",
+              paddingHorizontal: pad,
+              paddingTop: 16,
+              paddingBottom: 24,
             }}
           >
             {footer}

package/src/spacing.ts

@@ -21,3 +21,23 @@ export const SPACE = {
 } as const;
 
 export type SpaceToken = keyof typeof SPACE;
+
+/**
+ * The page's side gutter, by width — what a full-page surface pads by.
+ *
+ * ONE number, because a list and the record it opens are the same reading column
+ * seen twice: a gutter that differs between them slides the content sideways at
+ * the moment the reader changes screens. `PageContent` applies it; a screen that
+ * hand-rolls its own shell imports it rather than picking again.
+ *
+ * ON THE LADDER above, deliberately. Left to each app this lands on numbers like
+ * 14 and 28 — one of them not even a multiple of 4 — which is the "reads as
+ * broken" case this scale exists to prevent. `md` on a phone, where 28 a side
+ * spends 15% of a 375px screen on margin and 16 is the platform norm besides;
+ * `xl` wider, where 16 leaves a capped column nearly touching the chrome.
+ *
+ * COUPLED to `ROW_WASH_BLEED` (`control_surface`): a register row bleeds its wash
+ * OUTWARD past this, landing at `pagePad − ROW_WASH_BLEED`. Two numbers that must
+ * be read together is exactly why this one does not belong to the app.
+ */
+export const pagePad = (small: boolean): number => (small ? SPACE.md : SPACE.xl);