@lotics/ui 5.1.1 → 5.3.0

package/AGENTS.md

@@ -13,8 +13,8 @@ typeahead, async search, virtualization, and a11y the primitive already ships.
 - RN-Web only: `View`/`ScrollView` from `react-native`, the `Text` primitive (no raw
   `div`/`span`, no raw `fontSize`/`fontWeight`); styles are RN objects.
 - i18n: most components are string-free; the few that emit their own user-facing strings take
-  a `labels` prop (`DateRangeFilterField`, `Pagination`, `SortHeader`/`Table.sortLabels`) —
-  localize there.
+  a `labels` prop (`DateRangeFilterField`, `Pagination`, `SortHeader`/`Table.sortLabels`,
+  `RemainderMeter`) — localize there.
 
 ---
 
@@ -73,7 +73,8 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **Status / feedback** — `Badge` / `StatusBadge`, `Callout` (inline status), `EmptyState`,
   `CompletionState`, `ActivityIndicator` / `Loading`, `Skeleton`.
 - **Files** — `FileDropzone`, `FileThumbnail` / `FileThumbnailGrid`, `FilePreview` /
-  `FileGalleryModal`, `ImageGallery` (see §Data entry → Attachments).
+  `FileGalleryModal`, `ImageGallery`; for gated CRUD compose locally with `useSelectionMode` +
+  `shareOrDownloadFiles` + `rotateImageToBlob` (see §Data entry → Attachments).
 - **Specialized work surfaces** — `ScanField` (scan/verify), `StepList` (guided run),
   `RemainderMeter` + `AllocationRow` (allocation), `Timeline`, `Calendar`, `Gantt`,
   `comments_thread`.
@@ -208,6 +209,25 @@ instant-preview lifecycle (local object-URL now, `file_id` on complete); map eac
 `DisplayFile` (snake → camel: `preview_url`→`url`, `mime_type`→`mimeType`) for
 `<FileThumbnail file={…} uploading={f.status === "uploading"} />`.
 
+**Gated file CRUD is a PATTERN, composed locally — not a sealed kit component.** When a file field must
+GUARD deletion (operator-facing, accidental delete is a real risk), compose it in the app from the kit
+pieces; don't reach for a one-size widget (the action set + layout vary per app — the host frontend's
+`files_editor` and each app compose their own). The recipe: `FileDropzone` (add) + `FileThumbnailGrid
+files selectedIds onFilePress` (pass `selectedIds` ONLY in select mode) + `FileGalleryModal` (view +
+rotate + persist) + a `Dialog` confirm, all driven by **`useSelectionMode()`** — the reusable LOGIC. The
+gating rule: **NO per-thumbnail ✕** — delete is **Select → ⋯ menu → Delete → confirm**, so a stray tap
+never removes a file. Three reusable primitives back it (the logic is shared; the action bar + layout +
+copy stay local):
+- **`useSelectionMode()`** (`@lotics/ui/use_selection_mode`) — `{ active, selected, enter, exit, toggle,
+  toggleAll }`, an agnostic multi-select state machine (string ids; pairs with the grid's `selectedIds`).
+- **`shareOrDownloadFiles(files, { title })`** (`@lotics/ui/share_or_download`) — `navigator.share({ files })`
+  (mobile → Save to gallery / send to an app), else individual `downloadFileFromUrl` — **never a ZIP**.
+  It shares the BYTES (fetches each presigned URL → `File` at the tap), so URL expiry afterward is moot;
+  the share path needs the host iframe to grant `allow="web-share"` (else it falls back to download).
+- **`rotateImageToBlob(url, degrees)`** (`@lotics/ui/rotate_image`) — canvas-bake a 90° rotation into a
+  NEW blob for re-upload (`useImageRotation` is view-only; this is how a rotation is persisted). Pair with
+  `FileGalleryModal`'s `onPersistRotation`/`persisting` (the ✓ shown on a rotated image).
+
 ### Quick capture — the SPEED surface
 For fast repeat entry (logging activity, expenses), one compact capture row (a `SegmentedControl`
 mode, a `Combobox`-as-select, a `Counter`, an Enter-to-submit `TextInputField`); each entry commits
@@ -565,7 +585,7 @@ CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
 status_grid (StatusGrid + StatusLegend) · heatmap · legend_item · remainder_meter · allocation_row ·
 scan_field · file_dropzone · file_thumbnail · file_thumbnail_grid · file_preview ·
-file_gallery_modal · image_gallery · avatar · skeleton · activity_indicator · loading · divider ·
+file_gallery_modal · image_gallery · use_selection_mode · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·
 spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
 comments_thread · agent_run (live streaming work feed) · agent_progress (its compact floating
 expandable form — a composer's working state) · composer (Composer — the adaptive command/chat

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "5.1.1",
+  "version": "5.3.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -11,6 +11,8 @@
     "./inline_member_select": "./src/inline_member_select.tsx",
     "./mime": "./src/mime.ts",
     "./download": "./src/download.ts",
+    "./share_or_download": "./src/share_or_download.ts",
+    "./rotate_image": "./src/rotate_image.ts",
     "./file_picker": "./src/file_picker.ts",
     "./comments_thread": "./src/comments_thread.tsx",
     "./file_badge": "./src/file_badge.tsx",
@@ -25,6 +27,7 @@
     "./image_gallery": "./src/image_gallery.tsx",
     "./rotatable_image": "./src/rotatable_image.tsx",
     "./use_image_rotation": "./src/use_image_rotation.ts",
+    "./use_selection_mode": "./src/use_selection_mode.ts",
     "./file_thumbnail_grid": "./src/file_thumbnail_grid.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",

package/src/file_gallery_modal.tsx

@@ -42,6 +42,15 @@ export interface FileGalleryModalProps {
   rotation?: ImageRotation;
   /** Show 90° rotate controls for image files. Default true. */
   rotatable?: boolean;
+  /**
+   * Persist the active image's current view-rotation as a new stored file. When
+   * provided and the active image is rotated, a confirm (✓) control appears next
+   * to the rotate buttons. The host bakes the rotation + swaps the file, then
+   * typically closes the modal. View-rotation is reported in degrees (90/180/270).
+   */
+  onPersistRotation?: (file: DisplayFile, degrees: number) => void;
+  /** Disables the persist control while a rotation save is in flight. */
+  persisting?: boolean;
 }
 
 /**
@@ -49,7 +58,7 @@ export interface FileGalleryModalProps {
  * via FilePreview; unknown types show a download placeholder.
  */
 export function FileGalleryModal(props: FileGalleryModalProps) {
-  const { files, activeIndex, onIndexChange, captionHint, labels, onError, rotation, rotatable = true } = props;
+  const { files, activeIndex, onIndexChange, captionHint, labels, onError, rotation, rotatable = true, onPersistRotation, persisting } = props;
   const visible = activeIndex !== null;
   const overlayRef = useRef<View | null>(null);
   // Own the rotation when the host doesn't share one (standalone consumers).
@@ -132,6 +141,17 @@ export function FileGalleryModal(props: FileGalleryModalProps) {
             >
               <Icon name="rotate-cw" size={20} color={colors.white} />
             </Pressable>
+            {onPersistRotation && rot.rotationFor(file.id) !== 0 ? (
+              <Pressable
+                onPress={() => { if (!persisting) onPersistRotation(file, rot.rotationFor(file.id)); }}
+                accessibilityRole="button"
+                accessibilityLabel="Save rotation"
+                disabled={persisting}
+                style={[styles.controlButton, styles.controlButtonPrimary, persisting && styles.controlButtonBusy]}
+              >
+                <Icon name="check" size={20} color={colors.white} />
+              </Pressable>
+            ) : null}
           </View>
         ) : null}
 
@@ -213,6 +233,12 @@ const styles = StyleSheet.create({
     justifyContent: "center",
     alignItems: "center",
   },
+  controlButtonPrimary: {
+    backgroundColor: colors.blue["600"],
+  },
+  controlButtonBusy: {
+    opacity: 0.6,
+  },
   captionWrap: {
     position: "absolute",
     bottom: 24,

package/src/remainder_meter.tsx

@@ -2,6 +2,26 @@ import { StyleSheet, View, type DimensionValue } from "react-native";
 import { colors, solid } from "./colors";
 import { Text } from "./text";
 
+/**
+ * Override the meter's captions for localization. Each key is optional and
+ * falls back to English (mirrors `PaginationLabels` / `DateRangeFilterField`).
+ */
+export interface RemainderMeterLabels {
+  /** The left caption. Default: `{allocated} of {total} applied`. */
+  applied?: (allocated: string, total: string) => string;
+  /** UNDER state (a remainder still to place). Default: `{remainder} unapplied`. */
+  remaining?: (remainder: string) => string;
+  /** OVER state (over-allocated). Default: `Over by {amount}`. */
+  over?: (amount: string) => string;
+  /** EXACT state. Default: `Fully applied`. */
+  exact?: string;
+}
+
+const defaultApplied = (allocated: string, total: string) => `${allocated} of ${total} applied`;
+const defaultRemaining = (remainder: string) => `${remainder} unapplied`;
+const defaultOver = (amount: string) => `Over by ${amount}`;
+const DEFAULT_EXACT = "Fully applied";
+
 export interface RemainderMeterProps {
   /** The source amount being distributed — the payment, the available stock. */
   total: number;
@@ -9,6 +29,8 @@ export interface RemainderMeterProps {
   allocated: number;
   /** Format amounts (money / units). Defaults to a plain locale string. */
   format?: (n: number) => string;
+  /** Localize the captions; each key falls back to English. */
+  labels?: RemainderMeterLabels;
 }
 
 /**
@@ -20,17 +42,21 @@ export interface RemainderMeterProps {
  * distribution, budgeting.
  */
 export function RemainderMeter(props: RemainderMeterProps) {
-  const { total, allocated, format = (n) => n.toLocaleString() } = props;
+  const { total, allocated, format = (n) => n.toLocaleString(), labels } = props;
   const remainder = total - allocated;
   const state = remainder > 0 ? "under" : remainder < 0 ? "over" : "exact";
   const pct: DimensionValue = `${total <= 0 ? 0 : Math.min(100, (allocated / total) * 100)}%`;
   const barColor = state === "over" ? solid("red") : state === "exact" ? solid("emerald") : solid("blue");
   const right =
-    state === "exact" ? "Fully applied" : state === "over" ? `Over by ${format(-remainder)}` : `${format(remainder)} unapplied`;
+    state === "exact"
+      ? (labels?.exact ?? DEFAULT_EXACT)
+      : state === "over"
+        ? (labels?.over ?? defaultOver)(format(-remainder))
+        : (labels?.remaining ?? defaultRemaining)(format(remainder));
   return (
     <View style={{ gap: 8 }}>
       <View style={{ flexDirection: "row", alignItems: "baseline", gap: 8 }}>
-        <Text size="sm" color="muted" style={{ flex: 1 }}>{`${format(allocated)} of ${format(total)} applied`}</Text>
+        <Text size="sm" color="muted" style={{ flex: 1 }}>{(labels?.applied ?? defaultApplied)(format(allocated), format(total))}</Text>
         <Text size="sm" weight="medium" tabular color={state === "over" ? "danger" : state === "exact" ? "success" : "default"}>
           {right}
         </Text>

package/src/rotate_image.ts

@@ -0,0 +1,39 @@
+// Bake a quarter-turn rotation into a NEW image blob via canvas — the persisting
+// half of image rotation (useImageRotation is view-only). A consumer fetches the
+// stored image, rotates the pixels here, and re-uploads the result as a fresh
+// file. Pure web (canvas / createImageBitmap), no React Native imports.
+
+export async function rotateImageToBlob(
+  url: string,
+  degrees: number,
+  opts?: { credentials?: RequestCredentials; type?: string; quality?: number },
+): Promise<Blob> {
+  const norm = (((degrees % 360) + 360) % 360);
+  const res = await fetch(url, { cache: "no-store", credentials: opts?.credentials ?? "same-origin" });
+  if (!res.ok) throw new Error(`rotateImageToBlob: fetch failed ${res.status} ${res.statusText}`);
+  const srcBlob = await res.blob();
+  if (norm === 0) return srcBlob; // no-op rotation — return the bytes untouched
+
+  const bitmap = await createImageBitmap(srcBlob);
+  try {
+    const swap = norm === 90 || norm === 270;
+    const canvas = document.createElement("canvas");
+    canvas.width = swap ? bitmap.height : bitmap.width;
+    canvas.height = swap ? bitmap.width : bitmap.height;
+    const ctx = canvas.getContext("2d");
+    if (!ctx) throw new Error("rotateImageToBlob: no 2d canvas context");
+    ctx.translate(canvas.width / 2, canvas.height / 2);
+    ctx.rotate((norm * Math.PI) / 180);
+    ctx.drawImage(bitmap, -bitmap.width / 2, -bitmap.height / 2);
+    const type = opts?.type || (srcBlob.type.startsWith("image/") ? srcBlob.type : "image/jpeg");
+    return await new Promise<Blob>((resolve, reject) =>
+      canvas.toBlob(
+        (b) => (b ? resolve(b) : reject(new Error("rotateImageToBlob: toBlob produced no blob"))),
+        type,
+        opts?.quality ?? 0.92,
+      ),
+    );
+  } finally {
+    bitmap.close();
+  }
+}

package/src/share_or_download.test.ts

@@ -0,0 +1,39 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import { shareOrDownloadFiles } from "./share_or_download";
+
+afterEach(() => {
+  vi.restoreAllMocks();
+  vi.unstubAllGlobals();
+});
+
+describe("shareOrDownloadFiles", () => {
+  it("is a no-op (download/0) when there are no usable files", async () => {
+    expect(await shareOrDownloadFiles([])).toEqual({ delivered: "download", count: 0 });
+    expect(await shareOrDownloadFiles([{ url: "", filename: "x.png" }])).toEqual({ delivered: "download", count: 0 });
+  });
+
+  it("hands the BYTES (not the URL) to the OS share sheet when files can be shared", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(new Blob(["img"], { type: "image/png" }))));
+    // navigator.share is a true external boundary — assert WHAT crosses it. Typing
+    // the mock's param makes mock.calls[0][0] the shared payload.
+    const share = vi.fn(async (_data: { files: File[]; title?: string }) => undefined);
+    vi.stubGlobal("navigator", { canShare: () => true, share });
+
+    const res = await shareOrDownloadFiles([{ url: "https://r2/presigned", filename: "a.png", mimeType: "image/png" }], { title: "Ảnh" });
+
+    expect(res).toEqual({ delivered: "share", count: 1 });
+    const shared = share.mock.calls[0][0];
+    expect(shared.files).toHaveLength(1);
+    expect(shared.files[0]).toBeInstanceOf(File); // bytes, not a link → no expiry problem
+    expect(shared.files[0].name).toBe("a.png");
+    expect(shared.title).toBe("Ảnh");
+  });
+
+  it("treats a cancelled share sheet (AbortError) as done — never falls back to downloading", async () => {
+    vi.stubGlobal("fetch", vi.fn(async () => new Response(new Blob(["img"], { type: "image/png" }))));
+    const share = vi.fn(async () => { throw new DOMException("cancelled", "AbortError"); });
+    vi.stubGlobal("navigator", { canShare: () => true, share });
+
+    expect(await shareOrDownloadFiles([{ url: "u", filename: "a.png" }])).toEqual({ delivered: "share", count: 0 });
+  });
+});

package/src/share_or_download.ts

@@ -0,0 +1,69 @@
+// Share a set of files via the OS share sheet, or fall back to downloading them
+// individually — never a ZIP. On mobile the share sheet is the path to "Save to
+// Photos / gallery" and "send to <app>" (Web Share API Level 2, files variant);
+// on desktop or where file-share is unsupported, each file downloads on its own.
+//
+// Web Share inside an iframe requires the host to grant `allow="web-share"` on
+// the iframe element; without it `navigator.canShare({ files })` is false and we
+// fall through to downloads. Must be invoked from a user gesture (a click) — the
+// blob fetches happen inside that gesture's task so the share keeps activation.
+//
+// Pure web, no React Native / @lotics/shared imports — consumable by both the
+// host frontend and sandboxed custom-code apps via the per-file export.
+
+import { downloadFileFromUrl } from "./download";
+
+export interface ShareableFile {
+  url: string;
+  filename: string;
+  mimeType?: string;
+}
+
+export type ShareOrDownloadResult =
+  | { delivered: "share"; count: number }
+  | { delivered: "download"; count: number };
+
+async function toFile(f: ShareableFile, credentials: RequestCredentials): Promise<File> {
+  const res = await fetch(f.url, { cache: "no-store", credentials });
+  if (!res.ok) throw new Error(`fetch failed: ${res.status} ${res.statusText}`);
+  const blob = await res.blob();
+  return new File([blob], f.filename, { type: f.mimeType || blob.type || "application/octet-stream" });
+}
+
+export async function shareOrDownloadFiles(
+  files: ShareableFile[],
+  opts?: { title?: string; text?: string; credentials?: RequestCredentials },
+): Promise<ShareOrDownloadResult> {
+  const credentials = opts?.credentials ?? "same-origin";
+  const valid = files.filter((f) => f.url);
+  if (valid.length === 0) return { delivered: "download", count: 0 };
+
+  // Prefer the share sheet (mobile gallery / send). Feature-detect with canShare
+  // over real File objects so an iframe without `allow="web-share"` falls through.
+  const nav = typeof navigator !== "undefined" ? navigator : undefined;
+  if (nav && typeof nav.canShare === "function" && typeof nav.share === "function") {
+    let fileObjs: File[];
+    try {
+      fileObjs = await Promise.all(valid.map((f) => toFile(f, credentials)));
+    } catch {
+      fileObjs = [];
+    }
+    if (fileObjs.length > 0 && nav.canShare({ files: fileObjs })) {
+      try {
+        await nav.share({ files: fileObjs, title: opts?.title, text: opts?.text });
+        return { delivered: "share", count: fileObjs.length };
+      } catch (err) {
+        // User dismissed the sheet — done, not an error, do NOT also download.
+        if (err instanceof DOMException && err.name === "AbortError") {
+          return { delivered: "share", count: 0 };
+        }
+        // Anything else (share genuinely failed) → fall through to downloads.
+      }
+    }
+  }
+
+  for (const f of valid) {
+    await downloadFileFromUrl(f.url, f.filename, { credentials });
+  }
+  return { delivered: "download", count: valid.length };
+}

package/src/use_selection_mode.ts

@@ -0,0 +1,47 @@
+import { useCallback, useState } from "react";
+
+/**
+ * A "selection mode" state machine for a multi-select list (files, table rows, …):
+ * enter a mode, toggle items, select-or-clear all, exit. Agnostic — items are
+ * string ids, no domain coupling. Pairs with any list that renders a selection
+ * overlay from `selected` (e.g. `<FileThumbnailGrid selectedIds>`).
+ *
+ * It is the reusable LOGIC behind a gated-delete file field; the action bar, the
+ * layout, and the confirm Dialog are presentation the consumer composes locally.
+ */
+export interface SelectionMode {
+  /** Whether selection mode is active. */
+  active: boolean;
+  /** The currently-selected ids. */
+  selected: ReadonlySet<string>;
+  enter: () => void;
+  /** Leave selection mode AND clear the selection. */
+  exit: () => void;
+  toggle: (id: string) => void;
+  /** Select all `ids` when they aren't all already selected, else clear (stay in mode). */
+  toggleAll: (ids: readonly string[]) => void;
+}
+
+export function useSelectionMode(): SelectionMode {
+  const [active, setActive] = useState(false);
+  const [selected, setSelected] = useState<ReadonlySet<string>>(new Set());
+
+  const enter = useCallback(() => setActive(true), []);
+  const exit = useCallback(() => {
+    setActive(false);
+    setSelected(new Set());
+  }, []);
+  const toggle = useCallback((id: string) => {
+    setSelected((prev) => {
+      const next = new Set(prev);
+      if (next.has(id)) next.delete(id);
+      else next.add(id);
+      return next;
+    });
+  }, []);
+  const toggleAll = useCallback((ids: readonly string[]) => {
+    setSelected((prev) => (ids.length > 0 && prev.size === ids.length ? new Set() : new Set(ids)));
+  }, []);
+
+  return { active, selected, enter, exit, toggle, toggleAll };
+}