@lotics/ui 4.0.0 → 4.1.0

package/AGENTS.md

@@ -25,7 +25,8 @@ Pick by capability, not by name. (→ the source file for the API.)
 - **Actions** — `Button` (labelled; `color` = emphasis/risk, `shape` pill|rounded),
   `IconButton` (icon-only, needs `accessibilityLabel`/`tooltip`), `LinkButton` (quiet ghost
   action — Clear / Select all), `PillButton` (dismissible facet chip). A button is never a raw
-  `Pressable`.
+  `Pressable`. For a link OUT (a URL / record / document) use `Link` — underline+blue, the
+  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`.
@@ -72,6 +73,7 @@ This is the most common thing to get right. Match the JOB to the pattern:
 | a brand-NEW record (a form) | **fieldset form** (`FormField` + the 2-col grid) | structured entry + a Save |
 | a RELATED record (pick or make) | **find-or-create** (`Combobox allowCustom`) | one control covers both |
 | 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 |
 | a STATUS with terminal outcomes | **disposition** (open → resolve → revise) | guides the decision |
 | FILES | **attachment field** (dropzone + grid + gallery) | add / preview / delete |
@@ -122,6 +124,20 @@ snapshot the item on Edit so Cancel reverts, or DISCARDS a freshly-added one. Du
 the destructive **Delete is `danger-secondary`**; Cancel + the Save/Edit toggle sit right. Every
 screen composes its own (~15 lines) so the preview rows + form fit the data.
 
+### Billing & invoicing — the invoice DOCUMENT is the unit (`tpl_billing`)
+When charges get grouped into issuable documents (an e-invoice, a bill) and then collected, don't
+split the screen into "enter fees here, issue there" — that smears one job across two places. Make
+**each invoice a `Card` that holds its own editable charge lines** (amount input + payment method),
+its **live total**, its **status badge** (nothing-to-bill · draft · issued + ref), and its **issue
+action** in the footer. A charge never lives apart from the document it bills on. Issuing is gated
+**inline, never a dead end**: when a prerequisite is missing (a bill-to tax ID, a method on a
+charged line) the issue button disables with one muted line saying what's needed; the payment-method
+picker turns required the instant a line carries an amount. Issuing a real e-invoice is irreversible
+→ confirm in a `Dialog` (stage gate). A grand-total **receipt** validates first — surface the EXACT
+missing methods (`Alert.alert` listing each) rather than a vague "incomplete." A refundable
+**deposit** is its own card and its own receipt — never folded into the total due. Composition over
+`Card` + `NumberInput` + `Picker` + `Badge`; no new primitive.
+
 ### Tag field — `TagInput`, NOT `Combobox multi`
 A tag field's resting state should be a tidy CHIP BOX: `TagInput` is a bordered box of removable
 chips + an Add affordance; searching/creating happens in a POPOVER (a searchable, checkable list +
@@ -191,6 +207,17 @@ the "this is a gate" framing.
     weight="semibold"` + an optional `xs muted` subtitle.
 - **Time-constrained data gets a period filter** in the header band — `DateRangeFilterField`, never
   a static period badge. Every period-dependent number MUST follow the selection.
+- **Keyboard & focus — use `tabIndex`, never `focusable`.** RN-Web's `Pressable` silently ignores
+  `focusable` (it writes its own `tabIndex`), so set a pressable control's tab-stop status with
+  `tabIndex={0 | -1}` (`focusable` only works on a plain `View`/`TextInput`). Roving widgets
+  (Tabs/SegmentedControl/RadioPicker) keep ONE stop at `0`, the rest `-1`. And NEVER let a FOCUSED
+  control unmount — a conditional pointer affordance that vanishes on use (e.g. an "apply suggested
+  value" pill shown only while a field is empty) must be `tabIndex={-1}`, or the browser drops focus
+  to `<body>` and the next Tab jumps to the page's first focusable. A mouse-opened popover trigger
+  (Picker/Combobox/InlineSelect/InlineDatePicker) gets no `:focus-visible` ring, so it wears
+  **`ACTIVE_RING`** (`control_surface.ts`, a `0 0 0 2px zinc-900` box-shadow mirroring the focus
+  outline) on its open state — reuse that token, don't hand-roll a thin 1px edge. Full rules + the
+  keyboard test: `docs/accessibility.md` → Focus & tab order.
 - **Cards are banded — and composable** (all from `@lotics/ui/card`):
   ```tsx
   <Card style={{ padding: 0 }}>
@@ -290,7 +317,9 @@ recipe for a screen JOB; copy and adapt). Pick by the job:
   `tpl_dispatch` (capacity allocation) · `tpl_batch` (compose from parts) · `tpl_pick` (guided
   `ScanField` run) · `tpl_allocate` (`RemainderMeter` split) · `tpl_run` (preview → resolve → post).
 - **Data capture** — `tpl_intake` (multi-fieldset form + attachments) · `tpl_order` (the
-  transactional form: find-or-create + line items + attachment CRUD + 2-col grid) · `tpl_quick`
+  transactional form: find-or-create + line items + attachment CRUD + 2-col grid) · `tpl_billing`
+  (charges→invoice→collect: the invoice DOCUMENT is the unit — editable charge lines + method,
+  live total, status, inline-gated issue; validated receipt; separate deposit) · `tpl_quick`
   (quick-capture log) · `tpl_wizard` (`Stepper` form + review) · `tpl_record` (inline edit + Stage
   disposition + `TagInput` + Documents grid; `tpl_record_plain` = card-less).
 - **Records & lookup** — `tpl_detail` (full record + tabs) · `tpl_directory` (searchable register) ·
@@ -304,7 +333,7 @@ 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 ·
-status_badge · button · icon_button · link_button · pill_button · tabs · segmented_control ·
+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 ·
 radio_picker · counter · range_slider · date_picker · date_range_filter_field · time_picker ·

package/examples/tpl_billing.tsx

@@ -0,0 +1,344 @@
+import { useState } from "react";
+import { ScrollView, View } from "react-native";
+import { Text } from "@lotics/ui/text";
+import { colors } from "@lotics/ui/colors";
+import { Button } from "@lotics/ui/button";
+import { Card, CardBody, CardHeader, CardHeaderMeta, CardHeaderTitle } from "@lotics/ui/card";
+import { Badge } from "@lotics/ui/badge";
+import { Link } from "@lotics/ui/link";
+import { Icon } from "@lotics/ui/icon";
+import { Divider } from "@lotics/ui/divider";
+import { NumberInput } from "@lotics/ui/number_input";
+import { Picker } from "@lotics/ui/picker";
+import type { PickerOption } from "@lotics/ui/picker";
+import { Callout, CalloutText } from "@lotics/ui/callout";
+import { Dialog, DialogFooter, DialogHeader, DialogHeaderTitle } from "@lotics/ui/dialog";
+import { Alert } from "@lotics/ui/alert";
+import { formatMoney } from "@lotics/ui/format_money";
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Template · Billing & invoicing — the charges→invoice→collect flow as ONE
+// banded card, not a stack of disconnected cards. It's a single document, so it
+// reads as one: the bill-to, each invoice, the collect total, and the deposit
+// are BANDS separated by hairline Dividers. The INVOICE DOCUMENT is the unit —
+// each band is anchored by its own title + status badge and owns its editable
+// charge lines (amount + how it's paid), its live total, and its issue action,
+// so a charge never lives apart from the document it bills on. Issuing a real
+// e-invoice is irreversible and needs a bill-to tax ID, so it's gated inline
+// (never a dead end) and confirmed in a Dialog. A refundable DEPOSIT is its own
+// (tinted) band — collected separately, never folded into the total due.
+// ─────────────────────────────────────────────────────────────────────────────
+
+type Method = "cash" | "transfer" | "card";
+const METHODS: PickerOption<Method>[] = [
+  { value: "cash", label: "Cash" },
+  { value: "transfer", label: "Bank transfer" },
+  { value: "card", label: "Card" },
+];
+
+interface Charge {
+  key: string;
+  label: string;
+  /** The expected list price — offered as a one-tap fill while the line is unset. */
+  standard: number;
+  amount: number;
+  method: Method | "";
+}
+
+interface Invoice {
+  key: string;
+  title: string;
+  charges: Charge[];
+  /** Lookup code once issued to the e-invoice provider; "" = not issued. */
+  ref: string;
+}
+
+const INITIAL: Invoice[] = [
+  {
+    key: "service",
+    title: "Service",
+    ref: "",
+    charges: [
+      { key: "labor", label: "Labor", standard: 1_200_000, amount: 1_200_000, method: "cash" },
+      { key: "parts", label: "Parts", standard: 0, amount: 0, method: "" },
+    ],
+  },
+  {
+    key: "inspection",
+    title: "Inspection",
+    ref: "",
+    charges: [{ key: "insp", label: "Inspection fee", standard: 150_000, amount: 150_000, method: "" }],
+  },
+  {
+    key: "disposal",
+    title: "Disposal",
+    ref: "INV-2026-0414",
+    charges: [{ key: "disp", label: "Disposal fee", standard: 80_000, amount: 80_000, method: "transfer" }],
+  },
+];
+
+type Status = "none" | "draft" | "issued";
+const invoiceTotal = (inv: Invoice) => inv.charges.reduce((s, c) => s + c.amount, 0);
+const invoiceStatus = (inv: Invoice): Status => (inv.ref ? "issued" : invoiceTotal(inv) > 0 ? "draft" : "none");
+const missingMethods = (inv: Invoice) => inv.charges.filter((c) => c.amount > 0 && !c.method);
+
+/** One charge: label, an amount that reads blank until entered (a one-tap
+ *  Standard fill + "Set 0" while unset), and the payment method — which turns
+ *  required the moment the line carries an amount. */
+function ChargeLine({
+  charge, onAmount, onMethod, disabled,
+}: {
+  charge: Charge;
+  onAmount: (v: number) => void;
+  onMethod: (m: Method) => void;
+  disabled: boolean;
+}) {
+  const unset = charge.amount <= 0;
+  const needsMethod = charge.amount > 0 && !charge.method;
+  return (
+    <View style={{ flexDirection: "row", alignItems: "flex-start", gap: 10, flexWrap: "wrap" }}>
+      <Text size="sm" color="muted" style={{ width: 116, paddingTop: 10 }}>{charge.label}</Text>
+      <View style={{ flexGrow: 1, flexBasis: 130, gap: 4 }}>
+        <NumberInput
+          value={unset ? null : charge.amount}
+          onValueChange={(v) => onAmount(v ?? 0)}
+          min={0}
+          disabled={disabled}
+          accessibilityLabel={`${charge.label} amount`}
+        />
+        {unset && !disabled ? (
+          <View style={{ flexDirection: "row", gap: 8, flexWrap: "wrap" }}>
+            {charge.standard > 0 ? (
+              <Button title={`Standard ${formatMoney(charge.standard)}`} color="secondary" onPress={() => onAmount(charge.standard)} />
+            ) : null}
+            <Button title="Set 0" color="secondary" onPress={() => onAmount(0)} />
+          </View>
+        ) : null}
+      </View>
+      <View style={{ flexBasis: 168, gap: 4 }}>
+        <Picker
+          options={METHODS}
+          value={charge.method || null}
+          onValueChange={onMethod}
+          placeholder="How paid…"
+          disabled={disabled || unset}
+          accessibilityLabel={`Payment method · ${charge.label}`}
+        />
+        {needsMethod ? <Text size="xs" color="danger">Choose a method</Text> : null}
+      </View>
+    </View>
+  );
+}
+
+/** One invoice document, rendered as a BAND inside the single billing card: a
+ *  title + status header, its charge lines, and a total + issue row. The leading
+ *  Divider sets it off from the band above without a second card. */
+function InvoiceBand({
+  inv, taxId, onAmount, onMethod, onIssue,
+}: {
+  inv: Invoice;
+  taxId: string;
+  onAmount: (chKey: string, v: number) => void;
+  onMethod: (chKey: string, m: Method) => void;
+  onIssue: (inv: Invoice) => void;
+}) {
+  const total = invoiceTotal(inv);
+  const status = invoiceStatus(inv);
+  const missing = missingMethods(inv);
+  const canIssue = total > 0 && missing.length === 0 && !!taxId;
+  const blockReason = !taxId ? "Add the customer's tax ID to issue." : missing.length ? "Choose a payment method for every charged line." : "";
+  return (
+    <>
+      <Divider />
+      <CardBody style={{ gap: 10 }}>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+          <Text weight="semibold">{inv.title}</Text>
+          <View style={{ flex: 1 }} />
+          {status === "issued" ? (
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <Badge variant="dot" label="Issued" color="emerald" />
+              <Link size="xs" onPress={() => {}} accessibilityLabel={`Open invoice ${inv.ref}`}>{inv.ref}</Link>
+            </View>
+          ) : status === "draft" ? (
+            <Badge variant="dot" label="Draft" color="amber" />
+          ) : (
+            <Badge variant="dot" label="Nothing to bill" color="zinc" />
+          )}
+        </View>
+        {inv.charges.map((c) => (
+          <ChargeLine
+            key={c.key}
+            charge={c}
+            disabled={status === "issued"}
+            onAmount={(v) => onAmount(c.key, v)}
+            onMethod={(m) => onMethod(c.key, m)}
+          />
+        ))}
+        {total > 0 ? (
+          <View style={{ flexDirection: "row", alignItems: "center", gap: 8, flexWrap: "wrap", paddingTop: 2 }}>
+            <Text size="sm" color="muted" style={{ flex: 1 }}>
+              Total <Text weight="semibold" color="default" tabular>{formatMoney(total)}</Text>
+            </Text>
+            {status === "issued" ? (
+              <>
+                <Button title="Re-issue" color="secondary" disabled={!canIssue} onPress={() => onIssue(inv)} />
+              </>
+            ) : (
+              <Button title="Issue invoice" color="primary" disabled={!canIssue} onPress={() => onIssue(inv)} />
+            )}
+          </View>
+        ) : null}
+        {total > 0 && status !== "issued" && !canIssue ? <Text size="xs" color="muted">{blockReason}</Text> : null}
+      </CardBody>
+    </>
+  );
+}
+
+export function TplBilling() {
+  const [invoices, setInvoices] = useState<Invoice[]>(INITIAL);
+  // The bill-to: issuing an e-invoice needs a tax ID. Toggle it to see the gate.
+  const [taxId, setTaxId] = useState("0312456780");
+  const [deposit, setDeposit] = useState(0);
+  const [confirm, setConfirm] = useState<Invoice | null>(null);
+  const seq = useState(() => ({ n: 414 }))[0];
+
+  const patchCharge = (invKey: string, chKey: string, patch: Partial<Charge>) =>
+    setInvoices((prev) =>
+      prev.map((inv) =>
+        inv.key !== invKey ? inv : { ...inv, charges: inv.charges.map((c) => (c.key === chKey ? { ...c, ...patch } : c)) },
+      ),
+    );
+
+  const grandTotal = invoices.reduce((s, inv) => s + invoiceTotal(inv), 0);
+  const allMissing = invoices.flatMap(missingMethods);
+  const issuedCount = invoices.filter((i) => invoiceStatus(i) === "issued").length;
+
+  const issue = (inv: Invoice) => {
+    seq.n += 1;
+    const ref = `INV-2026-${String(seq.n).padStart(4, "0")}`;
+    setInvoices((prev) => prev.map((x) => (x.key === inv.key ? { ...x, ref } : x)));
+    setConfirm(null);
+  };
+
+  const printReceipt = () => {
+    if (allMissing.length > 0) {
+      Alert.alert(
+        "Missing payment method",
+        `Choose how these charges were paid before printing the receipt:\n\n${allMissing.map((c) => `• ${c.label} (${formatMoney(c.amount)})`).join("\n")}`,
+        [{ text: "OK" }],
+      );
+      return;
+    }
+    Alert.alert("Receipt", `Printing receipt for ${formatMoney(grandTotal)}.`, [{ text: "OK" }]);
+  };
+
+  return (
+    <ScrollView style={{ flex: 1, backgroundColor: colors.zinc[50] }} contentContainerStyle={{ padding: 28 }}>
+      <View style={{ width: "100%", maxWidth: 640, alignSelf: "center", gap: 16 }}>
+        <View style={{ flexDirection: "row", alignItems: "center", gap: 10 }}>
+          <Text size="xl" weight="semibold">Billing</Text>
+          <Badge label="Order #4821" color="zinc" />
+        </View>
+
+        {/* ONE banded card — bill-to · each invoice · collect · deposit */}
+        <Card style={{ padding: 0 }}>
+          <CardHeader>
+            <CardHeaderTitle info="One document: the bill-to, each invoice, the total, and the deposit are bands of the same card.">
+              Phí &amp; hóa đơn
+            </CardHeaderTitle>
+            <CardHeaderMeta>{formatMoney(grandTotal)}</CardHeaderMeta>
+          </CardHeader>
+
+          {/* bill-to band — issuing needs a tax ID; the toggle shows the gate */}
+          <CardBody>
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8, flexWrap: "wrap" }}>
+              <Icon name="building-2" size={16} color={colors.zinc[500]} />
+              <Text weight="medium">Harbor Freight Lines</Text>
+              <Text size="sm" color="muted">·</Text>
+              {taxId ? (
+                <Text size="sm" color="muted" tabular>MST {taxId}</Text>
+              ) : (
+                <Text size="sm" color="danger">No tax ID — required to issue</Text>
+              )}
+              <View style={{ flex: 1 }} />
+              <Button title={taxId ? "Remove tax ID" : "Add tax ID"} color="muted" onPress={() => setTaxId((t) => (t ? "" : "0312456780"))} />
+            </View>
+          </CardBody>
+
+          {/* invoice bands */}
+          {invoices.map((inv) => (
+            <InvoiceBand
+              key={inv.key}
+              inv={inv}
+              taxId={taxId}
+              onAmount={(chKey, v) => patchCharge(inv.key, chKey, { amount: v })}
+              onMethod={(chKey, m) => patchCharge(inv.key, chKey, { method: m })}
+              onIssue={setConfirm}
+            />
+          ))}
+
+          {/* collect band */}
+          <Divider />
+          <CardBody style={{ gap: 10 }}>
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <Text weight="semibold" style={{ flex: 1 }}>Tổng thu</Text>
+              <Text weight="semibold" size="lg" tabular>{formatMoney(grandTotal)}</Text>
+            </View>
+            {allMissing.length > 0 ? (
+              <Callout tone="warning">
+                <CalloutText>
+                  {allMissing.length} charged {allMissing.length === 1 ? "line has" : "lines have"} no payment method — set them before printing the receipt.
+                </CalloutText>
+              </Callout>
+            ) : null}
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <Text size="xs" color="muted" style={{ flex: 1 }}>{issuedCount} of {invoices.length} issued</Text>
+              <Button title="Print receipt" color="primary" disabled={grandTotal <= 0} onPress={printReceipt} />
+            </View>
+          </CardBody>
+
+          {/* deposit band — tinted + labelled separate, never part of the total */}
+          <Divider />
+          <CardBody style={{ backgroundColor: colors.zinc[50], gap: 8 }}>
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 8 }}>
+              <Text weight="semibold">Deposit</Text>
+              <Badge label="Collected separately" color="zinc" />
+            </View>
+            <View style={{ flexDirection: "row", alignItems: "center", gap: 10, flexWrap: "wrap" }}>
+              <Text size="sm" color="muted" style={{ width: 116 }}>Refundable</Text>
+              <View style={{ flexGrow: 1, flexBasis: 130 }}>
+                <NumberInput value={deposit || null} onValueChange={(v) => setDeposit(v ?? 0)} min={0} accessibilityLabel="Deposit amount" />
+              </View>
+              <Button
+                title="Deposit receipt"
+                color="secondary"
+                disabled={deposit <= 0}
+                onPress={() => Alert.alert("Deposit receipt", `Printing deposit receipt for ${formatMoney(deposit)}.`, [{ text: "OK" }])}
+              />
+            </View>
+          </CardBody>
+        </Card>
+      </View>
+
+      {/* issuing an e-invoice is irreversible — confirm in a Dialog (stage gate) */}
+      <Dialog width={460} open={confirm !== null} onOpenChange={(o) => { if (!o) setConfirm(null); }}>
+        <DialogHeader>
+          <DialogHeaderTitle>{confirm?.ref ? "Re-issue invoice?" : "Issue e-invoice?"}</DialogHeaderTitle>
+        </DialogHeader>
+        <View style={{ paddingHorizontal: 24, paddingVertical: 12 }}>
+          <Callout tone="warning">
+            <CalloutText>
+              {confirm
+                ? `Issue a real e-invoice for "${confirm.title}" (${formatMoney(invoiceTotal(confirm))}) to the provider. This writes a lookup code to the record and can't be undone.`
+                : ""}
+            </CalloutText>
+          </Callout>
+        </View>
+        <DialogFooter>
+          <Button title="Cancel" color="secondary" onPress={() => setConfirm(null)} />
+          <Button title="Issue" color="primary" onPress={() => confirm && issue(confirm)} />
+        </DialogFooter>
+      </Dialog>
+    </ScrollView>
+  );
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "exports": {
     "./tokens": "./src/tokens.ts",
@@ -110,6 +110,7 @@
     "./filter_pill": "./src/filter_pill.tsx",
     "./range_slider": "./src/range_slider.tsx",
     "./counter": "./src/counter.tsx",
+    "./link": "./src/link.tsx",
     "./link_button": "./src/link_button.tsx",
     "./sort_header": "./src/sort_header.tsx",
     "./skeleton": "./src/skeleton.tsx",

package/src/combobox.tsx

@@ -9,6 +9,7 @@ import {
 } from "react-native";
 import { useCallback, useEffect, useId, useMemo, useRef, useState, type ReactNode } from "react";
 import { colors } from "./colors";
+import { ACTIVE_RING } from "./control_surface";
 import { Text } from "./text";
 import { Icon, type IconName } from "./icon";
 import { TextInputField } from "./text_input_field";
@@ -289,7 +290,7 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
 
   return (
     <View style={style}>
-      <View ref={triggerRef} style={multi ? styles.multiBox : undefined}>
+      <View ref={triggerRef} style={multi ? [styles.multiBox, open && styles.openRing] : undefined}>
         {multi
           ? chips.map((chip) => (
               <View key={chip.value} style={styles.chip}>
@@ -337,7 +338,12 @@ export function Combobox<T extends string = string, D = unknown>(props: Combobox
           autoFocus={autoFocus}
           autoCapitalize="none"
           autoCorrect={false}
-          style={multi ? styles.multiInput : showChevron ? styles.selectInput : undefined}
+          style={[
+            multi ? styles.multiInput : showChevron ? styles.selectInput : undefined,
+            // Single-select wears the open ring on the input (which holds the
+            // border); multi wears it on the wrapper above (the input is borderless).
+            !multi && open ? styles.openRing : undefined,
+          ]}
           role="combobox"
           aria-expanded={showList}
           aria-controls={listboxId}
@@ -455,6 +461,9 @@ const styles = StyleSheet.create({
     borderWidth: 0,
     height: 28,
   },
+  openRing: {
+    boxShadow: ACTIVE_RING,
+  },
   // Select mode: room on the right for the trailing chevron.
   selectInput: {
     paddingRight: 32,

package/src/control_surface.ts

@@ -5,6 +5,14 @@ import { colors } from "./colors";
  *  buttons) aligns to it so a toolbar row reads as one band. */
 export const CONTROL_HEIGHT = 40;
 
+/** The active/open edge for an interactive control — a 2px zinc-900 ring flush
+ *  against the box (offset 0), MIRRORING the keyboard `:focus-visible` outline
+ *  (index.css). A mouse-opened popover trigger (Picker / Combobox / InlineSelect /
+ *  InlineDatePicker) never receives `:focus-visible`, so apply this on its open
+ *  state to read identically to a focused input — a lone 1px border looks thin
+ *  beside the kit's focus outline and selected-pill ring. */
+export const ACTIVE_RING = `0 0 0 2px ${colors.zinc[900]}`;
+
 /**
  * THE pill-surface contract — the single definition of the bordered, white,
  * rounded interactive surface shared by `ChipGroup` chips and `PillButton` (and

package/src/index.css

@@ -336,9 +336,12 @@ html {
   color: var(--color-zinc-900);
 }
 
-/* Keyboard focus ring. `:focus-visible` only matches keyboard-driven focus,
-   so pointer/touch interactions stay visually unchanged. The ring sits flush
-   against the element's border (offset 0, no gap) and, being an outline, never
+/* Focus ring — keyboard-driven only (`:focus-visible`), so pointer/touch
+   interactions stay clutter-free (no stray ring stacked on a clicked button,
+   tab, or segment that already shows its own state). A SELECT shows its own
+   active edge on a mouse-open via `ACTIVE_RING` (control_surface.ts) — that, not
+   this rule, is what rings the combobox/picker on a pointer open. The ring sits
+   flush against the border (offset 0, no gap) and, being an outline, never
    reflows layout. */
 :focus-visible {
   outline: 2px solid var(--color-zinc-900);

package/src/inline_date_picker.tsx

@@ -77,6 +77,7 @@ export function InlineDatePicker(props: InlineDatePickerProps) {
             display={display}
             placeholder={placeholder}
             disabled={disabled}
+            active={open && !disabled}
             accessibilityLabel={accessibilityLabel}
             trailing={
               saving ? (

package/src/inline_edit.tsx

@@ -5,6 +5,7 @@ import { IconButton } from "./icon_button";
 import { ActivityIndicator } from "./activity_indicator";
 import { PressableHighlight } from "./pressable_highlight";
 import { colors } from "./colors";
+import { ACTIVE_RING } from "./control_surface";
 import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
 
 /** The kit's standard control height (TextInputField, NumberInput, Picker, …).
@@ -109,6 +110,9 @@ interface InlineEditViewProps {
   accessibilityLabel?: string;
   /** Right-aligned adornment — e.g. a chevron for a select, a spinner while saving. */
   trailing?: ReactNode;
+  /** True while the field's popover (select/date) is open: wears the 2px active
+   *  ring so a mouse-opened trigger reads like a focused input (no `:focus-visible`). */
+  active?: boolean;
   ref?: Ref<View>;
 }
 
@@ -121,7 +125,7 @@ interface InlineEditViewProps {
  * select/date inline editors (it forwards ref + onPress to a `PopoverTrigger`).
  */
 export function InlineEditView(props: InlineEditViewProps) {
-  const { display, placeholder, onPress, disabled, accessibilityLabel, trailing, ref } = props;
+  const { display, placeholder, onPress, disabled, accessibilityLabel, trailing, active, ref } = props;
   return (
     <PressableHighlight
       ref={ref}
@@ -130,7 +134,7 @@ export function InlineEditView(props: InlineEditViewProps) {
       accessibilityRole="button"
       accessibilityLabel={accessibilityLabel}
       userSelect="none"
-      style={styles.view}
+      style={[styles.view, active && styles.viewActive]}
     >
       <Text numberOfLines={1} style={[viewTextStyle, display ? null : styles.placeholder]}>
         {display || placeholder || "—"}
@@ -219,6 +223,12 @@ const styles = StyleSheet.create({
     alignItems: "center",
     gap: 6,
   },
+  // Open (popover showing): the transparent edge fills in to the kit's 1px border
+  // under the 2px active ring — identical to a focused input.
+  viewActive: {
+    borderColor: colors.border,
+    boxShadow: ACTIVE_RING,
+  },
   placeholder: { color: colors.zinc[400] },
   editRow: { flexDirection: "row", alignItems: "flex-start", gap: 6 },
   editControl: { flex: 1, position: "relative" },

package/src/inline_select.tsx

@@ -61,6 +61,7 @@ export function InlineSelect<T extends string>(props: InlineSelectProps<T>) {
             display={selected?.label ?? ""}
             placeholder={placeholder}
             disabled={disabled}
+            active={open && !disabled}
             accessibilityLabel={accessibilityLabel}
             trailing={
               saving ? (

package/src/link.tsx

@@ -0,0 +1,32 @@
+import { type ReactNode } from "react";
+import { Pressable } from "react-native";
+import { Text, type TextSize } from "./text";
+import { colors } from "./colors";
+
+export interface LinkProps {
+  children: ReactNode;
+  /** Opening the link is the consumer's job (a URL via the app SDK's openExternal,
+   *  an in-app route, …) — Link is pure presentation + the press target. */
+  onPress: () => void;
+  size?: TextSize;
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+/**
+ * An EXTERNAL hyperlink — underline + blue, the universal "this opens somewhere
+ * else" signal (a document URL, a record, an invoice). The deliberate counterpart
+ * to `LinkButton`: `LinkButton` is a QUIET IN-APP ACTION (a ghost button — "Clear",
+ * "Show more") and intentionally NOT underlined; `Link` is a link OUT and IS
+ * underlined-blue so it reads as a destination, not an action. The consumer wires
+ * `onPress` to its opener.
+ */
+export function Link({ children, onPress, size = "sm", accessibilityLabel, testID }: LinkProps) {
+  return (
+    <Pressable onPress={onPress} accessibilityRole="link" accessibilityLabel={accessibilityLabel} testID={testID}>
+      <Text size={size} decoration="underline" style={{ color: colors.blue[600] }}>
+        {children}
+      </Text>
+    </Pressable>
+  );
+}

package/src/picker.tsx

@@ -2,6 +2,7 @@ import { Picker as RNPicker } from "@react-native-picker/picker";
 import { StyleSheet, View, Pressable, StyleProp, ViewStyle, TextStyle } from "react-native";
 import { useState, useCallback, useMemo, useEffect, useRef } from "react";
 import { colors } from "./colors";
+import { ACTIVE_RING } from "./control_surface";
 import { Text } from "./text";
 import { fontFamilyRegular, getInputTextStyle } from "./text_utils";
 import { Icon } from "./icon";
@@ -328,7 +329,9 @@ const styles = StyleSheet.create({
     height: 40,
   },
   opened: {
-    borderColor: colors.zinc["900"],
+    // Mouse-opened, so no `:focus-visible` — wear the same 2px zinc ring a
+    // focused input gets, over the unchanged 1px border (not a lone 1px edge).
+    boxShadow: ACTIVE_RING,
   },
   disabled: {
     opacity: 0.5,

package/src/popover.tsx

@@ -254,8 +254,17 @@ export function PopoverContent(props: PopoverContentProps) {
 
     return () => {
       cancelAnimationFrame(focusFrame);
-      const target = returnFocusRef.current;
+      const prior = returnFocusRef.current;
       returnFocusRef.current = null;
+      // Return focus to the TRIGGER (WAI-ARIA: focus returns to the element that
+      // invoked the popup). `previouslyFocused` is an unreliable proxy — RN-Web's
+      // Pressable triggers don't take focus on mouse press, so for a mouse-opened
+      // popover (a Picker/InlineSelect/menu) it is <body>; restoring there strands
+      // focus and the next Tab jumps to the page's first focusable. Fall back to
+      // the prior element only if the trigger is gone (e.g. a hover-revealed menu
+      // button that unmounted under the overlay).
+      const trigger = triggerRef.current;
+      const target = trigger && trigger.isConnected ? trigger : prior;
       if (target && typeof target.focus === "function") {
         target.focus();
       }

package/src/pressable_row.tsx

@@ -55,7 +55,10 @@ export function PressableRow(props: PressableRowProps) {
   return (
     <Pressable
       onPress={onPress}
-      focusable={false}
+      // Non-focusable surface: tabIndex, NOT focusable — RN-Web's Pressable
+      // ignores `focusable` and writes its own tabIndex (the keyboard target is
+      // the nested "Open …" button, not this row).
+      tabIndex={-1}
       {...mouseProps}
       style={({ pressed }) => [
         styles.row,

package/src/radio_picker.tsx

@@ -128,7 +128,9 @@ function RadioOption<T extends string | number | symbol>(
       accessibilityLabel={description ? `${label}, ${description}` : label}
       aria-checked={selected}
       // Roving tabindex: exactly one radio is the tab-stop. Arrow keys cycle.
-      focusable={isTabStop}
+      // tabIndex, NOT focusable — RN-Web's Pressable ignores `focusable` and
+      // writes its own tabIndex.
+      tabIndex={isTabStop ? 0 : -1}
       onKeyDown={onKeyDown}
     >
       <View

package/src/segmented_control.tsx

@@ -152,8 +152,9 @@ function Segment<T extends string>(props: SegmentProps<T>) {
       aria-checked={selected}
       aria-disabled={disabled}
       // Roving tabindex: only the selected segment (or the fallback) is a tab
-      // stop; the rest are reached with arrow keys.
-      focusable={isTabStop && !disabled}
+      // stop; the rest are reached with arrow keys. tabIndex, NOT focusable —
+      // RN-Web's Pressable ignores `focusable` and writes its own tabIndex.
+      tabIndex={isTabStop && !disabled ? 0 : -1}
     >
       {(state) => {
         const hovered = (state as { hovered?: boolean }).hovered;

package/src/tabs.tsx

@@ -125,8 +125,10 @@ function TabButton<T extends string>(props: TabButtonProps<T>) {
       // Roving tabindex: the selected tab is the tab-stop, others are reachable
       // via arrow keys. When no tab matches the current selection (props.value
       // is stale), the first tab is the fallback so the group stays keyboard-
-      // reachable.
-      focusable={isTabStop}
+      // reachable. Drive it with tabIndex, NOT focusable: RN-Web's Pressable
+      // ignores `focusable` (it writes its own tabIndex), so a focusable-based
+      // roving model silently leaves every tab a tab-stop.
+      tabIndex={isTabStop ? 0 : -1}
     >
       {(state) => {
         const { pressed } = state;

package/src/text.tsx

@@ -47,7 +47,7 @@ export interface TextProps {
 
 export type HeadingLevel = 1 | 2 | 3 | 4 | 5 | 6;
 
-type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
+export type TextSize = "xs" | "sm" | "md" | "lg" | "xl" | "xxl";
 type TextAlign = "left" | "right" | "center";
 type TextDecorationLine = "underline" | "lineThrough" | "underline lineThrough";
 type TextWeight = "regular" | "medium" | "semibold";