@lotics/ui 44.2.0 → 44.3.0

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

@@ -1599,6 +1599,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.3.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;
+}