@lotics/ui 44.2.0 → 44.4.0

package/MIGRATION.md

@@ -4,6 +4,29 @@ 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.
 
+## 44.4.0 — `MemberChip`'s `marker` is gone
+
+A minor that broke a type, recorded here under its exact version rather than held
+for a major: `marker` existed for one release, had a single consumer inside the
+kit, and underlined the chip's name to say "this opens something".
+
+Delete the prop. A chip that opens something is a `MemberPeek`, which now carries
+its own affordance through the trigger's control-band surface — the underline was
+decorating the text to describe the container.
+
+```tsx
+// before
+<MemberChip name={m.name} marker />
+
+// after
+<MemberPeek name={m.name} identity={m.email} groups={m.groups} />
+```
+
+A chip carrying `secondary` also takes a larger mark now (`lg` rather than the
+requested `md`), because two lines of text stand taller than a 28px avatar. Single
+-line chips are unchanged. Nothing to do — but a layout that hard-coded 28px
+beside a two-line chip will need the number.
+
 ## 44.0.0 — `Finding` is horizontal, and `FindingComparison` is gone
 
 `Finding` stacked six blocks — badge, title, detail, a labelled row per side, a hairline, the

package/docs/ai_patterns.md

@@ -108,6 +108,7 @@ Key props (full API: `../src/composer.tsx`):
 | `footerRight` | Footer-right content before Send (a model picker); forces expanded |
 | `maxLines` | Expanded growth cap before the input scrolls (default 10) |
 | `sendLabel` / `stopLabel` | Accessible/tooltip labels (default English "Send"/"Stop" — pass translations) |
+| `highlightRanges` | Character ranges of `value` to tint. What a range MEANS is yours — the composer paints a ground behind those characters and nothing more. It renders a mirror BEHIND the real field rather than styling the field itself, so the browser stays the editor and IME, undo, paste and selection are untouched; omit the prop and no mirror is rendered at all |
 | `textInputProps` | Extra `TextInput` props; a consumer `onKeyPress` runs before Enter-to-send and can `preventDefault()` to suppress it |
 
 For a run that needs a FILE + a prompt together (attach a photo, review/remove it, add a note,

package/docs/catalog.md

@@ -1295,9 +1295,16 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   reference is a FIELD, not a section — one pointer to one other row never earns a heading
   and a rail entry. Worked example: [`tpl_record`](../examples/tpl_record.tsx) § General
   (customer) and its Transport parties.
-- **`peek`** — `Peek`: drill-down for inline references — press a name/id where it appears
-  and get its details in an anchored popover, without leaving the screen; keep the content a
-  summary with ONE action to the full record.
+- **`peek`** — `Peek`: drill-down for a reference — press a name/id where it appears and get its
+  details in an anchored popover, without leaving the screen; keep the content a summary with ONE
+  action to the full record. **`variant` picks the register the TRIGGER sits in, and getting it
+  wrong is visible:** `text` (default) boxes the child at the 32px chip scale and bleeds the extra
+  height back out, so a reference inside a line of reading never grows that line; `control` takes
+  the full `CONTROL_HEIGHT` band and the control radius, for a token that is a control-band citizen
+  — anything built on `MemberChip`, whose `md` avatar is sized to `CONTROL_CONTENT_HEIGHT` for
+  exactly that. On the wrong one a chip under-fills the band and stands a different height from the
+  same chip un-peeked beside it. The horizontal bleed is common to both, so a peekable token keeps
+  the surface's left edge.
 
 ### Lists, tables & registers
 
@@ -1599,6 +1606,11 @@ component rather than showing it at zero.
 - **`matrix_totals`** — the data layer for `Matrix`: `matrixTotals` (the cross-tab
   aggregation) + `MatrixAxisItem` / `MatrixCellRef` / `MatrixTotalsResult`; React-free, so a
   KPI can be driven off the same numbers the grid shows.
+- **`highlight_segments`** — `splitHighlightSegments`: cuts a string into plain and
+  highlighted runs for `Composer`'s `highlightRanges`. React-free, and the reason it is
+  separate: it feeds a mirror sitting behind a real text field, so a boundary off by one
+  paints the tint adrift while everything still looks like a working composer. Overlapping,
+  unsorted and out-of-bounds ranges all normalize; no input drops a character.
 - **`legend_item`** — `LegendItem`: one swatch + label of a chart legend.
 - **`remainder_meter`** — `RemainderMeter`: allocated-vs-remaining meter
   (`RemainderMeterLabels` localized via the provider).

package/package.json

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

package/src/composer.tsx

@@ -1,9 +1,19 @@
-import React, { type ReactNode, type Ref, useCallback, useEffect, useState } from "react";
-import { View, TextInput as RNTextInput, ScrollView, StyleSheet, type TextInputProps } from "react-native";
+import React, { type ReactNode, type Ref, useCallback, useEffect, useMemo, useState } from "react";
+import {
+  View,
+  Text as RNText,
+  TextInput as RNTextInput,
+  ScrollView,
+  StyleSheet,
+  type NativeSyntheticEvent,
+  type TextInputProps,
+  type TextInputScrollEventData,
+} from "react-native";
 import { IconButton } from "./icon_button";
 import { colors } from "./colors";
 import { Text } from "./text";
 import { fontFamilyRegular, getInputTextStyle, INPUT_LETTER_SPACING } from "./text_utils";
+import { splitHighlightSegments, type HighlightRange } from "./highlight_segments";
 import { useAutoGrowHeight } from "./use_auto_grow_height";
 import { useLoticsLocale } from "./locale";
 
@@ -43,6 +53,10 @@ export interface ComposerProps {
   /** Control text externally; omit to let the composer manage its own state. */
   value?: string;
   onChangeText?: (text: string) => void;
+  /** Ranges of `value` to tint. What they MEAN is the caller's business — this
+   *  package never learns what a skill or a document is. Omit it and nothing is
+   *  rendered, so a consumer that never tints pays nothing. */
+  highlightRanges?: readonly HighlightRange[];
   /** Extra TextInput props (ref, onKeyPress, …). `onKeyPress` runs before the
    *  built-in Enter-to-send and can `preventDefault()` to suppress it. */
   textInputProps?: Partial<TextInputProps> & { ref?: Ref<RNTextInput> };
@@ -79,6 +93,7 @@ export function Composer(props: ComposerProps) {
     autoFocus,
     testID,
     textInputProps,
+    highlightRanges,
     pills,
     files,
     children,
@@ -186,12 +201,85 @@ export function Composer(props: ComposerProps) {
   // padding; `measureScrollHeight` subtracts that padding, so wrap-detection is
   // unaffected. Growth past one line is the EXPANDED layout's job (up to maxLines).
   const compactPadV = Math.max(2, Math.round((COMPACT_INPUT_HEIGHT - lineHeight) / 2));
+
+  // Null — not an empty array — when there is nothing to tint, so the mirror is
+  // not rendered at all for the ordinary message or for a consumer that never
+  // passes ranges.
+  const highlightSegments = useMemo(
+    () =>
+      highlightRanges && highlightRanges.length > 0
+        ? splitHighlightSegments(text, highlightRanges)
+        : null,
+    [text, highlightRanges],
+  );
+  const [mirrorScrollY, setMirrorScrollY] = useState(0);
+  const handleInputScroll = useCallback(
+    (e: NativeSyntheticEvent<TextInputScrollEventData>) => {
+      // The two platforms report the offset in different places and neither has
+      // the other's: RN measures the content and sends `contentOffset`, while
+      // rn-web forwards the <textarea>'s DOM scroll event verbatim, where the
+      // only offset is the element's own `scrollTop`. Reading just the native
+      // shape type-checks — RN's types promise `contentOffset` — and then throws
+      // on the web, on every scroll tick, while the tint silently stops tracking
+      // the words in exactly the long message this handler exists to follow.
+      const native: Partial<TextInputScrollEventData> & { target?: { scrollTop?: number } } =
+        e.nativeEvent;
+      setMirrorScrollY(native.contentOffset?.y ?? native.target?.scrollTop ?? 0);
+    },
+    [],
+  );
   const field = (
     <View
       key="field"
       onLayout={measure}
       style={expanded ? { height: containerHeight } : [styles.field, { height: COMPACT_INPUT_HEIGHT }]}
     >
+      {highlightSegments ? (
+        // A MIRROR, not a replacement. The real <textarea> stays and keeps every
+        // behaviour the browser gives it — IME composition (this workspace types
+        // Vietnamese), undo, paste, spellcheck, selection, a11y — none of which
+        // survives a contentEditable rewrite. It renders TRANSPARENT text purely
+        // to lay out identically, and paints the tint behind the words the field
+        // is drawing on top; the field's own text and caret are untouched, so
+        // there is nothing here that can swallow a keystroke.
+        //
+        // Alignment is by construction: same text style object, same padding
+        // expressions, same width. It translates with the field's own scroll so
+        // the tint cannot drift once the message outgrows `maxLines`.
+        <View
+          pointerEvents="none"
+          style={[
+            StyleSheet.absoluteFill,
+            { overflow: "hidden" },
+            expanded ? null : { paddingHorizontal: 10, paddingVertical: compactPadV },
+          ]}
+        >
+          <RNText
+            testID="composer-highlight-mirror"
+            // The RAW react-native Text, never the kit's: `Text` bakes tracking
+            // per type-ramp rung, which quietly overrode the explicit
+            // `letterSpacing` the field uses and drifted the tint a fraction of
+            // a pixel per character — invisible on a short line, off the words
+            // by the end of a long one. The mirror takes the field's own style
+            // array and nothing else.
+            style={[
+              styles.textInput,
+              getInputTextStyle(),
+              { color: "transparent" },
+              { transform: [{ translateY: -mirrorScrollY }] },
+            ]}
+          >
+            {highlightSegments.map((segment, i) => (
+              <RNText
+                key={i}
+                style={segment.highlighted ? styles.highlightSegment : undefined}
+              >
+                {segment.text}
+              </RNText>
+            ))}
+          </RNText>
+        </View>
+      ) : null}
       <RNTextInput
         ref={mergedInputRef}
         autoFocus={autoFocus}
@@ -205,11 +293,19 @@ export function Composer(props: ComposerProps) {
         multiline
         scrollEnabled={expanded && scrollEnabled}
         onContentSizeChange={onContentSizeChange}
+        onScroll={highlightSegments ? handleInputScroll : undefined}
         {...spreadInputProps}
         onKeyPress={handleKeyPress}
         style={[
           styles.textInput,
           getInputTextStyle(),
+          // ABOVE the mirror. The mirror is absolutely positioned, and a
+          // positioned box paints over static in-flow content whatever the
+          // source order — so without this its tint is an opaque ground drawn
+          // ON TOP of the field, and the words inside a mention disappear
+          // entirely. Geometry and font metrics can all agree while this is
+          // wrong; only rendering the thing shows it.
+          { position: "relative" as const, zIndex: 1 },
           { outlineStyle: "none" },
           (!expanded || !scrollEnabled) && { overflow: "hidden" as const },
           expanded ? null : { paddingHorizontal: 10, paddingVertical: compactPadV },
@@ -348,4 +444,10 @@ const styles = StyleSheet.create({
     fontFamily: fontFamilyRegular,
     letterSpacing: INPUT_LETTER_SPACING,
   },
+  // A GROUND, not coloured text: the words on screen are the field's, drawn on
+  // top, so the tint has to sit behind them rather than replace them.
+  highlightSegment: {
+    backgroundColor: colors.blue[100],
+    borderRadius: 4,
+  },
 });

package/src/highlight_segments.ts

@@ -0,0 +1,61 @@
+export interface HighlightRange {
+  /** Index of the first highlighted character. */
+  start: number;
+  /** Index one past the last highlighted character. */
+  end: number;
+}
+
+export interface HighlightSegment {
+  text: string;
+  highlighted: boolean;
+}
+
+/**
+ * Cut `value` into alternating plain and highlighted runs.
+ *
+ * Split out from the composer because it is the part that can be wrong in a way
+ * nobody sees: the mirror it feeds sits behind a real text field, so a segment
+ * boundary off by one paints the tint half a character adrift and everything
+ * still looks like a working composer. Ranges arrive from a caller that is
+ * matching text it does not control, so overlapping, unsorted, reversed and
+ * out-of-bounds inputs are all normal here — none of them may drop or duplicate
+ * a character, because the mirror has to lay out identically to the field it
+ * sits behind or the tint drifts from the words.
+ */
+export function splitHighlightSegments(
+  value: string,
+  ranges: readonly HighlightRange[],
+): HighlightSegment[] {
+  if (value.length === 0) return [];
+
+  const clamped = ranges
+    .map((r) => ({
+      start: Math.max(0, Math.min(r.start, value.length)),
+      end: Math.max(0, Math.min(r.end, value.length)),
+    }))
+    .filter((r) => r.end > r.start)
+    .sort((a, b) => a.start - b.start);
+
+  // Overlaps merge rather than nest: two tints over one character would render
+  // twice as dark, and the caller's ranges are matches over shared text.
+  const merged: HighlightRange[] = [];
+  for (const range of clamped) {
+    const last = merged[merged.length - 1];
+    if (last && range.start <= last.end) last.end = Math.max(last.end, range.end);
+    else merged.push({ ...range });
+  }
+
+  const segments: HighlightSegment[] = [];
+  let cursor = 0;
+  for (const range of merged) {
+    if (range.start > cursor) {
+      segments.push({ text: value.slice(cursor, range.start), highlighted: false });
+    }
+    segments.push({ text: value.slice(range.start, range.end), highlighted: true });
+    cursor = range.end;
+  }
+  if (cursor < value.length) {
+    segments.push({ text: value.slice(cursor), highlighted: false });
+  }
+  return segments;
+}

package/src/member_chip.tsx

@@ -2,7 +2,7 @@ import React from "react";
 import { View, StyleSheet, StyleProp, ViewStyle } from "react-native";
 import { Avatar } from "./avatar";
 import { Text } from "./text";
-import type { AvatarSize } from "./avatar_size";
+import { AVATAR_PX, type AvatarSize } from "./avatar_size";
 import { useLoticsLocale } from "./locale";
 
 /**
@@ -34,22 +34,6 @@ interface MemberChipProps {
    *  than as a current assignment. The chip keeps its height, because its usual
    *  home is a fixed row: this is a colour change, never an extra line. */
   inactive?: boolean;
-  /**
-   * This chip is a DOOR — something opens when it is pressed. Underlines the
-   * name in neutral ink, the kit's marker for "leads somewhere, and not away"
-   * (see `TextLink` with no `href`).
-   *
-   * It exists because a pressable that paints nothing at rest is text: with no
-   * ground, no border and no underline, its only affordance is a hover wash,
-   * which does not exist on touch and has not happened yet for anyone who has
-   * not already pointed at it. The chip then measures perfectly, carries a real
-   * focus ring, and is never pressed.
-   *
-   * Set it ONLY when the chip itself opens something. A chip inside a row that
-   * navigates must not wear it — the row is the door, and marking the chip
-   * promises a second destination that is not there.
-   */
-  marker?: boolean;
   style?: StyleProp<ViewStyle>;
 }
 
@@ -75,7 +59,6 @@ export function MemberChip({
   secondary,
   size = "md",
   inactive,
-  marker,
   style,
 }: MemberChipProps) {
   // `Avatar` has always taken this word from the pack; the NAME beside it was a
@@ -105,9 +88,20 @@ export function MemberChip({
   // name is not a pair, and leaving it on prose leading keeps every single-line
   // chip — every picker option, every cell — pixel-identical to before.
   const pairLeading = secondary ? ("tight" as const) : undefined;
+  // THE MARK IS NEVER SHORTER THAN WHAT IT MARKS. Two tight lines measure ~38
+  // at this rung, so beside a 28px avatar the text overflowed the mark by ten
+  // pixels and the person's face read as a decoration hung off their name.
+  // Tight leading is already the floor — 38 is as short as the pair gets — so
+  // the fix is the MARK, not the type: a chip carrying a supporting line is a
+  // taller object, and it takes the rung that covers the stack. That rung is
+  // `lg` = `CONTROL_HEIGHT`, which is the band a two-line chip belongs in
+  // anyway. A caller already above it (`xl`, a profile header) keeps what it
+  // asked for.
+  const markSize: AvatarSize =
+    secondary && AVATAR_PX[size] < AVATAR_PX.lg ? "lg" : size;
   return (
     <View style={[styles.row, style]}>
-      <Avatar size={size} name={displayName} source={image ? { uri: image } : undefined} />
+      <Avatar size={markSize} name={displayName} source={image ? { uri: image } : undefined} />
       <View style={styles.text}>
         <Text
           userSelect="none"
@@ -118,10 +112,6 @@ export function MemberChip({
           // supporting line except by colour.
           weight="medium"
           leading={pairLeading}
-          // NEUTRAL underline, never the navigation blue: pressing this opens
-          // the person in place rather than travelling to them, and blue
-          // underlined text promises a destination.
-          decoration={marker ? "underline" : undefined}
           color={inactive ? "zinc-500" : undefined}
           numberOfLines={1}
         >

package/src/member_peek.tsx

@@ -72,6 +72,12 @@ export function MemberPeek(props: MemberPeekProps) {
     <Peek
       accessibilityLabel={accessibilityLabel ?? words.profile(displayName)}
       content={<MemberProfileCard {...card} />}
+      // A chip is a CONTROL-BAND citizen — `md` is `CONTROL_CONTENT_HEIGHT`
+      // precisely so it seats in one. On the default `text` register the
+      // trigger boxed it at 32 and bled 4 off each side, so a peeking chip
+      // under-filled the band and stood shorter than the same chip un-peeked
+      // beside it.
+      variant="control"
       side={side}
       align={align}
     >
@@ -81,9 +87,6 @@ export function MemberPeek(props: MemberPeekProps) {
         secondary={secondary}
         size={size}
         inactive={card.inactive}
-        // This chip IS the door — without the marker it paints nothing at rest
-        // and only a pointer already on it would ever learn that.
-        marker
         style={style}
       />
     </Peek>

package/src/peek.tsx

@@ -3,6 +3,7 @@ import { StyleSheet } from "react-native";
 import { Popover, PopoverTrigger, PopoverContent } from "./popover";
 import type { PopoverSide, PopoverAlign } from "./popover";
 import { PressableHighlight } from "./pressable_highlight";
+import { CONTROL_HEIGHT, CONTROL_RADIUS } from "./control_surface";
 
 export interface PeekProps {
   /** The inline reference that becomes the trigger — a customer name, a
@@ -15,6 +16,27 @@ export interface PeekProps {
   content: ReactNode;
   /** Announced name for the trigger ("Hồ sơ KOMASPEC VIỆT NAM"). */
   accessibilityLabel: string;
+  /**
+   * WHICH REGISTER the trigger sits in — the two surfaces a peek lives on need
+   * different boxes, and picking by taste puts the wrong one on both.
+   *
+   * `text` (default) is a reference INSIDE a line of reading — a customer name
+   * in a sentence, an id in a table cell. It takes the 32px chip register and
+   * bleeds the extra height back out with negative margins, so wrapping a
+   * `Text` never grows the line it sits in.
+   *
+   * `control` is a reference that IS a control-band citizen — anything built on
+   * `MemberChip`, whose `md` avatar is sized to `CONTROL_CONTENT_HEIGHT` for
+   * exactly this. It takes the full `CONTROL_HEIGHT` band and no vertical
+   * bleed, so the token seats where every other control on the surface does
+   * instead of under-filling the band and standing a different height from the
+   * same chip un-peeked beside it.
+   *
+   * The HORIZONTAL bleed is common to both: the trigger's padding must not
+   * shift its content off the surface's left edge, or a peekable token sits 8px
+   * right of the plain one above it.
+   */
+  variant?: "text" | "control";
   side?: PopoverSide;
   align?: PopoverAlign;
 }
@@ -28,7 +50,7 @@ export interface PeekProps {
  * customer names, order ids, member names, linked records.
  */
 export function Peek(props: PeekProps) {
-  const { children, content, accessibilityLabel, side = "bottom", align = "start" } = props;
+  const { children, content, accessibilityLabel, variant = "text", side = "bottom", align = "start" } = props;
   return (
     <Popover side={side} align={align}>
       <PopoverTrigger>
@@ -36,7 +58,7 @@ export function Peek(props: PeekProps) {
           focusRing
           accessibilityRole="button"
           accessibilityLabel={accessibilityLabel}
-          style={styles.trigger}
+          style={[styles.trigger, variant === "control" ? styles.triggerControl : null]}
           // 32px visual, 40px touch target (32 + 2×4) — same as IconButton.
           hitSlop={4}
         >
@@ -51,9 +73,9 @@ export function Peek(props: PeekProps) {
 }
 
 const styles = StyleSheet.create({
-  // Inline bleed at the 32px chip register (matches Badge scale, fits inside
-  // text rows without inflating them); negative margins absorb the extra
-  // height so the line's layout never shifts. hitSlop keeps the 40px target.
+  // The `text` register: a 32px chip box (Badge scale) whose extra height is
+  // bled back out with negative margins, so a reference inside a line of
+  // reading never grows that line. hitSlop keeps the 40px touch target.
   trigger: {
     flexDirection: "row",
     alignItems: "center",
@@ -63,6 +85,16 @@ const styles = StyleSheet.create({
     marginHorizontal: -8,
     marginVertical: -4,
   },
+  // The `control` register: the surface's own band. The vertical bleed goes —
+  // a control-band token is SUPPOSED to occupy the band — and the radius joins
+  // every other control's, so a peekable chip corners like the inputs it sits
+  // among rather than like a badge. The horizontal bleed stays, so the token
+  // keeps the left edge (see `variant`).
+  triggerControl: {
+    minHeight: CONTROL_HEIGHT,
+    borderRadius: CONTROL_RADIUS,
+    marginVertical: 0,
+  },
   content: {
     width: 320,
   },