@lotics/ui 4.1.0 → 4.3.0

package/src/member_chip.tsx

@@ -0,0 +1,51 @@
+import React from "react";
+import { View, StyleSheet, StyleProp, ViewStyle } from "react-native";
+import { Avatar } from "./avatar";
+import { Text } from "./text";
+
+interface MemberChipProps {
+  /** Display name. Empty/blank falls back to a neutral label — pass
+   *  `name={member.name || member.email}` to prefer email when unnamed. */
+  name?: string | null;
+  /** Avatar image URL (a member's `image` from `useMembers`). Absent → initials. */
+  image?: string | null;
+  /** Optional secondary line under the name — e.g. email, role, department. */
+  secondary?: string | null;
+  /** Avatar diameter in px. Default 28. */
+  size?: number;
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Render a member/person as an avatar + name (+ optional secondary line) — the
+ * one canonical way to show a person inline: a member-picker option, an assignee,
+ * a `select_member` cell in a register or detail. The {@link Avatar} falls back
+ * to initials when there's no image.
+ *
+ * Pure: pass the member's fields in (from `useMembers`, or a resolved
+ * `select_member` cell joined against that roster); this component fetches
+ * nothing and carries no domain types.
+ */
+export function MemberChip({ name, image, secondary, size = 28, style }: MemberChipProps) {
+  const displayName = name?.trim() || "Unknown";
+  return (
+    <View style={[styles.row, style]}>
+      <Avatar size={size} name={displayName} source={image ? { uri: image } : undefined} />
+      <View style={styles.text}>
+        <Text userSelect="none" numberOfLines={1}>
+          {displayName}
+        </Text>
+        {secondary ? (
+          <Text userSelect="none" size="sm" color="zinc-500" numberOfLines={1}>
+            {secondary}
+          </Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: { flexDirection: "row", alignItems: "center", gap: 6 },
+  text: { flexShrink: 1 },
+});

package/src/member_select.tsx

@@ -0,0 +1,81 @@
+import React, { useCallback, useMemo } from "react";
+import { StyleProp, ViewStyle } from "react-native";
+import {
+  Picker,
+  type PickerOption,
+  type PickerValue,
+  type PickerOnValueChange,
+  type PickerOnClose,
+} from "./picker";
+import { MemberChip } from "./member_chip";
+
+/** A candidate member for {@link MemberSelect}. Shaped to accept a `useMembers`
+ *  row from `@lotics/app-sdk` (or any roster) directly. */
+export interface MemberSelectMember {
+  id: string;
+  name?: string | null;
+  image?: string | null;
+  email?: string | null;
+}
+
+interface MemberSelectProps<MULTI extends boolean = false> {
+  /**
+   * The candidate roster. An app feeds `useMembers()`; the product feeds any
+   * directory. Each member carries its own avatar (`image`), so options render
+   * with no side lookup.
+   */
+  members: MemberSelectMember[];
+  value?: PickerValue<string, MULTI> | null;
+  onValueChange?: PickerOnValueChange<string, MULTI>;
+  onClose?: PickerOnClose<string, MULTI>;
+  multi?: MULTI;
+  placeholder?: string;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  includeEmptyOption?: boolean;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+  accessibilityLabel?: string;
+}
+
+/**
+ * Choose member(s) — a {@link Picker} whose every option renders as a
+ * {@link MemberChip} (avatar + name). The one member-picker shape, so an app
+ * never re-wires `Picker` + `renderOptionContent` + a directory by hand. PURE:
+ * pass the candidate `members` (an app feeds `useMembers`, the product any
+ * roster); this fetches nothing. Single or multi via `multi`. Options are
+ * single-line by design — a picker row identifies a person by name + avatar;
+ * for a denser identity (email/role), render {@link MemberChip} with `secondary`
+ * on a roomier surface (a register row, a detail), not in a picker.
+ *
+ * ```tsx
+ * const { members } = useMembers();
+ * <MemberSelect members={members} value={assignee} onValueChange={setAssignee} />
+ * ```
+ */
+export function MemberSelect<MULTI extends boolean = false>(props: MemberSelectProps<MULTI>) {
+  const { members, ...picker } = props;
+
+  const byId = useMemo(() => new Map(members.map((m) => [m.id, m])), [members]);
+  const options = useMemo<PickerOption<string>[]>(
+    () => members.map((m) => ({ value: m.id, label: m.name || m.email || m.id })),
+    [members],
+  );
+
+  const renderOptionContent = useCallback(
+    (option: PickerOption<string>) => {
+      const member = byId.get(option.value);
+      if (!member) return null;
+      return <MemberChip name={member.name || member.email} image={member.image} />;
+    },
+    [byId],
+  );
+
+  return (
+    <Picker<string, MULTI>
+      options={options}
+      renderOptionContent={renderOptionContent}
+      {...picker}
+    />
+  );
+}

package/src/option_badge.tsx

@@ -0,0 +1,58 @@
+import React from "react";
+import { View, StyleSheet, StyleProp, ViewStyle } from "react-native";
+import { Badge } from "./badge";
+import { asColorName } from "./colors";
+
+/**
+ * One select option, as carried by a query CELL (`readSelect`) or the option
+ * LIST (`useFieldOptions`) in `@lotics/app-sdk`. `key` is optional — used only
+ * as a stable React key. `color` is a palette token; it may be absent (a cell
+ * carries only key + label) or a token this UI build doesn't recognize — either
+ * way the badge degrades to a neutral color.
+ */
+export interface OptionValue {
+  key?: string;
+  label: string;
+  color?: string | null;
+}
+
+interface OptionBadgeProps {
+  /**
+   * A single option, an array (a multi-select cell → one badge each), or
+   * null/empty (renders nothing — pair with your own placeholder).
+   */
+  value?: OptionValue | OptionValue[] | null;
+  /** Badge weight — see {@link Badge}. Default "tonal". */
+  variant?: "tonal" | "dot";
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * Render a select-field value as colored {@link Badge}(s) with the option's
+ * CONFIGURED color resolved automatically — so an app never hand-maintains an
+ * option-key → color map, and a freshly added or renamed option just renders.
+ * Multi-select wraps to one badge per option; an empty value renders nothing; an
+ * option with a missing/unrecognized color token falls back to a neutral badge.
+ *
+ * Feed it straight from `@lotics/app-sdk`: a `useFieldOptions` option for a
+ * picker, or `byKey(readSelect(cell)[0]?.key)` for a stored value.
+ */
+export function OptionBadge({ value, variant, style }: OptionBadgeProps) {
+  const options = value == null ? [] : Array.isArray(value) ? value : [value];
+  if (options.length === 0) return null;
+  if (options.length === 1) {
+    const o = options[0];
+    return <Badge label={o.label} color={asColorName(o.color)} variant={variant} style={style} />;
+  }
+  return (
+    <View style={[styles.wrap, style]}>
+      {options.map((o, i) => (
+        <Badge key={o.key ?? String(i)} label={o.label} color={asColorName(o.color)} variant={variant} />
+      ))}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  wrap: { flexDirection: "row", flexWrap: "wrap", alignItems: "center", gap: 4 },
+});

package/src/prompt_field.tsx

@@ -0,0 +1,150 @@
+import { useCallback, useState } from "react";
+import {
+  NativeSyntheticEvent,
+  StyleSheet,
+  TextInput as RNTextInput,
+  TextInputKeyPressEventData,
+  View,
+} from "react-native";
+import { colors, solid, tint } from "./colors";
+import { Icon } from "./icon";
+import { IconButton } from "./icon_button";
+import { ActivityIndicator } from "./activity_indicator";
+import { ACTIVE_RING } from "./control_surface";
+import { getInputTextStyle, fontFamilyRegular } from "./text_utils";
+
+export interface PromptFieldProps {
+  value: string;
+  onChangeText: (value: string) => void;
+  /** Fired on Enter (without Shift) or the send button. Receives the trimmed
+   *  text; never fires empty or while busy. */
+  onSubmit: (value: string) => void;
+  placeholder?: string;
+  /** The agent is working — the field locks and the send slot shows a spinner.
+   *  This is the imperative command surface: one prompt does work, you watch it
+   *  stream (see `AgentRun`), you don't chat. */
+  busy?: boolean;
+  disabled?: boolean;
+  autoFocus?: boolean;
+  accessibilityLabel?: string;
+  /** When set, a paperclip appears at the left of the footer — the composer can
+   *  attach files (e.g. the photo that starts a run). The host opens the picker. */
+  onAttach?: () => void;
+}
+
+/**
+ * The natural-language command surface for an AI app — a prompt box that
+ * triggers agent work, NOT a chat composer. Enter sends (Shift+Enter for a
+ * newline); while the agent runs, the field locks and the send slot spins. The
+ * violet sparkle marks it as the AI input. Pair with `AgentRun` (the streamed
+ * work it kicks off) and a session history of the outputs it produces.
+ */
+export function PromptField(props: PromptFieldProps) {
+  const { value, onChangeText, onSubmit, placeholder, busy, disabled, autoFocus, accessibilityLabel, onAttach } = props;
+  const [focused, setFocused] = useState(false);
+
+  const canSubmit = value.trim().length > 0 && !busy && !disabled;
+
+  const submit = useCallback(() => {
+    if (value.trim().length === 0 || busy || disabled) return;
+    onSubmit(value.trim());
+  }, [value, busy, disabled, onSubmit]);
+
+  // Web: Enter sends, Shift+Enter inserts a newline. RN's key event wraps the
+  // DOM event, so shiftKey/preventDefault are read defensively off nativeEvent.
+  const onKeyPress = useCallback(
+    (e: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
+      const ne = e.nativeEvent as unknown as { key: string; shiftKey?: boolean };
+      if (ne.key === "Enter" && !ne.shiftKey) {
+        (e as unknown as { preventDefault?: () => void }).preventDefault?.();
+        submit();
+      }
+    },
+    [submit],
+  );
+
+  return (
+    <View
+      style={[
+        styles.box,
+        focused ? { borderColor: colors.zinc[900], boxShadow: ACTIVE_RING } : null,
+        disabled ? { backgroundColor: colors.zinc[50] } : null,
+      ]}
+    >
+      <View style={styles.inputRow}>
+        <View style={styles.glyph}>
+          <Icon name="sparkles" size={14} color={solid("violet")} />
+        </View>
+        <RNTextInput
+          accessibilityLabel={accessibilityLabel ?? placeholder}
+          style={[styles.input, getInputTextStyle()]}
+          value={value}
+          onChangeText={onChangeText}
+          onKeyPress={onKeyPress}
+          onFocus={() => setFocused(true)}
+          onBlur={() => setFocused(false)}
+          placeholder={placeholder}
+          placeholderTextColor={colors.zinc[400]}
+          editable={!busy && !disabled}
+          autoFocus={autoFocus}
+          multiline
+          submitBehavior="newline"
+        />
+      </View>
+      <View style={styles.footer}>
+        {onAttach ? (
+          <IconButton icon="paperclip" color="none" size="sm" accessibilityLabel="Attach files" onPress={onAttach} disabled={busy || disabled} />
+        ) : null}
+        <View style={{ flex: 1 }} />
+        {busy ? (
+          <View style={styles.sendSlot}>
+            <ActivityIndicator size={18} color={solid("violet")} />
+          </View>
+        ) : (
+          <IconButton
+            icon="arrow-up"
+            color="primary"
+            accessibilityLabel="Send"
+            onPress={submit}
+            disabled={!canSubmit}
+          />
+        )}
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  box: {
+    borderWidth: 1,
+    borderColor: colors.border,
+    borderRadius: 14,
+    backgroundColor: colors.white,
+    paddingHorizontal: 12,
+    paddingTop: 10,
+    paddingBottom: 8,
+    gap: 6,
+  },
+  inputRow: { flexDirection: "row", gap: 8, alignItems: "flex-start" },
+  glyph: {
+    width: 24,
+    height: 24,
+    borderRadius: 7,
+    alignItems: "center",
+    justifyContent: "center",
+    backgroundColor: tint("violet", 0.1),
+    marginTop: 2,
+  },
+  input: {
+    flex: 1,
+    minHeight: 48,
+    maxHeight: 160,
+    paddingTop: 4,
+    paddingBottom: 0,
+    fontFamily: fontFamilyRegular,
+    // RN-Web focus outline is handled by the box ring, not the raw input.
+    outlineStyle: "none",
+  } as object,
+  footer: { flexDirection: "row", alignItems: "center" },
+  sendSlot: { width: 28, height: 28, alignItems: "center", justifyContent: "center" },
+});

package/src/sources.tsx

@@ -0,0 +1,92 @@
+import { StyleSheet, View } from "react-native";
+import { colors } from "./colors";
+import { Text } from "./text";
+import { Icon, type IconName } from "./icon";
+import { PressableHighlight } from "./pressable_highlight";
+
+export type SourceKind = "record" | "document" | "table" | "web" | "knowledge";
+
+export interface SourceRef {
+  id: string;
+  label: string;
+  kind?: SourceKind;
+  /** A locator under the label — "page 2", a record code, a column. */
+  detail?: string;
+}
+
+export interface SourcesProps {
+  sources: SourceRef[];
+  /** Eyebrow above the chips. Default "Sources". */
+  label?: string;
+  /** Pass to make each chip openable (jump to the record / document / page). */
+  onOpen?: (source: SourceRef) => void;
+}
+
+const KIND_ICON: Record<SourceKind, IconName> = {
+  record: "box",
+  document: "file-text",
+  table: "table-2",
+  web: "external-link",
+  knowledge: "book-open",
+};
+
+/**
+ * Where the AI's output came FROM — a row of source chips under a generated
+ * answer, summary, or extracted value, each openable. Provenance is what makes
+ * AI output verifiable; show it on anything the agent produced from data it
+ * read (extraction, summarization, Q&A). Renders nothing for an empty list.
+ */
+export function Sources(props: SourcesProps) {
+  if (props.sources.length === 0) return null;
+  return (
+    <View style={{ gap: 6 }}>
+      <Text size="xs" color="muted" transform="uppercase">
+        {props.label ?? "Sources"}
+      </Text>
+      <View style={styles.row}>
+        {props.sources.map((s) =>
+          props.onOpen ? (
+            <PressableHighlight key={s.id} onPress={() => props.onOpen?.(s)} style={styles.chip}>
+              <SourceChip source={s} />
+            </PressableHighlight>
+          ) : (
+            <View key={s.id} style={styles.chip}>
+              <SourceChip source={s} />
+            </View>
+          ),
+        )}
+      </View>
+    </View>
+  );
+}
+
+function SourceChip({ source }: { source: SourceRef }) {
+  return (
+    <>
+      <Icon name={KIND_ICON[source.kind ?? "document"]} size={12} color={colors.zinc[500]} />
+      <Text size="xs" weight="medium" numberOfLines={1}>
+        {source.label}
+      </Text>
+      {source.detail ? (
+        <Text size="xs" color="muted" numberOfLines={1}>
+          {source.detail}
+        </Text>
+      ) : null}
+    </>
+  );
+}
+
+const styles = StyleSheet.create({
+  row: { flexDirection: "row", flexWrap: "wrap", gap: 8 },
+  chip: {
+    flexDirection: "row",
+    alignItems: "center",
+    gap: 6,
+    paddingHorizontal: 10,
+    paddingVertical: 5,
+    borderRadius: 8,
+    borderWidth: 1,
+    borderColor: colors.border,
+    backgroundColor: colors.white,
+  },
+});

package/src/suggestion.tsx

@@ -0,0 +1,102 @@
+import { ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors, solid, tint } from "./colors";
+import { Text } from "./text";
+import { Icon } from "./icon";
+import { Button } from "./button";
+import { LinkButton } from "./link_button";
+import { Confidence, type ConfidenceLevel } from "./confidence";
+
+export interface SuggestionProps {
+  /** The proposal headline — what the AI suggests. */
+  title: string;
+  /** One line of WHY — the rationale the human is weighing. */
+  rationale?: string;
+  confidence?: ConfidenceLevel;
+  confidenceScore?: number;
+  /** The proposal body — render the proposed value/preview however fits (a
+   *  field stack, a chip row, a diagram). Omit for a title-only suggestion. */
+  children?: ReactNode;
+  onAccept?: () => void;
+  /** Tweak before accepting — the host opens its editor. */
+  onEdit?: () => void;
+  onDismiss?: () => void;
+  acceptLabel?: string;
+  /** Once resolved the card settles to a quiet outcome line (no actions). */
+  status?: "open" | "accepted" | "dismissed";
+}
+
+/**
+ * The core review-for-approval surface: an AI proposal the human accepts,
+ * edits, or dismisses — never auto-applied. The violet sparkle marks it as
+ * AI-proposed; a `Confidence` chip says how sure; the body shows the proposed
+ * value. The decision is the human's. For a shortlist, stack several (rank by
+ * confidence, the top one first). Pair with `AgentRun` (what produced it) and
+ * `ChangeReview` (when the proposal is an edit to existing state).
+ */
+export function Suggestion(props: SuggestionProps) {
+  const status = props.status ?? "open";
+  const hasConfidence = props.confidence != null || props.confidenceScore != null;
+  return (
+    <View style={[styles.card, status !== "open" ? styles.resolved : null]}>
+      <View style={styles.header}>
+        <Icon name="sparkles" size={14} color={solid("violet")} />
+        <Text size="sm" weight="semibold" style={{ flex: 1 }} numberOfLines={2}>
+          {props.title}
+        </Text>
+        {status === "open" && hasConfidence ? (
+          <Confidence level={props.confidence} score={props.confidenceScore} />
+        ) : null}
+      </View>
+
+      {props.rationale ? (
+        <Text size="xs" color="muted">
+          {props.rationale}
+        </Text>
+      ) : null}
+
+      {props.children ? <View>{props.children}</View> : null}
+
+      {status !== "open" ? (
+        <View style={styles.outcome}>
+          <Icon
+            name={status === "accepted" ? "circle-check" : "x"}
+            size={14}
+            color={status === "accepted" ? solid("emerald") : colors.zinc[400]}
+          />
+          <Text size="xs" color="muted">
+            {status === "accepted" ? "Accepted" : "Dismissed"}
+          </Text>
+        </View>
+      ) : (
+        <View style={styles.footer}>
+          {props.onDismiss ? <LinkButton title="Dismiss" onPress={props.onDismiss} /> : <View />}
+          <View style={styles.actions}>
+            {props.onEdit ? (
+              <Button title="Edit" color="secondary" shape="rounded" icon="square-pen" onPress={props.onEdit} />
+            ) : null}
+            {props.onAccept ? (
+              <Button title={props.acceptLabel ?? "Accept"} color="primary" shape="rounded" onPress={props.onAccept} />
+            ) : null}
+          </View>
+        </View>
+      )}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  card: {
+    borderWidth: 1,
+    borderColor: tint("violet", 0.35),
+    backgroundColor: colors.white,
+    borderRadius: 12,
+    padding: 14,
+    gap: 10,
+  },
+  resolved: { borderColor: colors.border, backgroundColor: colors.zinc[50] },
+  header: { flexDirection: "row", alignItems: "center", gap: 8 },
+  outcome: { flexDirection: "row", alignItems: "center", gap: 6 },
+  footer: { flexDirection: "row", alignItems: "center", justifyContent: "space-between" },
+  actions: { flexDirection: "row", alignItems: "center", gap: 8 },
+});