@lotics/ui 1.15.0 → 1.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "1.15.0",
+  "version": "1.17.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -9,6 +9,11 @@
     "./download": "./src/download.ts",
     "./file_badge": "./src/file_badge.tsx",
     "./file_thumbnail": "./src/file_thumbnail.tsx",
+    "./file_preview": {
+      "react-native": "./src/file_preview.tsx",
+      "default": "./src/file_preview.web.tsx"
+    },
+    "./file_preview_types": "./src/file_preview_types.ts",
     "./file_gallery_modal": "./src/file_gallery_modal.tsx",
     "./pagination": "./src/pagination.tsx",
     "./bar_chart": "./src/bar_chart.tsx",
@@ -99,6 +104,7 @@
     "./page_header": "./src/page_header.tsx",
     "./pager_view": "./src/pager_view.tsx",
     "./date_picker": "./src/date_picker.tsx",
+    "./date_filter": "./src/date_filter.tsx",
     "./time_picker": "./src/time_picker.tsx",
     "./time_field": "./src/time_field.tsx",
     "./date_calendar": "./src/date_calendar.tsx",
@@ -153,6 +159,8 @@
   },
   "license": "MIT",
   "peerDependencies": {
+    "@lotics/docx": "^0.1.0",
+    "@lotics/xlsx": "^0.1.0",
     "@react-native-picker/picker": ">=2.0.0",
     "expo-image": ">=3.0.0",
     "lucide-react": ">=0.460.0",
@@ -165,6 +173,12 @@
     "recharts": ">=3.0.0"
   },
   "peerDependenciesMeta": {
+    "@lotics/docx": {
+      "optional": true
+    },
+    "@lotics/xlsx": {
+      "optional": true
+    },
     "expo-image": {
       "optional": true
     },
@@ -187,6 +201,8 @@
     "test": "vitest run"
   },
   "devDependencies": {
+    "@lotics/docx": "^0.1.0",
+    "@lotics/xlsx": "^0.1.0",
     "recharts": "^3.8.1"
   }
 }

package/src/combobox.tsx

@@ -29,6 +29,13 @@ export interface ComboboxProps<T extends string = string> {
   searchPlaceholder?: string;
   /** Shown when there are no results and not loading. Default: "No results". */
   emptyText?: string;
+  /** Accept free entry: when the typed query matches no option, offer it as a
+   *  custom value. `onValueChange` then receives `{ value: query, label: query }`.
+   *  The consumer decides what an unknown value means (e.g. a manually-typed id). */
+  allowCustom?: boolean;
+  /** Label for the free-entry row (default: the raw query). Return `null` to
+   *  suppress it for a given query (e.g. still incomplete/invalid). */
+  customOptionLabel?: (query: string) => string | null;
   disabled?: boolean;
   autoFocus?: boolean;
   testID?: string;
@@ -56,6 +63,8 @@ export function Combobox<T extends string>(props: ComboboxProps<T>) {
     placeholder,
     searchPlaceholder,
     emptyText,
+    allowCustom,
+    customOptionLabel,
     disabled = false,
     autoFocus = false,
     testID,
@@ -73,9 +82,10 @@ export function Combobox<T extends string>(props: ComboboxProps<T>) {
     (v: T) => {
       const opt = options.find((o) => o.value === v);
       if (opt) onValueChange(opt);
+      else if (allowCustom && v) onValueChange({ value: v, label: v });
       setOpen(false);
     },
-    [options, onValueChange],
+    [options, onValueChange, allowCustom],
   );
 
   return (
@@ -117,6 +127,8 @@ export function Combobox<T extends string>(props: ComboboxProps<T>) {
           onValueChange={handleSelect}
           onRequestClose={() => setOpen(false)}
           enableSearch
+          allowCustom={allowCustom}
+          customOptionLabel={customOptionLabel}
           onSearchChange={debouncedSearch}
           // Local filtering is wrong when the consumer drives search server-side.
           serverFiltered={onSearchChange !== undefined}

package/src/custom_option.test.ts

@@ -0,0 +1,50 @@
+import { describe, it, expect } from "vitest";
+import { customOptionFor } from "./custom_option";
+
+const opts = [
+  { value: "BX1N", label: "BX1N" },
+  { value: "UX1N", label: "UX1N" },
+];
+
+describe("customOptionFor", () => {
+  it("offers the trimmed query when nothing matches", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "  ABCD ", options: opts }))
+      .toEqual({ value: "ABCD", label: "ABCD" });
+  });
+
+  it("suppressed when free entry is off", () => {
+    expect(customOptionFor({ allowCustom: false, multi: false, query: "ABCD", options: opts })).toBeNull();
+    expect(customOptionFor({ allowCustom: undefined, multi: false, query: "ABCD", options: opts })).toBeNull();
+  });
+
+  it("suppressed for multi-select", () => {
+    expect(customOptionFor({ allowCustom: true, multi: true, query: "ABCD", options: opts })).toBeNull();
+  });
+
+  it("suppressed for an empty / whitespace query", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "   ", options: opts })).toBeNull();
+  });
+
+  it("suppressed when the query matches an option value (case-insensitive)", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "bx1n", options: opts })).toBeNull();
+  });
+
+  it("uses customOptionLabel for the row label but keeps the raw value", () => {
+    expect(customOptionFor({
+      allowCustom: true, multi: false, query: "ABCD", options: opts,
+      customOptionLabel: (q) => `Add "${q}"`,
+    })).toEqual({ value: "ABCD", label: 'Add "ABCD"' });
+  });
+
+  it("suppressed when customOptionLabel returns null", () => {
+    expect(customOptionFor({
+      allowCustom: true, multi: false, query: "AB", options: opts,
+      customOptionLabel: () => null,
+    })).toBeNull();
+  });
+
+  it("ignores undefined / false holes in the options list", () => {
+    expect(customOptionFor({ allowCustom: true, multi: false, query: "ABCD", options: [undefined, false, ...opts] }))
+      .toEqual({ value: "ABCD", label: "ABCD" });
+  });
+});

package/src/custom_option.ts

@@ -0,0 +1,30 @@
+import type { PickerOption } from "./picker";
+
+/**
+ * Resolve the free-entry ("custom") option a search picker should offer for the
+ * current query — or `null` when it should not be offered. The option's `value`
+ * stays the raw trimmed query; consumers decide what an unknown value means.
+ *
+ * Suppressed when: free entry is disabled, the picker is multi-select, the query
+ * is empty, the query already matches an existing option's value
+ * (case-insensitive), or `customOptionLabel` returns `null` for it.
+ *
+ * Pure and RN-free so it is unit-testable in isolation from `PickerMenu`.
+ */
+export function customOptionFor<T extends string>(args: {
+  allowCustom: boolean | undefined;
+  multi: boolean;
+  query: string;
+  options: (PickerOption<T> | undefined | false)[];
+  customOptionLabel?: (query: string) => string | null;
+}): PickerOption<T> | null {
+  const { allowCustom, multi, query, options, customOptionLabel } = args;
+  if (!allowCustom || multi) return null;
+  const q = query.trim();
+  if (!q || options.some((o) => o && String(o.value).toLowerCase() === q.toLowerCase())) {
+    return null;
+  }
+  const label = customOptionLabel ? customOptionLabel(q) : q;
+  if (label == null) return null;
+  return { value: q as T, label };
+}

package/src/date_filter.tsx

@@ -0,0 +1,389 @@
+import React, { useCallback, useMemo, useRef, useState } from "react";
+import { ScrollView, StyleSheet, View } from "react-native";
+import { Text } from "./text";
+import { colors } from "./colors";
+import { MenuButton } from "./menu_button";
+import { Calendar, CalendarRangeValue, CalendarRef } from "./date_calendar";
+import { TimeField } from "./time_field";
+import { Switch } from "./switch";
+import { useScreenSize } from "./use_screen_size";
+import { SegmentLabels } from "./date_segments";
+import { PresetId, PRESET_IDS, getPresetValue } from "./date_filter_presets";
+
+type SelectionMode = "single" | "range";
+
+// =============================================================================
+// Types
+// =============================================================================
+
+export interface DateFilterValue {
+  start: { date: Date | null; time: string | null };
+  end: { date: Date | null; time: string | null };
+}
+
+/**
+ * Translated labels. Extends `SegmentLabels` (consumed by the time fields);
+ * the rest are the preset names and the range-display strings. The frontend
+ * feeds these from `useDateFilterLabels`; standalone apps pass literals.
+ */
+export interface DateFilterLabels extends SegmentLabels {
+  today: string;
+  yesterday: string;
+  tomorrow: string;
+  thisWeek: string;
+  thisMonth: string;
+  lastMonth: string;
+  custom: string;
+  from: string;
+  to: string;
+  selectDateRange: string;
+  selectDate: string;
+}
+
+const DEFAULT_LABELS: DateFilterLabels = {
+  year: "Year",
+  month: "Month",
+  day: "Day",
+  hour: "Hour",
+  minute: "Minute",
+  dayPeriod: "AM/PM",
+  today: "Today",
+  yesterday: "Yesterday",
+  tomorrow: "Tomorrow",
+  thisWeek: "This week",
+  thisMonth: "This month",
+  lastMonth: "Last month",
+  custom: "Custom",
+  from: "From",
+  to: "To",
+  selectDateRange: "Select date range",
+  selectDate: "Select date",
+};
+
+export interface DateFilterProps {
+  value: DateFilterValue;
+  onValueChange: (value: DateFilterValue) => void;
+  includeTime?: boolean;
+  /** Translated labels. Defaults to English. */
+  labels?: Partial<DateFilterLabels>;
+  /** BCP-47 locale for the calendar and date display. Defaults to "en-US". */
+  locale?: string;
+}
+
+// =============================================================================
+// Helpers
+// =============================================================================
+
+function presetLabel(id: PresetId, labels: DateFilterLabels): string {
+  switch (id) {
+    case "today":
+      return labels.today;
+    case "yesterday":
+      return labels.yesterday;
+    case "tomorrow":
+      return labels.tomorrow;
+    case "this_week":
+      return labels.thisWeek;
+    case "this_month":
+      return labels.thisMonth;
+    case "last_month":
+      return labels.lastMonth;
+    case "custom":
+      return labels.custom;
+  }
+}
+
+function formatDateDisplay(date: Date | null, locale: string | undefined): string {
+  if (!date) return "";
+  const isoDate = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, "0")}-${String(date.getDate()).padStart(2, "0")}`;
+  try {
+    return new Intl.DateTimeFormat(locale, {
+      month: "short",
+      day: "numeric",
+      year: "numeric",
+    }).format(date);
+  } catch {
+    return isoDate;
+  }
+}
+
+// =============================================================================
+// Main Component
+// =============================================================================
+
+export function DateFilter(props: DateFilterProps) {
+  const { value, onValueChange, includeTime = false, locale } = props;
+  const labels = useMemo<DateFilterLabels>(
+    () => ({ ...DEFAULT_LABELS, ...props.labels }),
+    [props.labels],
+  );
+  const screenSize = useScreenSize();
+  const calendarRef = useRef<CalendarRef>(null);
+  const [selectionMode, setSelectionMode] = useState<SelectionMode>(() => {
+    if (value.start.date && value.end.date) {
+      if (value.start.date.toDateString() !== value.end.date.toDateString()) {
+        return "range";
+      }
+    }
+    return "single";
+  });
+
+  const calendarValue: CalendarRangeValue = useMemo(
+    () => ({ start: value.start.date, end: value.end.date }),
+    [value.start.date, value.end.date],
+  );
+
+  const handleCalendarChange = useCallback(
+    (newValue: CalendarRangeValue) => {
+      // In single mode, one click selects a single date immediately
+      if (selectionMode === "single" && newValue.start && !newValue.end) {
+        onValueChange({
+          start: { date: newValue.start, time: value.start.time },
+          end: { date: newValue.start, time: value.end.time },
+        });
+        return;
+      }
+      onValueChange({
+        start: { date: newValue.start, time: value.start.time },
+        end: { date: newValue.end, time: value.end.time },
+      });
+    },
+    [onValueChange, value.start.time, value.end.time, selectionMode],
+  );
+
+  const handleModeChange = useCallback(
+    (isRange: boolean) => {
+      const newMode: SelectionMode = isRange ? "range" : "single";
+      setSelectionMode(newMode);
+
+      // Switching to single: collapse range to start date
+      if (newMode === "single" && value.start.date) {
+        onValueChange({
+          start: value.start,
+          end: { date: value.start.date, time: value.start.time },
+        });
+      }
+    },
+    [value, onValueChange],
+  );
+
+  const handleStartTimeChange = useCallback(
+    (time: string) => {
+      onValueChange({ ...value, start: { ...value.start, time: time || null } });
+    },
+    [onValueChange, value],
+  );
+
+  const handleEndTimeChange = useCallback(
+    (time: string) => {
+      onValueChange({ ...value, end: { ...value.end, time: time || null } });
+    },
+    [onValueChange, value],
+  );
+
+  // Which preset (if any) the current value matches.
+  const activePresetId = useMemo((): PresetId | null => {
+    if (!value.start.date && !value.end.date) return null;
+    const now = new Date();
+    for (const id of PRESET_IDS) {
+      const presetValue = getPresetValue(id, now);
+      if (!presetValue) continue; // "custom"
+      if (
+        value.start.date?.toDateString() === presetValue.start.date?.toDateString() &&
+        value.end.date?.toDateString() === presetValue.end.date?.toDateString()
+      ) {
+        return id;
+      }
+    }
+    return "custom";
+  }, [value]);
+
+  const handlePresetSelect = useCallback(
+    (id: PresetId) => {
+      // Re-clicking the active preset clears the filter
+      if (activePresetId === id) {
+        onValueChange({ start: { date: null, time: null }, end: { date: null, time: null } });
+        return;
+      }
+
+      const presetValue = getPresetValue(id, new Date());
+      if (!presetValue) {
+        // "Custom" clears the value so the user can select manually
+        onValueChange({ start: { date: null, time: null }, end: { date: null, time: null } });
+        return;
+      }
+
+      // Auto-switch to range mode for multi-day presets
+      if (presetValue.start.date && presetValue.end.date) {
+        const isSingleDay =
+          presetValue.start.date.toDateString() === presetValue.end.date.toDateString();
+        if (!isSingleDay && selectionMode === "single") setSelectionMode("range");
+      }
+
+      onValueChange(presetValue);
+
+      if (presetValue.start.date) {
+        calendarRef.current?.navigateToMonth(
+          presetValue.start.date.getFullYear(),
+          presetValue.start.date.getMonth(),
+        );
+      }
+    },
+    [onValueChange, activePresetId, selectionMode],
+  );
+
+  const renderPreset = (id: PresetId) => {
+    const isActive = activePresetId === id;
+    return (
+      <MenuButton
+        key={id}
+        title={
+          <Text size="sm" color={isActive ? "inverted" : "default"}>
+            {presetLabel(id, labels)}
+          </Text>
+        }
+        onPress={() => handlePresetSelect(id)}
+        style={[styles.presetItem, isActive && styles.presetItemActive]}
+      />
+    );
+  };
+
+  return (
+    <View style={[styles.container, { flexDirection: screenSize.small ? "column" : "row" }]}>
+      {/* Presets sidebar (desktop only) */}
+      {!screenSize.small && (
+        <View style={styles.presetsSidebar}>{PRESET_IDS.map(renderPreset)}</View>
+      )}
+
+      {/* Calendar and time pickers */}
+      <View style={styles.mainContent}>
+        <Calendar<"range">
+          ref={calendarRef}
+          mode="range"
+          value={calendarValue}
+          onValueChange={handleCalendarChange}
+          locale={locale}
+        />
+
+        {selectionMode === "range" ? (
+          <View style={styles.rangeDisplay}>
+            {value.start.date ? (
+              <View style={styles.rangeItem}>
+                <Text size="xs" color="zinc-500">
+                  {labels.from}
+                </Text>
+                <Text size="sm" weight="medium">
+                  {formatDateDisplay(value.start.date, locale) || labels.selectDate}
+                </Text>
+                {includeTime && (
+                  <View style={{ marginTop: 4 }}>
+                    <TimeField
+                      value={value.start.time || ""}
+                      onChange={handleStartTimeChange}
+                      segmentLabels={labels}
+                      locale={locale}
+                    />
+                  </View>
+                )}
+              </View>
+            ) : (
+              <View style={styles.rangeItem} />
+            )}
+            {value.end.date ? (
+              <View style={styles.rangeItem}>
+                <Text size="xs" color="zinc-500">
+                  {labels.to}
+                </Text>
+                <Text size="sm" weight="medium">
+                  {formatDateDisplay(value.end.date, locale) || labels.selectDate}
+                </Text>
+                {includeTime && value.end.date && (
+                  <View style={{ marginTop: 4 }}>
+                    <TimeField
+                      value={value.end.time || ""}
+                      onChange={handleEndTimeChange}
+                      segmentLabels={labels}
+                      locale={locale}
+                    />
+                  </View>
+                )}
+              </View>
+            ) : (
+              <View style={styles.rangeItem} />
+            )}
+          </View>
+        ) : null}
+
+        <View style={styles.modeToggle}>
+          <Switch value={selectionMode === "range"} onChange={handleModeChange} />
+          <Text size="sm" color="muted">
+            {labels.selectDateRange}
+          </Text>
+        </View>
+      </View>
+
+      {/* Presets (mobile only - below calendar) */}
+      {screenSize.small && (
+        <ScrollView
+          horizontal
+          showsHorizontalScrollIndicator={false}
+          style={styles.presetsScrollView}
+          contentContainerStyle={styles.presetsScrollContent}
+        >
+          {PRESET_IDS.map(renderPreset)}
+        </ScrollView>
+      )}
+    </View>
+  );
+}
+
+// =============================================================================
+// Styles
+// =============================================================================
+
+const styles = StyleSheet.create({
+  container: {
+    backgroundColor: colors.white,
+    borderRadius: 8,
+    gap: 16,
+  },
+  presetsSidebar: {
+    minWidth: 140,
+  },
+  presetsScrollView: {
+    borderTopWidth: 1,
+    borderTopColor: colors.zinc["200"],
+    paddingTop: 8,
+  },
+  presetsScrollContent: {
+    flexDirection: "row",
+    gap: 4,
+  },
+  presetItem: {
+    marginHorizontal: 0,
+    marginBottom: 2,
+  },
+  presetItemActive: {
+    backgroundColor: colors.zinc["800"],
+  },
+  mainContent: {
+    flex: 1,
+  },
+  modeToggle: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 8,
+    paddingTop: 8,
+    paddingBottom: 8,
+    paddingLeft: 8,
+  },
+  rangeDisplay: {
+    flexDirection: "row",
+    gap: 16,
+    paddingTop: 8,
+  },
+  rangeItem: {
+    flex: 1,
+    paddingLeft: 8,
+  },
+});

package/src/date_filter_presets.test.ts

@@ -0,0 +1,62 @@
+import { describe, it, expect } from "vitest";
+import { getPresetValue, PRESET_IDS, type PresetId } from "./date_filter_presets";
+
+// Wednesday, 10 June 2026, 14:30 — a fixed clock so every range is deterministic.
+const NOW = new Date(2026, 5, 10, 14, 30, 0, 0);
+
+function ymd(d: Date | null): string {
+  if (!d) return "null";
+  return `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+}
+
+describe("getPresetValue", () => {
+  it("today spans the start to end of the current day", () => {
+    const v = getPresetValue("today", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-06-10");
+    expect(ymd(v.end.date)).toBe("2026-06-10");
+    expect(v.start.date!.getHours()).toBe(0);
+    expect(v.start.date!.getMilliseconds()).toBe(0);
+    expect(v.end.date!.getHours()).toBe(23);
+    expect(v.end.date!.getMinutes()).toBe(59);
+    expect(v.end.date!.getMilliseconds()).toBe(999);
+  });
+
+  it("yesterday and tomorrow shift by one day", () => {
+    expect(ymd(getPresetValue("yesterday", NOW)!.start.date)).toBe("2026-06-09");
+    expect(ymd(getPresetValue("yesterday", NOW)!.end.date)).toBe("2026-06-09");
+    expect(ymd(getPresetValue("tomorrow", NOW)!.start.date)).toBe("2026-06-11");
+    expect(ymd(getPresetValue("tomorrow", NOW)!.end.date)).toBe("2026-06-11");
+  });
+
+  it("this_week runs Monday → Sunday around now", () => {
+    const v = getPresetValue("this_week", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-06-08"); // Monday
+    expect(v.start.date!.getDay()).toBe(1);
+    expect(ymd(v.end.date)).toBe("2026-06-14"); // Sunday
+    expect(v.end.date!.getDay()).toBe(0);
+  });
+
+  it("this_month covers the whole calendar month", () => {
+    const v = getPresetValue("this_month", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-06-01");
+    expect(ymd(v.end.date)).toBe("2026-06-30");
+  });
+
+  it("last_month covers the previous calendar month", () => {
+    const v = getPresetValue("last_month", NOW)!;
+    expect(ymd(v.start.date)).toBe("2026-05-01");
+    expect(ymd(v.end.date)).toBe("2026-05-31");
+  });
+
+  it("custom carries no range", () => {
+    expect(getPresetValue("custom", NOW)).toBeNull();
+  });
+
+  it("every preset id resolves (only custom is null)", () => {
+    for (const id of PRESET_IDS) {
+      const v = getPresetValue(id as PresetId, NOW);
+      if (id === "custom") expect(v).toBeNull();
+      else expect(v).not.toBeNull();
+    }
+  });
+});