@lotics/ui 22.3.0 → 23.1.0

package/src/inline_select.tsx

@@ -1,4 +1,4 @@
-import { useState, type ReactNode } from "react";
+import { useRef, useState, type ReactNode } from "react";
 import { View, StyleSheet } from "react-native";
 import { Icon } from "./icon";
 import { Text } from "./text";
@@ -24,9 +24,14 @@ interface InlineSelectBaseProps<T extends string, D = unknown> {
    *  as-is (e.g. an avatar "add" ghost for an `avatarOnly` member cell). */
   placeholder?: string | ReactNode;
   disabled?: boolean;
-  accessibilityLabel?: string;
-  /** Form field (default) or grid cell — see {@link InlineEditVariant}. */
+  /** How much frame shows at rest — see {@link InlineEditVariant}. Default "framed". */
   variant?: InlineEditVariant;
+  /** Verbs on the field's surface — an `InlineButton` Copy, Open… See
+   *  `InlineEditView.actions`: they sit INSIDE the field, in the same place in
+   *  every mode, and must be passed UNCONDITIONALLY (`disabled` the verb when it
+   *  has nothing to act on) or the field resizes as the value fills. */
+  actions?: ReactNode;
+  accessibilityLabel?: string;
   /** Show an in-menu search box; default false. */
   searchable?: boolean;
   /** Offer a "create" row when the query matches no option — picking it commits the
@@ -67,30 +72,36 @@ function InlineSelectShell(props: {
   display: string | ReactNode;
   placeholder?: string | ReactNode;
   accessibilityLabel?: string;
-  variant?: InlineEditVariant;
   saving: boolean;
   error: string | null;
   children: ReactNode;
+  variant?: InlineEditVariant;
+  actions?: ReactNode;
 }) {
+  // The popover INHERITS THE TRIGGER'S WIDTH, so it has to measure the FIELD —
+  // with verbs on the surface the value region inside it is narrower, and
+  // anchoring there would open a list too small for the row it belongs to.
+  const anchorRef = useRef<View>(null);
   return (
     <View>
-      <Popover open={props.open && !props.disabled} onOpenChange={props.onOpenChange} side="bottom" align="start" inheritTriggerWidth>
+      <Popover open={props.open && !props.disabled} onOpenChange={props.onOpenChange} triggerRef={anchorRef} side="bottom" align="start" inheritTriggerWidth>
         <PopoverTrigger>
           <InlineEditView
+            anchorRef={anchorRef}
+            actions={props.actions}
             variant={props.variant}
             display={props.display}
             placeholder={props.placeholder}
             disabled={props.disabled}
             active={props.open && !props.disabled}
             accessibilityLabel={props.accessibilityLabel}
-            // A `cell` reads value-first: it drops the resting chevron (the column
-            // header + the uniformly-editable grid are the affordance), like the date
-            // cell drops its calendar glyph. A `form` field keeps the chevron. The
-            // saving spinner shows in both.
+            // The resting chevron says "this opens a list" — the same promise on
+            // every surface, now that a field looks the same everywhere. The
+            // saving spinner replaces it while a write is in flight.
             trailing={
               props.saving ? (
                 <ActivityIndicator size={16} color={colors.zinc[400]} />
-              ) : props.variant === "cell" ? undefined : (
+              ) : (
                 <Icon name="chevron-down" size={18} color={colors.zinc[400]} />
               )
             }
@@ -108,7 +119,7 @@ function InlineSelectShell(props: {
 }
 
 export function InlineSelect<T extends string, D = unknown>(props: InlineSelectProps<T, D>) {
-  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, variant, searchable = false, allowCustom = false, customOptionLabel } = props;
+  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, variant, actions } = props;
   const labels = useLoticsLocale().inline;
   const [open, setOpen] = useState(false);
   const [saving, setSaving] = useState(false);
@@ -151,13 +162,14 @@ export function InlineSelect<T extends string, D = unknown>(props: InlineSelectP
     };
     return (
       <InlineSelectShell
+        variant={variant}
+        actions={actions}
         open={open}
         onOpenChange={onOpenChange}
         disabled={disabled}
         display={selected.length > 0 ? <View style={styles.tags}>{selected.map((o) => <View key={o.value}>{chip(o)}</View>)}</View> : ""}
         placeholder={placeholder}
         accessibilityLabel={accessibilityLabel}
-        variant={variant}
         saving={saving}
         error={error}
       >
@@ -196,13 +208,14 @@ export function InlineSelect<T extends string, D = unknown>(props: InlineSelectP
   };
   return (
     <InlineSelectShell
+      variant={variant}
+      actions={actions}
       open={open}
       onOpenChange={setOpen}
       disabled={disabled}
       display={selected ? (renderSelected ? renderSelected(selected) : renderOptionContent ? renderOptionContent(selected) : (selected.label ?? "")) : ""}
       placeholder={placeholder}
       accessibilityLabel={accessibilityLabel}
-      variant={variant}
       saving={saving}
       error={error}
     >

package/src/inline_text_input.tsx

@@ -1,4 +1,4 @@
-import { useCallback } from "react";
+import { useCallback, type ReactNode } from "react";
 import type { NativeSyntheticEvent, TextInputKeyPressEventData } from "react-native";
 import { TextInputField } from "./text_input_field";
 import { type InlineEditVariant, InlineEditFrame, useInlineEdit, type InlineEditControls } from "./inline_edit";
@@ -15,9 +15,22 @@ export interface InlineTextInputProps {
   disabled?: boolean;
   /** Strike + mute the resting value (a completed item that stays editable). */
   struck?: boolean;
-  /** Resting surface — "tint" (default, the zinc-50 chip) or "transparent". */
+  /** How much frame shows at rest — see {@link InlineEditVariant}. Default "framed". */
   variant?: InlineEditVariant;
+  /**
+   * Line budget for a value a reader has to read WHOLE rather than recognise —
+   * a payment term, an address, a clause. Default 1 (the single-line field).
+   * Above 1 the resting value wraps to that many lines AND the editor opens
+   * multiline at the same height, so the row does not reflow on click. Enter
+   * then inserts a newline; the field commits on blur (or the ✓ in "buttons").
+   */
+  numberOfLines?: number;
   accessibilityLabel?: string;
+  /** Verbs on the field's surface — an `InlineButton` Copy on a reference a reader
+   *  quotes elsewhere. See `InlineEditView.actions`: rendered in BOTH modes so the
+   *  field never changes width on focus, and passed UNCONDITIONALLY (`disabled` the
+   *  verb when there is nothing to act on). */
+  actions?: ReactNode;
 }
 
 /**
@@ -27,16 +40,18 @@ export interface InlineTextInputProps {
  * value in a dense record / detail surface.
  */
 export function InlineTextInput(props: InlineTextInputProps) {
-  const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant } = props;
+  const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant, actions, numberOfLines } = props;
+  const multiline = (numberOfLines ?? 1) > 1;
   const edit = useInlineEdit<string>({ value, onSave });
 
   const onKeyPress = useCallback(
     (e: NativeSyntheticEvent<TextInputKeyPressEventData>) => {
       const key = e.nativeEvent.key;
       if (key === "Escape") edit.cancel();
-      else if (key === "Enter") void edit.commit();
+      // On a multiline field Enter is a NEWLINE; the value commits on blur.
+      else if (key === "Enter" && !multiline) void edit.commit();
     },
-    [edit],
+    [edit, multiline],
   );
 
   // Commit on blur (the ergonomic default for moving through a form). In
@@ -49,7 +64,6 @@ export function InlineTextInput(props: InlineTextInputProps) {
 
   return (
     <InlineEditFrame
-      variant={variant}
       editing={edit.editing}
       display={value}
       placeholder={placeholder}
@@ -61,7 +75,10 @@ export function InlineTextInput(props: InlineTextInputProps) {
       error={edit.error}
       disabled={disabled}
       struck={struck}
+      variant={variant}
+      numberOfLines={numberOfLines}
       accessibilityLabel={accessibilityLabel}
+      actions={actions}
     >
       <TextInputField
         value={edit.draft}
@@ -69,8 +86,12 @@ export function InlineTextInput(props: InlineTextInputProps) {
         onBlur={onBlur}
         onKeyPress={onKeyPress}
         autoFocus
+        multiline={multiline}
+        numberOfLines={numberOfLines}
         placeholder={placeholder}
         accessibilityLabel={accessibilityLabel}
+        // With verbs on the field, the FRAME owns the surface and the ring.
+        seamless={actions != null}
       />
     </InlineEditFrame>
   );

package/src/inline_time_picker.tsx

@@ -1,4 +1,4 @@
-import { useCallback, useRef } from "react";
+import { useCallback, useRef, type ReactNode } from "react";
 import { Icon } from "./icon";
 import { colors } from "./colors";
 import { TimePicker } from "./time_picker";
@@ -14,9 +14,14 @@ export interface InlineTimePickerProps {
    *  an explicit ✓ saves and ✕ reverts. */
   controls?: InlineEditControls;
   disabled?: boolean;
-  accessibilityLabel?: string;
-  /** Resting surface — "tint" (default, the zinc-50 chip) or "transparent". */
+  /** How much frame shows at rest — see {@link InlineEditVariant}. Default "framed". */
   variant?: InlineEditVariant;
+  /** Verbs on the field's surface — an `InlineButton` Copy, Open… See
+   *  `InlineEditView.actions`: they sit INSIDE the field, in the same place in
+   *  every mode, and must be passed UNCONDITIONALLY (`disabled` the verb when it
+   *  has nothing to act on) or the field resizes as the value fills. */
+  actions?: ReactNode;
+  accessibilityLabel?: string;
 }
 
 /**
@@ -25,7 +30,7 @@ export interface InlineTimePickerProps {
  * field at the same height, so the form never reflows.
  */
 export function InlineTimePicker(props: InlineTimePickerProps) {
-  const { value, onSave, placeholder, controls = "blur", disabled, accessibilityLabel , variant } = props;
+  const { value, onSave, placeholder, controls = "blur", disabled, accessibilityLabel, variant, actions } = props;
   const edit = useInlineEdit<string>({ value, onSave });
   const dateLabels = useLoticsLocale().datePicker;
   // Segments emit ONLY on a complete "HH:mm", so a half-typed entry (an hour and
@@ -42,6 +47,7 @@ export function InlineTimePicker(props: InlineTimePickerProps) {
   return (
     <InlineEditFrame
       variant={variant}
+      actions={actions}
       editing={edit.editing}
       display={value}
       placeholder={placeholder}

package/src/input_metrics.ts

@@ -0,0 +1,17 @@
+/** Vertical breathing room inside an input, per side. */
+export const INPUT_VERTICAL_PADDING = 8;
+
+/**
+ * The height a MULTI-LINE input occupies, for `numberOfLines` lines of text.
+ *
+ * One formula with two callers on purpose: `TextInputField` sizes the editor
+ * with it, and an inline field's RESTING box reserves the same number. When
+ * each computed its own, the resting box came out 22px shorter and every click
+ * on a payment-term field shoved the rest of the form down the page.
+ *
+ * RN-free so it can be tested directly — the caller supplies the line height,
+ * which is the only platform-dependent part.
+ */
+export function multilineInputHeight(numberOfLines: number, lineHeight: number): number {
+  return numberOfLines * lineHeight + INPUT_VERTICAL_PADDING * 2;
+}

package/src/ledger.tsx

@@ -23,7 +23,7 @@ import { Text } from "./text";
 //       <LedgerRow label="Levy" value={levy} reference={{ label: "INV-0414", onPress }} />
 //     </LedgerGroup>
 //     <LedgerGroup label="Received" total={-received}>
-//       <LedgerRow label="Deposit" meta="03/06 · Cash" value={-1_550_000} tone="success" />
+//       <LedgerRow label="Deposit" meta="03/06, Cash" value={-1_550_000} tone="success" />
 //     </LedgerGroup>
 //     <LedgerTotal label="Outstanding" value={due} tone="danger" zeroLabel="Paid in full" />
 //   </Ledger>
@@ -95,7 +95,7 @@ export function LedgerGroup(props: LedgerGroupProps) {
 export interface LedgerRowProps {
   /** The line's name — what was charged / received. */
   label: string;
-  /** Inline context after the label — a date · method, a basis, a period. */
+  /** Inline context after the label — a date, method, a basis, a period. */
   meta?: string;
   /** The amount. Negative renders "− <abs>" (a receipt). */
   value: number;

package/src/locale.tsx

@@ -65,6 +65,8 @@ export interface LoticsLocale {
   sectionHeading: { info: string };
   /** `Chip`: the ✕ default name when no `dismissTooltip` is given. */
   chip: { remove: string };
+  /** `SequenceItem`: the reorder + drop controls on one position of a `Sequence`. */
+  sequence: { moveUp: string; moveDown: string; remove: string };
   /** `TrendFooter`: the direction words of the trend sentence. */
   trendFooter: { up: string; down: string };
   /** `SuggestionChip`: the press target's default name and the ✕ tooltip. */
@@ -114,12 +116,12 @@ export interface LoticsLocale {
   overlay: { close: string };
   /** `FileDropzone`: the resting main line, the secondary hint, and the
    *  drag-hover line. `hint` is a generic default — apps override the prop with
-   *  an accepted-types line ("… · PDF, ảnh"). */
+   *  an accepted-types line ("…, PDF, ảnh"). */
   fileDropzone: { label: string; hint: string; drop: string };
   /** `FileThumbnail`'s `RemoveButton`: the ✕ a11y name. */
   fileThumbnail: { remove: string };
-  /** `FilesEditor`'s shipped bar pieces (upload · select · select-all · download
-   *  · remove) and the remove confirm. A HOST verb is a plain `Button` and names
+  /** `FilesEditor`'s shipped bar pieces (upload, select, select-all, download,
+   *  remove) and the remove confirm. A HOST verb is a plain `Button` and names
    *  itself, so nothing here is about what an app happens to do with a file. */
   filesEditor: {
     upload: string;
@@ -222,6 +224,7 @@ export const en: LoticsLocale = {
   ledger: { rowDetails: (label) => `${label} details` },
   sectionHeading: { info: "About this data" },
   chip: { remove: "Remove" },
+  sequence: { moveUp: "Move up", moveDown: "Move down", remove: "Remove" },
   trendFooter: { up: "Up", down: "Down" },
   suggestionChip: { add: (label) => `Add: ${label}`, dismiss: "Dismiss suggestion" },
   confidence: { high: "High confidence", medium: "Medium confidence", low: "Low confidence" },
@@ -373,6 +376,7 @@ export const vi: LoticsLocale = {
   ledger: { rowDetails: (label) => `Chi tiết ${label}` },
   sectionHeading: { info: "Giải thích dữ liệu" },
   chip: { remove: "Xóa" },
+  sequence: { moveUp: "Lên trên", moveDown: "Xuống dưới", remove: "Xóa" },
   trendFooter: { up: "Tăng", down: "Giảm" },
   suggestionChip: { add: (label) => `Thêm: ${label}`, dismiss: "Bỏ gợi ý" },
   confidence: { high: "Độ tin cậy cao", medium: "Độ tin cậy trung bình", low: "Độ tin cậy thấp" },

package/src/matrix.tsx

@@ -203,7 +203,7 @@ function MatrixCell({ ctx, display, row, col, value }: MatrixCellProps) {
 
   const isSelected = selected?.row === row.key && selected?.col === col.key;
   const pressable = !!onSelectCell && value > 0;
-  const label = `${row.label} · ${col.label}: ${formatValue(value)}`;
+  const label = `${row.label}, ${col.label}: ${formatValue(value)}`;
 
   const content = showNumber ? (
     <Text size="sm" weight="medium" tabular align="center" color={value === 0 ? "zinc-500" : "default"}>

package/src/number_input.tsx

@@ -18,6 +18,17 @@ export interface NumberInputProps {
   disabled?: boolean;
   testID?: string;
   accessibilityLabel?: string;
+  /** The HOST paints the surface — drop this input's own border, fill, focus ring
+   *  AND horizontal padding, so the page draws one box and the text lands on the
+   *  host's inset rather than 8px further in. Set by an inline editor whose field
+   *  carries `actions`: the field's shell owns the surface (so the verbs never
+   *  move between modes) and owns the ring with it.
+   *
+   *  HEIGHT and VERTICAL padding stay — those are what keep the field the same
+   *  size in both modes; the horizontal inset is what has to be surrendered,
+   *  because the host already spent `CONTROL_TEXT_INSET` on it and two insets
+   *  stacked is a visible jump to the right on focus. */
+  seamless?: boolean;
 }
 
 /**
@@ -26,7 +37,7 @@ export interface NumberInputProps {
  * number in place on a record use `InlineNumberInput`.
  */
 export function NumberInput(props: NumberInputProps) {
-  const { value, onValueChange, min, max, disabled, onBlur, onKeyDown, autoFocus, testID, accessibilityLabel } = props;
+  const { value, onValueChange, min, max, disabled, onBlur, onKeyDown, autoFocus, testID, accessibilityLabel, seamless } = props;
   const binding = useFormField();
   const describedBy = [binding?.descriptionId, binding?.warningId, binding?.errorId].filter(Boolean).join(" ") || undefined;
   const { focusVisible, focusProps } = useFocusRing({ always: true });
@@ -55,17 +66,17 @@ export function NumberInput(props: NumberInputProps) {
       autoFocus={autoFocus}
       style={{
         height: 40,
-        paddingLeft: 8,
-        paddingRight: 8,
+        paddingLeft: seamless ? 0 : 8,
+        paddingRight: seamless ? 0 : 8,
         borderRadius: CONTROL_RADIUS,
-        borderWidth: 1,
+        borderWidth: seamless ? 0 : 1,
         borderStyle: "solid",
-        borderColor: hovered && !disabled ? HOVER_BORDER : colors.border,
-        backgroundColor: colors.background,
+        borderColor: seamless ? "transparent" : hovered && !disabled ? HOVER_BORDER : colors.border,
+        backgroundColor: seamless ? "transparent" : colors.background,
         fontFamily: fontFamilyRegular,
         ...inputTextStyleWeb,
         letterSpacing: -0.4,
-        boxShadow: focusVisible ? FOCUS_RING : "none",
+        boxShadow: !seamless && focusVisible ? FOCUS_RING : "none",
         outline: "none",
         boxSizing: "border-box",
         transition: "border-color 0.12s, box-shadow 0.12s",

package/src/pipeline.tsx

@@ -45,7 +45,7 @@ export interface PipelineProps {
  *   <PipelineStage status="done" title="Submitted">
  *     <PipelineField label="Date"><InlineDatePicker … /></PipelineField>
  *   </PipelineStage>
- *   <PipelineStage status="current" title="In review" meta="Waiting 3d · Ops">
+ *   <PipelineStage status="current" title="In review" meta="Waiting 3d, Ops">
  *     <PipelineNote tone="warning">Sent back — missing payslips.</PipelineNote>
  *     <PipelineActions>
  *       <Button title="Approve" color="primary" />

package/src/popover.tsx

@@ -656,7 +656,7 @@ export function PopoverContent(props: PopoverContentProps) {
           // the field.
           //
           // Floored at MIN_CONTROL_WIDTH so a genuinely narrow trigger — a
-          // `variant="cell"` select in a dense grid column — still opens a list
+          // a select in a dense grid column — still opens a list
           // wide enough to read, rather than inheriting a width nothing fits in.
           ...(inheritTriggerWidth &&
             !small &&

package/src/press_door.tsx

@@ -42,7 +42,7 @@ export interface PressDoorProps {
  * Wrap the content in the pressable itself (`PressableHighlight`, `FileRow`'s door) ONLY
  * when that content is non-interactive by construction.
  *
- * `TableRow` and `LinkedRecordBox` are the in-kit consumers.
+ * `TableRow` is the in-kit consumer.
  */
 export function PressDoor({ onPress, accessibilityLabel, radius = 10 }: PressDoorProps) {
   const { focusVisible, focusProps } = useFocusRing();

package/src/pressable_highlight.tsx

@@ -76,7 +76,7 @@ export interface PressableHighlightProps extends PressableProps {
  * checkbox, a `Link`) must not be built on it: a button cannot contain interactive
  * descendants. Compose the role-less `PressableRow` + a `PressDoor` sibling instead —
  * the surface takes the mouse, the door takes the keyboard, the controls stay their own
- * tab stops (`TableRow` and `LinkedRecordBox` are the references).
+ * tab stops (`TableRow` is the reference).
  */
 export function PressableHighlight(props: PressableHighlightProps) {
   const {

package/src/progress_bar.tsx

@@ -13,7 +13,7 @@ export interface ProgressBarProps {
    * it. */
   title?: string;
   /** Caption above-right of the bar: `percentage` → "50%", `fraction` →
-   * "1,250 / 2,500 · 50%" (separators follow the reader's locale). Reports the
+   * "1,250 / 2,500 (50%)" (separators follow the reader's locale). Reports the
    * TRUE ratio — over `max` it reads "105%" while the track stays clamped. */
   format?: ProgressBarFormat;
   /**
@@ -58,7 +58,7 @@ export function ProgressBar(props: ProgressBarProps) {
   const localeTag = useLocaleTag();
   /**
    * The TRACK clamps — a fill wider than its own track is meaningless. The CAPTION does not: a
-   * meter reading `2.100 / 2.000 · 100%` asserts a number that is false, and a reader scanning
+   * meter reading `2.100 / 2.000 (100%)` asserts a number that is false, and a reader scanning
    * percentages sees "exactly at the limit" when they are over it. Progress-toward-completion
    * never exceeds its max, so this only diverges for the over-allowance case, where the true
    * figure is the whole point.
@@ -87,7 +87,7 @@ export function ProgressBar(props: ProgressBarProps) {
 
   const caption =
     format === "fraction"
-      ? `${num(value)} / ${num(max)} · ${Math.round(ratio)}%`
+      ? `${num(value)} / ${num(max)} (${Math.round(ratio)}%)`
       : format === "percentage"
         ? `${Math.round(ratio)}%`
         : null;

package/src/record_summary.tsx

@@ -20,7 +20,7 @@ export interface RecordSummaryProps {
    *  the record page's one h1; pass 2 when the band sits inside a surface
    *  that already owns the h1 (a drawer with its own titled header). */
   level?: 1 | 2 | 3;
-  /** Identity qualifiers on the title line ("HCM → Hamburg · Export · FCL") —
+  /** Identity qualifiers on the title line ("HCM → Hamburg, Export, FCL") —
    *  sm muted; wraps under the title when narrow. */
   subtitle?: string;
   /** A status chip (a `Badge`) or any small node right after the title. */
@@ -32,7 +32,7 @@ export interface RecordSummaryProps {
 
 /**
  * The identity band of a single record's detail screen or drawer: ONE row —
- * title · subtitle · status chip, with an optional headline metric pinned
+ * title, subtitle, status chip, with an optional headline metric pinned
  * right. It exists to stop hand-rolled record headers drifting: mixed type
  * scales, several competing figures, color noise.
  *

package/src/result_header.tsx

@@ -10,8 +10,8 @@ import { Text, type HeadingLevel } from "./text";
  * ALREADY CREATED. The receipt states the outcome and routes — it never edits
  * (correction happens through the record's ordinary verbs, on the record):
  *
- * - ONE record → `ResultHeader` (tone mark inline on the title row · outcome
- *   title · failure reason line) + a handful of spread `DetailRow` receipt
+ * - ONE record → `ResultHeader` (tone mark inline on the title row, outcome
+ *   title, failure reason line) + a handful of spread `DetailRow` receipt
  *   lines (the identifying figures, not the field wall) + a `Confidence`
  *   callout naming exactly which values failed their deterministic checks.
  * - SEVERAL records → an attention-first `ListItem` register whose rows press

package/src/sequence.tsx

@@ -0,0 +1,170 @@
+import { Children, createContext, isValidElement, useContext, type ReactNode } from "react";
+import { StyleSheet, View } from "react-native";
+import { colors } from "./colors";
+import { IconButton } from "./icon_button";
+import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+import { useLoticsLocale } from "./locale";
+import { Text } from "./text";
+
+interface SequencePosition {
+  index: number;
+  count: number;
+}
+
+const SequenceItemContext = createContext<SequencePosition | null>(null);
+
+/** Half the control band, less the dot's own radius — puts the dot on the SAME
+ *  line as the first control in the item, not at the item's vertical centre (an
+ *  item that wraps to two lines must not drag its marker down). */
+const RAIL_LEAD = Math.round(INLINE_CONTROL_HEIGHT / 2) - 4;
+const RAIL_WIDTH = 12;
+/** The rail column plus its gap — what content must be indented by to line up
+ *  under the items (an "Add" link, a caption). Exported so a caller never
+ *  hand-picks a number that drifts from the rail. */
+export const SEQUENCE_INSET = RAIL_WIDTH + 10;
+
+export interface SequenceProps {
+  /** `SequenceItem`s, in order. Order IS the data — render them from your list. */
+  children: ReactNode;
+}
+
+/**
+ * An ORDERED list whose order is part of the data — a route's stops, an
+ * approval chain, a set of legs — rendered as a connected rail so the sequence
+ * reads without a single label saying "first" or "then".
+ *
+ * Reach for it when a thing has a variable number of POSITIONS. The alternative
+ * — one field per position (`Origin`, `Transfer point`, `Destination`) — cannot
+ * hold a second middle entry and cannot say that the entries are ordered; three
+ * identical field rows say nothing about which comes first.
+ *
+ * It is NOT a `Timeline` (an activity FEED: who changed what, when), NOT a
+ * `Stepper` (fixed named positions of a wizard), and NOT a `Pipeline` (ONE
+ * record walking stages that each own their controls). This is a list the user
+ * EDITS: add, remove, reorder.
+ *
+ * Each item supplies its own content — the kit draws the rail, the position
+ * affordances and the spacing:
+ *
+ *   <Sequence>
+ *     {stops.map((s, i) => (
+ *       <SequenceItem key={s.id} role={roleFor(i)} onMoveUp={…} onMoveDown={…} onRemove={…}>
+ *         <InlineTextInput … />
+ *       </SequenceItem>
+ *     ))}
+ *   </Sequence>
+ */
+export function Sequence({ children }: SequenceProps) {
+  const items = Children.toArray(children).filter(isValidElement);
+  return (
+    // NO gap: the rail is continuous, so each item's trailing segment has to
+    // meet the next item's leading one. Item spacing is the item's own padding,
+    // which the rail runs through.
+    <View>
+      {items.map((child, index) => (
+        <SequenceItemContext.Provider key={index} value={{ index, count: items.length }}>
+          {child}
+        </SequenceItemContext.Provider>
+      ))}
+    </View>
+  );
+}
+
+export interface SequenceItemProps {
+  /** What this position IS, derived by the caller from its index (`Origin`,
+   *  `Via`, `Destination`). Derive it, never store it — a stored role lies the
+   *  moment the list is reordered. */
+  role?: string;
+  /** The item's editors / content. */
+  children: ReactNode;
+  /** Swap with the item above. Omit (or leave undefined on the first item) and
+   *  the control renders disabled, so the column never changes width. */
+  onMoveUp?: () => void;
+  onMoveDown?: () => void;
+  onRemove?: () => void;
+  /** Names the item in the reorder/remove controls' announcements — "Remove
+   *  Antwerp" rather than three identical "Remove" buttons. */
+  accessibilityName?: string;
+  /** Width of the role column. Default 74. */
+  roleWidth?: number;
+}
+
+/**
+ * One position in a {@link Sequence} — its marker, its role, its content, and
+ * the controls that move or drop it.
+ *
+ * The reorder affordance is a pair of BUTTONS, not a drag handle: dragging is
+ * invisible to the keyboard, unreachable on a screen reader, and fiddly on a
+ * phone, and a list of three-to-six positions does not need the expressiveness.
+ * They render even where they cannot act (first item, last item) so the row's
+ * right edge never shifts between items.
+ */
+export function SequenceItem(props: SequenceItemProps) {
+  const { role, children, onMoveUp, onMoveDown, onRemove, accessibilityName, roleWidth = 74 } = props;
+  const pos = useContext(SequenceItemContext);
+  const labels = useLoticsLocale().sequence;
+  const first = pos == null || pos.index === 0;
+  const last = pos == null || pos.index === pos.count - 1;
+  const named = (verb: string) => (accessibilityName ? `${verb} ${accessibilityName}` : verb);
+  return (
+    <View style={styles.item}>
+      {/* THE RAIL — a leading segment, the dot on the control line, then a
+          trailing segment that fills whatever height the content takes. The end
+          segments are transparent rather than absent so every item keeps the
+          same geometry and the dots stay on one x. */}
+      <View style={styles.rail}>
+        <View style={[styles.segment, { height: RAIL_LEAD }, first && styles.segmentHidden]} />
+        <View style={styles.dot} />
+        <View style={[styles.segment, styles.segmentFill, last && styles.segmentHidden]} />
+      </View>
+      <View style={styles.body}>
+        {role != null ? (
+          <View style={{ width: roleWidth }}>
+            <Text size="xs" color="muted">
+              {role}
+            </Text>
+          </View>
+        ) : null}
+        <View style={styles.content}>{children}</View>
+        <View style={styles.controls}>
+          <IconButton
+            icon="chevron-up"
+            tooltip={labels.moveUp}
+            accessibilityLabel={named(labels.moveUp)}
+            disabled={first || onMoveUp == null}
+            onPress={() => onMoveUp?.()}
+          />
+          <IconButton
+            icon="chevron-down"
+            tooltip={labels.moveDown}
+            accessibilityLabel={named(labels.moveDown)}
+            disabled={last || onMoveDown == null}
+            onPress={() => onMoveDown?.()}
+          />
+          <IconButton
+            icon="x"
+            tooltip={labels.remove}
+            accessibilityLabel={named(labels.remove)}
+            disabled={onRemove == null}
+            onPress={() => onRemove?.()}
+          />
+        </View>
+      </View>
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  item: { flexDirection: "row", alignItems: "stretch", gap: 10 },
+  rail: { width: RAIL_WIDTH, alignItems: "center" },
+  segment: { width: 1, backgroundColor: colors.zinc[300] },
+  // Fills the rest of the item, INCLUDING its bottom padding, so the line
+  // arrives at the next item's leading segment with nothing between them.
+  segmentFill: { flex: 1 },
+  segmentHidden: { backgroundColor: "transparent" },
+  dot: { width: 7, height: 7, borderRadius: 999, backgroundColor: colors.zinc[400] },
+  // The item's own spacing — a gap on the parent would break the rail.
+  body: { flex: 1, minWidth: 0, flexDirection: "row", alignItems: "center", flexWrap: "wrap", columnGap: 8, rowGap: 4, paddingBottom: 6 },
+  content: { flexGrow: 1, flexBasis: 200, minWidth: 0, flexDirection: "row", alignItems: "center", flexWrap: "wrap", columnGap: 8, rowGap: 4 },
+  controls: { flexDirection: "row", alignItems: "center", gap: 2 },
+});