@lotics/ui 45.7.0 → 45.8.1

package/docs/catalog.md

@@ -165,14 +165,22 @@ in `actions`),
 the product's own knowledge docs use, not a raw textarea. It does NOT swap: the editor
 is mounted at rest and merely gains a draft on focus, so focusing moves nothing and
 the prose stays SELECTABLE rather than sitting under a button. Its toolbar is off for
-that reason — a band that appears with the edit pushes everything under it down.
+that reason — a band that appears with the edit pushes everything under it down — and it
+passes its **`variant`** THROUGH to the editor, which is what actually draws the box:
+the frame paints no surface here, so a variant that stopped at it stopped at nothing and
+every markdown field wore the document sheet, 4px right of the plain-text field above it.
 **`numberOfLines`** is the reserve, as everywhere else in the family); a
 READ-ONLY field in that same column uses `InlineStatic` (matches the editor box exactly, no
 input chrome, so it aligns pixel-for-pixel). **`MarkdownEditor`** is that editor standalone — a WYSIWYG whose value stays a plain
 markdown string, with a formatting toolbar as a SIBLING of the field (what the border
 encloses is the document; the controls that act on it sit outside it). Web is
 ProseMirror via `@lotics/markdown-editor`; native falls back to raw-text editing, and
-the platform-neutral `MarkdownEditorProps` is what stops the two drifting. Wrap it in a
+the platform-neutral `MarkdownEditorProps` is what stops the two drifting. **`variant`**
+is `"document"` (the default soft sheet) or the two FIELD states, `"framed"` / `"bare"`,
+DERIVED from `InlineEditVariant` so they cannot drift from the rest of the family. A field
+takes the control's corner and the control's text inset instead of the sheet's. The default
+is NAMED rather than left as absence: an optional prop whose omission is a distinct third
+mode reads exactly backwards to anyone who knows `TextInputField.variant`. Wrap it in a
 label with **`FormMarkdownEditor`**. Pass **`accessibilityLabel`** whenever the visible
 label is a sibling rather than a wrapping `FormField` — a `DetailRow`, an inline
 editor's frame — or the editable surface is an unnamed text box. A stack of labelled
@@ -827,13 +835,18 @@ source (`src/<module>.tsx`/`.ts`) is the API reference.
   rather than a value). Throws when the clipboard is unreachable — never resolve a write
   that did not happen, or the caller confirms a lie. Web-only (native has no
   `navigator.clipboard`).
-- **`back_button`** — `BackButton`: the one go-back control — don't hand-roll it (an
-  `arrow-left` `MenuButton` reads as another nav ITEM, not an exit). `onPress` +
-  `accessibilityLabel` (defaults to `label`, else the locale's `nav.back` — "Back" /
-  "Quay lại"). Bare, it's the chevron-left `IconButton` (lg, secondary) heading a
-  screen/panel; pass **`label`** to name where back GOES ("Danh sách") — the SAME
-  circular glyph with the destination beside it, ONE pressable over disc + words —
-  never an icon button beside unclickable prose.
+- **`back_button`** — `BackButton`: the CIRCULAR go-back control that HEADS a screen or
+  panel — don't hand-roll it (an `arrow-left` `MenuButton` reads as another nav ITEM, not
+  an exit). `onPress` + `accessibilityLabel` (defaults to `label`, else the locale's
+  `nav.back` — "Back" / "Quay lại"). Bare it is the 40px chevron-left disc; pass
+  **`label`** to name where back GOES ("Danh sách") — the SAME disc with the destination
+  beside it, ONE pressable over disc + words, never an icon button beside unclickable
+  prose. It takes no size or colour: one purpose, one look, and both variants draw the
+  one disc so they cannot drift.
+  **A back affordance INSIDE a header row is not this** — beside a drawer's title a 40px
+  disc outweighs the name it belongs to, so that one is a small `IconButton` (see
+  `screen_router` below). The distinction is prominence: this HEADS a surface, that
+  annotates a title.
 - **`link`** — `Link`: the EXTERNAL hyperlink — fixed underline+blue + `role="link"`;
   `onPress` only (the consumer wires the opener).
 - **`text_link`** — `TextLink`: underlined text that NAVIGATES — `href` renders a real

package/docs/data_entry.md

@@ -32,7 +32,11 @@ in [the templates](./templates.md) (`examples/tpl_*.tsx`).
 **The right-input-per-field law.** A field gets the control its SHAPE wants, never a default
 text box — and on a record surface radio/checkbox render as PERSISTENT controls (the control
 is the best display of the value; prose-shaped values and registry picks stay inline
-editors). Rich `InlineSelect` options carry a description line (`renderOptionContent` — it
+editors). **A MARKDOWN-typed field takes `InlineMarkdown`**, never `InlineTextInput`: the
+plain input prints the syntax it stores, so a reader sees `**` where every other surface
+showing that value renders it. It hides in the gap between two states of one field — the
+value is formatted wherever it is read-only and raw only where it is EDITABLE, which is one
+row, and looks like a quirk of that row rather than the wrong control. Rich `InlineSelect` options carry a description line (`renderOptionContent` — it
 shows in the resting row too; the `data` generic types option payloads). A DEPENDENT field
 renders only while its parent value makes it real — never a disabled ghost row. Worked rows:
 `tpl_record`'s Classification group.
@@ -145,6 +149,24 @@ over the first. **When "the layout must not move" is a requirement rather than a
 element is the only thing that delivers it** — a swap can be made to look stable, never to be it. So
 the editor is mounted at rest and gains a draft on focus, and the per-field cost is paid on purpose.
 If a screen ever holds dozens of these, the answer is fewer markdown fields on it, not a swap.
+
+**`variant` has to reach whatever actually DRAWS the box.** `InlineEditFrame` paints no surface on
+the path this field takes — it has no `actions` — so the editor's own frame is the field's frame,
+and a `variant` that stops at the wrapper stops at nothing: `bare` bought no change at all, and
+every markdown field wore the document sheet whatever the caller asked for. So `MarkdownEditor`
+takes the same `"framed" | "bare"` axis as `TextInputField`, and `InlineMarkdown` passes it through.
+
+**The half that is easy to miss is the INSET, not the border.** A document sheet insets its prose
+further than a control does (13px against `CONTROL_TEXT_INSET`'s 9), so an editor serving as a
+field lands 4px right of the plain-text field stacked directly above it — a ragged left edge inside
+one card, with nothing on screen naming the cause. A field variant is therefore what makes the
+editor a FIELD: it takes the control's corner (`CONTROL_RADIUS`) and the control's inset with it.
+The third value, `"document"`, is the default and every standalone surface in the product — and it
+is a NAMED value rather than an absence, because an optional prop whose omission is a distinct
+third mode reads backwards to anyone who knows `TextInputField.variant`, where omitting it gives
+you `"framed"`. `seamless` is the different case and not this one: that surrenders the surface to a
+host that draws it, and here there is no host — `InlineEditFrame` paints one only when it also owns
+the verbs, so with none the CHILD owns the surface.
 **A LINK does not swap**: marking a URL changes its ink, not its characters, so `InlineTextInput`
 takes a **`link`** treatment on its single `<input>` rather than swapping in a `TextLink`. Pressing
 the field still edits — an `Open` `InlineButton` in `actions` is how you reach the destination,

package/package.json

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

package/src/back_button.tsx

@@ -1,9 +1,8 @@
-import { IconButton } from "./icon_button";
 import { View } from "react-native";
 import { Icon } from "./icon";
 import { Text } from "./text";
 import { colors } from "./colors";
-import { CURSOR_ACTION } from "./control_surface";
+import { CONTROL_HEIGHT, CURSOR_ACTION } from "./control_surface";
 import { PressableHighlight } from "./pressable_highlight";
 import { useLoticsLocale } from "./locale";
 
@@ -18,26 +17,66 @@ interface BackButtonProps {
   accessibilityLabel?: string;
 }
 
+/**
+ * THE DISC, drawn ONCE for both variants and pressable in neither.
+ *
+ * It used to exist twice: the bare variant delegated to an `IconButton`, the
+ * labelled one hand-rolled the identical circle and restated that component's
+ * spec in a comment — "mirrors IconButton lg/secondary (40px, zinc-100, 20px
+ * zinc-900 glyph)". A spec copied into a comment is a spec that drifts: change
+ * `secondary` and one variant of ONE component follows while the other does not.
+ *
+ * Delegating both to `IconButton` is not the fix and never was. The labelled
+ * form is ONE pressable over the disc AND the words — an `IconButton` inside it
+ * is a button nested in a button, which is why the copy got written in the first
+ * place. So the shared thing is the SURFACE, not the control: inert here, and
+ * whichever pressable wraps it owns the gesture.
+ *
+ * IT BORROWS NOTHING FROM ANOTHER CONTROL. An earlier pass took the glyph ink
+ * from `getButtonIconColor("secondary")`, which reads as sharing until you say it
+ * out loud: this is not a secondary BUTTON, and tying its ink to that ladder
+ * means a change to the button palette silently restyles the back affordance for
+ * a reason no one would connect. The ink is `zinc-900` because that is what this
+ * glyph is.
+ *
+ * `CONTROL_HEIGHT` stays, and is not the same kind of borrowing: it is the
+ * SYSTEM's band height — the promise every 40px control aligns to — not another
+ * component's opinion. Typing `40` here would be the drift, not the reuse.
+ */
+const GLYPH = 20;
+
+function Disc() {
+  return (
+    <View
+      style={{
+        width: CONTROL_HEIGHT,
+        height: CONTROL_HEIGHT,
+        borderRadius: 999,
+        backgroundColor: colors.zinc[100],
+        alignItems: "center",
+        justifyContent: "center",
+      }}
+    >
+      <Icon name="chevron-left" size={GLYPH} color={colors.zinc[900]} />
+    </View>
+  );
+}
+
+/**
+ * THE go-back control: a circular glyph that leaves the current screen or panel,
+ * optionally naming where it goes.
+ *
+ * It is one purpose, so it takes no size or colour — a caller reaching for those
+ * wants a different control. In particular a drawer header's small inline arrow
+ * is NOT this: that sits beside a title inside a header row, where a 40px disc
+ * would outweigh the name it belongs to. That one is an `IconButton`, and the
+ * distinction is prominence — this one HEADS a surface, that one annotates a
+ * title.
+ */
 export function BackButton(props: BackButtonProps) {
   const locale = useLoticsLocale();
   const { onPress, label, accessibilityLabel = label ?? locale.nav.back } = props;
-  // Bare — the circular glyph IS the control.
-  if (label === undefined) {
-    return (
-      <IconButton
-        icon="chevron-left"
-        size="lg"
-        color="secondary"
-        accessibilityLabel={accessibilityLabel}
-        onPress={onPress}
-        style={{ alignSelf: "flex-start" }}
-      />
-    );
-  }
-  // Labelled — the SAME circular glyph, the destination named beside it, ONE
-  // pressable pill over both (words you can't press are a lie). The disc
-  // mirrors IconButton lg/secondary (40px, zinc-100, 20px zinc-900 glyph); the
-  // pill takes PressableHighlight's default hover/press wash + focus ring.
+
   return (
     <PressableHighlight
       focusRing
@@ -45,16 +84,28 @@ export function BackButton(props: BackButtonProps) {
       accessibilityLabel={accessibilityLabel}
       userSelect="none"
       onPress={onPress}
-      // Going back ACTS, exactly as the bare variant's `IconButton` does —
-      // without this, one component shows two cursors decided by a label.
-      style={{ cursor: CURSOR_ACTION, flexDirection: "row", alignItems: "center", gap: 8, alignSelf: "flex-start", borderRadius: 999, paddingRight: 14 }}
+      // Going back ACTS. One cursor for both variants — a label must not decide
+      // whether the same control looks pressable.
+      //
+      // The pill's own padding exists only when there are words to seat: bare,
+      // the disc IS the target and any padding would inflate it past the 40px
+      // every other control in the band is aligned to.
+      style={{
+        cursor: CURSOR_ACTION,
+        flexDirection: "row",
+        alignItems: "center",
+        gap: 8,
+        alignSelf: "flex-start",
+        borderRadius: 999,
+        paddingRight: label === undefined ? 0 : 14,
+      }}
     >
-      <View style={{ width: 40, height: 40, borderRadius: 999, backgroundColor: colors.zinc[100], alignItems: "center", justifyContent: "center" }}>
-        <Icon name="chevron-left" size={20} color={colors.zinc[900]} />
-      </View>
-      <Text size="sm" weight="medium" color="muted" numberOfLines={1}>
-        {label}
-      </Text>
+      <Disc />
+      {label === undefined ? null : (
+        <Text size="sm" weight="medium" color="muted" numberOfLines={1}>
+          {label}
+        </Text>
+      )}
     </PressableHighlight>
   );
 }

package/src/inline_markdown.tsx

@@ -81,6 +81,12 @@ export function InlineMarkdown(props: InlineMarkdownProps) {
         onFocus={edit.begin}
         onBlur={() => void edit.commit()}
         toolbar={false}
+        // THE FIELD'S FRAME IS THIS EDITOR'S OWN. `InlineEditFrame` draws no
+        // surface on the path this field takes (it has no `actions`), so the
+        // caller's `variant` has to reach the editor or it reaches nothing —
+        // which is what made a `bare` markdown field draw a document sheet
+        // anyway, 4px right of the plain-text field stacked above it.
+        variant={variant ?? "framed"}
         placeholder={placeholder}
         numberOfLines={numberOfLines}
         disabled={disabled}

package/src/markdown_editor.css

@@ -37,6 +37,46 @@
   opacity: 0.6;
 }
 
+/* THE TWO FIELD VARIANTS. Everything above is the `document` default and stays
+   the default: a standalone editor is a page's subject, and there are far more
+   of those than there are markdown FIELDS.
+
+   Both field variants are named explicitly rather than matched as "has a
+   variant at all". `document` is a real value that reaches the DOM too, so a
+   bare `[data-variant]` selector would catch the sheet and re-inset it — the
+   attribute says WHICH of three, never whether. */
+.md-editor[data-variant="framed"],
+.md-editor[data-variant="bare"] {
+  border-radius: 10px;
+}
+
+.md-editor[data-variant="framed"] > .md-editor-content,
+.md-editor[data-variant="bare"] > .md-editor-content {
+  padding-left: 8px;
+  padding-right: 8px;
+}
+
+/* The two numbers the field variants move are the KIT's, not this file's:
+   `CONTROL_RADIUS` (10) above replaces the sheet's 16 — a control corner, not a
+   page corner — and the text inset drops to `CONTROL_TEXT_INSET` (9) = a 1px
+   border plus 8px of padding, replacing the sheet's 13.
+
+   That second one is the whole visible defect this exists for: a document
+   insets its prose further than a control does, so an editor serving as a field
+   while keeping the sheet's inset lands 4px right of the plain-text field
+   stacked directly above it in the same card.
+
+   Vertical padding is untouched — a control's 40px height is governed by
+   `minHeight` elsewhere, and prose here is multi-line by definition.
+
+   BARE additionally has no ground and no edge at REST. The hover border and the
+   focus ring above still apply: a bare field draws its own frame, it just does
+   not draw it until you reach for it. */
+.md-editor[data-variant="bare"] {
+  border-color: transparent;
+  background-color: transparent;
+}
+
 .md-editor-content {
   flex: 1 1 auto;
   /* position:relative anchors the absolutely-positioned gap cursor. */

package/src/markdown_editor.tsx

@@ -7,7 +7,7 @@ import type { MarkdownEditorProps } from "./markdown_editor_props";
  * edited as raw text.
  */
 export function MarkdownEditor(props: MarkdownEditorProps) {
-  const { value, onChangeText, onBlur, onFocus, placeholder, numberOfLines, disabled, autoFocus, accessibilityLabel, testID } =
+  const { value, onChangeText, onBlur, onFocus, variant, placeholder, numberOfLines, disabled, autoFocus, accessibilityLabel, testID } =
     props;
 
   return (
@@ -19,6 +19,12 @@ export function MarkdownEditor(props: MarkdownEditorProps) {
       onFocus={onFocus}
       placeholder={placeholder}
       numberOfLines={numberOfLines ?? 6}
+      // The two FIELD variants pass straight through — they are this input's
+      // own prop and mean the same thing here as on web. `"document"` has no
+      // native counterpart: the soft sheet is a web-only treatment and there is
+      // no raw-text equivalent of it, so a document editor falls back to this
+      // input's own default frame rather than inventing one.
+      variant={variant === "document" ? undefined : variant}
       multiline
       autoGrow
       disabled={disabled}

package/src/markdown_editor.web.tsx

@@ -15,7 +15,7 @@ import { MarkdownToolbar } from "./markdown_toolbar.web";
  * plain markdown string. The ProseMirror engine lives in `@lotics/markdown-editor`.
  */
 export function MarkdownEditor(props: MarkdownEditorProps) {
-  const { value, onChangeText, onBlur, onFocus, toolbar = true, placeholder, numberOfLines, disabled, autoFocus, accessibilityLabel, testID } =
+  const { value, onChangeText, onBlur, onFocus, toolbar = true, variant = "document", placeholder, numberOfLines, disabled, autoFocus, accessibilityLabel, testID } =
     props;
 
   const hostRef = useRef<HTMLDivElement>(null);
@@ -82,6 +82,7 @@ export function MarkdownEditor(props: MarkdownEditorProps) {
         className="md-editor"
         data-testid={testID}
         data-disabled={disabled ? "true" : undefined}
+        data-variant={variant}
         style={{ minHeight }}
       />
     </>

package/src/markdown_editor_props.ts

@@ -1,3 +1,22 @@
+import type { InlineEditVariant } from "./inline_edit";
+
+/**
+ * What this editor IS, which decides the box it draws.
+ *
+ * DERIVED from `InlineEditVariant` rather than spelled out, so the two field
+ * states cannot drift from the rest of the `Inline*` family — this editor draws
+ * its own surface for the same reason every other no-verbs inline control does
+ * (`InlineEditFrame` paints one only when it also owns the ✓/✕ verbs), so it has
+ * to answer the same question in the same words.
+ *
+ * `"document"` is the third state and the DEFAULT, and it is named rather than
+ * left as absence on purpose: an optional two-value prop whose omission is a
+ * distinct third mode is a trap — nothing in the type says so, and the reader
+ * who knows `TextInputField.variant` (where omitting it means `"framed"`) reads
+ * it exactly backwards.
+ */
+export type MarkdownEditorVariant = "document" | InlineEditVariant;
+
 /**
  * Shared prop contract for the markdown editor. Declared platform-neutrally so
  * the web (`markdown_editor.web.tsx`) and native (`markdown_editor.tsx`)
@@ -17,6 +36,24 @@ export interface MarkdownEditorProps {
    * always there and shifts nothing, so it stays on.
    */
   toolbar?: boolean;
+  /**
+   * `"document"` (the default) is a soft 16px sheet — a knowledge doc, a
+   * settings screen, anywhere the editor is the page's subject.
+   *
+   * `"framed"` and `"bare"` make it a FIELD, and mean there what they mean on
+   * every other inline control: an edge at rest, or no edge until hover. Both
+   * also pull the text inset in to `CONTROL_TEXT_INSET`, which is the half
+   * that is easy to miss — a document insets its prose further than a control
+   * does, so an editor serving as a field while keeping the sheet's inset sits
+   * 4px right of the plain-text field stacked above it.
+   *
+   * The editor draws this itself rather than taking it from a host, because
+   * `InlineEditFrame` paints a surface only when it also owns the ✓/✕ verbs;
+   * with none, the CHILD owns the surface. That is the same contract
+   * `TextInputField` answers with its own `variant`, and the reason `seamless`
+   * is the wrong lever here — nothing is drawing a box to surrender to.
+   */
+  variant?: MarkdownEditorVariant;
   placeholder?: string;
   numberOfLines?: number;
   disabled?: boolean;