@lotics/ui 41.0.1 → 41.3.0

package/docs/templates.md

@@ -241,11 +241,10 @@ screens — register, per-row action, gated selection, and act-on-many in one. T
   - **Linked records** still push an editable screen for that record inside the drawer via the
     hosted `ScreenRouter` — while `canGoBack` the drawer header swaps to a back button + the
     pushed id and the ◀ ▶ sequencer hides; back pops with scroll preserved.
-  - Two things this template no longer demonstrates, so look elsewhere: the drawer does NOT
+  - One thing this template no longer demonstrates, so look elsewhere: the drawer does NOT
     write back to its row (settling a ledger used to flip the register's paid state live — the
-    drawer's money is the record's now), and the CRM call-log shape (outcome pills over a
-    multiline note, an outcome-typed history `Timeline`) went with the Activity section, which
-    the record surface has no counterpart for.
+    drawer's money is the record's now). The communications log lives on the record surface as
+    [`tpl_record`](../examples/tpl_record.tsx) § Activity.
 - **The "Enter data" INTAKE FORK** (the New CTA) — AI FIRST, the form as fallback, one phased
   dialog. The whole register page is ALSO a `<FileDropTarget … paste>` (the whole-surface intake
   standard): a file dropped or Ctrl/Cmd+V pasted ANYWHERE on the register opens this same dialog
@@ -457,11 +456,123 @@ billing, and quick-capture templates. Top → bottom:
   a label-left capture form (auto-stamped date/receipt-no, record-prefilled fields, the
   right input each) whose CTA and produced `FileRow` ride an empty-label `DetailRow` — the
   form-action alignment law (data_entry.md), worked.
-- **No Activity or Handoff section.** Progress owns both: it says where the record SITS and
-  carries the act that moves it, so a second section repeating the handoff — and a `Timeline` of
-  every change beside it — were two more places to look for one answer. What that costs is
-  explicit: the sibling record a handoff creates has no home on this surface, and there is no
-  audit trail. Both belong on the Progress stage that produced them if an app needs them back.
+- **Activity — what was SAID with the other party**, newest first, directly under Progress: the
+  two answer a reader's first two questions in order, where the record stands and what passed
+  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.
+
+  **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
+  they are: all of them answer what-came-of-it, which way, over what, and when. So the four
+  invariants are the row, and the body is a SET OF BLOCKS rather than a shape per kind. A shape
+  per kind writes the same block five times and lets the copies drift, and the sixth kind — the
+  one nobody has thought of — needs a sixth. **Every block is optional and any combination is
+  legal**, because what an entry carries is independent of what it is: a call may arrive as a
+  recording alone, gain a transcript minutes later and a summary after that.
+
+  The blocks, in the order they render (`ActivityBody` in `tpl_record` is the worked one):
+
+  | 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 |
+  | 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 |
+  | 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) |
+  | 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.
+
+  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
+  double-filing a recording are not history, and a feed with no way to remove them accumulates
+  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".
+
+  **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
+  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
+  record or the row already states, and any block whose content the reader can see rendered
+  directly above it.
+
+  **Two of those rows are the whole point of the section on a modern record.** A feed fills from
+  more than one direction — a person, a chat agent, an extraction off an upload, an automation
+  firing on a file — so the surface has to say which values nobody wrote and which a machine did.
+  An entry with no prose renders `placeholder` (see `Timeline`), never a phrase assembled from
+  the enums; and a machine's text is separated from a person's by SHAPE — an attribution line
+  plus a recessed ground — never by a weight nudge. The reasoning and the failure modes are in
+  ai_patterns.md §After the run.
+
+  **The transcript folds, and it reveals in place.** It is the source a summary was made from,
+  read rarely and in full when at all — and the reason anyone opens it is to check a claim the
+  summary made, so a dialog is wrong: it takes the claim off screen at the moment they want to
+  compare. Reveal it whole rather than into a scroll box; a scroller inside a scrolling drawer
+  traps the wheel, and a reader who pressed it asked for the length.
+
+  **The toggle is underlined text, and that is a deliberate exception.** Three controls were
+  tried. `Button color="muted"` measures transparent, borderless and undecorated at rest — the
+  wash arrives only on hover, so the affordance is hover-only (banned in §"Commit & feedback surfaces") and it
+  reads as a stray label between two content blocks. `Accordion` fixes the affordance and
+  overcorrects: it is a LIST-ROW primitive, a full-width header with its own chevron, nested
+  inside a row that already has one. What is left is a muted underlined `TextLink` in your own
+  `Pressable` — visible at rest, on the column's own left edge, and carrying no more weight than
+  the words. The ink keeps underline honest: blue leaves the surface, muted stays on it.
+
+  **Reveal it PLAIN, with no tinted well.** The toggle directly above already says what the text
+  is; a panel would put two identical recessed boxes on one row meaning two different things — a
+  verbatim record and a machine's reading of it. Keep the `Inset` for the machine's.
+
+  **The capture sits AT the feed**, as a `Composer` — compact until typed into. Logging an entry
+  is this section's input, not a distinct AREA of the record, and a section of its own costs a
+  rail entry, which is a claim that there is somewhere else to go.
+
+  **The tail FOLDS, it does not page.** A record's feed is read newest-first and the rest is
+  reference; an unbounded one makes every section below it unreachable by scroll. Show the recent
+  few with a toggle naming how many are behind it — a register pages, a record's feed folds.
+
+  The toggle is a `TextDisclosure`, the same control as the transcript's, because it is the same
+  act: it reveals more of what is already here. A `Button color="muted"` is the reach that feels
+  right and is not — measured, it is transparent, borderless and undecorated at rest, so the
+  affordance only arrives on hover and it reads as a stray line under the feed. It sits on the
+  SECTION's left edge, not the rows': the rows are inset by the disc rail, and at the fold's line
+  the rail has ended, so nothing visible occupies that indent. Same for any other fold on the
+  surface — a document set's "show the rest" is this control too.
+- **No Handoff section.** Progress owns it: it says where the record SITS and carries the act
+  that moves it, so a second section repeating the handoff was one more place to look for one
+  answer. What that costs is explicit: the sibling record a handoff creates has no home on this
+  surface. It belongs on the Progress stage that produced it if an app needs it back.
+
+  **Activity is not that trail, and the line is the SUBJECT.** Activity carries what a person
+  said or sent to a counterparty; the handoff trail carries where the record moved and which
+  field changed. Put desk transitions in Activity and it becomes the audit log this template
+  declined to build — a feed of everything, scanned for nothing.
 
   Recall is the undo: confirmed, it withdraws the sibling, clears the custody stamp that
   handoff wrote, and returns the record to the desk BEFORE it — one step, never a jump to the

package/examples/tpl_item_list.tsx

@@ -49,6 +49,7 @@ import { FileDropTarget } from "@lotics/ui/file_drop_target";
 import { Link } from "@lotics/ui/link";
 import { TextInputField } from "@lotics/ui/text_input_field";
 import type { DisplayFile } from "@lotics/ui/file_thumbnail";
+import { InlineFiles } from "@lotics/ui/inline_files";
 import { InlineSelect } from "@lotics/ui/inline_select";
 import { InlineTextInput } from "@lotics/ui/inline_text_input";
 import { useSelection } from "@lotics/ui/use_selection";
@@ -361,6 +362,7 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
   const [ngayNhan, setNgayNhan] = useState(() => (r ? isoReceived(r.ngayNhan) : ""));
   const [collected, setCollected] = useState(r?.daThu ? "yes" : "no");
   const [fee, setFee] = useState<number | null>(r?.phi ?? null);
+  const [docs, setDocs] = useState<DisplayFile[]>([]);
   if (!r) return null;
   return (
     <>
@@ -380,6 +382,25 @@ function LinkedRecordScreen({ ma }: { ma: string }) {
             <DetailRow label="Fee">
               <InlineNumberInput value={fee} onSave={persist(setFee)} min={0} format={(v) => (v == null ? "" : formatMoney(v))} accessibilityLabel="Fee" />
             </DetailRow>
+            {/* FILES AS A FIELD — the `Inline*` member that used to be missing,
+                so a record's documents got hand-rolled per app as `FileRows` +
+                `pickFiles` + a `Button`, each copy re-deriving the same
+                decisions and usually missing `InlineSlot` (which is what keeps
+                this value column a column rather than two left edges).
+
+                The MANY case: `multiple` defaults true, the CTA becomes
+                "Add document" once something is attached, and the host APPENDS.
+                `tpl_record` shows the single-file case, where the verb is
+                replace — see the table in data_entry.md §InlineFiles. */}
+            <DetailRow label="Documents">
+              <InlineFiles
+                files={docs}
+                onAdd={(picked) => setDocs((p) => [...p, ...toDisplayFiles(picked)])}
+                onRemove={(f) => setDocs((p) => p.filter((x) => x.id !== f.id))}
+                addLabel="Attach document"
+                addMoreLabel="Add document"
+              />
+            </DetailRow>
             <DetailRow label="Collected">
               <InlineSelect
                 value={collected}