@lotics/ui 27.12.0 → 27.13.1

package/docs/catalog.md

@@ -755,7 +755,10 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   just text. **`InlineSelect` is single OR multi** — pass `multi` for a tag SET (`value: T[]`,
   commits the new set on popover-CLOSE; selected tags render as badges via `renderSelected`),
   mirroring `Select`'s `multi` axis; there is NO separate tag component. Both modes take
-  `allowCustom` (a create-a-tag/option row) + `searchable`, plus **`autoFocus`** to open the list
+  `allowCustom` (a create-a-tag/option row) + `searchable` + **`customOptionPlacement`** (default
+  `"bottom"`, right for a tag field; pass `"top"` for a find-or-create REFERENCE picker over a long
+  registry, so the create row stays visible while the keyboard highlight stays on the first MATCH —
+  Enter on a partial query then attaches instead of duplicating), plus **`autoFocus`** to open the list
   on mount — for the picker a `ReferenceField`'s `Change` just dropped the reader into, so the
   correction stays one gesture; leave it off for a field that is merely empty, since stealing the
   list open on load is a different act. **`InlineMemberSelect` takes `avatarOnly`**

package/docs/composition.md

@@ -494,7 +494,7 @@ All view controls are 40px tall (`CONTROL_HEIGHT`), `sm` labels, in ONE wrapping
   (colored `Text`), not the buttons.
 - **Create buttons carry NO `+` icon** — "Add fee", not "+ Add fee". A create is `primary` and
   rides its section's HEADING row at the right edge — see § The add-placement law for why, and
-  for the one-verb-one-weight rule that keeps it primary in the `EmptyState` too. (The
+  for the one-verb-one-weight rule that keeps it `primary` wherever it renders. (The
   icon-only `+` `IconButton` — a composer's attach — is a different thing and keeps its glyph.)
 
 ## The action-gating law — disabled + the reason as a co-located Callout
@@ -600,11 +600,13 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
 
   The ADD is the one verb this law does NOT place next to its effect, and the add-placement law
   says why: a position that never moves beats a position that is adjacent, because "below the
-  last row" is a different place on every list and no place at all on an empty one.
-  **An add is `primary`, in the `EmptyState` too.** It is the act its section offers, so it
-  carries that section's weight; a lone `secondary` button reads as though the real action were
-  somewhere else. The rule that matters is that ONE VERB KEEPS ONE WEIGHT — the same add must
-  not be primary on an empty list and secondary on a full one.
+  last row" is a different place on every list and no place at all on an empty one. The heading
+  row therefore carries identity + meta + view controls + the section's ADD, and no other content
+  verb. **An add is `primary` wherever it renders** — on that heading row, or inside an
+  `EmptyState` in the one case § Empty states allows, where there is no heading to carry it. It
+  is the act its section offers, so it carries that section's weight; a lone `secondary` button
+  reads as though the real action were somewhere else. The rule that matters is that ONE VERB
+  KEEPS ONE WEIGHT — the same add must not be primary on an empty list and secondary on a full one.
   A record surface therefore carries several primaries, one per section, and that is correct:
   "one primary per SCREEN" governs the page BAND, not a stack of independent sections each with
   its own single act. The cost is real and worth knowing — the more sections offer an act, the
@@ -683,7 +685,13 @@ gate's SCOPE, once** — never prose beside the button, never revealed only on p
   line** that carries the type + identifying fact as TEXT (`type, code, city`) — COMMA-joined, never
   a middot (see Microcopy), and free to wrap the row taller. A type/attribute is **NOT a status, so it is text, never a `Badge`** (see
   Badge discipline below). (The kit suppresses `renderOptionContent` on the `allowCustom` "Create …" row so it keeps its plain + look.)
-  Plus `allowCustom` + `customOptionPlacement:"top"` + `customOptionLabel={q => 'Create "…"'}`. In
+  Plus `allowCustom` + `customOptionPlacement:"top"` + `customOptionLabel={q => 'Create "…"'}` —
+  the same three on `InlineSelect` where the reference sits in an inline-editor grid rather than a
+  form. **The create row names the ENTITY, not the role** (`Create new customer "…"` on a carrier
+  row, when one registry serves all the party roles): a per-role noun claims a registry per role,
+  which is a data model the screen does not have. The role is named by the PLACEHOLDER, and derive
+  that placeholder from the same noun the row is labelled by — passing the two separately is how a
+  row ends up promising "Find or create" over a picker that can only find. In
   `onValueChange`, an existing pick attaches; the custom row opens a create **`Dialog` prefilled with
   the typed query** (mint the record + link it) — so a party absent from the registry is created
   WITHOUT leaving the record. `customOptionPlacement:"top"` keeps the create row visible while the

package/docs/templates.md

@@ -53,6 +53,22 @@ the package index is [../AGENTS.md](../AGENTS.md).
 | AI ranks answers — look-up-and-explain | `tpl_lookup` |
 | AI over a record's documents (extract / cross-check / generate) | `tpl_record` — its Documents + Document set sections |
 
+### Register + drawer, or a navigated page?
+
+The register is the DEFAULT, and its row press opens the workspace `Drawer`. A record earns
+its own navigated route only when one of these holds:
+
+- **It is a destination.** Someone arrives cold from outside the register — a link in an
+  email, a notification, a handoff from another desk — and must land on the record without
+  the list to open it from.
+- **The work needs the canvas.** A docked comments gutter, a document read beside the fields,
+  an outline rail worth navigating — width the drawer's single column cannot give.
+
+The volume of DATA is not the test. A record with forty fields still closes in the drawer if
+the operator opens it from the list, works it, and goes back to the list. What an app without
+a destination skips is the ROUTE, never the template: the drawer renders `tpl_record` either
+way, so "no record page" must never become a hand-built detail surface.
+
 ## Composition rules — how a record surface is assembled
 
 Laws for any screen where a record's data is edited and a primary action produces its output
@@ -268,7 +284,10 @@ billing, and quick-capture templates. Top → bottom:
   ATTENTION state as a co-located `Callout` (e.g. overdue — record-scoped state reads here;
   field-scoped state stays on its field), then a quiet `SummaryLine` (desk, documents
  , to collect).
-- **GENERAL — the MAIN details, FIRST in the rail**; every later section is supplementary.
+- **GENERAL — the MAIN details, first in THIS record's rail** because its work starts at the
+  details; rule 1 orders sections by work flow, so a surface whose work starts at a DOCUMENT
+  (an invoice desk, a claims desk) leads with Documents and General follows. Every later
+  section is supplementary.
   A `SubsectionStack` (space-only beat) of a headingless LEAD group (the key facts) plus
   named groups (e.g. Order / Fulfilment / System — system identifiers get a HOME, not a
   per-row badge). Every group's `DetailTable` repeats the same `labelWidth` so the grid

package/examples/tpl_record.tsx

@@ -779,14 +779,53 @@ function RouteStops({ stops, onChange }: { stops: Stop[]; onChange: (next: Stop[
   );
 }
 
+/** The reference picker's option row, for EVERY picker over the customer registry
+ *  — the Customer row and the three party rows. A glyph tile beside the name over
+ *  a COMMA-joined muted metadata line (the identifying facts as TEXT: a type or
+ *  attribute is not a status, so it is never a `Badge`).
+ *
+ *  It is shared rather than written per row precisely because four pickers over
+ *  ONE registry drifting into four looks is how this surface decayed the first
+ *  time: three of them rendered a wall of bare names while the fourth carried the
+ *  city and tax ID a reader needs to tell two similarly-named companies apart. */
+function customerOptionRow(o: PickerOption<string, Customer>) {
+  return (
+    <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
+      <View style={{ width: 28, height: 28, borderRadius: 7, backgroundColor: colors.zinc[100], alignItems: "center", justifyContent: "center" }}>
+        <Icon name="building-2" size={14} color={colors.zinc[600]} />
+      </View>
+      <View style={{ flex: 1, minWidth: 0 }}>
+        <Text size="sm" numberOfLines={1}>{o.label}</Text>
+        {o.data ? <Text size="xs" color="muted">{[o.data.city, o.data.taxId ? `Tax ID ${o.data.taxId}` : "No tax ID"].filter(Boolean).join(", ")}</Text> : null}
+      </View>
+    </View>
+  );
+}
+
+/** The create row names the ENTITY, never the role the field fills it for: one
+ *  registry holds all four, so "Create new customer" on the carrier row says the
+ *  true thing — a customer record, attached here as the carrier. A per-role noun
+ *  would imply four registries and four kinds of record, which is the data model
+ *  the screen deliberately does not have. The ROLE is named by the field's own
+ *  placeholder, where it belongs. */
+const createCustomerLabel = (query: string) => `Create new customer “${query}”`;
+const NO_CUSTOMER_MATCH = "No customer matches — type a name to create one";
+
+/** Which party row a pick or a create is destined for. */
+type PartyTarget = "customer" | "shipTo" | "notify" | "carrier";
+
 /** A party ROW — a reference when one is attached, the find-or-create picker when
  *  not. The two states share the row so the field never moves; the picker is the
  *  field's EMPTY state, not a different kind of surface. */
-function PartyRow({ role, rec, options, placeholder, onPick, onOpen, onUnset, onSaveFacts }: {
+function PartyRow({ role, noun, rec, options, onPick, onOpen, onUnset, onSaveFacts }: {
   role: string;
+  /** The ROLE this field fills, for its placeholder — "consignee", "carrier".
+   *  The placeholder is derived from it rather than passed alongside it: the two
+   *  were separate props once, and the row ended up promising "Find or create"
+   *  over a picker that could only find. */
+  noun: string;
   rec: Customer | null;
   options: PickerOption<string, Customer>[];
-  placeholder: string;
   onPick: (opt: PickerOption<string, Customer>) => void;
   onOpen: () => void;
   onUnset: () => void;
@@ -825,10 +864,14 @@ function PartyRow({ role, rec, options, placeholder, onPick, onOpen, onUnset, on
           options={options}
           autoFocus={changing}
           onValueChange={(o) => { setChanging(false); onPick(o); }}
+          renderOptionContent={customerOptionRow}
           reflectSelection={false}
+          allowCustom
+          customOptionPlacement="top"
+          customOptionLabel={createCustomerLabel}
         >
-          <ComboboxInput icon="search" placeholder={placeholder} accessibilityLabel={role} />
-          <ComboboxContent emptyText="No match" />
+          <ComboboxInput icon="search" placeholder={`Find or create a ${noun}`} accessibilityLabel={role} />
+          <ComboboxContent emptyText={NO_CUSTOMER_MATCH} />
         </Combobox>
       )}
     </DetailRow>
@@ -987,7 +1030,13 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
   // ── customer section — TWO states: attached (read-only card, Remove
   // detaches) or empty (the find-or-create search). The "create" branch opens
   // a focused Dialog; non-null draft = the dialog is open.
-  const [custDraft, setCustDraft] = useState<{ name: string; taxId: string; contact: string; city: string } | null>(null);
+  //
+  // `target` is the row that opened it. All four party rows attach a record from
+  // the SAME registry, so they share one dialog rather than each carrying a copy
+  // — and the draft names its destination as DATA instead of the dialog holding a
+  // callback, so what is in flight stays inspectable and the commit stays one
+  // function.
+  const [custDraft, setCustDraft] = useState<{ target: PartyTarget; name: string; taxId: string; contact: string; city: string } | null>(null);
   // The Fetch button's in-flight state (the registry lookup).
   const [fetching, setFetching] = useState(false);
 
@@ -1303,14 +1352,24 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
     data: c,
   }));
 
-  // Find-or-create resolution: an existing pick attaches; the custom row opens
-  // the create Dialog, prefilled with the query.
-  const onPickCustomer = (opt: PickerOption<string, Customer>) => {
+  // Where each party row's attach lands. One map, so a row added later cannot
+  // acquire a create path and quietly forget to wire its attach.
+  const attachParty: Record<PartyTarget, (id: string | null) => void> = {
+    customer: setCustomerId,
+    shipTo: setShipTo,
+    notify: setNotify,
+    carrier: setCarrier,
+  };
+
+  // Find-or-create resolution, shared by all four party rows: an existing pick
+  // attaches; the custom row opens the create Dialog, prefilled with the query
+  // and carrying the row that asked for it.
+  const onPickParty = (target: PartyTarget) => (opt: PickerOption<string, Customer>) => {
     if (customers.some((c) => c.id === opt.value)) {
-      setCustomerId(opt.value);
+      attachParty[target](opt.value);
       return;
     }
-    setCustDraft({ name: opt.value, taxId: "", contact: "", city: "" });
+    setCustDraft({ target, name: opt.value, taxId: "", contact: "", city: "" });
   };
 
   const taxIdError =
@@ -1331,7 +1390,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
       since: "",
     };
     setCustomers((prev) => [...prev, c]);
-    setCustomerId(c.id);
+    attachParty[custDraft.target](c.id);
     setCustDraft(null);
   };
 
@@ -1401,10 +1460,6 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
     Alert.alert("Receipt", `Printing receipt for ${formatMoney(grandTotal)}.`, [{ text: "OK" }]);
   };
 
-  // Where the record SITS — the one index the pipeline reads off, and the act
-  // that leaves that desk. A closed record is past the last desk, so no stage
-  // is current and no gate is offered.
-  const deskIndex = stage === "closed" ? DESKS.length : DESKS.findIndex((x) => x.key === stage);
   // `handoff` separates the two acts that LOOK alike, as a DISCRIMINATED union
   // so the difference is in the type and not just a runtime branch: handing off
   // has a receiving DESK (it asks whom, then stamps that desk), closing has no
@@ -1871,25 +1926,15 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
                          drops you into is already focused and open, and the
                          correction stays one gesture. */
                       autoFocus={changingCustomer}
-                      onValueChange={(o) => { setChangingCustomer(false); onPickCustomer(o); }}
-                      renderOptionContent={(o) => (
-                        <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
-                          <View style={{ width: 28, height: 28, borderRadius: 7, backgroundColor: colors.zinc[100], alignItems: "center", justifyContent: "center" }}>
-                            <Icon name="building-2" size={14} color={colors.zinc[600]} />
-                          </View>
-                          <View style={{ flex: 1, minWidth: 0 }}>
-                            <Text size="sm" numberOfLines={1}>{o.label}</Text>
-                            {o.data ? <Text size="xs" color="muted">{[o.data.city, o.data.taxId ? `Tax ID ${o.data.taxId}` : "No tax ID"].filter(Boolean).join(", ")}</Text> : null}
-                          </View>
-                        </View>
-                      )}
+                      onValueChange={(o) => { setChangingCustomer(false); onPickParty("customer")(o); }}
+                      renderOptionContent={customerOptionRow}
                       reflectSelection={false}
                       allowCustom
                       customOptionPlacement="top"
-                      customOptionLabel={(q) => `Create new customer “${q}”`}
+                      customOptionLabel={createCustomerLabel}
                     >
                       <ComboboxInput icon="search" placeholder="Search customers by name…" accessibilityLabel="Attach customer" />
-                      <ComboboxContent emptyText="No customer matches — type a name to create one" />
+                      <ComboboxContent emptyText={NO_CUSTOMER_MATCH} />
                     </Combobox>
                   )}
                 </DetailRow>
@@ -2208,14 +2253,12 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
               <SubsectionHeading><SubsectionHeadingTitle>Consignment &amp; terms</SubsectionHeadingTitle></SubsectionHeading>
               <DetailTable labelWidth={150} minHeight={40}>
                 <PartyRow
-                  role="Ship to" rec={shipToRec} options={customerOptions}
-                  placeholder="Find or create a consignee"
-                  onPick={(o) => setShipTo(o.value)} onOpen={() => {}} onUnset={() => setShipTo(null)} onSaveFacts={saveCustomerFacts}
+                  role="Ship to" noun="consignee" rec={shipToRec} options={customerOptions}
+                  onPick={onPickParty("shipTo")} onOpen={() => {}} onUnset={() => setShipTo(null)} onSaveFacts={saveCustomerFacts}
                 />
                 <PartyRow
-                  role="Notify" rec={notifyRec} options={customerOptions}
-                  placeholder="Find or create a notify party"
-                  onPick={(o) => setNotify(o.value)} onOpen={() => {}} onUnset={() => setNotify(null)} onSaveFacts={saveCustomerFacts}
+                  role="Notify" noun="notify party" rec={notifyRec} options={customerOptions}
+                  onPick={onPickParty("notify")} onOpen={() => {}} onUnset={() => setNotify(null)} onSaveFacts={saveCustomerFacts}
                 />
                 {/* A CHOICE IS ONE ROW, like every other field.
                     `RadioPicker` renders three full-width bordered choices with
@@ -2314,9 +2357,8 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418" }: { chrome?:
               ) : null}
               <DetailTable labelWidth={150} minHeight={40}>
                 <PartyRow
-                  role="Carrier" rec={carrierRec} options={customerOptions}
-                  placeholder="Find or create a carrier"
-                  onPick={(o) => setCarrier(o.value)} onOpen={() => {}} onUnset={() => setCarrier(null)} onSaveFacts={saveCustomerFacts}
+                  role="Carrier" noun="carrier" rec={carrierRec} options={customerOptions}
+                  onPick={onPickParty("carrier")} onOpen={() => {}} onUnset={() => setCarrier(null)} onSaveFacts={saveCustomerFacts}
                 />
                 <DetailRow label="Booking no.">
                   <InlineTextInput value={booking} onSave={persist(setBooking)} placeholder="Add booking number…" accessibilityLabel="Booking number" />

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "27.12.0",
+  "version": "27.13.1",
   "type": "module",
   "exports": {
     "./vite": {

package/src/inline_select.tsx

@@ -49,6 +49,12 @@ interface InlineSelectBaseProps<T extends string, D = unknown> {
   allowCustom?: boolean;
   /** Label for the create row (default: `Add "<query>"`). */
   customOptionLabel?: (query: string) => string | null;
+  /** Where the create row sits — default "bottom", which is right for a tag field
+   *  whose list is short and whose create row is the ordinary outcome. Pass "top"
+   *  for a find-or-create REFERENCE picker over a long registry: the create row
+   *  stays visible without scrolling while the keyboard highlight stays on the
+   *  first MATCH, so Enter on a partial query attaches rather than duplicating. */
+  customOptionPlacement?: "top" | "bottom";
 }
 
 /**
@@ -129,7 +135,7 @@ function InlineSelectShell(props: {
 }
 
 export function InlineSelect<T extends string, D = unknown>(props: InlineSelectProps<T, D>) {
-  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, variant, actions, autoFocus = false } = props;
+  const { options, renderOptionContent, renderSelected, placeholder, disabled, accessibilityLabel, searchable = false, allowCustom = false, customOptionLabel, customOptionPlacement, variant, actions, autoFocus = false } = props;
   const labels = useLoticsLocale().inline;
   const [open, setOpen] = useState(autoFocus);
   const [saving, setSaving] = useState(false);
@@ -192,6 +198,7 @@ export function InlineSelect<T extends string, D = unknown>(props: InlineSelectP
           onRequestClose={() => onOpenChange(false)}
           allowCustom={allowCustom}
           customOptionLabel={customOptionLabel}
+          customOptionPlacement={customOptionPlacement}
           onCustomCommit={(raw) => {
             const created = raw.trim() as T;
             if (created && !draft.includes(created)) setDraft([...draft, created]);
@@ -238,6 +245,7 @@ export function InlineSelect<T extends string, D = unknown>(props: InlineSelectP
         onRequestClose={() => setOpen(false)}
         allowCustom={allowCustom}
         customOptionLabel={customOptionLabel}
+        customOptionPlacement={customOptionPlacement}
         onCustomCommit={(raw) => {
           const created = raw.trim() as T;
           if (created) pick(created);