@lotics/ui 46.12.0 → 46.13.0

package/docs/catalog.md

@@ -125,6 +125,28 @@ someone wants `md`. Initials are the first and **last** word of the name — "V
 Watson" → MW — because a Vietnamese name's first two words are the family and middle names
 that a whole office shares.
 
+### Several THINGS in one cell — `ThumbnailStack`
+
+`ThumbnailStack` is `AvatarGroup`'s sibling over a different subject: a capped, overlapping set
+of PICTURES answering "an order of what?", "which parts?", "what arrived?" in one register cell.
+Pass `{ id, label, image }` per thing; `max` (default 3) caps it and the rest become the `+N`
+mark at the end of the stack. Both components read their separating edge from `mark_stack.ts`,
+so a row carrying people in one column and goods in the next reads as one device used twice
+rather than two — but they **tuck by different fractions, and that is deliberate**: a face is
+edge-anchored and survives being covered two thirds of the way, while a product shot centres its
+subject in studio margin, so the facepile's ratio lands the remainder on top of the last
+photograph. Both ratios live in `mark_stack.ts` beside each other, with the reason.
+
+What differs from a facepile follows from a thing not being a person: the marks are ROUNDED
+SQUARES (round is the shape the kit spends on a face), and there is **no initials fallback** —
+"CA" is not a stand-in for a bag of coffee, so a thing with no picture renders a neutral
+placeholder and its `label` carries the meaning to a screen reader. Inert, like the facepile:
+its home is a pressable row and it must not hold a second destination.
+
+**Reach for it wherever a row states a COUNT of things it could show instead.** A register whose
+rows carry a bare number reads as a ledger of nothing in particular; the pictures are the row's
+own data, and they say what the business is before a word is read.
+
 ### A select-field value
 
 `OptionBadge` (a stored `select` value as its CONFIGURED colored badge) — never hand-map
@@ -691,6 +713,19 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`group_avatar`** — `GroupAvatar`: a name's initials in a zinc rounded square (`size` — the
   same rung scale AND the same initials rule as `Avatar`, default `md`); the avatar for
   image-less entities — groups, organizations. A person → `Avatar`/`MemberChip`.
+- **`thumbnail_stack`** — `ThumbnailStack`: the same capped stack over THINGS rather than
+  parties — a set of product, document or unit pictures answering "an order of what?" in one
+  register cell. Takes `{ id, label, image? }`, shows `max` (default 3) and makes the rest the
+  `+N` mark at the END of the stack. Rounded squares, not discs, and **no initials fallback**: a
+  name is a fair stand-in for a face and a useless one for a bag of coffee, so a picture-less
+  thing renders a neutral placeholder while its `label` carries the meaning to a screen reader.
+  Marks `announce` (the stack shows no text) and it is INERT, for the same reason the facepile
+  is. Reach for it wherever a row states a COUNT of things it could show instead.
+- **`mark_stack`** — the constants a capped stack of marks is built from: `MARK_RING` (the
+  translucent separating edge, shared, so the two stacks read as one device) plus a tuck ratio
+  EACH — `MARK_OVERLAP_RATIO` for faces and the shallower `THUMBNAIL_OVERLAP_RATIO` for things,
+  because a face survives being covered two thirds of the way and a centred product shot does
+  not. They sit together so the difference reads as a decision rather than a typo.
 - **`avatar_group`** — `AvatarGroup`: a SET of parties as overlapping marks — "who is on this" in
   one cell. Takes `{ id, name, kind: "person" | "group", image? }`, shows `max` of them (default
   3) and makes the rest a `+N` that is the LAST MARK IN THE STACK, not loose text beside it.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lotics/ui",
-  "version": "46.12.0",
+  "version": "46.13.0",
   "type": "module",
   "exports": {
     "./accordion": "./src/accordion.tsx",
@@ -171,6 +171,7 @@
     "./list_item": "./src/list_item.tsx",
     "./loading": "./src/loading.tsx",
     "./locale": "./src/locale.tsx",
+    "./mark_stack": "./src/mark_stack.ts",
     "./markdown": {
       "react-native": "./src/markdown.tsx",
       "default": "./src/markdown.web.tsx"
@@ -279,6 +280,7 @@
       "react-native": "./src/theme.ts",
       "default": "./src/theme.web.ts"
     },
+    "./thumbnail_stack": "./src/thumbnail_stack.tsx",
     "./time_columns": "./src/time_columns.tsx",
     "./time_options": "./src/time_options.ts",
     "./time_picker": "./src/time_picker.tsx",

package/src/avatar_group.tsx

@@ -5,6 +5,7 @@ import { Text } from "./text";
 import { AVATAR_PX, AVATAR_TEXT, type AvatarSize } from "./avatar_size";
 import { colors } from "./colors";
 import { useLoticsLocale } from "./locale";
+import { MARK_OVERLAP_RATIO, MARK_RING } from "./mark_stack";
 
 /** One party in the set. A PERSON takes the disc; a group or an organization
  *  takes the rounded square, which is `Avatar`'s own shape axis and the one
@@ -25,34 +26,6 @@ export interface AvatarGroupPrincipal {
  *  separable at a glance and a number is the more honest summary. */
 const DEFAULT_MAX = 3;
 
-/**
- * How far each mark tucks under the one before it, as a fraction of the rung.
- *
- * A FRACTION, not a pixel constant, so the stack is the same object at every
- * rung — a fixed inset barely stacks at `lg` and eats the marks at `sm`. Just
- * under a third leaves each mark's whole leading edge, which is as much of an
- * image or a pair of initials as the reader needs to tell the parties apart.
- */
-const OVERLAP_RATIO = 0.3;
-
-/**
- * The hairline separating each mark from the one it covers.
- *
- * TRANSLUCENT INK, never the surface colour — and that is what lets this
- * component overlap at all. The conventional facepile rings each mark in the
- * page background so the discs read as separate, which binds the ring to a
- * colour the row does not keep: a register row washes to `zinc[50]` on hover,
- * `zinc[100]` as the open record and `zinc[200]` while pressed, so a white
- * ring is a halo in three of the four states — and those are the states a
- * reader is in when they are actually looking at the row. A translucent dark
- * edge DARKENS whatever is behind it instead of matching it, so it holds on
- * every ground. `FileBadge` separates itself from its own surface the same way.
- *
- * A `boxShadow` rather than a border, because a border grows the box: a stacked
- * mark would render 2px wider than the identical mark in the next column.
- */
-const MARK_RING = "0 0 0 1px rgba(0,0,0,0.12)";
-
 /**
  * A SET of parties as marks — the answer to "who is on this" in one cell.
  *
@@ -116,7 +89,7 @@ export function AvatarGroup(props: AvatarGroupProps) {
   const shown = principals.slice(0, max);
   const hidden = principals.length - shown.length;
   const px = AVATAR_PX[size];
-  const overlap = Math.round(px * OVERLAP_RATIO);
+  const overlap = Math.round(px * MARK_OVERLAP_RATIO);
   // Descending, so the FIRST mark ends up on top. The remainder is one more
   // thing to lay under, hence its own slot in the depth.
   const depth = shown.length + (hidden > 0 ? 1 : 0);

package/src/mark_stack.ts

@@ -0,0 +1,54 @@
+/**
+ * The two constants a capped stack of marks is built from.
+ *
+ * They live here, side by side, because there are two stacks — a set of PARTIES
+ * (`avatar_group`) and a set of THINGS (`thumbnail_stack`) — and the decision
+ * each constant encodes is only legible NEXT TO the other one. The edge is
+ * shared: a stack that separated itself differently would read as a second
+ * device rather than as the same one over a different subject. The tuck is NOT,
+ * and the two ratios sitting together is what stops the difference looking like
+ * a typo in one of them.
+ */
+
+/**
+ * How far one FACE tucks under the one before it, as a fraction of the rung.
+ *
+ * A FRACTION, not a pixel constant, so the stack is the same object at every
+ * rung — a fixed inset barely stacks at `lg` and eats the marks at `sm`. Just
+ * under a third leaves each mark's whole leading edge, which is as much of an
+ * image or a pair of initials as the reader needs to tell the marks apart.
+ */
+export const MARK_OVERLAP_RATIO = 0.3;
+
+/**
+ * The same tuck, for a stack of THINGS — and it is deliberately shallower.
+ *
+ * A face is edge-anchored: hair, a jaw, a colour, all readable from the leading
+ * third, which is what lets a facepile overlap so hard. A product shot is the
+ * opposite — the subject is CENTRED with studio margin around it, so a third of
+ * the tile is exactly the part that carries the object. At the face ratio the
+ * remainder lands on top of the last photograph and reads as covering it rather
+ * than as following it, which is the one thing the mark must not do: it is a
+ * statement ABOUT the set, not a member of it competing for the same glance.
+ *
+ * Shallow rather than zero, because the marks still have to read as one object.
+ */
+export const THUMBNAIL_OVERLAP_RATIO = 0.15;
+
+/**
+ * The hairline separating each mark from the one it covers.
+ *
+ * TRANSLUCENT INK, never the surface colour — and that is what lets a stack
+ * overlap at all. The conventional facepile rings each mark in the page
+ * background so the marks read as separate, which binds the ring to a colour
+ * the row does not keep: a register row washes to `zinc[50]` on hover,
+ * `zinc[100]` as the open record and `zinc[200]` while pressed, so a white ring
+ * is a halo in three of the four states — and those are the states a reader is
+ * in when they are actually looking at the row. A translucent dark edge
+ * DARKENS whatever is behind it instead of matching it, so it holds on every
+ * ground. `FileBadge` separates itself from its own surface the same way.
+ *
+ * A `boxShadow` rather than a border, because a border grows the box: a stacked
+ * mark would render 2px wider than the identical mark in the next column.
+ */
+export const MARK_RING = "0 0 0 1px rgba(0,0,0,0.12)";

package/src/thumbnail_stack.tsx

@@ -0,0 +1,151 @@
+import { Image, View, type StyleProp, type ViewStyle } from "react-native";
+import { Icon } from "./icon";
+import { Text } from "./text";
+import { AVATAR_PX, AVATAR_TEXT, type AvatarSize } from "./avatar_size";
+import { colors } from "./colors";
+import { useLoticsLocale } from "./locale";
+import { MARK_RING, THUMBNAIL_OVERLAP_RATIO } from "./mark_stack";
+
+/** One THING in the set — a product, a document, a unit. Not a party: a thing
+ *  has no initials worth reading, so it is its picture or it is a placeholder. */
+export interface ThumbnailStackItem {
+  /** Stable identity — the React key. */
+  id: string;
+  /** What the thing is, for the screen reader. The stack shows no text. */
+  label: string;
+  /** The thing's own picture. Absent renders the neutral placeholder. */
+  image?: string | null;
+}
+
+/** Three reads as "a few"; past that the pictures stop being separable at a
+ *  glance and a number is the more honest summary. Same default as a facepile,
+ *  for the same reason. */
+const DEFAULT_MAX = 3;
+
+/**
+ * A SET of THINGS as pictures — the answer to "an order of what?" in one cell.
+ *
+ * The sibling of `AvatarGroup`, over a different subject. The two share their
+ * separating edge (`mark_stack.ts`) so a row carrying both reads as one device
+ * used twice. What differs is everything that follows from a thing not being a
+ * person — including how hard they tuck:
+ *
+ * **A shallower overlap.** A face is edge-anchored and survives being covered
+ * two thirds of the way; a product shot centres its subject in studio margin,
+ * so the face ratio puts the remainder on top of the last photograph. Both
+ * ratios live in `mark_stack.ts` beside each other, with the reason.
+ *
+ * **Square, not round.** Round is the shape the kit spends on a person's face.
+ * A rounded square is what `Avatar` already gives an organization, and a crate
+ * of goods belongs on that side of the axis.
+ *
+ * **No initials.** `Avatar` falls back to a person's initials because a name is
+ * a reasonable stand-in for a face. "CA" is not a stand-in for a bag of coffee
+ * — it is noise wearing the shape of information — so a thing with no picture
+ * renders a neutral placeholder that says only "something is here", and the
+ * label carries the meaning to anyone listening.
+ *
+ * **The remainder is the last mark IN the stack**, not text after it: `+9`
+ * trailing the pictures as loose type reads as a separate fact about the row
+ * instead of as the rest of this one.
+ *
+ * **It is INERT.** Its home is a register row, and a row that already presses
+ * must not hold a second destination four pixels to the left.
+ *
+ * **It caps what it was GIVEN.** The overflow counts from what will actually
+ * render, so `+9` never counts a mark the reader can see is missing. Drop what
+ * you cannot show before you pass it in.
+ *
+ * Pure: pass resolved labels and image urls; this fetches nothing.
+ */
+export interface ThumbnailStackProps {
+  items: readonly ThumbnailStackItem[];
+  /** Pictures shown before the remainder becomes `+N`. Default 3. */
+  max?: number;
+  /**
+   * A rung on the shared avatar scale — the same scale the marks in the
+   * neighbouring columns take, so a row of goods and a row of people sit on one
+   * beat. Everything inside derives from it; nothing here is a fixed pixel.
+   */
+  size?: AvatarSize;
+  style?: StyleProp<ViewStyle>;
+  testID?: string;
+}
+
+export function ThumbnailStack(props: ThumbnailStackProps) {
+  const { items, max = DEFAULT_MAX, size = "md", style, testID } = props;
+  const locale = useLoticsLocale();
+
+  if (items.length === 0) return null;
+
+  const shown = items.slice(0, max);
+  const hidden = items.length - shown.length;
+  const px = AVATAR_PX[size];
+  const overlap = Math.round(px * THUMBNAIL_OVERLAP_RATIO);
+  const radius = Math.round(px * 0.2);
+  // Descending, so the FIRST picture ends up on top and the remainder lies
+  // under everything rather than covering one of the things it is counting.
+  const depth = shown.length + (hidden > 0 ? 1 : 0);
+
+  return (
+    <View testID={testID} style={[{ flexDirection: "row", alignItems: "center" }, style]}>
+      {shown.map((item, index) => (
+        <View
+          key={item.id}
+          accessible
+          accessibilityLabel={item.label}
+          style={{
+            width: px,
+            height: px,
+            marginLeft: index === 0 ? 0 : -overlap,
+            // `zIndex` needs a positioned box to take effect in
+            // react-native-web; without it the marks stack in DOM order.
+            position: "relative",
+            zIndex: depth - index,
+            borderRadius: radius,
+            overflow: "hidden",
+            backgroundColor: colors.zinc["100"],
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: MARK_RING,
+          }}
+        >
+          {item.image ? (
+            <Image
+              source={{ uri: item.image }}
+              style={{ width: px, height: px }}
+              resizeMode="cover"
+              accessibilityIgnoresInvertColors
+            />
+          ) : (
+            <Icon name="package" size={Math.round(px * 0.5)} color={colors.zinc["400"]} />
+          )}
+        </View>
+      ))}
+      {hidden > 0 && (
+        <View
+          accessible
+          accessibilityLabel={locale.avatar.more(hidden)}
+          style={{
+            width: px,
+            height: px,
+            marginLeft: shown.length === 0 ? 0 : -overlap,
+            position: "relative",
+            zIndex: 0,
+            borderRadius: radius,
+            backgroundColor: colors.zinc["100"],
+            alignItems: "center",
+            justifyContent: "center",
+            boxShadow: MARK_RING,
+          }}
+        >
+          {/* The rung's own type — a fixed size here is how a stack ends up
+              with a 14px count beside 12px marks. */}
+          <Text size={AVATAR_TEXT[size]} weight="medium" color="zinc-700" aria-hidden>
+            {`+${hidden}`}
+          </Text>
+        </View>
+      )}
+    </View>
+  );
+}