@lotics/ui 38.0.0 → 38.1.0

package/AGENTS.md

@@ -118,9 +118,10 @@ CURRENT major only — upgrading an app across majors is `MIGRATION.md`.
   anyway. Use `FileRow` / `FileRows`, where the full name is the row and a second line can
   carry a date, a size, a status, a diff. Photos, scans and drawings are identified by their
   CONTENT — the filename is `IMG_4471.jpg` and tells nobody anything — so use
-  `FileThumbnailGrid`, where the picture is the identity and many fit on one screen. A mixed
-  set follows its majority; an app whose attachments are overwhelmingly paperwork should not
-  pay a grid's wasted space for the occasional photo.
+  `FileThumbnailGrid`, where the picture is the identity and many fit on one screen. **A mixed
+  set follows its MAJORITY, and that one surface holds the whole set — never split a pile by
+  file type** — the cost lands on the minority by design, not on the reader, who would otherwise
+  get two places to look for one thing.
   → [catalog.md](./docs/catalog.md).
 - **A reference to another record is a FIELD** — it wears the inline editor's own resting
   surface and PEEKS its facts on press; EVERY verb lives in the peek's footer as a `Button`,

package/docs/catalog.md

@@ -286,6 +286,21 @@ says the read succeeded and found nothing, a failed read knows neither.
 
 ### Files
 
+**Pick the surface FIRST, and pick exactly one per set.** Documents get a LIST (`FileRows`),
+images get a GRID (`FileThumbnailGrid`) — the discriminator is what identifies the file to the
+person hunting for it: a PDF's thumbnail is a grey page identical to every other grey page, so
+its NAME is the identity; a photo's filename is `IMG_4471.jpg` and tells nobody anything, so its
+CONTENT is. **A mixed pile follows its majority and stays whole.** Sorting one pile by mime type
+into a list *and* a grid is the mistake — it gives the reader two places to look for the same
+thing. The minority is not stranded by this: a non-image tile in a grid renders a `DocumentCard`
+printing its filename, and a photo in a list keeps its full name plus a meta line and is ONE tap
+from the picture, because a `FileRows` row press opens the built-in gallery. (The badge is
+MIME-driven, so that row shows a generic image mark, not the shot itself — which is the cost the
+majority already decided to pay.) A screen showing BOTH surfaces (`tpl_record`) does
+so because it holds two distinct SETS the reader asks different questions of — the paperwork
+that arrived on the record, and the hand-over photos taken against it — not because one set was
+split by type.
+
 `FilesEditor` (THE attachment surface: an upload-aware grid whose bar you COMPOSE — the root
 owns selection + gallery + confirmed remove, the bar pieces and any HOST verb go below it via
 `useFilesEditorSelection`),

package/examples/tpl_record.tsx

@@ -2683,7 +2683,7 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         </Section>
         </View>
 
-        {/* PHOTOS — the same collection, the other SURFACE.
+        {/* PHOTOS — a second SET, and therefore the other SURFACE.
 
             Files above is a row LIST because a shipping document is identified by
             its NAME: a PDF thumbnail is a grey page identical to every other grey
@@ -2693,6 +2693,17 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
             same verbs, different surface, decided by what the reader recognises.
             (AGENTS.md: documents get a LIST, images get a GRID.)
 
+            READ THIS BEFORE COPYING THE SHAPE. Two sections here does NOT mean
+            "sort one pile by mime type into a list and a grid". This record holds
+            two distinct SETS — the paperwork that arrived on it, and the hand-over
+            photos taken against it — which the reader asks different questions of.
+            A SINGLE pile picks ONE surface by its majority and keeps it: the odd
+            .docx among forty phone photos stays in the grid, where it renders a
+            `DocumentCard` printing its filename, and the odd photo among forty
+            PDFs stays in the list, where its row carries the full name and a press
+            opens the gallery. Splitting one set by type would give the reader two
+            places to look for the same thing.
+
             The ADD rides the heading row, right edge, exactly as it does on Files
             and Fees — a section's add sits in the same spot whether the section
             holds nought or forty. Note it is a plain `Button` + `pickFiles`, not

package/package.json

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