@lotics/ui 23.1.1 → 24.0.0

package/src/table.tsx

@@ -164,6 +164,27 @@ export type TableRowProps = {
   action?: ReactNode;
   /** Min row height (register mode; stacked rows size to their content). Default 52. */
   minHeight?: number;
+  /**
+   * The row's detail, revealed BENEATH it when `expanded` — the alternative to
+   * sending the reader somewhere else to see it.
+   *
+   * A register answers "which one", and the moment it cannot answer "and what
+   * about it" the reader is pushed into a drawer, loses the surrounding rows,
+   * and pays a navigation to come back — which is what makes scanning twenty
+   * records unaffordable. Expanding in place keeps the answer next to the
+   * question. Reach for it when the detail is READ or light-edit; a heavy form
+   * still deserves its own surface.
+   *
+   * Outside the pressable, so a control inside the detail is not swallowed by
+   * the row's own press.
+   */
+  detail?: ReactNode;
+  /**
+   * Whether `detail` is showing. CONTROLLED — the caller owns it, because who
+   * may be open at once is the caller's rule (one at a time, several, or one
+   * per group) and a component-local default would silently pick one.
+   */
+  expanded?: boolean;
   /** The `TableCell`s, one per column, in column order. */
   children: ReactNode;
 } & (
@@ -198,9 +219,10 @@ export type TableRowProps = {
  * slots, different geometry.
  */
 export function TableRow(props: TableRowProps) {
-  const { onPress, selected, marked, accessibilityLabel, leading, trailing, action, minHeight = 52, children } = props;
+  const { onPress, selected, marked, accessibilityLabel, leading, trailing, action, minHeight = 52, detail, expanded, children } = props;
   const ctx = useContext(TableContext);
   if (!ctx) throw new Error("TableRow must be used within a Table");
+  const showDetail = detail != null && expanded === true;
 
   const cells = (Children.toArray(children).filter(isValidElement) as ReactElement<TableCellProps>[])
     .map((cell, i) => ({ cell, column: ctx.columns[i] as TableColumn | undefined }))
@@ -249,13 +271,13 @@ export function TableRow(props: TableRowProps) {
     );
   }
 
-  return (
-    <PressableRow onPress={onPress} selected={selected} marked={marked} style={styles.row}>
+  const rowSurface = (
+    <PressableRow onPress={onPress} selected={selected || showDetail} marked={marked} style={styles.row}>
       {!ctx.stacked && ctx.leading > 0 ? <View style={[styles.slot, { width: ctx.leading }]}>{leading}</View> : null}
       {/* The door hit-tests above in-flow content; the cells/slots lift back above it
           via zIndex 1 (see `PressDoor`), so the door gets only the keyboard. Radius
           matches the register wash. */}
-      <PressDoor onPress={onPress} accessibilityLabel={accessibilityLabel} />
+      <PressDoor onPress={onPress} accessibilityLabel={accessibilityLabel} expanded={detail != null ? showDetail : undefined} />
       {ctx.stacked ? (
         body
       ) : (
@@ -271,6 +293,19 @@ export function TableRow(props: TableRowProps) {
       )}
     </PressableRow>
   );
+
+  if (!showDetail) return rowSurface;
+
+  // The detail is a SIBLING of the pressable, never inside it: the row's press
+  // surface spans its own children, so a control nested in the detail would be
+  // swallowed by the toggle — and a `<button>` inside the door is invalid HTML
+  // for the same reason the cells sit outside it.
+  return (
+    <View>
+      {rowSurface}
+      <View style={styles.detail}>{detail}</View>
+    </View>
+  );
 }
 
 export interface TableCellProps {
@@ -301,6 +336,23 @@ export function TableCell(props: TableCellProps) {
 }
 
 const styles = StyleSheet.create({
+  // The expanded detail. Indented to the identity column's text edge so it reads
+  // as belonging to the row above rather than as a new row, and given the row's
+  // own gutter so its content lines up with the cells it explains.
+  //
+  // Vertical padding is measured from the row's WASH, not its text: an expanded
+  // row wears the `selected` highlight, so the band's edge is the hard line the
+  // eye reads. With no top padding the detail's first control sat 3px off that
+  // edge while the bottom had a designed 16 — visibly cramped for an editor
+  // detail. Matching 16 both ends frames the detail evenly inside the band, and
+  // equals a `DetailTable`'s own row gap so a field grid keeps one rhythm from
+  // the row above it to the hairline below.
+  detail: {
+    paddingLeft: ROW_GUTTER,
+    paddingRight: ROW_GUTTER,
+    paddingTop: 16,
+    paddingBottom: 16,
+  },
   // A hairline under the column header anchors the columns; the rows below it are
   // Divider-separated.
   headerBand: {

package/src/text_button.tsx

@@ -0,0 +1,139 @@
+import { type ReactNode } from "react";
+import { StyleSheet } from "react-native";
+import { PressableHighlight } from "./pressable_highlight";
+import { Text } from "./text";
+
+/** Two only. Deliberately NOT the whole `TextColor` palette: `muted` would mute the
+ *  one thing carrying the act's weight, and the rest (warning/success/inverted) name
+ *  states, not verbs. Reach for `Button color="muted"` when an act must be quieter. */
+export type TextButtonColor = "default" | "danger";
+
+export interface TextButtonProps {
+  /** The verb, as words. */
+  children: ReactNode;
+  /** The act. REQUIRED — a text button with nothing to do is just `Text`. */
+  onPress: () => void;
+  /** `default` = neutral ink; `danger` = destructive. */
+  color?: TextButtonColor;
+  /**
+   * Nothing to act on. Pass it UNCONDITIONALLY and disable it rather than
+   * rendering the verb only once its target exists — an action that appears and
+   * disappears reflows the line it sits in, which is the one thing a control in
+   * a row of text must never do.
+   */
+  disabled?: boolean;
+  /** Announced name, when the words alone are ambiguous ("Open" → "Open customer"). */
+  accessibilityLabel?: string;
+  /** Truncate at this many lines (a label in a narrow row). */
+  numberOfLines?: number;
+  tooltip?: string;
+}
+
+/**
+ * A low-chrome ACTION rendered at text weight — "Select all", "Clear",
+ * "Add stop". The third member of the action family, by CHROME:
+ * `Button` (a 40px control with a surface) → `InlineButton` (28px, filled, living
+ * on a field's own surface) → this (no surface AT REST, sitting in a line of text).
+ *
+ * UNDERLINED, in NEUTRAL ink — what Airbnb ships for a text action, and the shape
+ * that keeps this kit's own colour rule intact:
+ *
+ *   underline = INTERACTIVE      blue = NAVIGATION
+ *   `Link`/`TextLink`  blue + underline  → navigates
+ *   `TextButton`       zinc + underline  → acts
+ *
+ * The underline is the affordance and it is not optional. With no surface and no
+ * tint, nothing else says at rest that the words can be pressed: POSITION is a
+ * learned convention rather than an affordance (invisible to a first-time reader),
+ * and hover is not one either — absent on touch, and revealed only once you are
+ * already there. A tint is the other way to say it, the one Material and HIG take,
+ * but blue is spoken for here and a second accent for "actionable" would collide
+ * with the one-accent-per-purpose rule.
+ *
+ * This is also why it holds INSIDE a run of prose, where colour alone could not
+ * distinguish an embedded control at all (WCAG 1.4.1 / F73).
+ *
+ * Built on `PressableHighlight` rather than a pressable `Text`, because a `Text`
+ * with `onPress` gets NEITHER hover nor a focus ring: it renders a real
+ * `<button>` with `tabIndex=0`, `outline: none` and no box-shadow, so a keyboard
+ * user lands on it with no indication they have. A focusable control with no focus
+ * treatment is a bug, and hand-rolling hover + focus onto `Text` would duplicate
+ * machinery this already owns. The inherited hover wash is Material's state layer
+ * by another name, and it costs nothing at rest, so the chrome ladder above holds.
+ *
+ * The padding/negative-margin bleed is `Peek`'s: the wash and the focus ring need
+ * room off the glyphs, and the margins give it back so the line's layout never
+ * shifts — `OptionList` depends on that, insetting 8px so its select-all verbs
+ * line up under the option labels above.
+ *
+ * ONE SIZE (`Text`'s own `sm`) and no icon: it sits in a line of text and matches
+ * it. A verb needing an icon or a real hit target is a `Button`.
+ *
+ * It is TEXT-height, not control-height, and that is deliberate: `marginVertical`
+ * absorbs the touch box so the height IN FLOW stays 24 and dropping one into a
+ * dense band (`OptionList`'s select-all, `FilterChip`'s Clear) cannot grow that
+ * band. Do NOT match `Button`'s 40 to make a mixed row line up — that inflates
+ * every inline use and collapses the chrome ladder above, turning this into a
+ * Button without a fill. A row that mixes rungs aligns them the way such a row
+ * should anyway: `alignItems: "center"`, which lands a centred 32px box's text on
+ * the same line as a centred 40px one (measured: 0px apart in a peek footer).
+ *
+ * It sets NO `alignSelf`, so it obeys its parent — which is what a row wants, and
+ * a baked `flex-start` top-aligned it against a taller sibling and silently
+ * overrode a footer's `alignItems: center`. In a COLUMN container a `Pressable`
+ * stretches, so the hover wash would run the full width for a two-word verb: wrap
+ * it in a `flexDirection: "row"` View there, the same thing a `Button` needs.
+ */
+export function TextButton(props: TextButtonProps) {
+  const { children, onPress, color = "default", disabled, accessibilityLabel, numberOfLines, tooltip } = props;
+  // `TextColor` tokens throughout, no raw palette access: neutral ink IS `default`,
+  // and `zinc-400` is `Button`'s own disabled ink — an inert control should read the
+  // same whatever its chrome, where muting to zinc-600 left it looking merely quiet.
+  const ink = disabled === true ? "zinc-400" : color === "danger" ? "danger" : "default";
+  return (
+    <PressableHighlight
+      focusRing
+      accessibilityRole="button"
+      accessibilityLabel={accessibilityLabel}
+      aria-disabled={disabled === true ? true : undefined}
+      disabled={disabled}
+      tooltip={tooltip}
+      // 32px box + 4px slop = the 40px target `Peek` keeps for the same shape. A
+      // text action measured 24px on its own, which clears WCAG 2.5.8's 24×24
+      // floor and nothing else — and it sits in dense rows, exactly where a thumb
+      // needs the margin most.
+      hitSlop={4}
+      onPress={onPress}
+      // After the inherited wash, so a disabled verb does not light up under the
+      // pointer — `hovered` still fires on a disabled Pressable.
+      style={[styles.trigger, disabled === true ? styles.dead : null]}
+    >
+      <Text decoration="underline" weight="medium" color={ink} numberOfLines={numberOfLines}>
+        {children}
+      </Text>
+    </PressableHighlight>
+  );
+}
+
+const styles = StyleSheet.create({
+  trigger: {
+    flexDirection: "row",
+    alignItems: "center",
+    // NO `alignSelf` here — see the prop. A baked `flex-start` is a CROSS-axis
+    // instruction, so it means "hug the words" only in a column; in a row it means
+    // top-align, and it silently overrode a footer's `alignItems: center`.
+    borderRadius: 6,
+    // Room for the wash + focus ring, given straight back as margin so adding a
+    // TextButton to a line cannot move anything around it (`Peek`'s idiom). The
+    // 32px box carries the touch target; `marginVertical` absorbs 8 of it, so the
+    // height IN FLOW stays 24 and a row's rhythm is unchanged.
+    minHeight: 32,
+    marginVertical: -4,
+    // 6 rather than `Peek`'s 8: these come in GROUPS (OptionList's select-all /
+    // deselect-all sit 16 apart), and an 8px bleed each side would leave adjacent
+    // washes touching.
+    paddingHorizontal: 6,
+    marginHorizontal: -6,
+  },
+  dead: { backgroundColor: "transparent" },
+});

package/src/text_link.tsx

@@ -1,39 +1,49 @@
 import { Text, type TextProps } from "./text";
 import { Icon, type IconName } from "./icon";
+import { colors } from "./colors";
 import { getTextColor } from "./text_utils";
 
 export interface TextLinkProps extends TextProps {
   /** Optional leading icon. */
   icon?: IconName;
   /** A URL — renders a real anchor (`<a href>` on web; middle-click / open-in-new-tab
-   *  work). For in-app routing, wrap `TextLink` or use `onPress`. */
+   *  work). For in-app routing, wrap `TextLink` in your own pressable. */
   href?: string;
-  /** An in-app action. With NEITHER `href` nor `onPress`, `TextLink` is just
-   *  underlined text you wrap in your own pressable (e.g. a table cell). */
-  onPress?: () => void;
 }
 
 /**
- * Underlined text that is OPTIONALLY a link (`href` → a web anchor) or an action
- * (`onPress` → pressable); with neither it's plain underlined text you drop inside
- * your own pressable (a table cell, a custom row). Colour comes from `color` (it
- * inherits every `Text` prop) — the neutral, configurable counterpart to `Link`,
- * which is fixed blue + `role="link"` for the "this opens somewhere else" signal.
+ * Underlined text that NAVIGATES — `href` renders a real anchor; with no `href`
+ * it is plain underlined text you drop inside your own pressable (a table cell, a
+ * custom row), or a MARKER that a value leads somewhere (a record reference).
+ * Colour comes from `color` (it inherits every `Text` prop) — the neutral,
+ * configurable counterpart to `Link`, which is fixed blue + `role="link"` for the
+ * "this opens somewhere else" signal.
+ *
+ * It does NOT act. An `onPress` here used to resolve to `role="button"`, so one
+ * export was three components — a link, a button, and a passive marker — behind
+ * one name, inside `OptionList`, `FilterChip` and others. That mode is
+ * `TextButton` now — also underlined, since that is what marks a surface-less
+ * control interactive, but in ZINC: blue is reserved for navigation, so the ink is
+ * what says whether a press moves you or acts. Pick by what the press DOES.
  */
 export function TextLink(props: TextLinkProps) {
-  const { icon, href, onPress, children, color, style, ...textProps } = props;
-  const interactive = href != null || onPress != null;
+  const { icon, href, children, color, style, ...textProps } = props;
   return (
     <Text
       decoration="underline"
       weight="medium"
       color={color}
       href={href}
-      onPress={onPress}
-      accessibilityRole={href != null ? "link" : onPress != null ? "button" : undefined}
+      accessibilityRole={href != null ? "link" : undefined}
       style={[
         icon ? { display: "flex", flexDirection: "row", alignItems: "center", gap: 4 } : null,
-        interactive ? { cursor: "pointer" } : null,
+        // Blue only when it actually NAVIGATES. An `href` is a destination, so it
+        // takes the navigation ink (`color` still overrides). Without one this is
+        // underlined text you wrap yourself, or a MARKER on a value that leads
+        // somewhere — the record's customer field is one, and pressing it opens a
+        // PEEK, so blue there would promise a trip it never takes.
+        href != null && color == null ? { color: colors.blue[600] } : null,
+        href != null ? { cursor: "pointer" } : null,
         style,
       ]}
       {...textProps}