@lotics/ui 43.1.0 → 43.3.0

package/MIGRATION.md

@@ -4,6 +4,37 @@ Breaking changes, newest first — normally per major, plus the rare minor that
 anyway (recorded under its exact version). The current contract lives in `AGENTS.md` + `docs/`;
 this file exists only to move an app from one release to the next.
 
+## 43.3.0 — a `bare` inline field sits on the column, and Enter finishes a one-line one
+
+Two fixes to `Inline*`, both of them behaviour a caller cannot see in a prop name.
+
+**A `bare` field now aligns its TEXT, not its box.** The field surface carries 8px
+of horizontal padding, which is invisible at rest on a variant that draws no
+border — so every bare value rendered 8px right of whatever named it. In a
+`DataGrid` that meant each column's values sat off its own header. The inset is
+now bled back out with a negative LEFT margin: glyphs land on the container's
+edge, the hover/focus border overhangs into the gutter, and hover moves nothing.
+
+Left only, deliberately. A matching right bleed aligns nothing on left-aligned
+text and pushes the frame past the edge its neighbours stop at, which shows the
+moment the border paints. **If you compensated with your own negative margin,
+remove it** — you will now be 8px out the other way. A field needs ~8px of slack
+on its left to hover into; in a zero-gap column, adjacent borders will touch. A
+DISABLED `framed` field is unaffected: it drops its border and fill so it cannot
+promise a press, but it stays in line with the enabled fields beside it.
+
+**`numberOfLines` now decides what ENTER does — wrapping no longer does.** The two
+were one flag, so `autoGrow` — a prop about fitting the value — silently turned
+Enter from "save" into "insert a newline". A one-line summary field that grew when
+it ran long became a field you could only leave by clicking away, and nothing at
+the call site said so.
+
+A field left at one line (or `numberOfLines={1}`) holds a single-line value that
+may WRAP, and Enter commits it. Declaring 2+ lines declares PROSE: Enter is a
+paragraph break and blur saves, exactly as before. **If you wrote
+`numberOfLines={1} autoGrow` and relied on Enter inserting a newline, raise the
+line budget** — that is now what says so.
+
 ## 43.0.0 — a time is PICKED, and there is nothing to type
 
 `TimePicker` is no longer a segmented text field. It is the value on a pressable
@@ -78,6 +109,19 @@ its reasoning are in `docs/composition.md` § The pointer cursor. If a component
 needs the pointer, set `CURSOR_ACTION` in its style — and if it is built on the bare
 react-native `Pressable`, note that the pointer is what you get by DEFAULT, from
 react-native-web, unless you set `CURSOR_DEFAULT`.
+## 42.5.0 — an expanded `Timeline` row shows its whole label
+
+The label was clamped to two lines whether the row was open or shut. Expanding a
+row is a request to see more of what is there, so a label that stays truncated
+through it leaves the caller exactly one way to make its own label readable:
+repeat it inside `details`. Then the reader meets the same sentence twice — once
+cut off, once whole — which reads as a rendering bug rather than as disclosure.
+
+It now clamps while collapsed only. **If you duplicated a label into `details`
+to work around this, delete the copy**; the row will show it in full on its own.
+Nothing else changes: a collapsed row is identical, and a row whose label already
+fitted in two lines is identical open or shut.
+
 ## 42.4.0 — `Picker` is named by its `FormField`, and its way back to empty has a name
 
 Two fixes to the same control, both about a thing on screen that the control did

package/docs/catalog.md

@@ -1487,9 +1487,12 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   provider-wired — pass `labels` (`DEFAULT_GANTT_LABELS` is English).
 - **`timeline`** — `Timeline`: a heterogeneous event LOG — per-row icon + expandable
   details; models the past, NOT progress. Three things it decides for you, because a row
-  cannot be trusted to a caller's data: the **label clamps to two lines** (and the
-  description likewise) — a row is a scan target, and an unclamped one lets a single
-  user-authored note set the section's height, so put the full text in `details` too;
+  cannot be trusted to a caller's data: the **label clamps to two lines WHILE COLLAPSED**
+  (the description always) — a row is a scan target, and an unclamped one lets a single
+  user-authored note set the section's height. Opening the row un-clamps it, so **never
+  repeat the label inside `details`**: the fact belongs to one element, and a copy means
+  the reader meets the same sentence twice, cut off and then whole. `details` carries
+  what the label does not — the attachments, the machine's reading, the provenance;
   **`placeholder`** marks a label the SURFACE supplied rather than one the record
   holds, drawing it in the unfilled-field ink — reach for it on any feed that fills
   from more than one direction, where an entry routinely arrives with no words in it;

package/docs/data_entry.md

@@ -84,6 +84,14 @@ layout), click OR keyboard focus opens it for editing **with nothing moving** (z
 whole point), and it commits on blur (Enter saves, Escape reverts) or via `controls="buttons"`
 (✓ / ✕).
 
+**`numberOfLines` declares what ENTER means — wrapping does not.** A field left at one line holds a
+single-line value that may WRAP when it runs long (a title, a summary), and Enter finishes it.
+Declaring 2+ lines declares PROSE: Enter is a paragraph break and blur is what saves. The two used
+to be one flag, so `autoGrow` — a prop about fitting the value — silently turned Enter into a
+newline, and a one-line summary field that grew became a field you could only leave by clicking
+away. Nothing at the call site said so, which is what made it worth separating rather than
+documenting.
+
 **How "nothing moves" is achieved differs by editor, and the difference is a rule.** A field whose
 resting value is the RAW string (`InlineTextInput`) is ONE `<input>` in both states — it never
 swaps elements, and `editing` is a style state driven by focus. Two elements cannot be made to
@@ -277,6 +285,17 @@ already promises and, repeated down a column, draws the grid a second time. Both
 identically, so this changes what a field looks like RESTING, never what it does. A hand-rolled
 pressable cell should match `bare`: nothing at rest, the border on hover — never a background wash.
 
+**A `bare` field aligns its TEXT, not its box.** Because it looks like text at rest, it sits on the
+column like text: the frame's 8px inset is pulled back out with a negative LEFT margin, so the glyphs
+land on the container's edge. Without that, every bare value rendered 8px right of the header naming
+it. The bleed is one-sided on purpose — a matching right bleed aligns nothing on left-aligned text and
+only pushes the frame past the edge its neighbours stop at, which shows the moment the border paints.
+Two consequences for callers: a `bare` field needs ~8px of slack on its LEFT to hover into (in a
+zero-gap column the borders of adjacent cells will touch), and it is the wrong variant for a surface
+where it must stay strictly inside its box — that is `framed`. A DISABLED `framed` field keeps the
+box: it drops the border and fill so it cannot promise a press, but it stays in line with the enabled
+fields beside it.
+
 A READ-ONLY value in the same column — a computed total, a system ID, a synced/locked field — is
 **`InlineStatic`**: it copies the editor box metrics exactly (height, padding, 1px transparent
 border) but stays FLAT and non-interactive, so editable (chip) vs read-only (flat) is legible at a
@@ -331,33 +350,46 @@ row that wants it. See the "General" section of `tpl_record`, which also reads t
 full record surface. Not every field is a same-height swap — a tag field, a status, or an
 attachment grid edit in place too (below).
 
-## When the editor is a MODE instead of a resident field
+## A value rendered TWICE is the bug — not the resident editor
+
+The section above is the default and holds everywhere. There is one thing that appears to
+contradict it, and the contradiction is worth naming because the wrong resolution is the
+tempting one: **a value that already appears elsewhere on the same surface.**
 
-The section above is the default and holds almost everywhere: the value IS the editor, nothing
-moves, and there is no verb to find. It has exactly one exception, and it is decided by a
-question with a factual answer — **does this value already appear somewhere else on the same
-surface?**
+A feed used to be the example. Its row LABEL was the gist, the body opened underneath, and a
+resident editor rendered the same sentence twice — stacked and identical, which reads as a
+mistake at any weight, so quieting the frame does not help. The fix looked like demoting the
+editor to a mode behind an **Edit** verb, and that is a workaround: it keeps the duplication and
+buys silence by hiding one copy behind a click. What it costs shows up immediately after —
+the verb has to live somewhere (a button nested in the row's own button, or a footer a scroll
+away from the sentence it edits), and every repair from there is a repair to the arrangement,
+not to the surface.
 
-On a FEED, it does. A row's identity line is the value, and the body opens under it, so a
-resident editor renders the same sentence twice, stacked and identical. Quieting the frame does
-not help: a sentence appearing twice reads as a mistake at any weight. So the editor becomes a
-mode, reached by an **Edit** verb in the row's trailing slot beside its other actions.
+**Render it once, and the question dissolves.** Text inside a press target cannot be edited where
+it sits, so a value a person WROTE does not belong in a row's label: the label is for derived,
+read-only text ("Stage changed to Won"). Move the prose out and it is an ordinary resident field
+with no mode, no verb, and one copy — `tpl_record`'s activity feed is the worked example, and the
+byline above it carries the derived facts that used to fight it for the row.
 
-**Except when the value is EMPTY, and that half matters more.** There is nothing to duplicate,
-and a surface fed by automations and extractions receives entries with no words in them
-routinely — a recording lands, the row says it has not been written up, and the empty field is
-the invitation to write it. Withhold it there and the feed can RECEIVE an entry it gives the
-reader no way to finish. **An empty value shows its field; a filled one waits to be asked.**
+So: if a resident editor would duplicate a value, **delete the duplicate**. Make the editor a mode
+only when the second appearance is genuinely load-bearing and cannot move.
 
 Two things follow that are easy to get wrong in the other direction:
 
-- **Name the verb for the words, not the row.** "Edit", not "Edit entry" — on a feed the entry
-  is a record of something that happened, and only the prose a PERSON wrote is editable at all.
-  Derived values (a header's participants), verbatim ones (a transcript), artifacts (media,
-  files) and a model's output (a summary — you re-run it, you do not hand-edit it) are all
-  read-only, and a verb naming the whole entry claims otherwise.
-- **One row in edit mode at a time.** Two half-finished sentences on one feed leave the reader
-  unable to say which one the next keystroke lands in.
+- **Only the prose a PERSON wrote is editable.** Derived values (a header's participants),
+  verbatim ones (a transcript), artifacts (media, files) and a model's output (a summary — you
+  re-run it, you do not hand-edit it) are all read-only. If a surface does end up with an edit
+  verb, name it for the words rather than the row: "Edit", not "Edit entry", which claims the
+  whole entry is yours to rewrite.
+- **An EMPTY value still shows its field, and shows it FRAMED.** A surface fed by automations
+  receives entries with no words in them routinely — a recording lands and nobody has written it
+  up — so withholding the field lets a feed RECEIVE an entry it gives the reader no way to
+  finish. Empty is also the state where `bare` fails: grey placeholder text on an invisible box
+  does not read as somewhere you can type. Follow the value — `variant={value ? "bare" : "framed"}`
+  — so a written-up entry reads as prose and an empty one is recognisable as an input from across
+  the page. A button that reveals a field is the wrong trade: `InlineTextInput` has no
+  `autoFocus` (permanently mounted, every field on a record would fight for focus on load), so
+  the revealed field cannot take the caret and the reader pays a second click for less clarity.
 
 ## Fieldset form — fields lay out on a RESPONSIVE two-column grid
 

package/docs/templates.md

@@ -461,12 +461,21 @@ billing, and quick-capture templates. Top → bottom:
   between us to get it there. It is NOT an audit trail and NOT the handoff — see the next bullet
   for the line, which is what keeps this section from becoming the change log Progress refuses.
 
-  **The row's LABEL is the GIST** — what came of the exchange, in the reader's own words. The
-  medium and the direction are metadata on the muted supporting line beneath it. Building it the
-  other way round is the natural mistake and it makes the feed unreadable: every row renders as a
-  pair of enum values ("Outbound Meeting"), the substance sits behind a chevron, and a column of
-  near-identical labels defeats the scan the feed exists for. Measured on a real one, that shape
-  spent 504px of chrome on 70px of content.
+  **The GIST is what the feed is scanned by** — what came of the exchange, in the reader's own
+  words. Building it the other way round is the natural mistake and it makes the feed unreadable:
+  every entry renders as a pair of enum values ("Outbound Meeting"), the substance sits behind a
+  chevron, and a column of near-identical labels defeats the scan the feed exists for. Measured on
+  a real one, that shape spent 504px of chrome on 70px of content.
+
+  **An entry is a COMMENT, not a `Timeline` row.** `Timeline` renders its label inside the row's
+  press target, which is right for derived read-only text ("Stage changed to Won") and wrong for
+  the one thing on an entry a person WROTE — text inside a button cannot be edited where it sits.
+  Four repairs came out of working around that (the verbs moved off the row, the label learned to
+  un-clamp, the body's second copy of the gist came out, and Edit ended up a scroll from the
+  sentence it edits) and none were independent. So the gist is a RESIDENT field and the derived
+  facts sit above it on a muted `xs` **byline** — which way it went, over what, when. Order does
+  not decide the scan; weight does. The byline is small and grey, the prose is `sm` on the page's
+  own ground, and the eye lands on the substance even though it reads second.
 
   **ONE anatomy, a body that VARIES.** An entry can be a call, a recorded demo, an email, a
   message or a note typed between meetings — and those differ in what they CARRY, not in what
@@ -481,25 +490,96 @@ billing, and quick-capture templates. Top → bottom:
 
   | Block | What it is | How it renders |
   |---|---|---|
-  | Participants | ONLY what cannot be derived — a third party who joined, an email's From/To. The record is already the counterparty and the row already says who logged it, so naming the obvious attendees is padding | muted line |
+  | Participants | ONLY what cannot be derived — a third party who joined, an email's From/To. The record is already the counterparty, so naming the obvious attendees is padding | muted line |
   | Subject | the one thing an email has that nothing else does | `sm` medium |
   | Media | the exchange itself, recorded | `MediaPlayer` — **give it a box**, it fills its parent and collapses to nothing without one |
   | Transcript | VERBATIM and long; the source a summary was made from | a muted underlined `TextLink` in your own `Pressable`, revealing PLAIN text — see the disclosure exception in composition.md §"Commit & feedback surfaces" |
-  | Prose | what a PERSON wrote — a note, a counterparty's email | `Markdown variant="embedded"` on the page's own ground |
+  | Prose | what the COUNTERPARTY sent — an email body. Not a second field of ours: an entry offering both a gist and a "note" gives one event two free-text boxes and nothing to tell a writer which to use, and the gist auto-grows, so it already carries whatever length someone wants | `Markdown variant="embedded"` on the page's own ground |
   | AI prose | what a MODEL wrote | ONE short label INSIDE the `Inset` ("AI summary") — floating above it, a 12px muted fragment over a tinted box reads as an orphan. Name the evidence only where it is NOT on screen: over a player the reader can see, "from the recording" is four words restating a video. Let the label replace the block's own `## Heading` rather than sit above it |
-  | Files | what came with it | documents → `FileRow`s (a name identifies them); images → `FileThumbnailGrid` (content does) |
+  | Files | what came with it — EVIDENCE, so it is writable | one `InlineFiles` (`onRemove`, no `onAdd`), mixed pdf/image, previewing in place |
   | Source | where it happened, if openable | `Link` |
-  | Author | who filed it | `MemberChip` for a person; `WaveAvatar` + name for an automation |
-
-  **The verbs — Edit and Delete — live at the BOTTOM of the open body, not in the row's trailing
-  slot.** Three defects came out of putting a control on the label row (a button nested in the
-  row's own button, a fixed-height box to hold it on the first line, and a gap close enough to
-  the chevron to read as one cluster) and every one of them exists only because something
-  interactive shared the row. In the body there is nothing to share with, the verbs sit beside
-  the content they act on, and the expansion the reader already chose IS the look-before-you-
-  delete step — which makes "two clicks" the feature rather than the cost. Provenance sits left
-  on that footer, the verbs right; they are two groups, so space pushes them apart rather than a
-  uniform gap making them peers.
+
+  **An entry's files are WRITABLE, on both paths.** A touchpoint is very often about a document —
+  you sent the quote, they sent the PO back — so a feed that displays `files` but offers no way to
+  file one is a read-only surface over a writable model, which reads as a missing feature every
+  time. Two places, because there are two moments: the section's `Composer` stages them on the
+  entry being logged (`actionsButton` + the `files` slot + `sendDisabled`, the three kit slots the
+  comment thread already used), and the entry's own menu attaches to one that already exists.
+
+  **`sendDisabled` is not optional once a composer can attach.** The default blocks send on empty
+  text, which is right for a message and wrong the moment an attachment is the whole point — "here
+  is the signed PO" needs no sentence. Pass `false` while files are staged, `undefined` otherwise
+  so the default returns.
+
+  **Attaching lives on the MENU, not on the file list.** The list's own CTA cannot work on an entry
+  with nothing attached — there is no list to hang it off — so a menu verb that works in every
+  state is the single path, and the list takes `onRemove` alone. Removing CONFIRMS: that file is
+  already in the customer's history, unlike a staged attachment on the composer, which is not yet
+  anything.
+
+  **An entry is its own `FileDropTarget`**, nested inside the record-level one. A file dropped on a
+  conversation belongs to that conversation; routing it to the record's Documents intake instead
+  leaves the reader to relate the two by hand. Nesting is sound rather than lucky — the component
+  stops propagation on every drag/drop event, so the innermost region wins, the outer one neither
+  fires nor lights, and the file is added once. Pass a plain child so the target paints its own
+  drag affordance: with two live regions the drag has to say WHICH one it is about to land in.
+  Both paths — the menu verb and the drop — call ONE append function, because two implementations
+  of "add to this list" is how one of them quietly becomes a replace. A section earns its own
+  target when the drop MEANS something different there; "the same thing, closer" does not.
+
+  **A MESSAGE's attachments are tiles — staged or filed.** The composer's `files` slot takes
+  `<FileGrid files={…} itemSize={THUMBNAIL_SIZE} onDisplayRemove={…}>` — the exact component and
+  size the product's own chat composer passes — because a staged file is not yet a document in a
+  list: it is a thing you are about to send, checked by LOOKING at it, and the control that
+  unstages it belongs on the tile. Getting this backwards is easy and invisible: a row of staged
+  attachments looks tidy and quietly makes the composer feel like a file manager.
+
+  Filing it does not turn it into a row — it turns it into a `FilesEditor`. Tiles either way, the
+  same as `chat_user_message` renders a posted message's attachments and the same as this record's
+  Files section, because evidence is recognised by LOOKING (a scanned PO, a photo of a seal). The
+  rows belong to a different object: `InlineFiles` is a labelled FIELD in a `DetailRow` ("Signed
+  contract", "Supplier original"), where the document set has a name, a cardinality and a
+  `blockedReason`. Reasoning from that field to a message's attachments is the mistake to avoid —
+  it is not "the filed version of the same thing".
+
+  **A FILED attachment must be hard to lose; a STAGED one is not yet anything.** That is the whole
+  difference between the two components. A bare `FileGrid` draws a ✕ on every tile, one click from
+  gone — right in a composer, wrong on a record's history. `FilesEditor`'s default view never draws
+  one at all: removal means opening the file and doing it from the gallery, where you are looking
+  at the thing you are about to delete and it still asks, naming the file. Reach for the editor and
+  three things you would otherwise hand-roll come with it — the confirmation, the full-screen
+  gallery, and press-to-open.
+
+  **Give it no children unless a toolbar earns its place.** `FilesEditor` renders its bar from its
+  children and nothing without them, and select mode is reachable ONLY from that bar — so omitting
+  it removes the mode rather than stranding it. A feed of eight entries does not want eight
+  toolbars.
+
+  **Never write a tile size as a number.** The kit exports the two that exist — `THUMBNAIL_SIZE`
+  (a composer attachment, a file tile you are meant to recognise) and `COMPACT_THUMBNAIL_SIZE` (the
+  badge on a list row) — and the product uses nothing else. A literal is how a surface ends up at
+  56 or 84 for no reason anyone can reconstruct, looking subtly unlike the same surface elsewhere;
+  the complaint arrives as "why is it smaller here", which is not a question a constant can raise.
+  For a grid that should FILL its container instead, omit `itemSize` and let `minItemWidth` derive
+  the columns — that is a different decision from the tile's size, not a smaller version of it.
+
+  **Copy the component, not the layout mode.** Chat's POSTED attachments use `columns={3}
+  partialRowAlign="end"`; the `partialRowAlign` is there because a chat bubble is right-aligned, so
+  a short last row hugging the end is what lines up. A comment on a record is a left-aligned block
+  and inherits neither. Matching chat means the same component and the same size constant, not
+  transplanting a decision that belongs to a bubble.
+
+  **One list, not the documents/images split.** That split — documents as rows because a name
+  identifies them, images as tiles because content does — holds where files are the SUBJECT (a
+  record's own Files and Photos sections). An entry's files are a small mixed set of evidence
+  identified by what they are, which is the shape the fee ledger's "Supplier original" already
+  uses: one `InlineFiles` taking `application/pdf,image/*`.
+
+  **Delete is the only verb on the entry itself, and it sits in an `ActionMenu` at the TOP RIGHT.** Edit
+  stopped existing the moment the gist became a resident field — the fix that removes a control
+  beats the one that relocates it — and what remains goes where every comment surface puts it,
+  beside the byline rather than in a footer a scroll below the sentence it acts on. The menu is a
+  SIBLING of the content, so nothing nests a button inside another.
 
   Delete belongs there DESPITE the feed being a record — because of what a multi-writer feed
   actually produces. An extraction filing against the wrong contact and an automation
@@ -507,15 +587,38 @@ billing, and quick-capture templates. Top → bottom:
   garbage it also asks you to trust. Name what leaves with the entry in the confirmation: a
   count somewhere else is the part nobody expects.
 
-  Only the GIST and the note are editable — everything else is derived, verbatim, an artifact or
-  a model's output. The editor is a MODE behind an **Edit** verb rather than a resident field,
-  because the gist is already the row's label and a resident one renders it twice; an EMPTY gist
-  shows its field regardless, because that is the write-up path for an entry an automation filed.
-  The rule and its two corollaries are in data_entry.md §"When the editor is a MODE instead of a
-  resident field".
+  Only the GIST is editable — everything else is derived, verbatim, an artifact or a model's
+  output, and a counterparty's own email body is a record of what THEY said for the same reason a
+  transcript is not editable. It is resident, with no mode and no verb, and it follows the value:
+  `bare` once written up so it reads as prose, `framed` while empty so it is recognisable as an
+  input. Both halves are in data_entry.md §"A value rendered TWICE is the bug".
+
+  **NO AUTHOR on an entry.** A recording is made by the people in the meeting and merely
+  transcribed by a service, so a byline reading "Recording bot" names the plumbing and fabricates
+  an author for somebody else's conversation. Once that shape is refused, showing an author on the
+  entries that happen to have one is worse than showing none — the reader learns only that we
+  attribute when we can, which is a fact about the pipeline. The record has an Owner; a customer's
+  history does not restate it once per entry. What a machine actually TOUCHED stays visible where
+  it changes how you read something: the `Inset` names an "AI summary", a transcript is labelled
+  verbatim. That is attribution of the CONTENT, which is the only kind that was load-bearing.
+
+  **The blocks SHOW; they are not folded behind a disclosure.** They are what the entry IS, and a
+  control that hides them makes the reader click to discover what the entry already says is there
+  — on every entry, forever. The fold that used to sit here was defended as "each is tall enough to
+  bury the next entry", which measurement did not support: an audio player is 54px and a file tile
+  row is 96, so hiding one behind a 20px disclosure buys 34px and costs a click. A video is the
+  honest counter-case at 358px and it still shows — it is the most informative thing on a recorded
+  call, the feed folds its own tail, and the byline and gist stay at the top of every entry, so the
+  scan survives a tall one.
+
+  **The TRANSCRIPT keeps its disclosure, and it is the only one.** It is the one block that is
+  unbounded by nature — a machine's verbatim record of half an hour — and the one nobody reads
+  straight through: you open it to check a claim the summary above made. That is what a disclosure
+  is for. An email BODY is prose of unknown length too and still shows, because it is human-written,
+  ordinarily short, and it IS the message rather than the source behind one.
 
   **A block earns its place by carrying what nothing else on the row does.** The failure is not
-  a missing block, it is three blocks saying one thing: a participants line, a rep's note and a
+  a missing block, it is three blocks saying one thing: a participants line, a rep's gist and a
   machine summary all reporting that the spreadsheet owner was absent. When the summary is good
   the rep usually adds nothing, and an entry with no note is the normal case rather than an
   incomplete one. Cut on sight: a label above a block that already labels itself, a fact the