@lotics/ui 7.2.0 → 7.4.0

package/AGENTS.md

@@ -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.2.0",
+  "version": "7.4.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/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/inline_member_select.tsx

@@ -18,6 +18,8 @@ interface InlineMemberSelectProps {
   placeholder?: string;
   disabled?: boolean;
   accessibilityLabel?: string;
+  /** Show an in-menu search box to filter the roster; default false. */
+  searchable?: boolean;
 }
 
 /**

package/src/inline_select.tsx

@@ -23,6 +23,8 @@ export interface InlineSelectProps<T extends string> {
   placeholder?: string;
   disabled?: boolean;
   accessibilityLabel?: string;
+  /** Show an in-menu search box; default false. */
+  searchable?: boolean;
 }
 
 /**
@@ -33,7 +35,7 @@ export interface InlineSelectProps<T extends string> {
  * standard and custom-rendered pickers are both supported here.
  */
 export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
-  const { value, onSave, options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel } = props;
+  const { value, onSave, options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false } = props;
   const [open, setOpen] = useState(false);
   const [saving, setSaving] = useState(false);
   const [error, setError] = useState<string | null>(null);
@@ -78,7 +80,7 @@ export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
         </PopoverTrigger>
         <PopoverContent disableBodyScroll>
           <OptionList
-            search={{ mode: "none" }}
+            search={{ mode: searchable ? "internal" : "none" }}
             options={options}
             value={value}
             onValueChange={(next) => void pick(next)}

package/src/member_select.tsx

@@ -32,6 +32,8 @@ interface MemberSelectProps<MULTI extends boolean = false> {
   placeholder?: string;
   disabled?: boolean;
   autoFocus?: boolean;
+  /** Show an in-menu search box to filter the roster; default false. */
+  searchable?: boolean;
   includeEmptyOption?: boolean;
   enableSelectAll?: boolean;
   /** Label for the "select all" link in multi-select mode. Pass a translated string. */