@lotics/ui 28.1.0 → 28.2.1

package/MIGRATION.md

@@ -4,6 +4,26 @@ 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.
 
+## 28.2.0 — `SubsectionHeadingTitle` takes a `description`
+
+Additive; nothing to change. The heading ramp's three rungs are meant to carry the SAME slots
+and differ only in type size — `description` was missing from the middle one, so a group that
+needed a muted line under its title had to borrow the section rung above it or hand-roll a
+`Text` off the ramp.
+
+It matters most where a GROUP receives something. A `FileDropTarget`-wrapped region shows no
+dropzone, so `AGENTS.md` requires the heading to name the drag and paste paths — and a surface
+with several PEER file regions (per-kind photo buckets, each its own target, because nothing in
+a dropped file says which bucket it belongs to) carries those regions at subsection rung:
+
+```tsx
+<SubsectionHeading>
+  <SubsectionHeadingTitle description="Kéo, dán hoặc bấm để thêm ảnh">Ảnh hạ</SubsectionHeadingTitle>
+</SubsectionHeading>
+```
+
+The rung is unchanged (`###`, lg semibold, level 3) — only the slot is new.
+
 ## 28.1.0 — `ChecklistItem` can announce more than its title
 
 Additive; nothing to change. `accessibilityLabel` overrides the row's accessible name, which

package/docs/catalog.md

@@ -451,13 +451,17 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   (16, fixed), no body component. `SectionHeadingTitle` is ALWAYS `##` (xl semibold;
   `weight="medium"` opt-down only) + `info` for an ⓘ provenance popover after the title,
   same as `CardHeaderTitle.info`. `SubsectionHeadingTitle` is the `###` lg-semibold level-3
-  title of a named group inside a section (same `info` ⓘ affordance as the section title) —
-  heading-row siblings ride its right edge. **A section's ADD is one of those siblings** — a
+  title of a named group inside a section (same `info` ⓘ AND `description` slots as the section
+  title) — heading-row siblings ride its right edge. Its `description` is what a files
+  SUBSECTION uses to name its drag/paste paths: a `FileDropTarget`-wrapped region shows no
+  dropzone, and a surface with several peer file regions (per-kind photo buckets, each its own
+  target) carries that line at THIS rung, not the section above it. **A section's ADD is one of those siblings** — a
   `primary` `Button` beside the title, rendered whether the collection is empty or full, never
   under the rows it extends and never repeated in the `EmptyState`
   (composition.md § The add-placement law). `DialogSectionHeadingTitle` is the `####`
   md-semibold rung with the SAME `icon`/`description`/`info` slots as the section title, so a
-  dialog surface loses only the type size, never an affordance. The heading ramp is FIXED:
+  dialog surface loses only the type size, never an affordance. **`description` is on every
+  rung** — the ramp's slots do not vary by level; only the type size does. The heading ramp is FIXED:
   `#` xxl / `##` xl / `###` lg / `####` md, no size props.
 - **`section_stack`** — `SectionStack`, `SubsectionStack` — stacks that own the
   between-block law, skipping null children: `SectionStack` = a fixed 56px beat + a hairline

package/docs/composition.md

@@ -46,7 +46,10 @@ restyle a heading level per-page.
   (`##` — xl semibold, optional muted `description` and `info` popover), everything left-aligned
   at the column edge; `SectionHeadingMeta`, any VIEW control, and the section's own ADD ride the
   heading row's right edge (the title's `flex: 1` pushes them) — see the add-placement law
-  below. The page column is a **`SectionStack`** — it owns the
+  below. A COUNT earns that slot only when what it counts is not fully on screen — collapsed,
+  paged, or long enough that the reader would have to scan to know. Over a list or thread
+  rendered whole directly beneath its own heading it restates what is already in view, and the
+  heading reads busier for it. The page column is a **`SectionStack`** — it owns the
   between-section law (a fixed 56px beat + a bare hairline separating one section from the NEXT;
   null/false children are skipped so a conditional section never leaves a stray hairline). The
   `Divider` NEVER goes directly under a heading — that orphans the title from its own content.
@@ -64,8 +67,11 @@ restyle a heading level per-page.
   stays ABSOLUTE — this is one more fixed size, never a `size`/`compact` knob on a rung above.
 - **Subsection title** — the level BELOW a section on a long record surface: `Subsection` ›
   `SubsectionHeading` › `SubsectionHeadingTitle` (`###` — lg semibold, with the same `info` ⓘ
-  affordance as `SectionHeadingTitle`; siblings — a `Badge`, a
-  `SectionHeadingMeta`, an action — ride the heading row's right edge). Sibling subsections stack
+  and `description` slots as `SectionHeadingTitle`; siblings — a `Badge`, a
+  `SectionHeadingMeta`, an action — ride the heading row's right edge). Reach for its
+  `description` when the GROUP is what receives something — a files subsection wrapped in its
+  own `FileDropTarget` has to name drag and paste itself, since a wrapped region shows no zone
+  and the section above it may hold several such groups. Sibling subsections stack
   in a **`SubsectionStack`** (a fixed 32px beat; no margins, no hand-rolled dividers).
   It is SPACE-ONLY while the groups are SHORT — the titles carry the grouping and hairlines
   belong to the SECTION level, one rule per altitude — and takes `divided` once the groups run

package/examples/tpl_record.tsx

@@ -12,7 +12,7 @@ import type { PickerOption } from "@lotics/ui/picker";
 import { Combobox, ComboboxInput, ComboboxContent } from "@lotics/ui/combobox";
 import { DetailRow, DetailTable } from "@lotics/ui/detail_row";
 import { Callout, CalloutText } from "@lotics/ui/callout";
-import { Section, SectionHeading, SectionHeadingMeta, SectionHeadingTitle, Subsection, SubsectionHeading, SubsectionHeadingTitle } from "@lotics/ui/section_heading";
+import { Section, SectionHeading, SectionHeadingTitle, Subsection, SubsectionHeading, SubsectionHeadingTitle } from "@lotics/ui/section_heading";
 import { SectionStack, SubsectionStack } from "@lotics/ui/section_stack";
 import { Checklist, ChecklistActions, ChecklistGroup, ChecklistItem, ChecklistNote } from "@lotics/ui/checklist";
 import { DateStamp } from "@lotics/ui/date_stamp";
@@ -2381,9 +2381,13 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         {!wide ? (
           <View onLayout={nav.register("comments")}>
           <Section>
+            {/* No count. The thread is RIGHT THERE — the number restates what
+                the reader is already looking at, and it is the kind of meta that
+                earns its place only when the thing it counts is collapsed, or
+                off-screen, or expensive to scan. None of those hold for a
+                discussion rendered in full directly beneath its own heading. */}
             <SectionHeading>
               <SectionHeadingTitle description="Notes on this record — everyone with access sees them.">Comments</SectionHeadingTitle>
-              <SectionHeadingMeta>{`${comments.length} ${comments.length === 1 ? "comment" : "comments"}`}</SectionHeadingMeta>
             </SectionHeading>
             {commentsThread}
           </Section>
@@ -2626,9 +2630,9 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
                 the verb is off-screen entirely, and on an empty list there is no
                 last row to sit under, so it had to be a SECOND button inside the
                 `EmptyState`. One verb, two renderings, neither findable without
-                scanning. The heading row is the section's control line — it
-                already carries `SectionHeadingMeta` and the title grows to push
-                its siblings right — so the add belongs on it, in the same spot
+                scanning. The heading row is the section's control line — where a
+                section's meta and verbs sit, with the title growing to push its
+                siblings right — so the add belongs on it, in the same spot
                 whether the list holds nought or forty. */}
             <Button title="Add fee" color="primary" onPress={addFee} />
           </SectionHeading>
@@ -3632,13 +3636,12 @@ export function TplRecord({ chrome = "page", code = "RC-2026-0418", openSection
         {/* The panel is a PEER of the sections beside it, not a widget, so its
             title takes the ramp's section rung rather than a hand-picked size —
             and it takes the WHOLE construct. `SectionHeadingTitle` carries
-            `flex: 1` so it can push meta to a heading row's right edge; dropped
-            straight into this column it grows VERTICALLY instead and starves the
-            thread beneath it. The row wrapper is what makes that flex mean what
-            it was written to mean. */}
+            `flex: 1` so it can push a heading row's trailing content to the right
+            edge; dropped straight into this column it grows VERTICALLY instead
+            and starves the thread beneath it. The row wrapper is what makes that
+            flex mean what it was written to mean. */}
         <SectionHeading>
           <SectionHeadingTitle>Comments</SectionHeadingTitle>
-          <SectionHeadingMeta>{`${comments.length} ${comments.length === 1 ? "comment" : "comments"}`}</SectionHeadingMeta>
         </SectionHeading>
         {/* The panel's OWN scroller, so a long thread scrolls inside itself and
             never lengthens the record. The thread inside it is the same one the

package/package.json

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

package/src/section_heading.tsx

@@ -87,6 +87,17 @@ export function SubsectionHeading(props: SubsectionHeadingProps) {
 
 export interface SubsectionHeadingTitleProps {
   children: React.ReactNode;
+  /**
+   * Muted line under the title, as on the rungs either side of this one.
+   *
+   * The ramp carries the same slots at every rung, and this was the one gap in
+   * it. It matters most for a group that RECEIVES something: a files region
+   * wrapped in a `FileDropTarget` shows no dropzone, so drag and paste are
+   * invisible unless the heading names them — and a surface with several peer
+   * file regions (per-kind photo buckets, each its own drop target) puts them at
+   * THIS rung, where the prescribed line previously had nowhere to sit.
+   */
+  description?: string;
   /** Heading rank. Defaults to 3 — one level under `SectionHeadingTitle`'s 2. */
   level?: HeadingLevel;
   /** An ⓘ popover after the title — a short "what this is / where it came from"
@@ -98,14 +109,25 @@ export interface SubsectionHeadingTitleProps {
  * xl section title and above the md/sm body. Grows to push siblings (a
  * `SectionHeadingMeta`, a `Badge`, an action) to the right edge. */
 export function SubsectionHeadingTitle(props: SubsectionHeadingTitleProps) {
-  const { children, level = 3, info } = props;
+  const { children, description, level = 3, info } = props;
   const words = useLoticsLocale();
+  // Same anatomy as `SectionHeadingTitle` one rung down: the title row keeps its
+  // own `flexDirection: "row"` so `info` sits beside the text, and the column
+  // wrapper carries the `flex: 1` that lets a heading row push meta to its right
+  // edge. Without the wrapper the description would land on the title's LINE.
   return (
-    <View style={{ flex: 1, flexDirection: "row", alignItems: "center", gap: 6 }}>
-      <Text level={level} size="lg" weight="semibold">
-        {children}
-      </Text>
-      {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
+    <View style={{ flex: 1, gap: 2 }}>
+      <View style={{ flexDirection: "row", alignItems: "center", gap: 6 }}>
+        <Text level={level} size="lg" weight="semibold">
+          {children}
+        </Text>
+        {info ? <InfoPopover text={info} accessibilityLabel={words.sectionHeading.info} /> : null}
+      </View>
+      {description ? (
+        <Text color="zinc-500" size="sm">
+          {description}
+        </Text>
+      ) : null}
     </View>
   );
 }