@lotics/ui 4.1.0 → 4.2.0

package/AGENTS.md

@@ -29,7 +29,20 @@ Pick by capability, not by name. (→ the source file for the API.)
   destination signal; the opposite of `LinkButton` (a quiet in-app action, never underlined).
 - **Pick from a list** — `Picker` (known options, native typeahead, single/multi/custom-render,
   no search box). Search-as-you-type / async / create-new → `Combobox`. A selectable card row →
-  `CardSelectItem`.
+  `CardSelectItem`. For a SELECT-FIELD picker, render each option as its colored chip
+  (`renderOptionContent={(o) => <OptionBadge value={o} />}`).
+- **Pick member(s)** — `MemberSelect` (a `Picker` that renders each option as a `MemberChip`,
+  single or multi) — the ready member picker; pass it the roster (`members={useMembers().members}`).
+  Don't re-wire `Picker` + `renderOptionContent` + a directory by hand.
+- **A person / member (display)** — `MemberChip` (avatar + name + optional secondary line) — the
+  ONE way to show a member inline: a picker option, an assignee, a `select_member` value. Pure:
+  resolve the member from your directory (`useMembers`) and pass `name` / `image`; never hand-roll
+  `Avatar` + `Text`. (The product's `MemberBadge` is just `memberId → MemberChip`; `MemberSelect`
+  renders these per option.)
+- **A select-field value** — `OptionBadge` (a stored `select` value as its CONFIGURED colored
+  badge) — never hand-map option-key → color. Feed it a resolved option (`useFieldOptions` for a
+  picker option, or `byKey(readSelect(cell)[0]?.key)` for a stored value); multi-select wraps to
+  one badge each; a missing/unknown color token degrades to neutral.
 - **Tags / multi-select chip box** — `TagInput` (chips + an Add-popover checklist + create), NOT
   `Combobox multi` (see §Data entry).
 - **Text & form** — `TextInputField`, `NumberInput`, `SearchInput`; wrap with `FormField`;
@@ -75,6 +88,7 @@ This is the most common thing to get right. Match the JOB to the pattern:
 | REPEATING rows you build & revise | **line items** (create→preview→edit) | add / edit / remove, live totals |
 | CHARGES that bill onto documents | **billing** (`tpl_billing`) | the invoice document is the unit |
 | a multi-value TAG field | **`TagInput`** | a chip box, not a search input |
+| ONE choice from a small visible set | **`ChipGroup` pills** (or `RadioPicker`) | required single-select, one tap, every option visible |
 | a STATUS with terminal outcomes | **disposition** (open → resolve → revise) | guides the decision |
 | FILES | **attachment field** (dropzone + grid + gallery) | add / preview / delete |
 | many entries FAST | **quick capture** (one row, Enter to add) | repeat-entry speed |
@@ -333,6 +347,9 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
 
 text · card (Card · CardHeader · CardHeaderTitle · CardHeaderMeta · CardBody · CardFooter) ·
 section_heading (SectionHeading · SectionHeadingTitle — compound, owns no margin) · badge ·
+option_badge (OptionBadge — a select value as its configured colored badge) ·
+member_chip (MemberChip — avatar + name; the universal person render) ·
+member_select (MemberSelect — a Picker of MemberChip options; the member picker) ·
 status_badge · button · icon_button · link · link_button · pill_button · tabs · segmented_control ·
 picker · combobox · tag_input (TagInput — chip box + Add-popover; for tags, not Combobox multi) ·
 text_input_field · number_input · search_input · form_field · checkbox · checkbox_input · switch ·
@@ -349,4 +366,5 @@ status_grid (StatusGrid + StatusLegend) · heatmap · legend_item · remainder_m
 scan_field · file_dropzone · file_thumbnail · file_thumbnail_grid · file_preview ·
 file_gallery_modal · image_gallery · avatar · skeleton · activity_indicator · loading · divider ·
 spacer · stack · section_card · page_header · page_content · calendar (calendar/index.ts) · gantt ·
-comments_thread · format_money · format_date · colors (solid · tint · ramp · ColorName).
+comments_thread · format_money · format_date · colors (solid · tint · ramp · ColorName ·
+isColorName · asColorName — coerce a stored option/status token to a ColorName, neutral fallback).

package/package.json

@@ -1,10 +1,13 @@
 {
   "name": "@lotics/ui",
-  "version": "4.1.0",
+  "version": "4.2.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
     "./colors": "./src/colors.ts",
+    "./option_badge": "./src/option_badge.tsx",
+    "./member_chip": "./src/member_chip.tsx",
+    "./member_select": "./src/member_select.tsx",
     "./mime": "./src/mime.ts",
     "./download": "./src/download.ts",
     "./file_picker": "./src/file_picker.ts",

package/src/chip_group.tsx

@@ -3,17 +3,19 @@ import { Text } from "./text";
 import { PressableHighlight } from "./pressable_highlight";
 import { pillSurfaceStyle } from "./control_surface";
 
-// Exclusive filter chips — the view-control sibling of the form-input
-// selectors. Picking between the one-of-N controls:
-//   - ChipGroup: a SMALL, HOT filter set (≤ ~10 short options) the user flips
-//     between constantly — every option stays visible, switching is one tap,
-//     the row wraps on narrow widths. Reads as "narrow this view".
-//   - Picker: many options or tight space — compact, but hides the set behind
-//     a click. Reads as "choose a value".
-//   - RadioPicker: a form input that SETS data on a record (radio circles
-//     signal "this writes"), not a view filter.
-// Chips carry quiet zinc styling: bordered white at rest, dark fill when
-// active — color stays reserved for status semantics and primary actions.
+// One-of-N chips: every option visible, one tap to switch, the row wraps on
+// narrow widths. Quiet zinc styling — bordered white at rest, dark fill when
+// active (color stays reserved for status + primary actions). Two jobs, one
+// control:
+//   - a SMALL, HOT FILTER the user flips between constantly ("narrow this
+//     view") — model the unfiltered state as an explicit option (e.g. "All").
+//   - a small REQUIRED single-select in a form / composer (a call outcome, a
+//     1–N grade) — pills keep every choice in view and entry to one tap; an
+//     empty initial value (nothing chosen yet) is fine here.
+// Reach for `Picker` when options are many or space is tight (it hides the set
+// behind a click); for `RadioPicker` when the radio-circle "this writes"
+// affordance suits a denser form. It's affordance + density, not
+// filter-vs-write — the same ChipGroup serves both.
 
 export interface ChipOption<T extends string = string> {
   label: string;
@@ -29,8 +31,9 @@ export interface ChipGroupProps<T extends string = string> {
    */
   accessibilityLabel: string;
   options: ChipOption<T>[];
-  /** The active option — exactly one; include an explicit "all" option for
-   *  the unfiltered state rather than modelling it as no selection. */
+  /** The active option. As a FILTER, model the unfiltered state as an explicit
+   *  option (e.g. "All"); as a FORM selector, an empty value (nothing chosen
+   *  yet) is valid. */
   value: T;
   onValueChange: (value: T) => void;
 }

package/src/colors.test.ts

@@ -0,0 +1,45 @@
+import { describe, it, expect } from "vitest";
+import { isColorName, asColorName } from "./colors";
+
+describe("isColorName", () => {
+  it("accepts palette family names", () => {
+    expect(isColorName("blue")).toBe(true);
+    expect(isColorName("emerald")).toBe(true);
+    expect(isColorName("zinc")).toBe(true);
+  });
+
+  it("rejects role keys and scalar colors (not selectable families)", () => {
+    expect(isColorName("border")).toBe(false);
+    expect(isColorName("border_shadow")).toBe(false);
+    expect(isColorName("background")).toBe(false);
+    expect(isColorName("shadow")).toBe(false);
+    expect(isColorName("black")).toBe(false);
+    expect(isColorName("white")).toBe(false);
+  });
+
+  it("rejects unknown tokens and non-strings", () => {
+    expect(isColorName("chartreuse")).toBe(false);
+    expect(isColorName("")).toBe(false);
+    expect(isColorName(undefined)).toBe(false);
+    expect(isColorName(null)).toBe(false);
+    expect(isColorName(42)).toBe(false);
+  });
+});
+
+describe("asColorName", () => {
+  it("passes a valid family through", () => {
+    expect(asColorName("purple")).toBe("purple");
+  });
+
+  it("degrades an unknown/absent token to the neutral default", () => {
+    // The graceful-degradation contract: a select option whose color token this
+    // build doesn't recognize, or none at all, renders neutral rather than break.
+    expect(asColorName("chartreuse")).toBe("zinc");
+    expect(asColorName(undefined)).toBe("zinc");
+    expect(asColorName(null)).toBe("zinc");
+  });
+
+  it("honors a custom fallback", () => {
+    expect(asColorName(undefined, "slate")).toBe("slate");
+  });
+});

package/src/colors.ts

@@ -359,3 +359,28 @@ export function ramp(name: ColorName, count: number): string[] {
     return scale[RAMP_STOPS[idx]];
   });
 }
+
+/**
+ * Is `value` a usable {@link ColorName} — a palette FAMILY, not a role key
+ * (`border`/`background`/…) and not `black`/`white`? A family resolves to a
+ * shade object; the role/scalar keys resolve to a string, so "value is an
+ * object" is the test (no name list to keep in sync).
+ */
+export function isColorName(value: unknown): value is ColorName {
+  return (
+    typeof value === "string" &&
+    value in colors &&
+    typeof (colors as Record<string, unknown>)[value] === "object"
+  );
+}
+
+/**
+ * Coerce an arbitrary color token to a {@link ColorName}, falling back to a
+ * neutral. The single graceful-degradation point for stored option/status
+ * colors: a select option's `color` may be a token a newer table config
+ * introduced that this UI build predates, or absent entirely — either way a
+ * component renders a neutral badge instead of breaking. Used by `OptionBadge`.
+ */
+export function asColorName(value: unknown, fallback: ColorName = "zinc"): ColorName {
+  return isColorName(value) ? value : fallback;
+}

package/src/file_dropzone.tsx

@@ -20,8 +20,9 @@ export interface FileDropzoneProps {
   hint?: string;
   /** Main line while a drag hovers the zone ("Thả để tải lên"). */
   dropLabel?: string;
-  /** Zone height — size it to the surface (compact 120 in a form field,
-   * 200+ as a screen's main affordance). Default 160. */
+  /** Minimum zone height — it grows to fit the icon + labels + padding, so a
+   * small value never crops the content. Size it to the surface (compact ~120 in
+   * a form field, 200+ as a screen's main affordance). Default 160. */
   height?: number;
   disabled?: boolean;
   accessibilityLabel?: string;
@@ -127,7 +128,7 @@ export function FileDropzone(props: FileDropzoneProps) {
       onHoverOut={() => setHovered(false)}
       style={[
         styles.zone,
-        { height },
+        { minHeight: height },
         hovered && !dragging ? styles.zoneHovered : null,
         dragging ? styles.zoneDragging : null,
         disabled ? styles.zoneDisabled : null,
@@ -160,6 +161,7 @@ const styles = StyleSheet.create({
     borderColor: colors.zinc[300],
     backgroundColor: colors.zinc[50],
     paddingHorizontal: 20,
+    paddingVertical: 16,
   },
   zoneHovered: {
     borderColor: colors.zinc[400],

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 },
+});