@lotics/ui 41.0.1 → 41.3.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "41.0.1",
+  "version": "41.3.0",
   "type": "module",
   "exports": {
     "./vite": {
@@ -109,6 +109,7 @@
       "react-native": "./src/markdown.tsx",
       "default": "./src/markdown.web.tsx"
     },
+    "./markdown_types": "./src/markdown_types.ts",
     "./markdown.css": "./src/markdown.css",
     "./confidence": "./src/confidence.tsx",
     "./finding": "./src/finding.tsx",
@@ -153,6 +154,7 @@
     "./inline_edit": "./src/inline_edit.tsx",
     "./inline_slot": "./src/inline_slot.tsx",
     "./inline_static": "./src/inline_static.tsx",
+    "./inline_files": "./src/inline_files.tsx",
     "./inline_text_input": "./src/inline_text_input.tsx",
     "./inline_number_input": "./src/inline_number_input.tsx",
     "./inline_select": "./src/inline_select.tsx",
@@ -193,6 +195,7 @@
     "./counter": "./src/counter.tsx",
     "./link": "./src/link.tsx",
     "./reference_field": "./src/reference_field.tsx",
+    "./text_disclosure": "./src/text_disclosure.tsx",
     "./text_link": "./src/text_link.tsx",
     "./sort_header": "./src/sort_header.tsx",
     "./skeleton": "./src/skeleton.tsx",

package/src/file_rows.tsx

@@ -10,7 +10,6 @@ import { Alert } from "./alert";
 import { FileRow } from "./file_row";
 import { ActionMenu, type ActionMenuItem } from "./action_menu";
 import { FileGalleryModal } from "./file_gallery_modal";
-import { resolveMime } from "./file_badge";
 import { downloadFileFromUrl } from "./download";
 import { type GalleryLabels } from "./file_preview_types";
 import { useLoticsLocale } from "./locale";
@@ -18,7 +17,18 @@ import type { DisplayFile } from "./file_thumbnail";
 
 export interface FileRowsProps {
   files: DisplayFile[];
-  /** Secondary line per file. Default: the file-type label (e.g. "PDF"). */
+  /**
+   * Secondary line per file. Default: NONE.
+   *
+   * It defaulted to the file-type label, which every row already states twice —
+   * the `FileBadge` encodes the type as its colour AND prints it inside the
+   * glyph, and the filename ends in the extension. A fourth statement of one
+   * fact is not a caption, it is noise, and it cost every consumer a line of
+   * row height to say nothing.
+   *
+   * Pass something the NAME does not already carry — what an invoice covers, who
+   * uploaded it, when it landed.
+   */
   meta?: (file: DisplayFile) => string | undefined;
   /** Adds a (confirmed) "Remove" to each ⋯ menu and the gallery toolbar. The host
    *  drops the file from its own state. */
@@ -84,7 +94,7 @@ export function FileRows({ files, meta, onRemove, onOpenExternal, onDownload, on
           <FileRow
             key={file.id}
             name={file.filename}
-            meta={meta ? meta(file) : resolveMime(file.mimeType).label}
+            meta={meta ? meta(file) : undefined}
             mimeType={file.mimeType}
             onPress={() => setActiveIndex(index)}
             trailing={<ActionMenu accessibilityLabel={`${l.actions}: ${file.filename}`} items={items} />}

package/src/inline_files.tsx

@@ -0,0 +1,219 @@
+import { useCallback, useState } from "react";
+import { View } from "react-native";
+import { Button } from "./button";
+import { Text } from "./text";
+import { FileRows } from "./file_rows";
+import { INLINE_CONTROL_HEIGHT } from "./inline_edit";
+import { pickFiles } from "./file_picker";
+import { type DisplayFile } from "./file_thumbnail";
+import { type GalleryLabels } from "./file_preview_types";
+import { useLoticsLocale } from "./locale";
+
+export interface InlineFilesProps {
+  /** What is attached now. */
+  files: DisplayFile[];
+  /**
+   * The user picked these. The HOST uploads them and persists the result — this
+   * kit never talks to a server, so `files` only changes when the host says so.
+   *
+   * **`multiple` decides what the host must DO with them**: appending on a
+   * single-file field is how a field that holds one contract quietly ends up
+   * holding three. See that prop.
+   *
+   * Return a promise and the CTA stays busy until it settles, which is the whole
+   * of this component's loading state: a picked file is in flight for as long as
+   * the host takes, and a control that re-arms immediately invites the second
+   * press that files it twice.
+   *
+   * Omit for a read-only field — the same list, no CTA.
+   */
+  onAdd?: (picked: File[]) => void | Promise<void>;
+  /** Adds a (confirmed) Remove to each row's ⋯ menu. Omit for add-only. */
+  onRemove?: (file: DisplayFile) => void;
+  /** Open outside the app — a new tab on the frontend, `openExternal` in a
+   *  sandboxed app. Omit and the row still previews in place. */
+  onOpenExternal?: (file: DisplayFile) => void;
+  /** Override the download (the host frontend sends `credentials`). */
+  onDownload?: (file: DisplayFile) => void;
+  /**
+   * **The FIELD's cardinality, not the picker's convenience.** Default `true`.
+   *
+   * `true` — a set. The picker takes several at once, and the CTA reads
+   * `addMoreLabel` once something is attached, because adding a second page to a
+   * document set is an ordinary act.
+   *
+   * `false` — exactly one. The picker takes one, and the CTA reads
+   * `replaceLabel`, because "add another" is not a thing a single-file field can
+   * do: the honest verb is replace, and offering "add" there produces a field
+   * holding two of something the schema says there is one of. **The host must
+   * then SET rather than append in `onAdd`** — the component cannot enforce it
+   * (it does not own the data), and the failure is silent, so the call site
+   * reads `onAdd={([f]) => setFile(f)}` against `onAdd={(fs) => setFiles([...files, ...fs])}`
+   * and the difference is visible where it is decided.
+   *
+   * This is a fact about the field, which is why it is a prop and the LIST shape
+   * is not: one file or many, the reader still identifies a document by its name.
+   */
+  multiple?: boolean;
+  /**
+   * CTA words for the three states — nothing attached, adding to a set,
+   * replacing the one.
+   *
+   * Three, because they are three different acts and a generic "Add files"
+   * misleads in two of them. Name them for the domain ("Attach original" /
+   * "Add page" / "Replace contract") and the field stops needing a caption to
+   * explain itself. Each falls back to the one before it, so a single-file field
+   * that never says `replaceLabel` still reads sensibly.
+   */
+  addLabel?: string;
+  addMoreLabel?: string;
+  replaceLabel?: string;
+  /** Replaces the CTA's words while `onAdd` is in flight. Omit and the CTA keeps
+   *  its words and simply disables — no invented English in a localized app. */
+  busyLabel?: string;
+  /**
+   * Renders this sentence INSTEAD of the CTA — for a field with nothing to
+   * attach TO yet (a scan whose invoice does not exist; a line before its order
+   * is saved).
+   *
+   * Deliberately not a disabled button. A disabled control states that you may
+   * not, and leaves the reader to work out why and what would change it; a
+   * sentence states the act that unblocks it. Same pixels, one of them useful.
+   */
+  blockedReason?: string;
+  /** Shown when nothing is attached AND there is no CTA. Default "—". */
+  emptyLabel?: string;
+  /** Native accept filter, e.g. `"application/pdf,image/*"`. */
+  accept?: string;
+  /** Translated gallery/menu chrome, forwarded to `FileRows`. */
+  labels?: Partial<GalleryLabels>;
+  /** Credentials mode for the preview fetches — `"include"` for auth-gated
+   *  proxy URLs, omitted for an app's presigned URLs. */
+  credentials?: RequestCredentials;
+  onError?: (error: unknown, meta: { fileId: string; mimeType: string }) => void;
+}
+
+/**
+ * The FILES member of the `Inline*` family — a record's attachments, editable in
+ * the value column of a `DetailRow`.
+ *
+ * Every other field type had both halves already (`Select`/`InlineSelect`,
+ * `TextInputField`/`InlineTextInput`); files had only the section-scale one
+ * (`FilesEditor`), so a record FIELD holding documents was hand-rolled per app as
+ * `FileRows` + a picker + a button. Each copy re-derived the same decisions —
+ * including the alignment one, which has a counter-intuitive answer: this field
+ * sits on the inline grid's VERTICAL beat but takes NO horizontal inset, because
+ * its children are boxes rather than text (see the comment on the wrapper).
+ *
+ * A LIST, not a grid, and not switchable: documents are identified by NAME — a
+ * PDF/Word/Excel thumbnail is a grey page identical to every other grey page — so
+ * a grid of them is a wall of one tile under a truncated caption. Images are
+ * identified by their CONTENT and want `FileGrid` / `FilesEditor` instead. Which
+ * one a field holds is a judgment about the DATA, so it picks the component, not
+ * a prop on this one.
+ *
+ * Lean on purpose: no selection mode, no bulk bar, no upload queue. It shows,
+ * previews, adds and removes. Reach for `FilesEditor` when a surface genuinely
+ * needs multi-select and bulk download — a record row does not.
+ */
+export function InlineFiles(props: InlineFilesProps) {
+  const {
+    files,
+    onAdd,
+    onRemove,
+    onOpenExternal,
+    onDownload,
+    multiple = true,
+    addLabel,
+    addMoreLabel,
+    replaceLabel,
+    busyLabel,
+    blockedReason,
+    emptyLabel = "—",
+    accept,
+    labels,
+    credentials,
+    onError,
+  } = props;
+
+  const loc = useLoticsLocale().filesEditor;
+  const [busy, setBusy] = useState(false);
+
+  /**
+   * Single-flight, released in `finally`.
+   *
+   * The picker is INSIDE the guard, not around it: a second press while the
+   * dialog is open would open a second dialog, and both would resolve into
+   * `onAdd`. Cancelling still settles (`pickFiles` resolves `[]`), so the guard
+   * releases without the host being called.
+   */
+  const add = useCallback(async () => {
+    if (busy || onAdd === undefined) return;
+    setBusy(true);
+    try {
+      const picked = await pickFiles({ accept, multiple });
+      if (picked.length === 0) return;
+      await onAdd(picked);
+    } finally {
+      setBusy(false);
+    }
+  }, [busy, onAdd, accept, multiple]);
+
+  const base = addLabel ?? loc.upload;
+  const cta =
+    files.length === 0
+      ? base
+      : multiple
+        ? (addMoreLabel ?? base)
+        : (replaceLabel ?? base);
+
+  return (
+    /* The inline grid's VERTICAL contract only — deliberately not `InlineSlot`.
+     *
+     * That component pads 8px + a 1px border so a raw STRING's baseline lands
+     * where an editor's text does, which is right for text and wrong here: these
+     * children are BOXES (file rows, a button), and a box aligns with the
+     * editors' box, not with their text. Measured, `InlineSlot` pushed this
+     * field 9px right of every input above it — one value column, two left
+     * edges, which is the exact defect the slot exists to prevent, arriving
+     * through the slot itself.
+     *
+     * The LIST fills the column and the CTA does not, because they are different
+     * kinds of thing: a file row is this field's VALUE and every other value in
+     * the column (a text input, a select) spans it, so a short row would read as
+     * a different column; the button is an ACTION, and a full-bleed one reads as
+     * the section's rather than this field's. Hence stretch by default, with the
+     * CTA opting out via `alignSelf` rather than the container shrinking both.
+     */
+    <View style={{ minHeight: INLINE_CONTROL_HEIGHT, justifyContent: "center" }}>
+      <View style={{ gap: 8, width: "100%" }}>
+        {files.length > 0 ? (
+          <FileRows
+            files={files}
+            onRemove={onRemove}
+            onOpenExternal={onOpenExternal}
+            onDownload={onDownload}
+            onError={onError}
+            labels={labels}
+            credentials={credentials}
+          />
+        ) : null}
+        {blockedReason !== undefined ? (
+          <Text size="sm" color="muted">{blockedReason}</Text>
+        ) : onAdd !== undefined ? (
+          <View style={{ alignSelf: "flex-start" }}>
+            <Button
+              title={busy ? (busyLabel ?? cta) : cta}
+              icon="paperclip"
+              color="secondary"
+              disabled={busy}
+              onPress={() => void add()}
+            />
+          </View>
+        ) : files.length === 0 ? (
+          <Text size="sm" color="muted">{emptyLabel}</Text>
+        ) : null}
+      </View>
+    </View>
+  );
+}

package/src/inline_text_input.tsx

@@ -25,8 +25,37 @@ export interface InlineTextInputProps {
    * a payment term, an address, a clause. Default 1 (the single-line field).
    * Above 1 the field is that many lines tall and wraps, in both states. Enter
    * then inserts a newline; the field commits on blur (or the ✓ in "buttons").
+   *
+   * With `autoGrow` this becomes the MINIMUM rather than the whole budget.
    */
   numberOfLines?: number;
+  /**
+   * Grow to fit the value instead of clipping it at `numberOfLines`.
+   *
+   * A fixed budget is right for a value with a KNOWN shape — a two-line address,
+   * a payment term — where reserving the space keeps the page still. It is wrong
+   * for open prose, and it fails in the worst way: the field renders a box the
+   * value does not fit, with no ellipsis, no scrollbar and no scroll, so the
+   * reader is given no evidence that anything is missing. Measured on a record
+   * note, 285 characters drew 76px of a 116px value — two lines gone, silently.
+   *
+   * Growing costs nothing this control was protecting: the field is ONE input in
+   * both states, so a grown box is the same height resting and editing, and
+   * nothing moves on focus. It grows as you type, which is the same promise the
+   * value's own wrapping already makes.
+   *
+   * Reach for it wherever the length is the AUTHOR's choice rather than the
+   * field's. Keep the fixed budget in the two cases it is still right:
+   *
+   * - **A value that can be arbitrarily long.** Growth has no ceiling — measured,
+   *   406 characters is already 238px — so a field that may hold a document wants
+   *   the reserve, and a length that overflows it is the signal that the value
+   *   belongs somewhere else.
+   * - **A GRID cell** (`variant="bare"` in a `DataGrid`). A cell that varies with
+   *   its data breaks the row rhythm the grid promises — see the register laws in
+   *   composition.md. Grow on a record surface, reserve in a table.
+   */
+  autoGrow?: boolean;
   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
@@ -46,8 +75,9 @@ export interface InlineTextInputProps {
  * implementation detail.
  */
 export function InlineTextInput(props: InlineTextInputProps) {
-  const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant, actions, numberOfLines } = props;
-  const multiline = (numberOfLines ?? 1) > 1;
+  const { value, onSave, placeholder, controls = "blur", disabled, struck, accessibilityLabel , variant, actions, numberOfLines, autoGrow } = props;
+  // Growing implies wrapping: a field that grows on one line has nowhere to go.
+  const multiline = (numberOfLines ?? 1) > 1 || autoGrow === true;
   const edit = useInlineEdit<string>({ value, onSave });
 
   const onKeyPress = useCallback(
@@ -128,6 +158,7 @@ export function InlineTextInput(props: InlineTextInputProps) {
         onKeyPress={onKeyPress}
         multiline={multiline}
         numberOfLines={numberOfLines}
+        autoGrow={autoGrow}
         placeholder={placeholder}
         accessibilityLabel={accessibilityLabel}
         // `disabled`, NOT `editable`: TextInputField derives editability as

package/src/markdown.css

@@ -60,6 +60,49 @@
   margin: 0;
 }
 
+/*
+ * EMBEDDED — markdown that is a VALUE on someone else's page, not the page.
+ *
+ * The scale above is a document's: `h1` is 24/600, which is exactly a
+ * `SectionHeadingTitle`. That is right when the markdown IS the surface (a
+ * knowledge doc, a terms page) and wrong the moment it is a field on a record,
+ * because the author of the text is then not the author of the page — and
+ * increasingly is not a person at all. A model asked for a call summary writes
+ * `##` headings and liberal `**bold**`, and the page hands them a rung one step
+ * under its own section headings: measured on a real interaction log, a machine
+ * summary inside a feed row drew 18px/600 headings over 44 medium-weight runs,
+ * so the least-trustworthy content on the screen was also the loudest.
+ *
+ * Embedded, every heading collapses to ONE treatment at the body's own size,
+ * one weight step above `strong`. A heading is still legible as a heading —
+ * it owns its line and carries the space around it, which is SHAPE rather than
+ * scale — and it can no longer outrank the surface it was dropped into.
+ */
+.ui-markdown-embedded h1,
+.ui-markdown-embedded h2,
+.ui-markdown-embedded h3,
+.ui-markdown-embedded h4,
+.ui-markdown-embedded h5,
+.ui-markdown-embedded h6 {
+  font-family: Inter_600SemiBold, "apple-system", "BlinkMacSystemFont", "Segoe UI",
+    "Roboto", "Oxygen", "Ubuntu", "Cantarell", "Fira Sans", "Droid Sans",
+    "Helvetica Neue", sans-serif;
+  font-size: 14px;
+  line-height: 20px;
+  font-weight: 600;
+  padding-top: 8px;
+  padding-bottom: 2px;
+}
+
+/* A value never opens with a gap its container did not ask for. */
+.ui-markdown-embedded > :first-child {
+  padding-top: 0;
+}
+
+.ui-markdown-embedded > :last-child {
+  padding-bottom: 0;
+}
+
 /* Block elements */
 
 .ui-markdown p {

package/src/markdown.tsx

@@ -1,5 +1,6 @@
 import { View } from "react-native";
 import { Text } from "./text";
+import type { MarkdownProps } from "./markdown_types";
 
 /**
  * Native fallback. The rich renderer (`markdown.web.tsx`) is react-markdown over
@@ -7,11 +8,16 @@ import { Text } from "./text";
  * native, so this renders the source as plain text. Rich markdown shows on web
  * (custom-code apps + the frontend on web), which is where it's used; the web
  * variant is picked via the conditional `exports` in package.json.
+ *
+ * `variant` is accepted and ignored: plain text has one scale, so there is no
+ * heading to demote. The props type is NOT re-exported — import it from
+ * `@lotics/ui/markdown_types`, the same way `MediaPlayerProps` is reached.
  */
-export function Markdown({ children }: { children: string }) {
+export function Markdown({ children }: MarkdownProps) {
   return (
     <View>
       <Text size="sm">{children}</Text>
     </View>
   );
 }
+

package/src/markdown.web.tsx

@@ -5,11 +5,12 @@ import ReactMarkdown from "react-markdown";
 import { remarkGfmSafe } from "./remark_gfm_safe";
 import { Icon } from "./icon";
 import { colors } from "./colors";
+import type { MarkdownProps } from "./markdown_types";
 
-export function Markdown({ children }: { children: string }) {
+export function Markdown({ children, variant = "document" }: MarkdownProps) {
   return (
     <View>
-      <div className="ui-markdown">
+      <div className={variant === "embedded" ? "ui-markdown ui-markdown-embedded" : "ui-markdown"}>
         <ReactMarkdown remarkPlugins={[remarkGfmSafe]} components={markdownComponents}>
           {children}
         </ReactMarkdown>
@@ -18,6 +19,7 @@ export function Markdown({ children }: { children: string }) {
   );
 }
 
+
 const markdownComponents = {
   table: CopyableTable,
 };

package/src/markdown_types.ts

@@ -0,0 +1,21 @@
+export interface MarkdownProps {
+  children: string;
+  /**
+   * Whose type ladder the headings belong to.
+   *
+   * **`"document"` (default)** — the markdown IS the surface: a knowledge doc, a
+   * terms page, a rendered artifact. Its `h1` is the page's `h1`.
+   *
+   * **`"embedded"`** — the markdown is a VALUE on a page someone else designed:
+   * a field on a record, a summary in a feed row, a note in a drawer. Every
+   * heading collapses to the body's own size so it cannot outrank the section
+   * that contains it.
+   *
+   * **Reach for `"embedded"` whenever the text was not written by whoever built
+   * the screen** — and that is now the common case, because the writer is
+   * routinely a model. A model asked for a summary emits `##` headings and heavy
+   * `**bold**` with no idea what surrounds them, so document scale puts the
+   * least-trustworthy content on the screen at the loudest rung on it.
+   */
+  variant?: "document" | "embedded";
+}

package/src/member_chip.tsx

@@ -36,15 +36,25 @@ interface MemberChipProps {
  */
 export function MemberChip({ name, image, secondary, size = "md", style }: MemberChipProps) {
   const displayName = name?.trim() || "Unknown";
+  // THE TEXT FOLLOWS THE RUNG. `size` used to scale the avatar alone, so a chip
+  // asked for the dense rung got a 24px avatar beside a 14px name — half-dense,
+  // and the mismatch surfaces wherever the chip sits INSIDE a sentence: a 12px
+  // "Logged by" running straight into a 14px name reads as two type systems
+  // meeting mid-phrase, and their line boxes (16 against 20) then refuse to
+  // share a baseline under any `alignItems: "center"`.
+  //
+  // Only `sm` steps down, because only `sm` claims to be dense; every larger
+  // rung keeps the body size, where a person's name belongs.
+  const textSize = size === "sm" ? "xs" : "sm";
   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}>
+        <Text userSelect="none" size={textSize} numberOfLines={1}>
           {displayName}
         </Text>
         {secondary ? (
-          <Text userSelect="none" size="sm" color="zinc-500" numberOfLines={1}>
+          <Text userSelect="none" size={textSize} color="zinc-500" numberOfLines={1}>
             {secondary}
           </Text>
         ) : null}

package/src/text_disclosure.tsx

@@ -0,0 +1,70 @@
+import { Pressable } from "react-native";
+import { TextLink } from "./text_link";
+import type { TextSize } from "./text";
+
+export interface TextDisclosureProps {
+  /** Open state — controlled, because the content it reveals is the caller's. */
+  expanded: boolean;
+  onToggle: (expanded: boolean) => void;
+  /** What is behind it, as a noun: "transcript", "3 earlier replies". The verb
+   *  is supplied — a caller writing its own "Show …" ends up with two vocabularies
+   *  for one control the first time somebody writes "View". */
+  label: string;
+  /** Matches the prose it sits in. Default "sm". */
+  size?: TextSize;
+  /** Announced name, when `label` alone is ambiguous on a page with several. */
+  accessibilityLabel?: string;
+  testID?: string;
+}
+
+/**
+ * An in-prose DISCLOSURE: muted underlined text that reveals adjacent content in
+ * place — a transcript under its player, a long value under its summary.
+ *
+ * The counterpart to {@link TextLink}, and the pair is the point: underlined text
+ * either GOES somewhere or REVEALS something, and the INK says which.
+ *
+ *   blue + `role="link"` (`Link`)   → leaves this surface
+ *   muted underline (this)          → reveals more of it, right here
+ *
+ * Both answer "show me more"; only one takes the reader away, which is the single
+ * question the affordance exists to answer. Anything that MUTATES — saves, sends,
+ * deletes, opens an overlay — carries a control surface instead (`Button` in
+ * chrome, `InlineButton` on a field). See composition.md §"Commit & feedback surfaces".
+ *
+ * **Why this is a component rather than three lines at each call site.** It
+ * carries a contract, and every part of it is a thing a hand-roll gets wrong:
+ *
+ * - **`role="button"`, never `role="link"`.** The obvious reach is `Link`, which
+ *   announces a destination — so a screen-reader user is told they are leaving a
+ *   page that is about to unfold under them.
+ * - **Muted, never blue.** Blue is the promise of a trip. One caller passing the
+ *   navigation ink is all it takes for underline to stop meaning anything.
+ * - **Reveal only.** The exception to "underline navigates" is this narrow, and a
+ *   named component is what keeps it narrow — the next author reaching for quiet
+ *   text to hang a DELETE on finds a name that does not fit.
+ *
+ * **What it is not.** Not `Accordion`: that is a list-row disclosure with a header
+ * and a chevron, right for a run of expandable rows and heavy furniture for a verb
+ * inside one. Not `Button color="muted"`: measured, that is transparent,
+ * borderless and undecorated at rest, so its affordance arrives only on hover —
+ * invisible to keyboard and touch, and against a text column it reads as a label.
+ */
+export function TextDisclosure(props: TextDisclosureProps) {
+  const { expanded, onToggle, label, size = "sm", accessibilityLabel, testID } = props;
+  return (
+    <Pressable
+      onPress={() => onToggle(!expanded)}
+      accessibilityRole="button"
+      // The STATE, announced. Without it a screen reader hears the same words
+      // whichever way the disclosure is sitting.
+      aria-expanded={expanded}
+      accessibilityLabel={accessibilityLabel}
+      testID={testID}
+    >
+      <TextLink size={size} color="muted">
+        {expanded ? `Hide ${label}` : `Show ${label}`}
+      </TextLink>
+    </Pressable>
+  );
+}

package/src/text_link.tsx

@@ -26,9 +26,19 @@ export interface TextLinkProps extends TextProps {
  * The act mode briefly became its own surface-less component and is now gone
  * entirely: it made underline mean two things separable only by ink, and it competed
  * with the `Button` colour ladder for the job `muted` already does. **Underlined text
- * is the NAVIGATION affordance; anything that acts carries a control surface** —
- * `Button` in chrome, `InlineButton` on a field. A quiet verb that cannot sit against
- * a text column belongs in chrome, not in a rung of its own.
+ * GOES somewhere or REVEALS something; anything that MUTATES carries a control
+ * surface** — `Button` in chrome, `InlineButton` on a field.
+ *
+ * The reveal half is the one narrow exception, and this component is how you build
+ * it: an in-prose DISCLOSURE (a transcript under its player, a long value under its
+ * summary) wrapped in your own `Pressable`, `color="muted"` so it never wears the
+ * navigation blue. It exists because the rule used to end "a quiet verb that cannot
+ * sit against a text column belongs in chrome" — and a disclosure cannot go to
+ * chrome, it belongs to the thing above it. The two controls that fit chrome both
+ * fail here: a `muted` Button is transparent and undecorated at rest (a hover-only
+ * affordance), and an `Accordion` is a list row nested inside a list row. The INK is
+ * what keeps underline unambiguous — blue leaves, muted stays. See composition.md
+ * §"Commit & feedback surfaces".
  */
 export function TextLink(props: TextLinkProps) {
   const { icon, href, children, color, style, ...textProps } = props;