@lotics/ui 44.9.0 → 44.10.0

package/MIGRATION.md

@@ -4,6 +4,33 @@ 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.9.1 — a pivot's figures align, and a ledger row stops losing its own name
+
+No API is removed and nothing fails to compile. Three renders change.
+
+**`Matrix` right-aligns its figures instead of centring them.** Every value, column
+header and total was `align="center"` while the cells also set `tabular` — and tabular
+figures exist so digits line up in a column, which centring throws away. Measured on a
+real pivot: centred, 24 figures painted across **14 distinct right edges**; right-aligned,
+**12** — exactly one per column. No `align` prop came with this: a matrix is one measure
+across two dimensions, so its cells cannot want different alignments, and a prop for a
+centred case nobody has is surface without a consumer.
+
+**`Matrix` row labels carry default ink, not `muted`.** A pivot whose rows are entities
+rendered every entity name a step quieter than the numbers about it, inverting how the
+grid is read — you find the row by its name, then scan across.
+
+**`MATRIX_COL_GAP` is exported.** It was the literal `3` in four places, so a caller
+sizing its own column budget had to hard-code it and could drift from what the grid draws.
+
+**A `LedgerRow`'s `meta` yields before its label, and by 3×.** Only the label carried a
+`flexShrink`, and RN-web resolves the unstyled caption to `1` as well — so under pressure
+both shrank proportionally, and because a caption is usually the longer string, the
+SUBORDINATE text ended up wider than the row's identity. Measured in a 180px row: before,
+the label kept 31px of the 77 it needs while the caption kept 41 of 103; after, the label
+keeps 55 and the caption 16. Any caller that dropped `meta` at small widths to dodge this
+can stop.
+
 ## 44.8.0 — a value column gets its own floor, and eight defaults stop fighting their own docs
 
 No API is removed. Three of these change what an existing screen renders, so read them even

package/docs/ai_patterns.md

@@ -464,12 +464,21 @@ Reach for it whenever an agent run happens inside a dialog — which is nearly a
 const run = useAgentRun("intake");            // @lotics/app-sdk
 <AgentRunScope>                                {/* wraps the Dialog, like ClarifyWizardScope */}
   <Dialog …>
-    <AgentRunPane run={run} onCancel={back} />                              {/* content */}
+    <AgentRunPane run={run} onCancel={back} onLanding={landed} />           {/* content */}
     <DialogFooter><AgentRunActions run={run} onStop={back} /></DialogFooter> {/* actions */}
   </Dialog>
 </AgentRunScope>
 ```
 
+**Pass `onLanding` if the run's RESULT drives anything.** The pane owns the `answerChoice` call, so
+after a question it is the only thing holding how the answered leg ended — your own `run()` promise
+already resolved, with `parked`, and never resolves again. Give `onLanding` the same handler you
+give `run()`: it is typed from your run (no cast), and it re-fires if answering leads to a follow-up
+ask. Omit it and an answered run completes with the host none the wiser — the transcript reads
+"done", your review step never opens, and the paid read is discarded. A host that instead reads its
+result off `status`/`output` does not need it, but is then re-deriving from a render what it was
+handed directly.
+
 **The parked question REPLACES the feed — that is the contract, not a style.** The run is blocked
 on the answer, so the question is the only thing to act on; it gets the dialog's own scroller and
 its actions sit outside it. Stacked under the transcript in an unscrollable box — the arrangement

package/docs/catalog.md

@@ -1407,8 +1407,9 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
 - **`table`** — `Table` + `TableRow` + `TableCell`: the paginated high-volume register
   (columns defined once, `sortLabels` localizable; rows are `PressableRow`-based).
   CONTAINER-RESPONSIVE with no prop (measures itself, like `Breakdown`/`DetailTable`): when
-  the width can't fit every column it hides columns by `TableColumn.priority` (higher drops
-  first; default = column order, rightmost first; column 0 — the identity — never drops), and
+  the width can't fit every column it hides columns by `TableColumn.priority` (**`1` = highest,
+  as in P1/P2/P3** — the smallest number is the last to go; default = column order, rightmost
+  first; column 0 — the identity — never drops), and
   below the two-column floor every row STACKS: the identity cell (column 0) HEADS the pile
   unlabelled — its column name would only restate the value — and each REMAINING cell renders
   as a `DetailRow`-spread line (muted label left, value at the right edge — one vocabulary with
@@ -1705,7 +1706,11 @@ component rather than showing it at zero.
 - **`matrix`** — `Matrix`: the PIVOT cross-tab — band-compound `Matrix` root +
   `Matrix.Header` (corner + axis labels) + `Matrix.Grid` (`display` number|heat|both — the
   cells, pressable, the value IN the cell) + `Matrix.Totals` (row + column + grand) +
-  `Matrix.Legend`. Pick over `Heatmap` when the NUMBER and totals matter.
+  `Matrix.Legend`. Pick over `Heatmap` when the NUMBER and totals matter. Figures are
+  RIGHT-aligned — they are `tabular`, and centring them defeats the aligned column that is
+  the reason to read a pivot at all — and row labels carry default ink, because a row's
+  label is its identity, not chrome. `MATRIX_COL_GAP` is exported for a caller budgeting
+  its own column widths.
 - **`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.
@@ -2139,7 +2144,10 @@ component rather than showing it at zero.
   works and, the moment it asks, renders the question IN PLACE OF the feed — in the dialog's own
   scroller, with the wizard's verbs pinned in the `DialogFooter` via `AgentRunActions`. Replacing
   rather than stacking is the CONTRACT: stacked under the transcript a multi-question ask clips
-  its own Submit and strands a live `awaiting_input` run. `run` is a structural shape
+  its own Submit and strands a live `awaiting_input` run. `onLanding` hands back how the ANSWERED
+  leg ended — the pane makes that call, so without it the continuation's outcome is lost and a host
+  waiting on its own `run()` promise waits forever (that promise already resolved `parked`). A
+  refused answer keeps the question up and shows why, rather than a dead Submit. `run` is a structural shape
   (`AgentRunLike`), so `useAgentRun()` satisfies it with no `@lotics/app-sdk` dependency and a
   mock satisfies it with no backend — `AgentRunQuestion` names the question shape so a template
   or test DECLARES one rather than mapping from `ClarifyWizardQuestion` (an option is a label +

package/package.json

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

package/src/agent_run_pane.tsx

@@ -1,7 +1,8 @@
-import { useCallback, useMemo, type ReactNode } from "react";
+import { useCallback, useMemo, useState, type ReactNode } from "react";
 import { View } from "react-native";
 import { AgentRun, type AgentRunProps } from "./agent_run";
 import { Button } from "./button";
+import { Text } from "./text";
 import { useLoticsLocale } from "./locale";
 import type { AgentUIPart } from "./agent_transform";
 import { ClarifyWizard, ClarifyWizardActions, ClarifyWizardScope, type ClarifyWizardAnswer } from "./clarify_wizard";
@@ -31,12 +32,20 @@ export interface AgentRunQuestion {
   allow_custom?: boolean;
 }
 
-export interface AgentRunLike {
+export interface AgentRunLike<TLanding = unknown> {
   status: "idle" | "streaming" | "awaiting_input" | "completed" | "error";
   parts: readonly AgentUIPart[];
   /** Non-null exactly while parked. */
   pendingChoice: { questions: AgentRunQuestion[] } | null;
-  answerChoice: (answers: { value: string; custom: boolean }[]) => Promise<unknown>;
+  /**
+   * GENERIC in what it resolves, and that is the whole point of the parameter.
+   * A run leg reports HOW it ended — settled with an output, parked again on a
+   * follow-up, failed, aborted — and this pane is the thing that calls it, so it
+   * is the only thing holding that answer. Naming the type would mean importing
+   * `@lotics/app-sdk` and breaking the one-way boundary above; inferring it from
+   * the caller's own run costs nothing and hands `onLanding` back fully typed.
+   */
+  answerChoice: (answers: { value: string; custom: boolean }[]) => Promise<TLanding>;
   /**
    * STOP the run — server-side, not just locally. `useAgentRun().cancel` is
    * exactly this; do NOT pass its `abort`, which detaches the listener and
@@ -61,12 +70,30 @@ export function AgentRunScope({ children }: { children: ReactNode }) {
   return <ClarifyWizardScope>{children}</ClarifyWizardScope>;
 }
 
-export interface AgentRunPaneProps {
-  run: AgentRunLike;
+export interface AgentRunPaneProps<TLanding = unknown> {
+  run: AgentRunLike<TLanding>;
   labelForCall?: AgentRunProps["labelForCall"];
   renderToolOutput?: AgentRunProps["renderToolOutput"];
   /** Abandon a parked question — the run is left for the operator to retry. */
   onCancel: () => void;
+  /**
+   * How the ANSWERED leg ended. Required for correctness in any host that acts
+   * on a run's result, because this pane owns the `answerChoice` call and the
+   * caller's own `run()` promise already resolved — with `parked` — and will
+   * never resolve again.
+   *
+   * Without it the continuation's outcome had nowhere to go: the pane discarded
+   * it, and a host that had been told a landing is how you learn an outcome sat
+   * on a finished transcript with nothing to advance to. That shipped, and cost
+   * a paid extraction every time an agent asked a question.
+   *
+   * Re-fires for a follow-up ask: answering can land `parked` again.
+   *
+   * A host reading its result off hook state instead does not need this — but it
+   * is then re-deriving from a render what it was handed directly, which is the
+   * pattern the landing union exists to retire.
+   */
+  onLanding?: (landing: TLanding) => void;
 }
 
 /**
@@ -80,8 +107,9 @@ export interface AgentRunPaneProps {
  * dialog's height and clipped its own Submit. Every app rebuilt this arrangement
  * by hand and it only had to be got wrong once.
  */
-export function AgentRunPane(props: AgentRunPaneProps) {
-  const { run, labelForCall, renderToolOutput, onCancel } = props;
+export function AgentRunPane<TLanding>(props: AgentRunPaneProps<TLanding>) {
+  const { run, labelForCall, renderToolOutput, onCancel, onLanding } = props;
+  const loc = useLoticsLocale().agentRun;
   // The DIALOG's gutter, not this pane's own container measurement. Asking
   // `useContainerSize()` here answered "small" for a 760px dialog while the
   // header, scroll area and footer asked the SCREEN and answered "not small" —
@@ -101,17 +129,35 @@ export function AgentRunPane(props: AgentRunPaneProps) {
       })),
     [pending],
   );
+  // A REFUSED answer (400 invalid, 409 raced cancel) leaves the run parked and
+  // still answerable, so the wizard stays up and the reason goes above it. It
+  // used to be a bare `void`, which made that an unhandled rejection: the button
+  // did nothing, the question stayed, and nothing said why.
+  const [answerError, setAnswerError] = useState<string | null>(null);
   const submit = useCallback(
     (answers: ClarifyWizardAnswer[]) => {
-      void run.answerChoice(answers.map((a) => ({ value: a.value, custom: a.custom })));
+      setAnswerError(null);
+      run.answerChoice(answers.map((a) => ({ value: a.value, custom: a.custom }))).then(
+        (landing) => onLanding?.(landing),
+        // A rejection is always an `Error` on the SDK's path, but a promise can
+        // carry anything, so the fallback is the localized label rather than
+        // whatever `String()` makes of a non-Error — "[object Object]" is not a
+        // thing to show an operator who is mid-answer.
+        (e: unknown) => setAnswerError(e instanceof Error ? e.message : loc.error),
+      );
     },
-    [run],
+    [run, onLanding, loc],
   );
 
   if (pending) {
     return (
       <DialogScrollArea>
-        <View style={{ paddingVertical: 4 }}>
+        <View style={{ paddingVertical: 4, gap: 8 }}>
+          {answerError !== null ? (
+            <Text size="sm" color="danger">
+              {answerError}
+            </Text>
+          ) : null}
           <ClarifyWizard questions={questions} onSubmit={submit} onCancel={onCancel} />
         </View>
       </DialogScrollArea>

package/src/ledger.tsx

@@ -237,7 +237,7 @@ export function LedgerRow(props: LedgerRowProps) {
         {label}
       </Text>
       {meta ? (
-        <Text size="xs" color="muted" numberOfLines={1}>
+        <Text size="xs" color="muted" numberOfLines={1} style={styles.yield}>
           {meta}
         </Text>
       ) : null}
@@ -357,6 +357,13 @@ const styles = StyleSheet.create({
   rowHovered: { backgroundColor: colors.zinc[50] },
   grow: { flexGrow: 1, flexShrink: 1 },
   shrink: { flexShrink: 1 },
+  // The META yields BEFORE the label, and by more. Only the label carried a
+  // shrink, so under width pressure the row'''s IDENTITY was the one thing that
+  // gave way while its subordinate qualifier held full width — a narrow ledger
+  // read "Tổng thu (chư…" beside an intact "03/06, Cash". A caption qualifies a
+  // number; the label names it, and the name is what a reader needs when the
+  // row is too tight for both.
+  yield: { flexShrink: 3 },
   total: { gap: 6 },
   // The BASIS row, the only one whose two sides can differ in height: its label may
   // carry a stacked `meta` while the figure stays one line. Centring then measures the

package/src/matrix.tsx

@@ -25,6 +25,11 @@ interface MatrixContextValue {
   totalColWidth: number;
 }
 
+/** Gap between a matrix's columns. Exported because a caller sizing its own
+ *  column budget needs the same number the grid renders with — hard-coding it
+ *  is how a width budget and the layout drift apart. */
+export const MATRIX_COL_GAP = 3;
+
 const MatrixContext = createContext<MatrixContextValue | null>(null);
 
 function useMatrix(): MatrixContextValue {
@@ -138,12 +143,12 @@ function MatrixHeader({ corner, totalLabel }: MatrixHeaderProps) {
         )}
       </View>
       {cols.map((c) => (
-        <Text key={c.key} size="xs" color="muted" align="center" numberOfLines={1} style={styles.colCell}>
+        <Text key={c.key} size="xs" color="muted" align="right" numberOfLines={1} style={styles.colCell}>
           {c.label}
         </Text>
       ))}
       {hasTotals ? (
-        <Text size="xs" color="muted" weight="medium" align="center" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
+        <Text size="xs" color="muted" weight="medium" align="right" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
           {resolvedTotalLabel}
         </Text>
       ) : null}
@@ -163,14 +168,14 @@ function MatrixGrid({ display = "both" }: MatrixGridProps) {
     <View style={styles.grid}>
       {rows.map((r) => (
         <View key={r.key} style={styles.row}>
-          <Text size="sm" color="muted" numberOfLines={1} style={[styles.rowLabel, { width: rowLabelWidth }]}>
+          <Text size="sm" numberOfLines={1} style={[styles.rowLabel, { width: rowLabelWidth }]}>
             {r.label}
           </Text>
           {cols.map((c) => (
             <MatrixCell key={c.key} ctx={ctx} display={display} row={r} col={c} value={value(r.key, c.key)} />
           ))}
           {hasTotals ? (
-            <Text size="sm" weight="semibold" tabular align="center" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
+            <Text size="sm" weight="semibold" tabular align="right" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
               {formatValue(rowTotals.get(r.key) ?? 0)}
             </Text>
           ) : null}
@@ -206,7 +211,7 @@ function MatrixCell({ ctx, display, row, col, value }: MatrixCellProps) {
   const label = `${row.label}, ${col.label}: ${formatValue(value)}`;
 
   const content = showNumber ? (
-    <Text size="sm" weight="medium" tabular align="center" color={value === 0 ? "zinc-500" : "default"}>
+    <Text size="sm" weight="medium" tabular align="right" color={value === 0 ? "zinc-500" : "default"}>
       {value === 0 ? "" : formatValue(value)}
     </Text>
   ) : null;
@@ -254,11 +259,11 @@ function MatrixTotals({ label }: MatrixTotalsProps) {
         {label ?? locale.matrix.total}
       </Text>
       {cols.map((c) => (
-        <Text key={c.key} size="sm" weight="semibold" tabular align="center" numberOfLines={1} style={styles.colCell}>
+        <Text key={c.key} size="sm" weight="semibold" tabular align="right" numberOfLines={1} style={styles.colCell}>
           {formatValue(colTotals.get(c.key) ?? 0)}
         </Text>
       ))}
-      <Text size="sm" weight="semibold" tabular align="center" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
+      <Text size="sm" weight="semibold" tabular align="right" numberOfLines={1} style={[styles.totalCol, { width: totalColWidth }]}>
         {formatValue(grandTotal)}
       </Text>
     </View>
@@ -295,21 +300,21 @@ Matrix.Legend = MatrixLegend;
 
 const styles = StyleSheet.create({
   container: {
-    gap: 3,
+    gap: MATRIX_COL_GAP,
   },
   headRow: {
     flexDirection: "row",
     alignItems: "center",
-    gap: 3,
+    gap: MATRIX_COL_GAP,
     paddingBottom: 2,
   },
   grid: {
-    gap: 3,
+    gap: MATRIX_COL_GAP,
   },
   row: {
     flexDirection: "row",
     alignItems: "center",
-    gap: 3,
+    gap: MATRIX_COL_GAP,
   },
   rowLabel: {
     paddingRight: 8,
@@ -333,7 +338,7 @@ const styles = StyleSheet.create({
   totalsRow: {
     flexDirection: "row",
     alignItems: "center",
-    gap: 3,
+    gap: MATRIX_COL_GAP,
     marginTop: 3,
     paddingTop: 8,
     borderTopWidth: 1,

package/src/table_fit.ts

@@ -20,12 +20,22 @@ export interface TableFitColumn {
   key: string;
   /** Fixed width in px; omit for a flexible column. */
   width?: number;
-  /** Drop precedence when the container can't fit every column: HIGHER numbers
-   *  drop first, ties drop right-to-left. The FIRST column is the row's identity
-   *  — it never drops.
+  /** This column's claim on space, **`1` = highest**, the way P1/P2/P3 rank a
+   *  bug: the column you least want to lose gets the SMALLEST number. Said the
+   *  other way round it is the same rule — the larger the number, the sooner the
+   *  column drops, and ties drop right-to-left. The FIRST column is the row's
+   *  identity and never drops.
    *
-   *  An unannotated column defaults to `columns.length + index`, which is above
-   *  every hand-written priority rather than interleaved with them, so an
+   *  Stated rank-first deliberately. "Higher drops first" is accurate and was
+   *  all this said, but a reader who takes `priority` to mean "bigger is more
+   *  important" inverts it and gives their most important column the LARGEST
+   *  number — which is then the first column the fit sheds. That failure is
+   *  invisible at desk width and shows only on a phone, so it reviews as
+   *  correct. It has been read backwards once already.
+   *
+   *  An unannotated column defaults to `columns.length + index`, which sits
+   *  above the small ranks a real annotation uses rather than interleaved with
+   *  them, so an
    *  unannotated register still sheds right-to-left AND an explicit priority is
    *  strictly safer than none. Defaulting to the bare index made annotation
    *  actively harmful: marking your most important column `priority: 1` TIED it