@lotics/ui 3.3.0 → 3.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "3.3.0",
+  "version": "3.5.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -19,6 +19,8 @@
     "./file_preview_types": "./src/file_preview_types.ts",
     "./file_gallery_modal": "./src/file_gallery_modal.tsx",
     "./image_gallery": "./src/image_gallery.tsx",
+    "./rotatable_image": "./src/rotatable_image.tsx",
+    "./use_image_rotation": "./src/use_image_rotation.ts",
     "./file_thumbnail_grid": "./src/file_thumbnail_grid.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
@@ -79,6 +81,7 @@
     "./action_menu": "./src/action_menu.tsx",
     "./card_select_item": "./src/card_select_item.tsx",
     "./badge": "./src/badge.tsx",
+    "./callout": "./src/callout.tsx",
     "./divider": "./src/divider.tsx",
     "./spacer": "./src/spacer.tsx",
     "./index.css": "./src/index.css",

package/src/alert.tsx

@@ -135,14 +135,20 @@ class Alert {
       }, []);
 
       useEffect(() => {
+        // Close on KEYUP + capture + stopImmediatePropagation — the same event
+        // RN-web Modal closes on, run first and stopped — so an alert opened over
+        // a drawer/dialog closes only the alert, not the modal behind it. Closing
+        // on keydown would unmount the alert before the keyup and let RN's keyup
+        // close the modal underneath too. (Matches the Popover's ESC handling.)
         const handleEscape = (e: KeyboardEvent) => {
           if (e.key === "Escape" && alertOptions.cancelable !== false) {
+            e.stopImmediatePropagation();
             handleDismiss();
           }
         };
 
-        document.addEventListener("keydown", handleEscape);
-        return () => document.removeEventListener("keydown", handleEscape);
+        document.addEventListener("keyup", handleEscape, true);
+        return () => document.removeEventListener("keyup", handleEscape, true);
       }, [handleDismiss]);
 
       if (!visible) {

package/src/callout.tsx

@@ -0,0 +1,75 @@
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Icon, type IconName } from "./icon";
+import { colors } from "./colors";
+
+export type CalloutTone = "info" | "success" | "warning" | "error" | "neutral";
+
+interface CalloutProps {
+  /** Sets the accent (icon + tint + border) and the default icon. Default "info". */
+  tone?: CalloutTone;
+  /** Optional bold heading above the message. */
+  title?: string;
+  /** The message body — kept in the default text color for legibility on the tint. */
+  message: string;
+  /** Override the per-tone default icon (any kit icon), or `null` to drop it. */
+  icon?: IconName | null;
+}
+
+interface ToneStyle {
+  bg: string;
+  border: string;
+  icon: string;
+  glyph: IconName;
+}
+
+const TONES: Record<CalloutTone, ToneStyle> = {
+  info: { bg: colors.blue[50], border: colors.blue[200], icon: colors.blue[600], glyph: "info" },
+  success: { bg: colors.emerald[50], border: colors.emerald[200], icon: colors.emerald[600], glyph: "circle-check" },
+  warning: { bg: colors.amber[50], border: colors.amber[200], icon: colors.amber[600], glyph: "triangle-alert" },
+  error: { bg: colors.red[50], border: colors.red[200], icon: colors.red[600], glyph: "circle-alert" },
+  neutral: { bg: colors.zinc[50], border: colors.zinc[200], icon: colors.zinc[500], glyph: "info" },
+};
+
+/**
+ * An inline callout — a tinted, bordered box carrying a short status message
+ * (info / success / warning / error / neutral). Use it inline in a flow: form
+ * feedback, a heads-up, an actionable empty state. For a blocking, dismissible
+ * prompt use `Alert`; for a one-word status use `Badge`. The tone is carried by
+ * the icon + tint + border (never color alone — the icon and text stay legible),
+ * so it reads on a glance and meets contrast on the light tint.
+ */
+export function Callout({ tone = "info", title, message, icon }: CalloutProps) {
+  const t = TONES[tone];
+  const glyph = icon === null ? null : (icon ?? t.glyph);
+  return (
+    <View
+      accessibilityRole={tone === "error" || tone === "warning" ? "alert" : undefined}
+      style={[styles.container, { backgroundColor: t.bg, borderColor: t.border }]}
+    >
+      {glyph ? <Icon name={glyph} size={18} color={t.icon} /> : null}
+      <View style={styles.body}>
+        {title ? (
+          <Text size="sm" weight="semibold">
+            {title}
+          </Text>
+        ) : null}
+        <Text size="sm">{message}</Text>
+      </View>
+    </View>
+  );
+}
+
+export type { CalloutProps };
+
+const styles = StyleSheet.create({
+  container: {
+    flexDirection: "row",
+    alignItems: "flex-start",
+    gap: 10,
+    padding: 12,
+    borderRadius: 10,
+    borderWidth: 1,
+  },
+  body: { flex: 1, gap: 2, paddingTop: 1 },
+});

package/src/empty_state.tsx

@@ -1,21 +1,36 @@
+import type { ReactNode } from "react";
 import { View, StyleSheet } from "react-native";
 import { Text } from "./text";
+import { Icon, type IconName } from "./icon";
+import { colors } from "./colors";
 
 interface EmptyStateProps {
   /** What's empty, in plain language ("Không có nhân viên nào khớp"). */
   message: string;
   /** What the user can do about it ("Thử từ khóa khác"). */
   hint?: string;
+  /** Optional Lucide glyph centered above the message — a visual anchor so the
+   *  empty region reads as a deliberate state, not two lone lines of muted text. */
+  icon?: IconName;
+  /** Optional call-to-action below the text (e.g. a Button) for an actionable
+   *  empty state ("no records yet → create one"). */
+  action?: ReactNode;
 }
 
 /**
  * Centered placeholder for an empty list/filter result. Generous vertical
  * space on purpose — an empty region that collapses to nothing reads as a
- * rendering bug, not a state.
+ * rendering bug, not a state. Pass `icon` for a visual anchor and `action`
+ * for a CTA when the empty state is actionable.
  */
 export function EmptyState(props: EmptyStateProps) {
   return (
     <View style={styles.container}>
+      {props.icon ? (
+        <View style={styles.icon}>
+          <Icon name={props.icon} size={28} color={colors.zinc[400]} />
+        </View>
+      ) : null}
       <Text size="sm" color="muted">
         {props.message}
       </Text>
@@ -24,6 +39,7 @@ export function EmptyState(props: EmptyStateProps) {
           {props.hint}
         </Text>
       ) : null}
+      {props.action ? <View style={styles.action}>{props.action}</View> : null}
     </View>
   );
 }
@@ -34,4 +50,10 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 4,
   },
+  icon: {
+    marginBottom: 4,
+  },
+  action: {
+    marginTop: 8,
+  },
 });

package/src/file_gallery_modal.tsx

@@ -16,6 +16,8 @@ import { Icon } from "./icon";
 import { colors } from "./colors";
 import type { DisplayFile } from "./file_thumbnail";
 import { FilePreview } from "./file_preview";
+import { isImageMimeType } from "./mime";
+import { useImageRotation, type ImageRotation } from "./use_image_rotation";
 import type { PreviewLabels } from "./file_preview_types";
 
 export interface FileGalleryModalProps {
@@ -32,6 +34,14 @@ export interface FileGalleryModalProps {
   labels?: Partial<PreviewLabels>;
   /** Reported when a file fails to render (host wires to its logger). */
   onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
+  /**
+   * Optional shared rotation state (from `useImageRotation`) — pass it to keep an
+   * inline gallery and this modal in sync. Omitted ⇒ the modal keeps its own
+   * in-memory rotation. View-only; image files only.
+   */
+  rotation?: ImageRotation;
+  /** Show 90° rotate controls for image files. Default true. */
+  rotatable?: boolean;
 }
 
 /**
@@ -39,9 +49,12 @@ export interface FileGalleryModalProps {
  * via FilePreview; unknown types show a download placeholder.
  */
 export function FileGalleryModal(props: FileGalleryModalProps) {
-  const { files, activeIndex, onIndexChange, captionHint, labels, onError } = props;
+  const { files, activeIndex, onIndexChange, captionHint, labels, onError, rotation, rotatable = true } = props;
   const visible = activeIndex !== null;
   const overlayRef = useRef<View | null>(null);
+  // Own the rotation when the host doesn't share one (standalone consumers).
+  const internalRotation = useImageRotation();
+  const rot = rotation ?? internalRotation;
 
   const close = useCallback(() => onIndexChange(null), [onIndexChange]);
   const next = useCallback(() => {
@@ -53,22 +66,35 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
     onIndexChange(Math.max(activeIndex - 1, 0));
   }, [activeIndex, onIndexChange]);
 
-  // Keyboard navigation (web only — RN native handles via Modal accessibility).
+  // Arrow nav (web only — RN native handles via Modal accessibility). Capture +
+  // stopImmediatePropagation so ←/→ drive THIS gallery and never also reach a
+  // record-nav arrow handler on a drawer behind it.
+  //
+  // Escape is deliberately NOT handled here — it closes via the Modal's
+  // `onRequestClose`, which RN-web fires on KEYUP and scopes to the topmost
+  // modal (its `activeModalStack`). Closing here on KEYDOWN would unmount this
+  // modal first, so by the keyup RN's active modal is the drawer underneath and
+  // it closes that too — the "ESC closes the preview AND the record" bug.
   useEffect(() => {
     if (!visible || typeof window === "undefined") return;
     function onKey(e: KeyboardEvent) {
-      if (e.key === "Escape") close();
-      else if (e.key === "ArrowRight") next();
-      else if (e.key === "ArrowLeft") prev();
+      if (e.key === "ArrowRight") {
+        e.stopImmediatePropagation();
+        next();
+      } else if (e.key === "ArrowLeft") {
+        e.stopImmediatePropagation();
+        prev();
+      }
     }
-    window.addEventListener("keydown", onKey);
-    return () => window.removeEventListener("keydown", onKey);
-  }, [visible, close, next, prev]);
+    window.addEventListener("keydown", onKey, true);
+    return () => window.removeEventListener("keydown", onKey, true);
+  }, [visible, next, prev]);
 
   if (!visible || activeIndex === null) return null;
   const file = files[activeIndex];
   if (!file) return null;
 
+  const isImage = isImageMimeType(file.mimeType);
   const total = files.length;
   const caption = captionHint
     ? `${file.filename} · ${activeIndex + 1} / ${total} · ${captionHint}`
@@ -85,9 +111,30 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
         />
 
         <View style={styles.previewPanel}>
-          <FilePreview file={file} labels={labels} onError={onError} />
+          <FilePreview file={file} labels={labels} onError={onError} rotation={rot.rotationFor(file.id)} />
         </View>
 
+        {isImage && rotatable ? (
+          <View style={styles.controls}>
+            <Pressable
+              onPress={() => rot.rotate(file.id, -1)}
+              accessibilityRole="button"
+              accessibilityLabel="Rotate left"
+              style={styles.controlButton}
+            >
+              <Icon name="rotate-ccw" size={20} color={colors.white} />
+            </Pressable>
+            <Pressable
+              onPress={() => rot.rotate(file.id, 1)}
+              accessibilityRole="button"
+              accessibilityLabel="Rotate right"
+              style={styles.controlButton}
+            >
+              <Icon name="rotate-cw" size={20} color={colors.white} />
+            </Pressable>
+          </View>
+        ) : null}
+
         {activeIndex > 0 ? (
           <Pressable
             onPress={prev}
@@ -151,6 +198,21 @@ const styles = StyleSheet.create({
   navRight: {
     right: 16,
   },
+  controls: {
+    position: "absolute",
+    top: 16,
+    right: 16,
+    flexDirection: "row",
+    gap: 8,
+  },
+  controlButton: {
+    width: 44,
+    height: 44,
+    borderRadius: 22,
+    backgroundColor: "rgba(0, 0, 0, 0.4)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
   captionWrap: {
     position: "absolute",
     bottom: 24,

package/src/file_preview.tsx

@@ -1,7 +1,8 @@
-import { View, Image, StyleSheet } from "react-native";
+import { View, StyleSheet } from "react-native";
 import { Text } from "./text";
 import { DocumentCard } from "./file_thumbnail";
 import { isImageMimeType } from "./mime";
+import { RotatableImage } from "./rotatable_image";
 import { type FilePreviewProps, resolveLabels } from "./file_preview_types";
 
 /**
@@ -9,17 +10,10 @@ import { type FilePreviewProps, resolveLabels } from "./file_preview_types";
  * document placeholder. Rich document rendering (docx/xlsx/pdf) is web-only —
  * the `.web.tsx` variant carries it; native consumers download instead.
  */
-export function FilePreview({ file, labels }: FilePreviewProps) {
+export function FilePreview({ file, labels, rotation }: FilePreviewProps) {
   const l = resolveLabels(labels);
   if (isImageMimeType(file.mimeType)) {
-    return (
-      <Image
-        source={{ uri: file.url }}
-        resizeMode="contain"
-        style={styles.image}
-        accessibilityIgnoresInvertColors
-      />
-    );
+    return <RotatableImage uri={file.url} alt={file.filename} rotation={rotation} />;
   }
   return (
     <View style={styles.placeholder}>
@@ -32,7 +26,6 @@ export function FilePreview({ file, labels }: FilePreviewProps) {
 }
 
 const styles = StyleSheet.create({
-  image: { flex: 1, width: "100%" },
   placeholder: { flex: 1, justifyContent: "center", alignItems: "center", gap: 16 },
   placeholderText: { marginTop: 8 },
 });

package/src/file_preview.web.tsx

@@ -13,6 +13,7 @@ import {
 } from "./mime";
 import { type FilePreviewProps, resolveLabels, type PreviewLabels } from "./file_preview_types";
 import { SpreadsheetView } from "./spreadsheet_view";
+import { RotatableImage } from "./rotatable_image";
 import { downloadFileFromUrl } from "./download";
 
 /**
@@ -24,11 +25,18 @@ import { downloadFileFromUrl } from "./download";
  * Pure: i18n via `labels` props, errors via `onError` — no lingui/analytics
  * (purity test). Lifted from the frontend gallery so both share one renderer.
  */
-export function FilePreview({ file, labels, onError }: FilePreviewProps) {
+export function FilePreview({ file, labels, onError, rotation }: FilePreviewProps) {
   const l = resolveLabels(labels);
 
   if (isImageMimeType(file.mimeType)) {
-    return <img alt={file.filename} src={file.url} style={imageStyle} />;
+    return (
+      <RotatableImage
+        uri={file.url}
+        alt={file.filename}
+        rotation={rotation}
+        backgroundColor="rgba(10, 10, 10, 0.8)"
+      />
+    );
   }
   if (isPdfMimeType(file.mimeType)) {
     return <iframe src={file.url} title={file.filename} style={fullFrameStyle} />;
@@ -156,12 +164,6 @@ const styles = StyleSheet.create({
   placeholderText: { marginTop: 8 },
 });
 
-const imageStyle: React.CSSProperties = {
-  width: "100%",
-  height: "100%",
-  objectFit: "contain",
-  backgroundColor: "rgba(10, 10, 10, 0.8)",
-};
 const fullFrameStyle: React.CSSProperties = { width: "100%", height: "100%", border: "none" };
 const mediaElementStyle: React.CSSProperties = {
   width: "100%",

package/src/file_preview_types.ts

@@ -28,6 +28,8 @@ export interface FilePreviewProps {
    * package stays analytics-free), so the host wires this to its logger.
    */
   onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
+  /** View rotation in degrees (0/90/180/270) — applied to image previews only. */
+  rotation?: number;
 }
 
 export function resolveLabels(labels: Partial<PreviewLabels> | undefined): PreviewLabels {

package/src/filter_pill.tsx

@@ -1,4 +1,4 @@
-import { type ReactNode } from "react";
+import { type ReactNode, useState } from "react";
 import { StyleSheet } from "react-native";
 import { Text } from "./text";
 import { Icon } from "./icon";
@@ -23,8 +23,11 @@ export interface FilterPillProps {
   clearLabel?: string;
   /** The editor revealed on press — a premium primitive (`RangeSlider`,
    *  `Counter`, `PickerMenu` multi) or any composed control. `FilterPill` owns
-   *  the pill + popover chrome; the consumer owns the value and applies it. */
-  children: ReactNode;
+   *  the pill + popover chrome; the consumer owns the value and applies it.
+   *  Pass a render function to receive `close` — the one editor that closes on
+   *  action is single-select (`<PickerMenu>` → close on pick); range/counter/
+   *  multi stay open and dismiss on outside-press, so they pass a plain node. */
+  children: ReactNode | ((api: { close: () => void }) => ReactNode);
   side?: PopoverSide;
   align?: PopoverAlign;
   /** Optional controlled popover state — for an editor that closes on Save. */
@@ -71,8 +74,18 @@ export function FilterPill(props: FilterPillProps) {
   // custom footer — a valued, non-clearable pill ("Target: 20") keeps its chevron.
   const showClear = active && !!onClear && !footer;
 
+  // Own the open state so the editor can close itself via the render-prop
+  // `close`, while still honoring a controlled `open`/`onOpenChange` from the
+  // parent (the Save-footer VALUE-pill case).
+  const [internalOpen, setInternalOpen] = useState(false);
+  const isOpen = open ?? internalOpen;
+  const setOpen = (next: boolean) => {
+    if (open === undefined) setInternalOpen(next);
+    onOpenChange?.(next);
+  };
+
   return (
-    <Popover side={side} align={align} open={open} onOpenChange={onOpenChange}>
+    <Popover side={side} align={align} open={isOpen} onOpenChange={setOpen}>
       <PopoverTrigger>
         <PillButton onDismiss={showClear ? onClear : undefined} dismissTooltip={clearLabel}>
           <Text size="sm" weight="medium" color={active ? "zinc-900" : "zinc-700"} numberOfLines={1}>
@@ -82,7 +95,7 @@ export function FilterPill(props: FilterPillProps) {
         </PillButton>
       </PopoverTrigger>
       <PopoverContent style={styles.body} disableBodyScroll>
-        {children}
+        {typeof children === "function" ? children({ close: () => setOpen(false) }) : children}
         {footer ? (
           <PopoverFooter>{footer}</PopoverFooter>
         ) : showClear ? (

package/src/icon.tsx

@@ -51,6 +51,7 @@ import ChevronsDownUp from "lucide-react-native/dist/esm/icons/chevrons-down-up"
 import ChevronsUpDown from "lucide-react-native/dist/esm/icons/chevrons-up-down";
 import CircleAlert from "lucide-react-native/dist/esm/icons/circle-alert";
 import CircleCheck from "lucide-react-native/dist/esm/icons/circle-check";
+import TriangleAlert from "lucide-react-native/dist/esm/icons/triangle-alert";
 import Clock from "lucide-react-native/dist/esm/icons/clock";
 import Code from "lucide-react-native/dist/esm/icons/code";
 import CodeXml from "lucide-react-native/dist/esm/icons/code-xml";
@@ -153,6 +154,7 @@ import RectangleEllipsis from "lucide-react-native/dist/esm/icons/rectangle-elli
 import Redo from "lucide-react-native/dist/esm/icons/redo";
 import RefreshCw from "lucide-react-native/dist/esm/icons/refresh-cw";
 import Repeat from "lucide-react-native/dist/esm/icons/repeat";
+import RotateCcw from "lucide-react-native/dist/esm/icons/rotate-ccw";
 import RotateCw from "lucide-react-native/dist/esm/icons/rotate-cw";
 import Scan from "lucide-react-native/dist/esm/icons/scan";
 import Search from "lucide-react-native/dist/esm/icons/search";
@@ -241,6 +243,7 @@ const iconComponents = {
   "chevrons-up-down": ChevronsUpDown,
   "circle-alert": CircleAlert,
   "circle-check": CircleCheck,
+  "triangle-alert": TriangleAlert,
   clock: Clock,
   code: Code,
   "code-xml": CodeXml,
@@ -344,6 +347,7 @@ const iconComponents = {
   redo: Redo,
   "refresh-cw": RefreshCw,
   repeat: Repeat,
+  "rotate-ccw": RotateCcw,
   "rotate-cw": RotateCw,
   scan: Scan,
   search: Search,

package/src/image_gallery.tsx

@@ -8,15 +8,27 @@
 // relying on percentage/flex-basis resolution (which collapses inside an
 // auto-width parent).
 import { useState } from "react";
-import { View, Image, Pressable } from "react-native";
+import { View, Pressable, type ViewStyle } from "react-native";
 import { Text } from "./text";
+import { Icon } from "./icon";
 import { colors } from "./colors";
 import { ActivityIndicator } from "./activity_indicator";
 import { FileThumbnail, type DisplayFile } from "./file_thumbnail";
 import { FileGalleryModal } from "./file_gallery_modal";
+import { RotatableImage } from "./rotatable_image";
+import { useImageRotation } from "./use_image_rotation";
 
 const GAP = 12;
 
+const rotateButtonStyle: ViewStyle = {
+  width: 32,
+  height: 32,
+  borderRadius: 16,
+  backgroundColor: "rgba(0, 0, 0, 0.45)",
+  alignItems: "center",
+  justifyContent: "center",
+};
+
 export interface ImageGalleryProps {
   images: DisplayFile[];
   loading?: boolean;
@@ -34,6 +46,8 @@ export interface ImageGalleryProps {
   mainAspectRatio?: number;
   /** Main image's fraction of the width in "right" mode (0–1). Default 0.6. */
   mainFraction?: number;
+  /** Show 90° rotate controls on images — inline and in the zoom modal. Default true. */
+  rotatable?: boolean;
 }
 
 export function ImageGallery({
@@ -45,10 +59,13 @@ export function ImageGallery({
   thumbnailPosition = "bottom",
   mainAspectRatio = 4 / 3,
   mainFraction = 0.6,
+  rotatable = true,
 }: ImageGalleryProps) {
   const [selected, setSelected] = useState(0);
   const [zoomIdx, setZoomIdx] = useState<number | null>(null);
   const [containerWidth, setContainerWidth] = useState(0);
+  // Per-image rotation, shared with the zoom modal so a turn survives opening it.
+  const rotation = useImageRotation();
 
   if (loading) return <ActivityIndicator />;
   if (images.length === 0) return <Text size="sm" color="muted">{emptyText}</Text>;
@@ -59,23 +76,47 @@ export function ImageGallery({
   const width = maxWidth ? Math.min(containerWidth, maxWidth) : containerWidth;
 
   const mainImage = (
-    <Pressable
-      onPress={() => setZoomIdx(idx)}
-      accessibilityRole="button"
-      accessibilityLabel="Zoom image"
-      style={{
-        width: "100%",
-        aspectRatio: mainAspectRatio,
-        borderRadius: 8,
-        borderWidth: 1,
-        borderColor: colors.border,
-        backgroundColor: colors.zinc["100"],
-        overflow: "hidden",
-        cursor: "pointer",
-      }}
-    >
-      <Image source={{ uri: main.url }} resizeMode="contain" style={{ width: "100%", height: "100%" }} />
-    </Pressable>
+    // The rotate controls sit OUTSIDE the zoom Pressable (an absolute sibling on
+    // top) so pressing them turns the image instead of opening the modal.
+    <View style={{ width: "100%" }}>
+      <Pressable
+        onPress={() => setZoomIdx(idx)}
+        accessibilityRole="button"
+        accessibilityLabel="Zoom image"
+        style={{
+          width: "100%",
+          aspectRatio: mainAspectRatio,
+          borderRadius: 8,
+          borderWidth: 1,
+          borderColor: colors.border,
+          backgroundColor: colors.zinc["100"],
+          overflow: "hidden",
+          cursor: "pointer",
+        }}
+      >
+        <RotatableImage uri={main.url} alt={main.filename} rotation={rotation.rotationFor(main.id)} />
+      </Pressable>
+      {rotatable ? (
+        <View style={{ position: "absolute", top: 8, right: 8, flexDirection: "row", gap: 6 }}>
+          <Pressable
+            onPress={() => rotation.rotate(main.id, -1)}
+            accessibilityRole="button"
+            accessibilityLabel="Rotate left"
+            style={rotateButtonStyle}
+          >
+            <Icon name="rotate-ccw" size={16} color={colors.white} />
+          </Pressable>
+          <Pressable
+            onPress={() => rotation.rotate(main.id, 1)}
+            accessibilityRole="button"
+            accessibilityLabel="Rotate right"
+            style={rotateButtonStyle}
+          >
+            <Icon name="rotate-cw" size={16} color={colors.white} />
+          </Pressable>
+        </View>
+      ) : null}
+    </View>
   );
 
   const thumbnails = images.length > 1 ? (
@@ -117,6 +158,8 @@ export function ImageGallery({
         activeIndex={zoomIdx}
         onIndexChange={setZoomIdx}
         captionHint={captionHint}
+        rotation={rotation}
+        rotatable={rotatable}
       />
     </View>
   );

package/src/rotatable_image.tsx

@@ -0,0 +1,56 @@
+import { useState } from "react";
+import { View, Image, StyleSheet, type StyleProp, type ViewStyle } from "react-native";
+
+export interface RotatableImageProps {
+  uri: string;
+  /** Accessible name for the image. */
+  alt?: string;
+  /** Degrees clockwise — normalized to 0/90/180/270. */
+  rotation?: number;
+  /** Fill behind the contained image. */
+  backgroundColor?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * An image that rotates in 90° steps and REFITS: at a quarter turn the image box
+ * is laid out in the container's SWAPPED dimensions, then rotated into place — so
+ * a rotated landscape photo fills the frame instead of shrinking into a corner.
+ * `resizeMode="contain"` preserves aspect ratio; the container measures itself
+ * via `onLayout`. Works on web (react-native-web) and native.
+ */
+export function RotatableImage({ uri, alt, rotation = 0, backgroundColor, style }: RotatableImageProps) {
+  const [size, setSize] = useState({ width: 0, height: 0 });
+  const deg = (((rotation % 360) + 360) % 360);
+  const quarter = deg === 90 || deg === 270;
+  const boxWidth = quarter ? size.height : size.width;
+  const boxHeight = quarter ? size.width : size.height;
+
+  return (
+    <View
+      onLayout={(e) =>
+        setSize({ width: e.nativeEvent.layout.width, height: e.nativeEvent.layout.height })
+      }
+      style={[styles.container, backgroundColor ? { backgroundColor } : null, style]}
+    >
+      {size.width > 0 && size.height > 0 ? (
+        <Image
+          source={{ uri }}
+          resizeMode="contain"
+          accessibilityLabel={alt}
+          style={{ width: boxWidth, height: boxHeight, transform: [{ rotate: `${deg}deg` }] }}
+        />
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: {
+    width: "100%",
+    height: "100%",
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden",
+  },
+});

package/src/use_image_rotation.ts

@@ -0,0 +1,30 @@
+import { useCallback, useMemo, useState } from "react";
+
+/**
+ * Per-file view rotation for image viewers — degrees (0/90/180/270) keyed by
+ * file id, held in memory. Shared between an inline gallery and its fullscreen
+ * modal so a rotation survives prev/next navigation and open/close while the
+ * gallery is mounted. View-only: it is a render transform, never a mutation of
+ * the stored file.
+ */
+export interface ImageRotation {
+  rotations: Record<string, number>;
+  rotationFor: (id: string) => number;
+  /** Advance a quarter-turn; `step` 1 = clockwise, -1 = counter-clockwise. */
+  rotate: (id: string, step?: 1 | -1) => void;
+}
+
+export function useImageRotation(): ImageRotation {
+  const [rotations, setRotations] = useState<Record<string, number>>({});
+
+  const rotate = useCallback((id: string, step: 1 | -1 = 1) => {
+    setRotations((prev) => {
+      const next = ((((prev[id] ?? 0) + step * 90) % 360) + 360) % 360;
+      return { ...prev, [id]: next };
+    });
+  }, []);
+
+  const rotationFor = useCallback((id: string) => rotations[id] ?? 0, [rotations]);
+
+  return useMemo(() => ({ rotations, rotationFor, rotate }), [rotations, rotationFor, rotate]);
+}