@lotics/ui 1.23.0 → 1.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.23.0",
+  "version": "1.25.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -16,6 +16,8 @@
     },
     "./file_preview_types": "./src/file_preview_types.ts",
     "./file_gallery_modal": "./src/file_gallery_modal.tsx",
+    "./image_gallery": "./src/image_gallery.tsx",
+    "./file_thumbnail_grid": "./src/file_thumbnail_grid.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
     "./line_chart": "./src/line_chart.tsx",

package/src/file_thumbnail_grid.tsx

@@ -0,0 +1,165 @@
+// Pure, reusable thumbnail-grid layout + a file-specific specialization.
+//
+// `ThumbnailGrid<T>` is the layout engine (three mutually-exclusive modes:
+// compact / fixed-columns / auto-columns, with `maxVisible` overflow). It is
+// item-agnostic — pass `renderItem`. `FileThumbnailGrid` is the common case:
+// a grid of `DisplayFile`s rendered with `FileThumbnail` (any file type —
+// image/video/audio/doc — via FileThumbnail's own type handling).
+//
+// The Lotics-coupled file grid (`@lotics/ui-internal/file_grid`, which mixes in
+// upload-progress thumbnails) composes `ThumbnailGrid` with its own renderItem,
+// so the layout lives in exactly one place.
+import React, { useState } from "react";
+import { View, StyleSheet, type ViewStyle } from "react-native";
+import { Text } from "./text";
+import { FileThumbnail, type DisplayFile, THUMBNAIL_SIZE } from "./file_thumbnail";
+
+export interface ThumbnailGridProps<T> {
+  items: T[];
+  keyExtractor: (item: T) => string;
+  /** Render one item. `size` is passed in compact mode (fixed px); omitted in
+   *  column modes, where the item fills its flex cell. */
+  renderItem: (item: T, size?: number) => React.ReactNode;
+  /** Fixed pixel size per item → flat horizontal wrap. Takes precedence. */
+  itemSize?: number;
+  /** Fixed column count → items fill 1/N of the row width. */
+  columns?: number;
+  /** Minimum item width for auto column count when neither itemSize nor columns
+   *  is set. Default 96. */
+  minItemWidth?: number;
+  /** Gap between items. Default 8. */
+  gap?: number;
+  /** Max items shown before a "+N" overflow indicator. */
+  maxVisible?: number;
+  /** Alignment of a partial last row. Default "start". */
+  partialRowAlign?: "start" | "end";
+  style?: ViewStyle;
+  /** Disable press/click interactions (sets pointerEvents none). */
+  disablePress?: boolean;
+  /** Rendered inside the container after the grid (e.g. a retry-all button). */
+  footer?: React.ReactNode;
+}
+
+export function ThumbnailGrid<T>(props: ThumbnailGridProps<T>) {
+  const {
+    items,
+    keyExtractor,
+    renderItem,
+    itemSize,
+    columns,
+    minItemWidth = THUMBNAIL_SIZE,
+    gap = 8,
+    maxVisible,
+    partialRowAlign = "start",
+    style,
+    disablePress,
+    footer,
+  } = props;
+
+  const [containerWidth, setContainerWidth] = useState(0);
+
+  const isCompact = itemSize !== undefined;
+  const dynamicColumns =
+    !isCompact && columns === undefined && containerWidth > 0
+      ? Math.max(1, Math.floor((containerWidth + gap) / (minItemWidth + gap)))
+      : undefined;
+  const effectiveColumns = columns ?? dynamicColumns;
+
+  const visible = maxVisible ? items.slice(0, maxVisible) : items;
+  const overflow = maxVisible ? Math.max(0, items.length - maxVisible) : 0;
+  const canRender = isCompact || columns !== undefined || containerWidth > 0;
+
+  if (items.length === 0) return null;
+
+  const renderRows = (rowItems: T[], cols: number) => {
+    const rows: T[][] = [];
+    for (let i = 0; i < rowItems.length; i += cols) rows.push(rowItems.slice(i, i + cols));
+    return rows.map((row, rowIndex) => {
+      const spacers =
+        row.length < cols
+          ? Array.from({ length: cols - row.length }, (_, i) => (
+              <View key={`spacer-${i}`} style={styles.flexItem} />
+            ))
+          : null;
+      return (
+        <View key={rowIndex} style={[styles.row, { gap }]}>
+          {partialRowAlign === "end" && spacers}
+          {row.map((item) => (
+            <View key={keyExtractor(item)} style={styles.flexItem}>
+              {renderItem(item)}
+            </View>
+          ))}
+          {partialRowAlign === "start" && spacers}
+        </View>
+      );
+    });
+  };
+
+  return (
+    <View
+      style={[isCompact && styles.compactContainer, { gap }, style]}
+      pointerEvents={disablePress ? "none" : "auto"}
+      onLayout={(e) => setContainerWidth(e.nativeEvent.layout.width)}
+    >
+      {canRender &&
+        (isCompact
+          ? visible.map((item) => (
+              <React.Fragment key={keyExtractor(item)}>{renderItem(item, itemSize)}</React.Fragment>
+            ))
+          : effectiveColumns !== undefined
+            ? renderRows(visible, effectiveColumns)
+            : null)}
+
+      {overflow > 0 && (
+        <Text size="sm" color="muted" userSelect="none">
+          +{overflow}
+        </Text>
+      )}
+
+      {footer}
+    </View>
+  );
+}
+
+export interface FileThumbnailGridProps {
+  files: DisplayFile[];
+  itemSize?: number;
+  columns?: number;
+  minItemWidth?: number;
+  gap?: number;
+  maxVisible?: number;
+  partialRowAlign?: "start" | "end";
+  style?: ViewStyle;
+  disablePress?: boolean;
+  /** Selected file IDs — renders a selection overlay on those thumbnails. */
+  selectedIds?: ReadonlySet<string>;
+  onFilePress?: (file: DisplayFile) => void;
+  onRemove?: (id: string) => void;
+}
+
+export function FileThumbnailGrid(props: FileThumbnailGridProps) {
+  const { files, selectedIds, onFilePress, onRemove, disablePress, ...layout } = props;
+  return (
+    <ThumbnailGrid
+      {...layout}
+      items={files}
+      keyExtractor={(f) => f.id}
+      disablePress={disablePress}
+      renderItem={(file, size) => (
+        <FileThumbnail
+          file={file}
+          size={size}
+          onPress={disablePress || !onFilePress ? undefined : () => onFilePress(file)}
+          onRemove={onRemove ? () => onRemove(file.id) : undefined}
+          selected={selectedIds?.has(file.id)}
+        />
+      )}
+    />
+  );
+}
+
+const styles = StyleSheet.create({
+  compactContainer: { flexDirection: "row", flexWrap: "wrap", userSelect: "none" },
+  row: { flexDirection: "row" },
+  flexItem: { flex: 1 },
+});

package/src/image_gallery.tsx

@@ -0,0 +1,123 @@
+// Ecommerce-style image gallery: a large main image plus a thumbnail grid.
+// Click a thumbnail to swap the main image; click the main image to zoom it
+// full-screen via FileGalleryModal. Source-agnostic — takes DisplayFile[], so
+// any caller (record photos, uploads, chat attachments) can use it.
+//
+// Width is measured with onLayout (like FileThumbnailGrid) and the columns are
+// sized from it, so the gallery adapts to the available space instead of
+// 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 { Text } from "./text";
+import { colors } from "./colors";
+import { ActivityIndicator } from "./activity_indicator";
+import { FileThumbnail, type DisplayFile } from "./file_thumbnail";
+import { FileGalleryModal } from "./file_gallery_modal";
+
+const GAP = 12;
+
+export interface ImageGalleryProps {
+  images: DisplayFile[];
+  loading?: boolean;
+  /** Shown when there are no images and not loading. Pass a translated string. */
+  emptyText?: string;
+  /** Optional max width. Omit to fill the container. */
+  maxWidth?: number;
+  /** Hint shown in the full-screen zoom modal. Pass a translated string. */
+  captionHint?: string;
+  /** "bottom" stacks thumbnails under the main image; "right" puts the main
+   *  image (~60% of the width) and the thumbnail grid side by side. */
+  thumbnailPosition?: "bottom" | "right";
+  /** Aspect ratio (width / height) of the main image box. Default 4/3. A
+   *  smaller value (e.g. 1) makes a taller, larger preview. */
+  mainAspectRatio?: number;
+  /** Main image's fraction of the width in "right" mode (0–1). Default 0.6. */
+  mainFraction?: number;
+}
+
+export function ImageGallery({
+  images,
+  loading = false,
+  emptyText = "No images.",
+  maxWidth,
+  captionHint = "ESC to close · ←/→ to navigate",
+  thumbnailPosition = "bottom",
+  mainAspectRatio = 4 / 3,
+  mainFraction = 0.6,
+}: ImageGalleryProps) {
+  const [selected, setSelected] = useState(0);
+  const [zoomIdx, setZoomIdx] = useState<number | null>(null);
+  const [containerWidth, setContainerWidth] = useState(0);
+
+  if (loading) return <ActivityIndicator />;
+  if (images.length === 0) return <Text size="sm" color="muted">{emptyText}</Text>;
+
+  const idx = Math.min(selected, images.length - 1);
+  const main = images[idx];
+  const right = thumbnailPosition === "right";
+  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>
+  );
+
+  const thumbnails = images.length > 1 ? (
+    <View style={{ flexDirection: "row", flexWrap: "wrap", gap: 6 }}>
+      {images.map((img, i) => (
+        // Border radius = FileThumbnail's own radius (8) + the 2px border, so
+        // the active highlight is concentric with the thumbnail's corners.
+        <View
+          key={img.id}
+          style={{
+            borderRadius: 10,
+            borderWidth: 2,
+            borderColor: i === idx ? colors.zinc["900"] : colors.zinc["200"],
+          }}
+        >
+          <FileThumbnail file={img} size={56} onPress={() => setSelected(i)} />
+        </View>
+      ))}
+    </View>
+  ) : null;
+
+  return (
+    <View onLayout={(e) => setContainerWidth(e.nativeEvent.layout.width)}>
+      {width > 0 &&
+        (right && thumbnails ? (
+          <View style={{ flexDirection: "row", gap: GAP }}>
+            <View style={{ width: (width - GAP) * mainFraction }}>{mainImage}</View>
+            <View style={{ width: (width - GAP) * (1 - mainFraction) }}>{thumbnails}</View>
+          </View>
+        ) : (
+          <View style={{ gap: 8, width }}>
+            {mainImage}
+            {thumbnails}
+          </View>
+        ))}
+
+      <FileGalleryModal
+        files={images}
+        activeIndex={zoomIdx}
+        onIndexChange={setZoomIdx}
+        captionHint={captionHint}
+      />
+    </View>
+  );
+}

package/src/index.css

@@ -337,10 +337,12 @@ html {
 }
 
 /* Keyboard focus ring. `:focus-visible` only matches keyboard-driven focus,
-   so pointer/touch interactions stay visually unchanged. */
+   so pointer/touch interactions stay visually unchanged. The ring sits flush
+   against the element's border (offset 0, no gap) and, being an outline, never
+   reflows layout. */
 :focus-visible {
   outline: 2px solid var(--color-zinc-900);
-  outline-offset: 2px;
+  outline-offset: 0;
 }
 :focus:not(:focus-visible) {
   outline: none;

package/src/menu_list_item.tsx

@@ -4,11 +4,15 @@ import { Text } from "./text";
 import { colors } from "./colors";
 import { Icon, IconName } from "./icon";
 import { PressableHighlight } from "./pressable_highlight";
+import type { TextColor } from "./text_utils";
 
 export interface MenuListItemProps {
   ref?: Ref<View>;
   icon?: IconName | React.ReactNode;
   title: string;
+  /** Title color. Default ink — set it to mark the row as an action (e.g. a
+   *  leading "Browse all" tinted to match its icon). */
+  titleColor?: TextColor;
   description?: string;
   right?: React.ReactNode;
   onPress?: () => void;
@@ -32,6 +36,7 @@ export function MenuListItem(props: MenuListItemProps) {
     ref,
     icon,
     title,
+    titleColor,
     description,
     right,
     onPress,
@@ -52,7 +57,7 @@ export function MenuListItem(props: MenuListItemProps) {
     <>
       {resolvedIcon}
       <View style={styles.textContainer}>
-        <Text weight="medium" numberOfLines={1} userSelect="none">
+        <Text weight="medium" color={titleColor} numberOfLines={1} userSelect="none">
           {title}
         </Text>
         {!!description && (

package/src/search_select.tsx

@@ -14,14 +14,29 @@ import { MenuListItem } from "./menu_list_item";
 import { ActivityIndicator } from "./activity_indicator";
 import { Popover, PopoverContent } from "./popover";
 import type { PickerOption } from "./picker";
+import type { TextColor } from "./text_utils";
 import { useDebouncedCallback } from "./use_debounced_callback";
 import { useListKeyboardNav } from "./use_list_keyboard_nav";
 
+/** A pinned action row in the dropdown — not a search result, an action. */
+export interface SearchSelectAction {
+  key: string;
+  label: string;
+  icon?: ReactNode;
+  /** Tints the label so it reads as an action (match it to the icon's color). */
+  color?: TextColor;
+  onPress: () => void;
+}
+
 export interface SearchSelectProps<T extends string = string, D = unknown> {
   /** Result options for the current query. The consumer refreshes these in
    *  response to `onSearchChange` — search runs server-side, so the whole table
    *  is never shipped to the client. */
   options: PickerOption<T, D>[];
+  /** Pinned action rows shown at the very top of the dropdown (above results and
+   *  recents), always available while open and keyboard-navigable alongside the
+   *  options — e.g. a "Browse all" that opens a full picker. */
+  leadingActions?: SearchSelectAction[];
   /** Debounced; fires as the user types. Drive a server re-query from it. */
   onSearchChange: (query: string) => void;
   /** Fires when the user picks a result or a recent. */
@@ -78,6 +93,7 @@ export function SearchSelect<T extends string = string, D = unknown>(
 ) {
   const {
     options,
+    leadingActions = [],
     onSearchChange,
     onValueChange,
     recentOptions,
@@ -108,16 +124,30 @@ export function SearchSelect<T extends string = string, D = unknown>(
 
   const searching = query.trim().length > 0;
   const list = searching ? options : (recentOptions ?? []);
+  // The navigable set is the leading actions followed by the option list, so
+  // arrow keys + aria-activedescendant span both. `nLead` is the boundary.
+  const nLead = leadingActions.length;
 
   const debouncedSearch = useDebouncedCallback(onSearchChange, searchDebounceMs);
 
-  const scrollToIndex = useCallback((index: number) => {
-    scrollRef.current?.scrollTo({ y: Math.max(0, index * OPTION_HEIGHT - 80), animated: false });
-  }, []);
+  // Only the option list scrolls (actions are pinned above it), so map the
+  // combined index back into the list before scrolling.
+  const scrollToIndex = useCallback(
+    (index: number) => {
+      if (index < nLead) return;
+      scrollRef.current?.scrollTo({ y: Math.max(0, (index - nLead) * OPTION_HEIGHT - 80), animated: false });
+    },
+    [nLead],
+  );
 
   const handleSelect = useCallback(
     (index: number) => {
-      const opt = list[index];
+      if (index < nLead) {
+        leadingActions[index].onPress();
+        setOpen(false);
+        return;
+      }
+      const opt = list[index - nLead];
       if (!opt || opt.disabled) return;
       onValueChange(opt);
       // The trailing search is irrelevant once a pick is made. Cancel it and
@@ -131,12 +161,12 @@ export function SearchSelect<T extends string = string, D = unknown>(
       // search again without re-clicking.
       inputRef.current?.focus();
     },
-    [list, onValueChange, onSearchChange, debouncedSearch],
+    [list, leadingActions, nLead, onValueChange, onSearchChange, debouncedSearch],
   );
 
   const { activeIndex, setActiveIndex, handleKey } = useListKeyboardNav({
-    count: list.length,
-    isDisabled: (i) => list[i]?.disabled ?? false,
+    count: nLead + list.length,
+    isDisabled: (i) => (i >= nLead ? (list[i - nLead]?.disabled ?? false) : false),
     onSelect: handleSelect,
     onClose: () => setOpen(false),
     onActiveChange: scrollToIndex,
@@ -168,10 +198,11 @@ export function SearchSelect<T extends string = string, D = unknown>(
     [open, handleKey],
   );
 
-  // Nothing to show ⇒ don't open an empty popover (focused box, no recents).
-  const showList = open && !disabled && (searching || list.length > 0);
+  // Nothing to show ⇒ don't open an empty popover. Leading actions (e.g.
+  // "Browse all") always give the popover something to show on focus.
+  const showList = open && !disabled && (nLead > 0 || searching || list.length > 0);
   const activeOptionId =
-    activeIndex >= 0 && activeIndex < list.length ? optionId(activeIndex) : undefined;
+    activeIndex >= 0 && activeIndex < nLead + list.length ? optionId(activeIndex) : undefined;
   const listLabel = searching ? accessibilityLabel : recentsLabel;
 
   return (
@@ -217,6 +248,22 @@ export function SearchSelect<T extends string = string, D = unknown>(
           testID={testID ? `${testID}-popover` : undefined}
         >
           <View style={styles.menu}>
+            {nLead > 0
+              ? leadingActions.map((action, i) => (
+                  <MenuListItem
+                    key={action.key}
+                    nativeID={optionId(i)}
+                    testID={`search-action-${action.key}`}
+                    role="option"
+                    icon={action.icon}
+                    title={action.label}
+                    titleColor={action.color}
+                    focused={i === activeIndex}
+                    onPress={() => handleSelect(i)}
+                    onHoverIn={() => setActiveIndex(i)}
+                  />
+                ))
+              : null}
             {!searching && list.length > 0 ? (
               <View style={styles.sectionHeader}>
                 <Text size="xs" weight="medium" color="zinc-500">
@@ -239,27 +286,31 @@ export function SearchSelect<T extends string = string, D = unknown>(
                   <ActivityIndicator />
                 </View>
               ) : list.length === 0 ? (
-                <View style={styles.statusRow}>
-                  <Text size="sm" color="zinc-500">
-                    {emptyText}
-                  </Text>
-                </View>
+                // Only "no results" while searching — an empty recents list (no
+                // query) just shows the leading actions above, nothing more.
+                searching ? (
+                  <View style={styles.statusRow}>
+                    <Text size="sm" color="zinc-500">
+                      {emptyText}
+                    </Text>
+                  </View>
+                ) : null
               ) : (
                 list.map((opt, i) => (
                   <MenuListItem
                     key={opt.value}
-                    nativeID={optionId(i)}
+                    nativeID={optionId(nLead + i)}
                     testID={`search-option-${opt.value}`}
                     role="option"
                     icon={renderOptionIcon?.(opt)}
                     title={opt.label ?? opt.value}
                     description={getOptionDescription?.(opt)}
                     right={renderOptionRight?.(opt)}
-                    focused={i === activeIndex}
+                    focused={nLead + i === activeIndex}
                     selected={opt.value === selectedValue}
                     disabled={opt.disabled}
-                    onPress={() => handleSelect(i)}
-                    onHoverIn={() => setActiveIndex(i)}
+                    onPress={() => handleSelect(nLead + i)}
+                    onHoverIn={() => setActiveIndex(nLead + i)}
                   />
                 ))
               )}
@@ -275,6 +326,8 @@ const styles = StyleSheet.create({
   input: {
     backgroundColor: colors.background,
     boxShadow: colors.border_shadow,
+    // A pill, matching the search input inside the picker dialog.
+    borderRadius: 999,
   },
   menu: {
     gap: 2,

package/src/table.tsx

@@ -48,9 +48,11 @@ export function Table<TRow extends Record<string, unknown>>(props: TableProps<TR
                 {col.label}
               </Text>
               {sortable ? (
-                <Text size="xs" color="muted" userSelect="none">
-                  {active ? (sort?.dir === "asc" ? "↑" : "↓") : "↕"}
-                </Text>
+                <Icon
+                  name={active ? (sort?.dir === "asc" ? "chevron-up" : "chevron-down") : "chevrons-up-down"}
+                  size={14}
+                  color={active ? colors.zinc[700] : colors.zinc[400]}
+                />
               ) : null}
             </View>
           );

package/src/table.web.tsx

@@ -61,9 +61,11 @@ export function Table<TRow extends Record<string, unknown>>(props: TableProps<TR
                 {col.label}
               </Text>
               {sortable ? (
-                <Text size="xs" color="muted" userSelect="none">
-                  {active ? (sort?.dir === "asc" ? "↑" : "↓") : "↕"}
-                </Text>
+                <Icon
+                  name={active ? (sort?.dir === "asc" ? "chevron-up" : "chevron-down") : "chevrons-up-down"}
+                  size={14}
+                  color={active ? colors.zinc[700] : colors.zinc[400]}
+                />
               ) : null}
             </>
           );

package/src/table_picker.tsx

@@ -83,6 +83,9 @@ export interface TablePickerProps<TRow extends Record<string, unknown>> {
   loading?: boolean;
   /** Message when there are no rows and nothing is loading. */
   emptyLabel?: string;
+  /** Max dialog width — a browse table needs more room than a form dialog.
+   *  Default 1080. */
+  maxWidth?: number | `${number}%`;
   testID?: string;
 }
 
@@ -142,6 +145,7 @@ export function TablePicker<TRow extends Record<string, unknown>>(
     onPageChange,
     loading = false,
     emptyLabel,
+    maxWidth = 1080,
     testID,
   } = props;
 
@@ -196,7 +200,7 @@ export function TablePicker<TRow extends Record<string, unknown>>(
   );
 
   return (
-    <Dialog open={open} onOpenChange={onOpenChange} height="90%" testID={testID}>
+    <Dialog open={open} onOpenChange={onOpenChange} height="90%" maxWidth={maxWidth} testID={testID}>
       <View style={styles.root}>
         {title ? (
           <Text size="lg" weight="semibold" color="zinc-900" style={styles.title}>
@@ -269,11 +273,12 @@ const styles = StyleSheet.create({
     flex: 1,
     width: "100%",
     gap: 12,
-    paddingHorizontal: 4,
-  },
-  title: {
-    paddingHorizontal: 4,
+    // Match the Dialog's own horizontal inset (the close button sits at 24) so
+    // the content isn't flush against the dialog edges.
+    paddingHorizontal: 24,
+    paddingBottom: 8,
   },
+  title: {},
   search: {
     width: "100%",
   },