@lotics/ui 1.6.1 → 1.9.0

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/kpi_card.tsx

@@ -0,0 +1,77 @@
+import { View, StyleSheet, type ViewStyle, type StyleProp } from "react-native";
+import { Text } from "./text";
+import { Metric, type MetricFormat, type MetricSize, type MetricTone } from "./metric";
+import { TrendChip } from "./trend_chip";
+import { SPACE } from "./spacing";
+
+interface KPICardProps {
+  /** Short uppercase label above the value. Identifies the metric. */
+  label: string;
+  /** The number to display. `null` renders as `emptyLabel`. */
+  value: number | string | null | undefined;
+  format?: MetricFormat;
+  currency?: string;
+  locale?: string;
+  emptyLabel?: string;
+  /** Numeric size hint. Default `lg`; pass `hero` for the dominant
+   * metric in a card; `md` for supporting metrics in a horizontal strip. */
+  size?: MetricSize;
+  tone?: MetricTone;
+  /** Optional ±% trend chip next to the value. Pass `null` (not omitted)
+   * to explicitly hide — useful when the comparator base is 0 and the
+   * percentage would be meaningless. */
+  trend?: number | null;
+  /**
+   * Goes below the value. Free text. Typical uses: comparator detail
+   * ("Tháng trước: 50.000.000 đ"), unit hint ("Hồ sơ"), or short caveat
+   * ("Tính theo ngày tạo").
+   */
+  caption?: string;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * One labeled metric block — the building block of a KPI strip or hero
+ * row. Forces the recipe so authors can't drift:
+ *   - Uppercase muted label (eyeline anchor)
+ *   - Metric value with tabular nums + tighter tracking at display sizes
+ *   - Optional inline trend chip (the "is this good?" indicator)
+ *   - Optional caption below for comparator detail / unit / caveat
+ *
+ * The recipe matches Mercury's checking dashboard, Stripe's revenue cards,
+ * Linear's project metrics. Without enforcing it, dashboards drift into
+ * "every metric looks slightly different" — the #1 readability tell on
+ * mediocre dashboards.
+ */
+export function KPICard(props: KPICardProps) {
+  const { label, value, format, currency, locale, emptyLabel, size = "lg", tone, trend, caption, style } = props;
+  return (
+    <View style={[styles.container, style]}>
+      <Text size="xs" color="muted" transform="uppercase">
+        {label}
+      </Text>
+      <View style={styles.valueRow}>
+        <Metric
+          value={value}
+          format={format}
+          currency={currency}
+          locale={locale}
+          emptyLabel={emptyLabel}
+          size={size}
+          tone={tone}
+        />
+        {trend != null && <TrendChip value={trend} />}
+      </View>
+      {caption && (
+        <Text size="xs" color="muted">
+          {caption}
+        </Text>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  container: { gap: SPACE.xs },
+  valueRow: { flexDirection: "row", alignItems: "baseline", gap: SPACE.sm, flexWrap: "wrap" },
+});

package/src/legend_item.tsx

@@ -0,0 +1,47 @@
+import { View, StyleSheet } from "react-native";
+import { Text } from "./text";
+import { Metric } from "./metric";
+import { SPACE } from "./spacing";
+
+interface LegendItemProps {
+  /** Square swatch color — should match the segment in the chart this
+   * legend annotates. */
+  color: string;
+  label: string;
+  /** Optional count to render after the label. `null` for loading state. */
+  value?: number | string | null;
+}
+
+/**
+ * Color swatch + label + optional count. Used as the legend row below a
+ * `StackedProgressBar`, a `ChartBar` with categorical colors, or any
+ * other chart where consumers need to map color → meaning.
+ *
+ * Tabular nums on the value (via Metric) keep counts aligned when several
+ * legend items sit in a row.
+ */
+export function LegendItem(props: LegendItemProps) {
+  return (
+    <View style={styles.row}>
+      <View style={[styles.swatch, { backgroundColor: props.color }]} />
+      <Text size="sm" color="muted">
+        {props.label}
+      </Text>
+      {props.value !== undefined && <Metric value={props.value} size="sm" />}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: SPACE.sm,
+    minWidth: 130,
+  },
+  swatch: {
+    width: 8,
+    height: 8,
+    borderRadius: 2,
+  },
+});

package/src/metric.tsx

@@ -1,4 +1,4 @@
-import { View, StyleSheet } from "react-native";
+import { View, StyleSheet, type TextStyle } from "react-native";
 import { Text } from "./text";
 import { colors } from "./colors";
 import { useMemo } from "react";
@@ -8,6 +8,15 @@ export type MetricFormat = "currency" | "number" | "percentage" | "none";
 /** Semantic colour of the metric value. `default` inherits the text colour. */
 export type MetricTone = "default" | "warning" | "danger";
 
+/**
+ * Visual scale. `md` is the historical default — matches body display size.
+ * `hero` is for the single most important number in a section ("Doanh thu
+ * trong tháng: 10.000.000 đ" at the top of a card with smaller supporting
+ * metrics below). Mercury / Stripe / Linear all use this hero-supporting
+ * hierarchy to give dashboards a reading order.
+ */
+export type MetricSize = "sm" | "md" | "lg" | "hero";
+
 export interface MetricProps {
   value: number | string | null | undefined;
   previousValue?: number | string | null | undefined;
@@ -16,8 +25,26 @@ export interface MetricProps {
   locale?: string;
   emptyLabel?: string;
   tone?: MetricTone;
+  size?: MetricSize;
 }
 
+const SIZE_TO_TEXT_SIZE: Record<MetricSize, "md" | "lg" | "xl" | "xxl"> = {
+  sm: "md",
+  md: "lg",
+  lg: "xl",
+  hero: "xxl",
+};
+
+// Letter-spacing tightens as font-size grows — "designed" not "inflated".
+// Hero gets the tightest tracking (-1.2) to match the 48px display size's
+// expected condensation.
+const SIZE_TO_LETTER_SPACING: Record<MetricSize, number> = {
+  sm: 0,
+  md: -0.25,
+  lg: -0.5,
+  hero: -1.2,
+};
+
 const TREND_UP = "↑";
 const TREND_DOWN = "↓";
 const TREND_FLAT = "→";
@@ -36,6 +63,7 @@ export function Metric(props: MetricProps) {
     locale,
     emptyLabel = "-",
     tone = "default",
+    size = "md",
   } = props;
 
   const displayValue = useMemo(() => {
@@ -66,9 +94,20 @@ export function Metric(props: MetricProps) {
   return (
     <View style={styles.container}>
       <Text
-        size="xl"
-        weight="semibold"
-        style={tone === "default" ? undefined : { color: TONE_COLOR[tone] }}
+        size={SIZE_TO_TEXT_SIZE[size]}
+        weight="medium"
+        style={[
+          // Tabular nums prevent the comma/decimal jitter when 1,234 sits
+          // next to 7,890 across cards — proportional glyphs misalign every
+          // column. Tighter tracking at display sizes reads as "designed",
+          // not "inflated body text" (Linear / Stripe / Geist all do this
+          // at hero metrics).
+          {
+            fontVariantNumeric: "tabular-nums",
+            letterSpacing: SIZE_TO_LETTER_SPACING[size],
+          } as TextStyle,
+          tone === "default" ? undefined : { color: TONE_COLOR[tone] },
+        ]}
       >
         {displayValue}
       </Text>

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/overlay_scope.ts

@@ -0,0 +1,44 @@
+import { useEffect } from "react";
+import { Platform } from "react-native";
+
+/**
+ * Tracks how many modal/overlay surfaces (dialogs, popovers) are currently open.
+ * A counter — not a boolean — so nested overlays compose correctly.
+ */
+let activeCount = 0;
+
+/**
+ * True while at least one modal dialog or popover is open. Read synchronously
+ * by the keyboard shortcut registry to suppress lower-layer page shortcuts so
+ * an open overlay does not hijack keystrokes (e.g. native Ctrl+F find).
+ */
+export function isOverlayScopeActive(): boolean {
+  return activeCount > 0;
+}
+
+/**
+ * Imperatively marks an overlay surface as open. Returns a release function
+ * that must be called exactly once when the overlay closes. Prefer the
+ * `useOverlayScope` hook in React components — this is the testable core.
+ */
+export function pushOverlayScope(): () => void {
+  activeCount++;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    activeCount--;
+  };
+}
+
+/**
+ * Marks an overlay surface as open while `active` is true. Web-only — no-op on
+ * native. Call this from overlay primitives (Dialog, Popover, etc.), not from
+ * individual call sites.
+ */
+export function useOverlayScope(active: boolean): void {
+  useEffect(() => {
+    if (Platform.OS !== "web" || !active) return;
+    return pushOverlayScope();
+  }, [active]);
+}