@lotics/ui 1.8.0 → 1.10.0

package/package.json

@@ -1,10 +1,15 @@
 {
   "name": "@lotics/ui",
-  "version": "1.8.0",
+  "version": "1.10.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
     "./colors": "./src/colors.ts",
+    "./mime": "./src/mime.ts",
+    "./download": "./src/download.ts",
+    "./file_badge": "./src/file_badge.tsx",
+    "./file_thumbnail": "./src/file_thumbnail.tsx",
+    "./file_gallery_modal": "./src/file_gallery_modal.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
     "./line_chart": "./src/line_chart.tsx",
@@ -14,6 +19,7 @@
     "./trend_chip": "./src/trend_chip.tsx",
     "./section_card": "./src/section_card.tsx",
     "./kpi_card": "./src/kpi_card.tsx",
+    "./ring_gauge": "./src/ring_gauge.tsx",
     "./alert_row": "./src/alert_row.tsx",
     "./stacked_progress_bar": "./src/stacked_progress_bar.tsx",
     "./legend_item": "./src/legend_item.tsx",

package/src/download.ts

@@ -0,0 +1,36 @@
+// Pure web file-download primitive. Uses fetch+blob+anchor because
+// `window.open(url, "_blank")` is silently dropped by sandboxed iframes
+// (no `allow-popups`), and direct anchor navigation without the `download`
+// attribute doesn't trigger a save dialog for inline MIME types (HTML,
+// JSON, PDFs, etc.).
+//
+// `cache: "no-store"` avoids a CORS cache collision: if a prior <img>
+// loaded the same URL without an Origin header, the cached response
+// (missing Access-Control-Allow-Origin) gets reused for the fetch and
+// fails. Bypassing the cache forces a fresh CORS-aware request.
+//
+// No React Native / @lotics/shared imports — kept pure so both the host
+// frontend and sandboxed custom-code apps can consume via the per-file
+// export without dragging the wider UI surface.
+
+export async function downloadFileFromUrl(url: string, filename: string): Promise<void> {
+  if (!url) throw new Error("downloadFileFromUrl: empty url");
+
+  const response = await fetch(url, { cache: "no-store" });
+  if (!response.ok) {
+    throw new Error(`File download failed: ${response.status} ${response.statusText}`);
+  }
+
+  const blob = await response.blob();
+  const blobUrl = URL.createObjectURL(blob);
+  try {
+    const link = document.createElement("a");
+    link.href = blobUrl;
+    link.download = filename;
+    document.body.appendChild(link);
+    link.click();
+    link.remove();
+  } finally {
+    URL.revokeObjectURL(blobUrl);
+  }
+}

package/src/file_badge.tsx

@@ -0,0 +1,160 @@
+import { Text, View } from "react-native";
+import { fontFamilySemiBold } from "./text_utils";
+import { Icon, type IconName } from "./icon";
+import { isVideoMimeType, isAudioMimeType } from "./mime";
+
+const VIDEO_COLOR = "#ea580c";
+const AUDIO_COLOR = "#db2777";
+
+const MIME_MAP: Record<string, { label: string; color: string }> = {
+  "application/pdf": { label: "PDF", color: "#ef4444" },
+  "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { label: "XLSX", color: "#16a34a" },
+  "application/vnd.ms-excel": { label: "XLS", color: "#16a34a" },
+  "text/csv": { label: "CSV", color: "#16a34a" },
+  "application/vnd.openxmlformats-officedocument.wordprocessingml.document": { label: "DOCX", color: "#2563eb" },
+  "application/msword": { label: "DOC", color: "#2563eb" },
+  "image/png": { label: "PNG", color: "#7c3aed" },
+  "image/jpeg": { label: "JPG", color: "#7c3aed" },
+  "video/mp4": { label: "MP4", color: VIDEO_COLOR },
+  "video/webm": { label: "WEBM", color: VIDEO_COLOR },
+  "video/quicktime": { label: "MOV", color: VIDEO_COLOR },
+  "audio/mpeg": { label: "MP3", color: AUDIO_COLOR },
+  "audio/wav": { label: "WAV", color: AUDIO_COLOR },
+  "audio/x-wav": { label: "WAV", color: AUDIO_COLOR },
+  "audio/mp4": { label: "M4A", color: AUDIO_COLOR },
+  "audio/x-m4a": { label: "M4A", color: AUDIO_COLOR },
+  "audio/ogg": { label: "OGG", color: AUDIO_COLOR },
+};
+
+const DEFAULT_BADGE = { label: "FILE", color: "#71717a" };
+
+export function resolveMime(mimeType: string): { label: string; color: string } {
+  return MIME_MAP[mimeType] ?? DEFAULT_BADGE;
+}
+
+const DEFAULT_SIZE = 26;
+
+interface FileBadgeProps {
+  mimeType: string;
+  /** Base width in pixels. Height, radii, font, and padding scale proportionally. Default: 26 */
+  size?: number;
+  /** Show a "TMPL" overlay to distinguish templates from regular files. */
+  isTemplate?: boolean;
+}
+
+/**
+ * Two-tone file badge: white top, colored bottom with label.
+ * Derives label and color from mime type.
+ */
+function getMediaIcon(mimeType: string): IconName | undefined {
+  if (isVideoMimeType(mimeType)) return "play";
+  if (isAudioMimeType(mimeType)) return "music";
+  return undefined;
+}
+
+export function FileBadge({ mimeType, size = DEFAULT_SIZE, isTemplate }: FileBadgeProps) {
+  const { label, color } = resolveMime(mimeType);
+  const scale = size / DEFAULT_SIZE;
+  const height = Math.round(32 * scale);
+  const radius = Math.round(4 * scale);
+  const bottomHeight = Math.round(14 * scale);
+  const fontSize = Math.round(7 * scale);
+  const lineHeight = Math.round(10 * scale);
+  const paddingTop = Math.round(4 * scale);
+  const paddingH = Math.round(3 * scale);
+  const lineGap = Math.round(3 * scale);
+  const lineThickness = Math.max(1, Math.round(1.5 * scale));
+  const tmplFontSize = Math.max(5, Math.round(5.5 * scale));
+  const tmplPadH = Math.round(2 * scale);
+  const tmplPadV = Math.max(1, Math.round(1 * scale));
+  const tmplRadius = Math.round(2 * scale);
+  const mediaIcon = getMediaIcon(mimeType);
+  const mediaIconSize = Math.max(10, Math.round(14 * scale));
+
+  return (
+    <View style={{
+      width: size,
+      height,
+      borderRadius: radius,
+      overflow: "hidden",
+      shadowColor: "#000",
+      shadowOffset: { width: 0, height: 1 },
+      shadowOpacity: 0.08,
+      shadowRadius: 3,
+      elevation: 2,
+    }}>
+      <View style={{
+        flex: 1,
+        backgroundColor: mediaIcon !== undefined ? color : "white",
+        borderWidth: 1,
+        borderBottomWidth: 0,
+        borderColor: "rgba(0,0,0,0.08)",
+        borderTopLeftRadius: radius,
+        borderTopRightRadius: radius,
+        paddingTop: mediaIcon !== undefined ? 0 : paddingTop,
+        paddingHorizontal: mediaIcon !== undefined ? 0 : paddingH,
+        gap: mediaIcon !== undefined ? 0 : lineGap,
+        alignItems: mediaIcon !== undefined ? "center" : undefined,
+        justifyContent: mediaIcon !== undefined ? "center" : undefined,
+      }}>
+        {mediaIcon !== undefined ? (
+          <Icon name={mediaIcon} size={mediaIconSize} color="white" />
+        ) : (
+          <>
+            <View style={{ height: lineThickness, borderRadius: 1, backgroundColor: "rgba(0,0,0,0.08)" }} />
+            <View style={{ height: lineThickness, borderRadius: 1, backgroundColor: "rgba(0,0,0,0.08)" }} />
+            <View style={{ height: lineThickness, borderRadius: 1, backgroundColor: "rgba(0,0,0,0.08)", width: "60%" }} />
+          </>
+        )}
+        {isTemplate && (
+          <View style={{
+            position: "absolute",
+            top: 0,
+            left: 0,
+            right: 0,
+            bottom: 0,
+            alignItems: "center",
+            justifyContent: "center",
+          }}>
+            <View style={{
+              backgroundColor: "white",
+              borderRadius: tmplRadius,
+              paddingHorizontal: tmplPadH,
+              paddingVertical: tmplPadV,
+              shadowColor: "#000",
+              shadowOffset: { width: 0, height: 0.5 },
+              shadowOpacity: 0.1,
+              shadowRadius: 1,
+              elevation: 1,
+            }}>
+              <Text style={{
+                fontFamily: fontFamilySemiBold,
+                fontSize: tmplFontSize,
+                fontWeight: "700",
+                color: "#374151",
+                letterSpacing: 0.2,
+              }}>TMPL</Text>
+            </View>
+          </View>
+        )}
+      </View>
+      <View style={{
+        height: bottomHeight,
+        alignItems: "center",
+        justifyContent: "center",
+        backgroundColor: color,
+        borderBottomLeftRadius: radius,
+        borderBottomRightRadius: radius,
+      }}>
+        <Text style={{
+          fontFamily: fontFamilySemiBold,
+          fontSize,
+          fontWeight: "700",
+          color: "white",
+          letterSpacing: 0.3,
+          lineHeight,
+        }}>{label}</Text>
+      </View>
+    </View>
+  );
+}

package/src/file_gallery_modal.tsx

@@ -0,0 +1,188 @@
+// FileGalleryModal — pure fullscreen image preview with prev/next nav + ESC close.
+// Pure primitive: takes DisplayFile[] only, no Lotics domain coupling. Frontend
+// has a richer modal in `frontend/components/file_gallery.tsx` that handles
+// xlsx/docx/pdf inline rendering — leave that one for Lotics-specific previews
+// and use this primitive when only images need previewing.
+
+import { useCallback, useEffect, useRef } from "react";
+import {
+  Image,
+  Modal,
+  Pressable,
+  StyleSheet,
+  View,
+} from "react-native";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { colors } from "./colors";
+import { isImageMimeType } from "./mime";
+import type { DisplayFile } from "./file_thumbnail";
+
+export interface FileGalleryModalProps {
+  files: DisplayFile[];
+  /** Index of the file currently shown. When null, the modal is closed. */
+  activeIndex: number | null;
+  onIndexChange: (next: number | null) => void;
+  /**
+   * Optional caption suffix shown under the image. Useful for hint text like
+   * "ESC để đóng · ←/→ để chuyển". When omitted, just shows filename + count.
+   */
+  captionHint?: string;
+}
+
+/**
+ * Image-focused fullscreen preview. Non-image MIME types render as a simple
+ * "{filename} · cannot preview" card — callers needing rich preview should use
+ * a Lotics-specific gallery instead.
+ */
+export function FileGalleryModal(props: FileGalleryModalProps) {
+  const { files, activeIndex, onIndexChange, captionHint } = props;
+  const visible = activeIndex !== null;
+  const overlayRef = useRef<View | null>(null);
+
+  const close = useCallback(() => onIndexChange(null), [onIndexChange]);
+  const next = useCallback(() => {
+    if (activeIndex === null) return;
+    onIndexChange(Math.min(activeIndex + 1, files.length - 1));
+  }, [activeIndex, files.length, onIndexChange]);
+  const prev = useCallback(() => {
+    if (activeIndex === null) return;
+    onIndexChange(Math.max(activeIndex - 1, 0));
+  }, [activeIndex, onIndexChange]);
+
+  // Keyboard navigation (web only — RN native handles via Modal accessibility).
+  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();
+    }
+    window.addEventListener("keydown", onKey);
+    return () => window.removeEventListener("keydown", onKey);
+  }, [visible, close, next, prev]);
+
+  if (!visible || activeIndex === null) return null;
+  const file = files[activeIndex];
+  if (!file) return null;
+
+  const total = files.length;
+  const caption = captionHint
+    ? `${file.filename} · ${activeIndex + 1} / ${total} · ${captionHint}`
+    : `${file.filename} · ${activeIndex + 1} / ${total}`;
+
+  return (
+    <Modal visible transparent onRequestClose={close} animationType="fade">
+      <View style={styles.overlay} ref={overlayRef}>
+        <Pressable
+          accessibilityRole="button"
+          accessibilityLabel="Close"
+          onPress={close}
+          style={StyleSheet.absoluteFill}
+        />
+
+        {isImageMimeType(file.mimeType) ? (
+          <Image
+            source={{ uri: file.url }}
+            style={styles.image}
+            resizeMode="contain"
+          />
+        ) : (
+          <View style={styles.unsupportedCard}>
+            <Text size="md" style={styles.unsupportedText}>
+              {file.filename}
+            </Text>
+            <Text size="sm" color="muted">
+              Cannot preview this file type in the gallery.
+            </Text>
+          </View>
+        )}
+
+        {activeIndex > 0 ? (
+          <Pressable
+            onPress={prev}
+            accessibilityRole="button"
+            accessibilityLabel="Previous"
+            style={[styles.navButton, styles.navLeft]}
+          >
+            <Icon name="chevron-left" size={28} color={colors.white} />
+          </Pressable>
+        ) : null}
+
+        {activeIndex < total - 1 ? (
+          <Pressable
+            onPress={next}
+            accessibilityRole="button"
+            accessibilityLabel="Next"
+            style={[styles.navButton, styles.navRight]}
+          >
+            <Icon name="chevron-right" size={28} color={colors.white} />
+          </Pressable>
+        ) : null}
+
+        <View style={styles.captionWrap} pointerEvents="none">
+          <View style={styles.captionPill}>
+            <Text size="sm" style={styles.captionText}>{caption}</Text>
+          </View>
+        </View>
+      </View>
+    </Modal>
+  );
+}
+
+const styles = StyleSheet.create({
+  overlay: {
+    flex: 1,
+    backgroundColor: "rgba(0, 0, 0, 0.88)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  image: {
+    width: "92%",
+    height: "85%",
+  },
+  unsupportedCard: {
+    backgroundColor: colors.white,
+    borderRadius: 8,
+    padding: 24,
+    maxWidth: 480,
+    gap: 8,
+    alignItems: "center",
+  },
+  unsupportedText: {
+    fontWeight: "600",
+  },
+  navButton: {
+    position: "absolute",
+    top: "50%",
+    transform: [{ translateY: -28 }],
+    width: 56,
+    height: 56,
+    borderRadius: 28,
+    backgroundColor: "rgba(0, 0, 0, 0.4)",
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  navLeft: {
+    left: 16,
+  },
+  navRight: {
+    right: 16,
+  },
+  captionWrap: {
+    position: "absolute",
+    bottom: 24,
+    left: 0,
+    right: 0,
+    alignItems: "center",
+  },
+  captionPill: {
+    backgroundColor: "rgba(0, 0, 0, 0.7)",
+    paddingHorizontal: 12,
+    paddingVertical: 6,
+    borderRadius: 6,
+  },
+  captionText: {
+    color: colors.white,
+  },
+});

package/src/file_thumbnail.tsx

@@ -0,0 +1,437 @@
+import { FileBadge, resolveMime } from "./file_badge";
+import { fontFamilySemiBold } from "./text_utils";
+import { Text } from "./text";
+import { Icon, type IconName } from "./icon";
+import { Checkbox } from "./checkbox";
+import { colors } from "./colors";
+import { useCallback, useState } from "react";
+import {
+  GestureResponderEvent,
+  Image,
+  Text as RNText,
+  View,
+  Pressable,
+  StyleSheet,
+  Linking,
+} from "react-native";
+import { isImageMimeType, isVideoMimeType, isAudioMimeType } from "./mime";
+
+export const THUMBNAIL_SIZE = 96;
+export const COMPACT_THUMBNAIL_SIZE = 32;
+
+/**
+ * Returns the icon name for playable media (video/audio) so a MediaCard can
+ * render a play/music glyph instead of document placeholder lines. Returns
+ * undefined for non-media files, which should fall back to DocumentCard.
+ */
+export function getMediaIcon(mimeType: string): IconName | undefined {
+  if (isVideoMimeType(mimeType)) return "play";
+  if (isAudioMimeType(mimeType)) return "music";
+  return undefined;
+}
+
+// =============================================================================
+// Core Display Type
+// =============================================================================
+
+/**
+ * Normalized file format for display components.
+ * All file sources (database, chat messages, uploads) convert to this.
+ */
+export interface DisplayFile {
+  id: string;
+  filename: string;
+  mimeType: string;
+  /** Direct URL to the file */
+  url: string;
+  /** Optional thumbnail URL for images */
+  thumbnailUrl?: string;
+  /** Preview URL for legacy Excel files (.xls converted to .xlsx server-side) */
+  previewUrl?: string;
+}
+
+// =============================================================================
+// FileThumbnail - Main display component
+// =============================================================================
+
+interface FileThumbnailProps {
+  file: DisplayFile;
+  /** Explicit pixel size. When omitted, fills container (width: "100%", aspectRatio: 1). */
+  size?: number;
+  /** Called when thumbnail is pressed */
+  onPress?: () => void;
+  /** Called when thumbnail is long-pressed */
+  onLongPress?: () => void;
+  /** Called when the completed file is removed */
+  onRemove?: () => void;
+  /** When defined, renders a selection overlay with a checkbox. */
+  selected?: boolean;
+}
+
+/**
+ * Displays a file as a square thumbnail.
+ * Works with any file source via DisplayFile interface.
+ */
+export function FileThumbnail(props: FileThumbnailProps) {
+  const { file, size, onPress, onLongPress, onRemove, selected } = props;
+
+  const rootStyle =
+    size !== undefined ? { width: size, height: size } : { width: "100%" as const, aspectRatio: 1 };
+
+  if (isImageMimeType(file.mimeType)) {
+    return (
+      <View style={rootStyle}>
+        <ImageThumbnail file={file} size={size} onPress={onPress} onLongPress={onLongPress} />
+        {onRemove && <RemoveButton onPress={onRemove} />}
+        {selected !== undefined && <SelectionOverlay selected={selected} />}
+      </View>
+    );
+  }
+
+  const mediaIcon = getMediaIcon(file.mimeType);
+
+  if (size !== undefined && size <= COMPACT_THUMBNAIL_SIZE && mediaIcon === undefined) {
+    return (
+      <View style={rootStyle}>
+        <DocumentBadge
+          mimeType={file.mimeType}
+          size={size}
+          onPress={onPress ?? (() => Linking.openURL(file.url))}
+          onLongPress={onLongPress}
+        />
+        {onRemove && <RemoveButton onPress={onRemove} />}
+      </View>
+    );
+  }
+
+  return (
+    <View style={rootStyle}>
+      {mediaIcon !== undefined ? (
+        <MediaCard
+          mimeType={file.mimeType}
+          filename={file.filename}
+          icon={mediaIcon}
+          size={size}
+          onPress={onPress ?? (() => Linking.openURL(file.url))}
+          onLongPress={onLongPress}
+        />
+      ) : (
+        <DocumentCard
+          mimeType={file.mimeType}
+          filename={file.filename}
+          size={size}
+          onPress={onPress ?? (() => Linking.openURL(file.url))}
+          onLongPress={onLongPress}
+        />
+      )}
+      {onRemove && <RemoveButton onPress={onRemove} />}
+      {selected !== undefined && <SelectionOverlay selected={selected} />}
+    </View>
+  );
+}
+
+// =============================================================================
+// Base Components (exported for direct use when needed)
+// =============================================================================
+
+interface DocumentBadgeProps {
+  mimeType: string;
+  size?: number;
+  isTemplate?: boolean;
+  onPress?: () => void;
+  onLongPress?: () => void;
+}
+
+/**
+ * Compact two-tone file badge with document lines and colored label.
+ */
+export function DocumentBadge(props: DocumentBadgeProps) {
+  const { mimeType, isTemplate, onPress, onLongPress } = props;
+
+  return (
+    <Pressable onPress={onPress} onLongPress={onLongPress}>
+      <FileBadge mimeType={mimeType} isTemplate={isTemplate} />
+    </Pressable>
+  );
+}
+
+interface DocumentCardProps {
+  mimeType: string;
+  filename: string;
+  size?: number;
+  onPress?: () => void;
+  onLongPress?: () => void;
+  overlay?: React.ReactNode;
+}
+
+/**
+ * Document preview card: placeholder lines (future: file preview) + footer with filename and type label.
+ */
+export function DocumentCard(props: DocumentCardProps) {
+  const { mimeType, filename, size, onPress, onLongPress, overlay } = props;
+  const { label, color } = resolveMime(mimeType);
+
+  const sizeStyle =
+    size !== undefined
+      ? { width: size, height: size }
+      : { width: "100%" as const, height: "100%" as const };
+
+  return (
+    <Pressable style={[styles.documentCard, sizeStyle]} onPress={onPress} onLongPress={onLongPress}>
+      <View style={styles.documentCardBody}>
+        <View style={styles.placeholderLines}>
+          <View style={styles.placeholderLine} />
+          <View style={styles.placeholderLine} />
+          <View style={[styles.placeholderLine, { width: "60%" }]} />
+          <View style={styles.placeholderLine} />
+          <View style={[styles.placeholderLine, { width: "40%" }]} />
+        </View>
+      </View>
+      <View style={styles.documentCardFooter}>
+        <Text size="xs" numberOfLines={1} color="zinc-500" userSelect="none">
+          {filename}
+        </Text>
+        <View style={[styles.typeLabel, { backgroundColor: color }]}>
+          <RNText style={styles.typeLabelText}>{label}</RNText>
+        </View>
+      </View>
+      {overlay}
+    </Pressable>
+  );
+}
+
+interface MediaCardProps {
+  mimeType: string;
+  filename: string;
+  /** Icon rendered in the body — typically "play" for video or "music" for audio. */
+  icon: IconName;
+  size?: number;
+  onPress?: () => void;
+  onLongPress?: () => void;
+  overlay?: React.ReactNode;
+}
+
+/**
+ * Playable-media preview card: colored body with a large icon (play/music) +
+ * footer with filename and type label. Visual counterpart to DocumentCard
+ * for videos and audio files.
+ */
+export function MediaCard(props: MediaCardProps) {
+  const { mimeType, filename, size, onPress, onLongPress, overlay, icon } = props;
+  const { label, color } = resolveMime(mimeType);
+
+  const sizeStyle =
+    size !== undefined
+      ? { width: size, height: size }
+      : { width: "100%" as const, height: "100%" as const };
+
+  const isCompact = size !== undefined && size <= COMPACT_THUMBNAIL_SIZE;
+
+  if (isCompact) {
+    const iconSize = Math.max(12, Math.round(size * 0.55));
+    return (
+      <Pressable
+        style={[styles.mediaCardCompact, sizeStyle, { backgroundColor: color }]}
+        onPress={onPress}
+        onLongPress={onLongPress}
+      >
+        <Icon name={icon} size={iconSize} color={colors.white} />
+        {overlay}
+      </Pressable>
+    );
+  }
+
+  const iconSize = size !== undefined ? Math.max(20, Math.min(Math.round(size * 0.4), 56)) : 44;
+  const backdrop = iconSize + 20;
+
+  return (
+    <Pressable style={[styles.documentCard, sizeStyle]} onPress={onPress} onLongPress={onLongPress}>
+      <View style={[styles.mediaCardBody, { backgroundColor: color }]}>
+        <View style={[styles.mediaIconBackdrop, { width: backdrop, height: backdrop, borderRadius: backdrop / 2 }]}>
+          <Icon name={icon} size={iconSize} color={colors.white} />
+        </View>
+      </View>
+      <View style={styles.documentCardFooter}>
+        <Text size="xs" numberOfLines={1} color="zinc-500" userSelect="none">
+          {filename}
+        </Text>
+        <View style={[styles.typeLabel, { backgroundColor: color }]}>
+          <RNText style={styles.typeLabelText}>{label}</RNText>
+        </View>
+      </View>
+      {overlay}
+    </Pressable>
+  );
+}
+
+// =============================================================================
+// Internal Components (exported so upload-aware wrappers in @lotics/ui-internal
+// can reuse them without duplication)
+// =============================================================================
+
+interface ImageThumbnailProps {
+  file: DisplayFile;
+  /** Explicit pixel size. When omitted, fills container. */
+  size?: number;
+  onPress?: () => void;
+  onLongPress?: () => void;
+}
+
+function ImageThumbnail(props: ImageThumbnailProps) {
+  const { file, size, onPress, onLongPress } = props;
+  const [useFallback, setUseFallback] = useState(false);
+
+  // Use thumbnail if available, fallback to full URL
+  const url = !useFallback && file.thumbnailUrl ? file.thumbnailUrl : file.url;
+
+  const sizeStyle =
+    size !== undefined
+      ? { width: size, height: size }
+      : { width: "100%" as const, height: "100%" as const };
+
+  return (
+    <Pressable
+      onPress={onPress}
+      onLongPress={onLongPress}
+      style={[styles.imageThumbnail, sizeStyle]}
+    >
+      <Image
+        source={{ uri: url }}
+        style={styles.image}
+        resizeMode="cover"
+        onError={() => setUseFallback(true)}
+      />
+    </Pressable>
+  );
+}
+
+export function RemoveButton({ onPress }: { onPress: () => void }) {
+  const handlePress = useCallback(
+    (e: GestureResponderEvent) => {
+      e.stopPropagation();
+      onPress();
+    },
+    [onPress],
+  );
+  return (
+    <Pressable onPress={handlePress} style={styles.removeButton}>
+      <Icon name="x" size={14} color={colors.zinc[700]} />
+    </Pressable>
+  );
+}
+
+function SelectionOverlay({ selected }: { selected: boolean }) {
+  return (
+    <View
+      style={[styles.selectionOverlay, selected && styles.selectionOverlaySelected]}
+      pointerEvents="none"
+    >
+      <View style={styles.selectionCheckbox}>
+        <Checkbox checked={selected} />
+      </View>
+    </View>
+  );
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = StyleSheet.create({
+  documentCard: {
+    borderRadius: 8,
+    backgroundColor: colors.white,
+    borderWidth: 1,
+    borderColor: colors.zinc["200"],
+    overflow: "hidden",
+  },
+  documentCardBody: {
+    flex: 1,
+    justifyContent: "center",
+    padding: 10,
+  },
+  mediaCardBody: {
+    flex: 1,
+    justifyContent: "center",
+    alignItems: "center",
+  },
+  mediaCardCompact: {
+    borderRadius: 6,
+    alignItems: "center",
+    justifyContent: "center",
+    overflow: "hidden",
+  },
+  mediaIconBackdrop: {
+    alignItems: "center",
+    justifyContent: "center",
+    backgroundColor: "rgba(255, 255, 255, 0.22)",
+  },
+  placeholderLines: {
+    gap: 4,
+  },
+  placeholderLine: {
+    height: 2,
+    borderRadius: 1,
+    backgroundColor: colors.zinc["200"],
+  },
+  documentCardFooter: {
+    gap: 2,
+    paddingHorizontal: 8,
+    paddingVertical: 6,
+    borderTopWidth: 1,
+    backgroundColor: colors.zinc['50'],
+    borderTopColor: colors.zinc["200"],
+    alignItems: "flex-start",
+  },
+  typeLabel: {
+    borderRadius: 3,
+    paddingHorizontal: 4,
+    paddingVertical: 1,
+  },
+  typeLabelText: {
+    fontFamily: fontFamilySemiBold,
+    fontSize: 8,
+    fontWeight: "700",
+    color: "white",
+    letterSpacing: 0.3,
+  },
+  imageThumbnail: {
+    borderRadius: 8,
+    overflow: "hidden",
+  },
+  image: {
+    width: "100%",
+    height: "100%",
+  },
+  removeButton: {
+    position: "absolute",
+    top: -6,
+    right: -6,
+    width: 22,
+    height: 22,
+    alignItems: "center",
+    justifyContent: "center",
+    borderRadius: 999,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.zinc["50"],
+    zIndex: 1,
+  },
+  selectionOverlay: {
+    position: "absolute",
+    top: 0,
+    left: 0,
+    right: 0,
+    bottom: 0,
+    borderRadius: 8,
+    zIndex: 1,
+  },
+  selectionOverlaySelected: {
+    backgroundColor: "rgba(0, 0, 0, 0.15)",
+  },
+  selectionCheckbox: {
+    position: "absolute",
+    bottom: 4,
+    right: 4,
+  },
+});

package/src/mime.ts

@@ -0,0 +1,15 @@
+// Tiny MIME helpers inlined so `@lotics/ui` stays free of @lotics/shared
+// (enforced by primitives_purity.test.ts). The richer MIME taxonomy lives
+// in `@lotics/shared/file_type` for Lotics-coupled code.
+
+export function isImageMimeType(mimeType: string): boolean {
+  return mimeType.toLowerCase().startsWith("image/");
+}
+
+export function isVideoMimeType(mimeType: string): boolean {
+  return mimeType.toLowerCase().startsWith("video/");
+}
+
+export function isAudioMimeType(mimeType: string): boolean {
+  return mimeType.toLowerCase().startsWith("audio/");
+}

package/src/ring_gauge.tsx

@@ -0,0 +1,72 @@
+import { View } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+
+export interface RingGaugeProps {
+  /** Progress value, 0–100. Clamped to that range. */
+  value: number;
+  /** Short label under the ring. */
+  label: string;
+  /** Optional one-line context under the label. */
+  caption?: string;
+  /** Diameter in px. Default 128. */
+  size?: number;
+  /** Ring stroke width in px. Default 12. */
+  thickness?: number;
+  /** Arc color. Default teal accent. */
+  color?: string;
+}
+
+/**
+ * Circular progress gauge — an at-a-glance ring for a 0–100% metric
+ * (on-time rate, SLA compliance, win rate). The percentage leads in the
+ * center; the track behind it shows the remaining-to-100 context. Pairs
+ * with `KPICard` (figures) — use a ring when the number IS a ratio to 100.
+ *
+ * Implementation: native HTML `<svg>` (like `Sparkline`) — Vite can't
+ * resolve react-native-svg's native paths, and the `<View>` wrapper
+ * preserves the RN layout surface. The arc starts at 12 o'clock
+ * (`rotate(-90)`) and grows clockwise via `strokeDasharray`.
+ */
+export function RingGauge(props: RingGaugeProps) {
+  const { value, label, caption, size = 140, thickness = 10, color = colors.teal[600] } = props;
+  const clamped = Math.max(0, Math.min(100, value));
+  const center = size / 2;
+  const radius = (size - thickness) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const dash = (clamped / 100) * circumference;
+
+  return (
+    <View style={{ alignItems: "center", gap: 12 }}>
+      <View style={{ width: size, height: size, alignItems: "center", justifyContent: "center" }}>
+        <svg width={size} height={size} viewBox={`0 0 ${size} ${size}`} style={{ position: "absolute" }}>
+          <circle cx={center} cy={center} r={radius} fill="none" stroke={colors.zinc[200]} strokeWidth={thickness} />
+          <circle
+            cx={center}
+            cy={center}
+            r={radius}
+            fill="none"
+            stroke={color}
+            strokeWidth={thickness}
+            strokeLinecap="round"
+            strokeDasharray={`${dash} ${circumference}`}
+            transform={`rotate(-90 ${center} ${center})`}
+          />
+        </svg>
+        <Text size="xxl" weight="semibold">
+          {Math.round(clamped)}%
+        </Text>
+      </View>
+      <View style={{ alignItems: "center", gap: 2 }}>
+        <Text size="sm" weight="medium">
+          {label}
+        </Text>
+        {caption ? (
+          <Text size="xs" color="muted">
+            {caption}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}

package/src/tokens.ts

@@ -3,9 +3,16 @@
  * Lotics surfaces (parent app, custom_code iframe apps, browser extension).
  *
  * The colors come from `colors.ts` (re-exported below) — same module
- * the parent app's React Native components consume via
- * `colors.zinc[900]` / `colors.background` / etc. The iframe runtime
- * emits these same values as CSS variables via {@link getCssVariables}.
+ * BOTH the parent app's and custom-code apps' components consume via
+ * `colors.zinc[900]` / `colors.background` / etc. Custom-code apps use
+ * `@lotics/ui` components directly (rendered through react-native-web; the
+ * starter scaffold wires the alias — see `docs/apps.md`), so they self-theme
+ * via the same `colors` module with no CSS variables involved.
+ *
+ * {@link getCssVariables} is an OPT-IN helper that serializes these tokens to
+ * `--lotics-*` CSS variables for apps that hand-roll plain DOM/CSS instead of
+ * using `@lotics/ui` components. Nothing injects them automatically — the
+ * runtime does NOT emit them, and the component path does not need them.
  *
  * **CSS variable naming mirrors the parent's TS references 1:1**:
  *   colors.zinc[900]    → var(--lotics-zinc-900)
@@ -86,8 +93,11 @@ export const radius = {
 
 /**
  * Emit a CSS string defining all design tokens as `:root` custom
- * properties. Used by the iframe runtime so plain-DOM components can
- * consume the same palette as the parent app's React Native components.
+ * properties. OPT-IN: an app that hand-rolls plain DOM/CSS (instead of
+ * using `@lotics/ui` components, which self-theme via the `colors` module)
+ * can inject this to consume the same palette. Nothing calls it
+ * automatically — there is no runtime that emits it; the component path
+ * doesn't need it.
  *
  * Variable names mirror `colors` 1:1 — palette entries (zinc, red,
  * etc.) emit as `--lotics-<name>-<shade>`, top-level entries (black,