@lotics/ui 7.3.0 → 7.5.0

package/AGENTS.md

@@ -20,8 +20,8 @@ typeahead, async search, virtualization, and a11y the primitive already ships.
   per-instance `labels`/`clearLabel`/`selectAllLabel` still overrides for one-offs, and an un-wrapped
   app stays English. Wired so far: `Pagination`, `SortHeader`/`Table.sortLabels`, `OptionList`
   (+ `Select`/`Combobox` built on it), `FilterChip`, `Drawer`, `Confidence`, `RemainderMeter`,
-  `ChangeReview`/`ChangeReviewActions`, and `DateRangeFilterField`/`DateFilter` (presets + footer +
-  time-segment a11y, one `dateRange` slice). Adding a string to a wired component's `*Labels` forces
+  `ChangeReview`/`ChangeReviewActions`, `DateRangeFilterField`/`DateFilter` (presets + footer +
+  time-segment a11y, one `dateRange` slice), and `FormField` (the `optional` marker). Adding a string to a wired component's `*Labels` forces
   both packs in `locale.tsx` to fill it (compile error) — that's how the kit avoids a silent English
   leak. Not yet on the provider (pass `labels` for now): calendar/gantt, the file/preview/comment labels.
 
@@ -97,6 +97,13 @@ Pick by capability, not by name. (→ the source file for the API.)
   recharts), `RingGauge`, `ProgressBar` / `StackedProgressBar` / `StepProgress`, `Breakdown`
   (a stacked bar + ranked share rows, pressable to drill; `maxRows` folds the long tail behind a
   "Show N more" toggle — `labels` to localize — so several facet cards align to one height in a row),
+  `Funnel` (a CONVERSION funnel — ordered stages as bars that NARROW; the step conversion rate is the
+  HEADLINE (a bold aligned row across the top, the first stage = the 100% baseline), the count is the
+  supporting figure below — the Amplitude/Mixpanel convention, never pin the rate to the fill height.
+  `orientation` vertical columns | horizontal bars; pass `onSelect`+`selectedKey` to make the bars
+  press-to-drill (the selected stays solid, others dim — the caller renders the records). The
+  subset/drop-off sibling of `StackedProgressBar` — nested cohorts that shrink "calls → connected →
+  won", NOT a whole split across stages — that's `StackedProgressBar`),
   `StatusGrid` + `StatusLegend`, `Heatmap` (density: colour-only, "where does it cluster"),
   `Matrix` (the PIVOT cross-tab: the NUMBER in each cell — optionally a heat wash behind it — plus
   row/column/grand totals; press a cell to drill).
@@ -801,6 +808,7 @@ step_progress · timeline (heterogeneous event LOG — per-row icon + expandable
 alert · peek · empty_state · completion_state · callout (Callout · CalloutTitle ·
 CalloutText · CalloutActions) · kpi_card · kpi_strip · metric · trend_chip · sparkline ·
 bar_chart · line_chart · pie_chart · ring_gauge · progress_bar · stacked_progress_bar · breakdown ·
+funnel (Funnel — conversion funnel: narrowing bars + the step rate as a bold aligned headline row, count below; `orientation` vertical|horizontal, `onSelect`/`selectedKey` press-to-drill; the subset/drop-off sibling of stacked_progress_bar's whole-split) ·
 status_grid (StatusGrid + StatusLegend) · heatmap (density cross-tab — colour-only, no numbers) · matrix (Matrix — the PIVOT cross-tab: band-compound `Matrix` root + `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) + `Matrix.Legend`; the data layer `matrixTotals`/`MatrixAxisItem`/`MatrixCellRef` import from `@lotics/ui/matrix_totals`. Pick over `Heatmap` when the NUMBER and totals matter, not just where it clusters) · legend_item · remainder_meter · allocation_row ·
 scan_field · file_dropzone · files_editor (FilesEditor — THE all-in-one attachment field: FileGrid + a toolbar (Upload primary · Select · Download all) that swaps into a batch SELECT mode (Select all · a Menu of Download/Share/Delete · Done) + built-in gallery + Alert-confirmed remove; host wires `files` + `onAdd`/`onRemove` (+ optional `uploads`, `onShareSelected`, `readOnly`, `labels`, `galleryLabels`); mirrors the frontend cell_files_editor. Use FileGrid/FileRows bare only when you own the chrome) · file_grid (FileGrid — the upload-aware grid: completed files + a live upload queue in one surface; FileUpload/PendingUpload types; the add-files default) · uploading_thumbnail (UploadingThumbnail — the single in-flight upload tile FileGrid renders; reach for it only when hand-rolling a non-grid upload layout) · file_thumbnail · file_thumbnail_grid · file_row · file_rows (FileRows — batteries-included file list: row press → built-in gallery + a ⋯ Download/Open-external/Remove menu; composes FileRow + ActionMenu + FileGalleryModal) · file_preview ·
 file_gallery_modal · image_gallery · use_selection_mode · share_or_download · rotate_image · avatar · skeleton · activity_indicator · loading · divider ·

package/examples/tpl_dashboard.tsx

@@ -32,6 +32,7 @@ import { type IconName } from "@lotics/ui/icon";
 import { KPIStrip } from "@lotics/ui/kpi_strip";
 import { Peek } from "@lotics/ui/peek";
 import { StackedProgressBar } from "@lotics/ui/stacked_progress_bar";
+import { Funnel } from "@lotics/ui/funnel";
 import { formatMoney } from "@lotics/ui/format_money";
 
 // ─────────────────────────────────────────────────────────────────────────────
@@ -409,6 +410,22 @@ export function TplDashboard() {
           </Card>
         </View>
 
+        {/* chart row 3: the SAME pipeline as a CONVERSION funnel — narrowing
+            cohorts + step drop-off rates, the subset lens vs the composition bar above */}
+        <View style={{ flexDirection: "row", gap: 16 }}>
+          <Card style={{ padding: 0, flex: 1 }}>
+            <CardHeader>
+              <CardHeaderTitle info="Of all prospects, how many reach each stage — the drop-off from first contact to a closed win">
+                Conversion funnel
+              </CardHeaderTitle>
+              <CardHeaderMeta>This quarter</CardHeaderMeta>
+            </CardHeader>
+            <View style={{ paddingHorizontal: 20, paddingVertical: 16 }}>
+              <Funnel stages={PHEU_STAGES.map((s) => ({ key: s.key, label: s.label, value: s.count }))} color={solid("blue")} />
+            </View>
+          </Card>
+        </View>
+
         {/* needs attention — each row expands in place to the records behind its count */}
         <Card style={{ padding: 0 }}>
           <CardHeader>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "7.3.0",
+  "version": "7.5.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -53,6 +53,7 @@
     "./stacked_progress_bar": "./src/stacked_progress_bar.tsx",
     "./legend_item": "./src/legend_item.tsx",
     "./breakdown": "./src/breakdown.tsx",
+    "./funnel": "./src/funnel.tsx",
     "./status_grid": "./src/status_grid.tsx",
     "./heatmap": "./src/heatmap.tsx",
     "./matrix": "./src/matrix.tsx",

package/src/form_field.tsx

@@ -2,6 +2,7 @@ import { createContext, useContext, useId } from "react";
 import { StyleProp, View, ViewStyle } from "react-native";
 import { Text } from "./text";
 import { Spacer } from "./spacer";
+import { useLoticsLocale } from "./locale";
 
 export interface FormFieldProps {
   label: string;
@@ -9,7 +10,8 @@ export interface FormFieldProps {
   description?: string;
   error?: string;
   style?: StyleProp<ViewStyle>;
-  /** Label shown next to `label` when `optional` is true. Default: "Optional". Pass a translated string from the consumer. */
+  /** Label shown next to `label` when `optional` is true. Defaults to the locale
+   *  pack's `formField.optional` ("Optional"); pass to override for one instance. */
   optionalLabel?: string;
 }
 
@@ -40,7 +42,8 @@ export function useFormField(): FormFieldBinding | null {
 }
 
 export function FormField(props: FormFieldProps & { children: React.ReactNode }) {
-  const { label, description, error, optional, style, children, optionalLabel = "Optional" } = props;
+  const { label, description, error, optional, style, children, optionalLabel } = props;
+  const resolvedOptionalLabel = optionalLabel ?? useLoticsLocale().formField.optional;
 
   const inputId = useId();
   const labelId = `${inputId}-label`;
@@ -72,7 +75,7 @@ export function FormField(props: FormFieldProps & { children: React.ReactNode })
           )}
           {!!optional && (
             <Text numberOfLines={1} size="sm" color="zinc-500">
-              {optionalLabel}
+              {resolvedOptionalLabel}
             </Text>
           )}
         </View>

package/src/funnel.tsx

@@ -0,0 +1,218 @@
+import { type ReactNode } from "react";
+import { View, StyleSheet } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { PressableHighlight } from "./pressable_highlight";
+
+export interface FunnelStage {
+  /** Identifier — the React key + the `onSelect` value. */
+  key: string;
+  /** Stage name (the widest / top-of-funnel stage first). */
+  label: string;
+  /** Count at this stage. Expected to be non-increasing down the list. */
+  value: number;
+}
+
+export interface FunnelProps {
+  /** Ordered stages, widest (top of funnel) first. Each bar is sized `value ÷
+   *  stages[0].value`, so the bars narrow through the funnel and the drop-off
+   *  IS the shape. */
+  stages: FunnelStage[];
+  /** `vertical` = columns side-by-side that fill the width evenly, height ∝
+   *  value capped at `size`; `horizontal` = stacked rows, bar width ∝ value.
+   *  Default `vertical`. */
+  orientation?: "vertical" | "horizontal";
+  /** Bar fill — one accent for the whole funnel (one cohort narrowing, not many
+   *  categories). Defaults to the neutral ink. */
+  color?: string;
+  /** Format a stage value (default `toLocaleString`). */
+  formatValue?: (n: number) => string;
+  /** Format the step conversion rate beside a stage (its value ÷ the stage
+   *  above). Default `"NN%"`; return `null` to hide a rate. */
+  formatRate?: (rate: number) => string | null;
+  /** Make the bars press-to-drill: pressing a stage calls `onSelect(key)`, and
+   *  pressing the selected stage again calls `onSelect(null)`. Pair with
+   *  `selectedKey` — the selected bar stays solid, the others dim. The drill
+   *  CONTENT (the records behind the stage) is the caller's to render. */
+  onSelect?: (key: string | null) => void;
+  /** The drilled stage (dims the others). */
+  selectedKey?: string | null;
+  /** xs muted uppercase eyebrow above the funnel. Omit inside a band that
+   *  already names it. */
+  title?: string;
+  /** Vertical: the column area height (the cap). Horizontal: bar thickness.
+   *  Defaults 160 / 28. */
+  size?: number;
+  accessibilityLabel?: string;
+}
+
+const defaultFormatValue = (n: number): string => n.toLocaleString("en-US");
+const defaultFormatRate = (rate: number): string => `${Math.round(rate * 100)}%`;
+const RADIUS = 2;
+const DIM = 0.28;
+
+/**
+ * Conversion funnel — ordered stages as bars that NARROW (each sized value ÷
+ * the top stage), with the step conversion rate (value ÷ the stage above)
+ * beside each. The drop-off is the shape, so it reads "where do they fall
+ * out?" at a glance. `vertical` columns or `horizontal` bars; pass `onSelect`
+ * to make the bars press-to-drill (select/deselect, the others dim).
+ *
+ * The SUBSET/conversion sibling of `StackedProgressBar`: a funnel is nested
+ * cohorts that shrink (calls → connected → won), NOT a composition of a whole
+ * (StackedProgressBar — items distributed ACROSS stages that sum to a total).
+ */
+export function Funnel(props: FunnelProps) {
+  const {
+    stages,
+    orientation = "vertical",
+    color = colors.zinc[800],
+    formatValue = defaultFormatValue,
+    formatRate = defaultFormatRate,
+    onSelect,
+    selectedKey = null,
+    title,
+    size = orientation === "vertical" ? 160 : 28,
+    accessibilityLabel,
+  } = props;
+
+  const top = stages[0]?.value ?? 0;
+  const fractionOf = (v: number) => (top > 0 ? Math.max(0, Math.min(1, v / top)) : 0);
+  const rateOf = (i: number) => {
+    const prev = i > 0 ? stages[i - 1].value : null;
+    return prev != null && prev > 0 ? formatRate(stages[i].value / prev) : null;
+  };
+  const fillOpacity = (key: string) => (selectedKey != null && selectedKey !== key ? DIM : 1);
+
+  // A bar is pressable only when onSelect is wired; press the selected one again
+  // to clear. `fill` makes the press target span the column (vertical).
+  const press = (key: string, label: string, fill: boolean, node: ReactNode) => {
+    if (!onSelect) return node;
+    return (
+      <PressableHighlight
+        accessibilityRole="button"
+        accessibilityState={{ selected: selectedKey === key }}
+        accessibilityLabel={label}
+        onPress={() => onSelect(selectedKey === key ? null : key)}
+        style={fill ? styles.pressFill : undefined}
+      >
+        {node}
+      </PressableHighlight>
+    );
+  };
+
+  const titleNode = title ? (
+    <Text size="xs" color="muted" transform="uppercase">
+      {title}
+    </Text>
+  ) : null;
+
+  if (orientation === "vertical") {
+    return (
+      <View style={styles.vContainer} accessibilityLabel={accessibilityLabel}>
+        {titleNode}
+        {/* the conversion rate is the headline — an aligned row across the top
+            (the funnel's story, read left→right); the first stage is the 100%
+            entry baseline. */}
+        <View style={styles.vRow}>
+          {stages.map((stage, i) => {
+            const rate = i === 0 ? formatRate(1) : rateOf(i);
+            return (
+              <View key={stage.key} style={styles.vCell}>
+                {rate ? (
+                  <Text size="sm" weight="semibold" tabular>
+                    {rate}
+                  </Text>
+                ) : null}
+              </View>
+            );
+          })}
+        </View>
+        <View style={[styles.vRow, { height: size }]}>
+          {stages.map((stage) => (
+            <View key={stage.key} style={styles.vSlot}>
+              {press(
+                stage.key,
+                `${stage.label}: ${formatValue(stage.value)}`,
+                true,
+                <View style={styles.vTrack}>
+                  <View style={[styles.vFill, { height: `${fractionOf(stage.value) * 100}%`, backgroundColor: color, opacity: fillOpacity(stage.key) }]} />
+                </View>,
+              )}
+            </View>
+          ))}
+        </View>
+        {/* count (supporting) + label below each column. */}
+        <View style={styles.vRow}>
+          {stages.map((stage) => (
+            <View key={stage.key} style={styles.vCaption}>
+              <Text size="sm" tabular>
+                {formatValue(stage.value)}
+              </Text>
+              <Text size="xs" color="muted" numberOfLines={1} style={styles.center}>
+                {stage.label}
+              </Text>
+            </View>
+          ))}
+        </View>
+      </View>
+    );
+  }
+
+  return (
+    <View style={styles.hContainer} accessibilityLabel={accessibilityLabel}>
+      {titleNode}
+      {stages.map((stage, i) => {
+        const rate = rateOf(i);
+        return (
+          <View key={stage.key}>
+            {press(
+              stage.key,
+              `${stage.label}: ${formatValue(stage.value)}`,
+              false,
+              <View style={styles.hStage}>
+                <View style={styles.hHead}>
+                  <Text size="sm" weight="medium">
+                    {stage.label}
+                  </Text>
+                  {rate ? (
+                    <Text size="xs" color="muted" tabular>
+                      {rate}
+                    </Text>
+                  ) : null}
+                  <View style={styles.spacer} />
+                  <Text size="sm" weight="semibold" tabular>
+                    {formatValue(stage.value)}
+                  </Text>
+                </View>
+                <View style={[styles.hTrack, { height: size }]}>
+                  <View style={[styles.hFill, { width: `${fractionOf(stage.value) * 100}%`, height: size, backgroundColor: color, opacity: fillOpacity(stage.key) }]} />
+                </View>
+              </View>,
+            )}
+          </View>
+        );
+      })}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  // vertical — columns fill the width evenly (flex:1), height ∝ value, capped at `size`
+  vContainer: { gap: 8 },
+  vRow: { flexDirection: "row", alignItems: "flex-end", gap: 10 },
+  vCell: { flex: 1, alignItems: "center" },
+  vSlot: { flex: 1, height: "100%" },
+  pressFill: { flex: 1, height: "100%" },
+  vTrack: { flex: 1, width: "100%", borderRadius: RADIUS, backgroundColor: colors.zinc[100], overflow: "hidden", justifyContent: "flex-end" },
+  vFill: { width: "100%", borderRadius: RADIUS },
+  vCaption: { flex: 1, alignItems: "center", gap: 1 },
+  center: { textAlign: "center" },
+  // horizontal — stacked rows, bar width ∝ value
+  hContainer: { gap: 12 },
+  hStage: { gap: 6 },
+  hHead: { flexDirection: "row", alignItems: "baseline", gap: 8 },
+  spacer: { flex: 1 },
+  hTrack: { borderRadius: RADIUS, backgroundColor: colors.zinc[100], overflow: "hidden" },
+  hFill: { borderRadius: RADIUS },
+});

package/src/locale.tsx

@@ -24,12 +24,14 @@ export interface LoticsLocale {
   /** `SortHeader` a11y prefix + asc/desc suffixes. */
   sortHeader: Required<SortHeaderLabels>;
   /** `OptionList` (and everything built on it — `Select`, `Combobox`, the
-   *  in-cell editors): the select-all/deselect-all links, the empty state, and
-   *  the `Combobox` recents header. */
-  optionList: { selectAll: string; deselectAll: string; noResults: string; recent: string };
+   *  in-cell editors): the select-all/deselect-all links, the empty state, the
+   *  internal search-field placeholder, and the `Combobox` recents header. */
+  optionList: { selectAll: string; deselectAll: string; noResults: string; recent: string; searchPlaceholder: string };
   /** `FilterChip` (and `ColumnFilter`): the generic clear affordance, used when
    *  a call site doesn't pass a dimension-specific `clearLabel`. */
   filterChip: { clear: string };
+  /** `FormField`: the "Optional" marker shown next to the label when `optional`. */
+  formField: { optional: string };
   /** `Drawer`: the record prev/next + close controls (screen-reader names). */
   drawer: { previous: string; next: string; close: string };
   /** `Confidence`: the full level phrase ("High confidence" …). */
@@ -74,8 +76,9 @@ export const en: LoticsLocale = {
     ascending: ", ascending",
     descending: ", descending",
   },
-  optionList: { selectAll: "Select all", deselectAll: "Deselect all", noResults: "No results", recent: "Recent" },
+  optionList: { selectAll: "Select all", deselectAll: "Deselect all", noResults: "No results", recent: "Recent", searchPlaceholder: "Search…" },
   filterChip: { clear: "Clear" },
+  formField: { optional: "Optional" },
   drawer: { previous: "Previous record", next: "Next record", close: "Close" },
   confidence: { high: "High confidence", medium: "Medium confidence", low: "Low confidence" },
   remainderMeter: {
@@ -123,8 +126,9 @@ export const vi: LoticsLocale = {
     ascending: " (tăng dần)",
     descending: " (giảm dần)",
   },
-  optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", noResults: "Không có kết quả", recent: "Gần đây" },
+  optionList: { selectAll: "Chọn tất cả", deselectAll: "Bỏ chọn tất cả", noResults: "Không có kết quả", recent: "Gần đây", searchPlaceholder: "Tìm…" },
   filterChip: { clear: "Xóa" },
+  formField: { optional: "Tùy chọn" },
   drawer: { previous: "Bản ghi trước", next: "Bản ghi sau", close: "Đóng" },
   confidence: { high: "Độ tin cậy cao", medium: "Độ tin cậy trung bình", low: "Độ tin cậy thấp" },
   remainderMeter: {

package/src/option_list.tsx

@@ -58,7 +58,7 @@ export function OptionList<T extends string, MULTI extends boolean = false, D =
           icon="search"
           value={list.query}
           onChangeText={list.setQuery}
-          placeholder={search.placeholder ?? "Search…"}
+          placeholder={search.placeholder ?? loc.searchPlaceholder}
           autoFocus={!small}
           autoCapitalize="none"
           autoCorrect={false}