@qoretechnologies/reqraft 0.10.65 → 0.10.66-pr.145.g124fc92

package/src/components/form/engine/_structuredData/SchemaDataView.tsx

@@ -17,6 +17,7 @@ import React from 'react';
 import styled from 'styled-components';
 import { useContextSelector } from 'use-context-selector';
 import { CompactRowContext } from '../compactRowContext';
+import { useIsCalmForm } from '../formAppearance';
 import {
   MONO_FONT_STACK,
   StyledCodePreview,
@@ -216,13 +217,25 @@ const StyledItemFields = styled.div<{ $border: string; $rule: boolean }>`
  * case-sensitive — a service method is `onOrderStatus`, not `ONORDERSTATUS` —
  * and the item heading is a value.
  */
-const StyledFieldLabel = styled(StyledRowLabel)`
+const StyledFieldLabelBase = styled(StyledRowLabel)<{ $calm?: boolean }>`
   font-size: 12px;
-  text-transform: uppercase;
-  letter-spacing: 0.06em;
-  opacity: 0.55;
+  /* Calm: the name as written. The calm look forces nothing into capitals, and
+     its detail pages no longer do either, so the vocabulary this label borrows
+     is sentence case there too. */
+  text-transform: ${({ $calm }) => ($calm ? 'none' : 'uppercase')};
+  letter-spacing: ${({ $calm }) => ($calm ? 'normal' : '0.06em')};
+  opacity: ${({ $calm }) => ($calm ? 0.7 : 0.55)};
 `;
 
+/** The record field label in the form's appearance — see `StyledFieldLabelBase`. */
+const StyledFieldLabel = (
+  props: Omit<React.ComponentProps<typeof StyledFieldLabelBase>, '$calm'>
+) => {
+  const calm = useIsCalmForm();
+
+  return <StyledFieldLabelBase {...props} $calm={calm} />;
+};
+
 const StyledFields = styled.div`
   /* The supporting fields step in under the heading, so the heading keeps the
      left edge to itself. This is the half that answers "the name is written in

package/src/components/form/engine/compactRowContext.ts

@@ -69,6 +69,11 @@ export interface ICompactRowContext {
   // display name in the read-first chip.
   templates?: IReqoreFormTemplates;
   expandedOptions: string[];
+  /** Fields the person has opened and left: an empty required one among them is a
+   *  fault (`todo`); one they have not been to yet is only `pending`. */
+  visitedOptions: string[];
+  /** The host reported a submit attempt: every empty required field is a fault. */
+  revealRequired: boolean;
   highlightedOptions: string[];
   flashedOptions: string[];
   infoPanelOverrides: Record<string, boolean>;

package/src/components/form/engine/compactRowStyles.ts

@@ -1,5 +1,5 @@
 import { ReqoreP, ReqorePanel } from '@qoretechnologies/reqore';
-import { GAP_FROM_SIZE, TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
+import { GAP_FROM_SIZE, PADDING_FROM_SIZE, TSizes } from '@qoretechnologies/reqore/dist/constants/sizes';
 import styled, { css } from 'styled-components';
 
 // Styled primitives for the compact (read-first) rows and their editor cards.
@@ -22,6 +22,18 @@ export const COMPACT_PANEL_LEFT = COMPACT_VALUE_LEFT - 10;
 // own horizontal padding so the labels line up flush with the field labels below
 // them (no extra gutter — the spine/rail that used a fluid indent are gone).
 export const GROUP_INDENT = `${COMPACT_ROW_PAD_X}px`;
+/**
+ * Calm appearance: the inset of everything inside a section — rows, group
+ * headings, the one-of sentence, and the section's own header label, so all of
+ * them start on one left edge.
+ */
+export const CALM_SECTION_INSET = 16;
+/**
+ * The extra inset a calm section header's label needs to land on that edge:
+ * Reqore pads a `normal` panel's title bar by `PADDING_FROM_SIZE.normal`, and
+ * the label makes up the rest itself.
+ */
+export const CALM_SECTION_HEADER_INSET = CALM_SECTION_INSET - PADDING_FROM_SIZE.normal;
 
 // Measured label column (GLOBAL). The label column sizes to the WIDEST field
 // label across the whole form, clamped to [MIN, MAX]. FormEngine measures the
@@ -202,10 +214,15 @@ export const StyledCompactPanel = styled(ReqorePanel)<{
 
 // Compact group header laid out as the panel's `label`: the group name, a
 // hairline that fades toward the status chip, and the chip pinned at the end.
-export const StyledGroupHeader = styled.div`
+export const StyledGroupHeader = styled.div<{ $calm?: boolean }>`
   display: flex;
   align-items: center;
-  gap: 12px;
+  /* Calm: the label, its quiet count and (on Needs attention) the one amber
+     dot read as a single phrase, so they sit closer than the default's
+     label-and-chip pair. */
+  gap: ${({ $calm }) => ($calm ? 8 : 12)}px;
+  /* …and starts on the rows' left edge. */
+  padding-left: ${({ $calm }) => ($calm ? CALM_SECTION_HEADER_INSET : 0)}px;
   flex: 1;
   min-width: 0;
 `;
@@ -225,14 +242,30 @@ export const StyledStatusBox = styled(ReqorePanel)<{
   $bg?: string;
   /** The page's own background, for the PINNED header — see below. */
   $surface?: string;
+  /**
+   * Calm appearance: the box is an ordinary panel — Reqore paints the theme's
+   * panel surface and its one neutral hairline — so no tint, no accent edge
+   * and no recessed Optional box are drawn over it. Only the radius is kept,
+   * so a calm form has the same shape as a default one.
+   */
+  $calm?: boolean;
 }>`
-  &&& {
-    border: 1px solid ${({ $accent }) => `${$accent}33`};
-    /* $bg lets the muted "Optional" box opt into a darker, recessed surface
-       instead of the faint accent tint the coloured boxes use. */
-    background: ${({ $accent, $bg }) => $bg || `${$accent}1f`};
-    border-radius: 10px;
-  }
+  ${({ $calm, $accent, $bg }) =>
+    $calm ?
+      css`
+        &&& {
+          border-radius: 10px;
+        }
+      `
+    : css`
+        &&& {
+          border: 1px solid ${`${$accent}33`};
+          /* $bg lets the muted "Optional" box opt into a darker, recessed surface
+             instead of the faint accent tint the coloured boxes use. */
+          background: ${$bg || `${$accent}1f`};
+          border-radius: 10px;
+        }
+      `}
 
   /* A PINNED header needs a surface of its own.
   
@@ -248,13 +281,16 @@ export const StyledStatusBox = styled(ReqorePanel)<{
      Optional box already carries an opaque \`$bg\`, so that is used as-is.
   
      Only when \`$surface\` is supplied — i.e. only on a form that pins at all —
-     so an unpinned box is pixel-identical to before. */
-  ${({ $surface, $accent, $bg }) =>
+     so an unpinned box is pixel-identical to before.
+
+     Calm boxes carry no tint, so the pinned header is just the panel surface
+     the caller passes as \`$surface\`. */
+  ${({ $surface, $accent, $bg, $calm }) =>
     $surface ?
       css`
         &&& > .reqore-panel-title {
           background-color: ${$bg || $surface};
-          ${$bg ? '' : `background-image: linear-gradient(${$accent}1f, ${$accent}1f);`}
+          ${$bg || $calm ? '' : `background-image: linear-gradient(${$accent}1f, ${$accent}1f);`}
         }
       `
     : ''}
@@ -264,42 +300,76 @@ export const StyledStatusBox = styled(ReqorePanel)<{
 // one-of required group (in the Needs-attention box) so the constraint reads as
 // one unit. The connection rail + status nodes still render inside (they convey
 // which member satisfies the group); this box adds the explicit heading.
-export const StyledRequiredClusterBox = styled.div<{ $border: string; $tint: string }>`
-  border: 1px solid ${({ $border }) => $border};
-  border-radius: 8px;
-  background: ${({ $tint }) => $tint};
-  padding: 2px 6px 6px;
-  margin: 4px 0;
+export const StyledRequiredClusterBox = styled.div<{
+  $border: string;
+  $tint: string;
+  /** Calm: no box of its own — the heading and the hairlines carry the group. */
+  $calm?: boolean;
+}>`
+  ${({ $calm, $border, $tint }) =>
+    $calm ?
+      ''
+    : css`
+        border: 1px solid ${$border};
+        border-radius: 8px;
+        background: ${$tint};
+        padding: 2px 6px 6px;
+        margin: 4px 0;
+      `}
   /* The members render directly here (not via the gapped group body), so give
      them the same modest gap the rest of the rows have. Pin the divider-centring
      var to that gap (it doesn't widen in narrow like the group body's does). */
   display: flex;
   flex-flow: column;
-  --readfirst-row-gap: 4px;
-  gap: 4px;
+  --readfirst-row-gap: ${({ $calm }) => ($calm ? 0 : 4)}px;
+  gap: ${({ $calm }) => ($calm ? 0 : 4)}px;
 `;
-export const StyledRequiredClusterHeader = styled.div<{ $color: string }>`
+export const StyledRequiredClusterHeader = styled.div<{ $color: string; $calm?: boolean }>`
   display: flex;
   align-items: center;
   gap: 6px;
-  padding: 8px 0 4px ${GROUP_INDENT};
-  font-size: 10px;
-  font-weight: 600;
-  letter-spacing: 1px;
-  text-transform: uppercase;
   color: ${({ $color }) => $color};
+  font-weight: 600;
+  /* Calm: an amber sentence over the rows it is about, at the rows' own text
+     size and inset — the instruction, not an upper-case eyebrow. */
+  ${({ $calm }) =>
+    $calm ?
+      css`
+        padding: 12px ${CALM_SECTION_INSET}px 2px;
+        font-size: 13px;
+      `
+    : css`
+        padding: 8px 0 4px ${GROUP_INDENT};
+        font-size: 10px;
+        letter-spacing: 1px;
+        text-transform: uppercase;
+      `}
 `;
 
 // Thin schema-group sub-label inside a status box (CONNECTION / AUTHENTICATION /
 // …). Quiet by design — the box header is the loud heading; this just keeps each
 // field's group context as you scan. Indented to the rows' content line.
-export const StyledStatusBoxGroupLabel = styled.div`
-  font-size: 10px;
-  font-weight: 500;
-  letter-spacing: 1px;
-  text-transform: uppercase;
-  opacity: 0.5;
-  padding: 8px 0 2px ${GROUP_INDENT};
+//
+// Calm: the group's name as written (no upper-casing), at the rows' text size in
+// the primary text colour — the field labels below it are grey, so the heading
+// is told apart by colour and the space above it, not by shouting.
+export const StyledStatusBoxGroupLabel = styled.div<{ $calm?: boolean; $color?: string }>`
+  ${({ $calm, $color }) =>
+    $calm ?
+      css`
+        font-size: 13px;
+        font-weight: 600;
+        color: ${$color || 'inherit'};
+        padding: 14px ${CALM_SECTION_INSET}px 2px;
+      `
+    : css`
+        font-size: 10px;
+        font-weight: 500;
+        letter-spacing: 1px;
+        text-transform: uppercase;
+        opacity: 0.5;
+        padding: 8px 0 2px ${GROUP_INDENT};
+      `}
 `;
 
 // Required-group "connection" rail: contiguous members are linked by a continuous
@@ -334,14 +404,24 @@ export const StyledClusterNode = styled.span<{ $color: string; $filled: boolean;
   }
 `;
 
-export const StyledEditCard = styled.div<{ $bg: string; $border: string }>`
-  padding: 12px;
+export const StyledEditCard = styled.div<{ $bg: string; $border: string; $calm?: boolean }>`
   display: flex;
   flex-flow: column;
   gap: 8px;
   background: ${({ $bg }) => $bg};
-  border: 1px solid ${({ $border }) => $border};
-  border-radius: 8px;
+  /* Calm: an open field is a row of its section, set apart by the section's own
+     hairlines and the active-row tint — not a second card drawn inside the
+     first. */
+  ${({ $calm, $border }) =>
+    $calm ?
+      css`
+        padding: 12px ${CALM_SECTION_INSET}px;
+      `
+    : css`
+        padding: 12px;
+        border: 1px solid ${$border};
+        border-radius: 8px;
+      `}
 
   /* Single-value editors (operators, long-string, markdown, richtext, byte-size)
      carry the card's own "Clear value" action, so suppress the value input's
@@ -566,6 +646,10 @@ export const StyledGroupBody = styled.div<{
       HAS to be seen — the divider tint that separates two fields is ~8% of the
       text colour, which disappears entirely as a 1px dashed border. */
   $moreBorder: string;
+  /** Calm appearance: label/value rows split by full-width hairlines. */
+  $calm?: boolean;
+  /** The calm section's hairline — the same edge its panel is drawn with. */
+  $hairline?: string;
 }>`
   display: flex;
   flex-flow: column;
@@ -871,6 +955,102 @@ export const StyledGroupBody = styled.div<{
     padding-top: 0;
     padding-bottom: 0;
   }
+
+  /* CALM appearance — a section of label/value rows split by hairlines.
+
+     Every entry the body holds (a row, the column an open row sits in, a
+     group heading, the one-of cluster, the "N more fields" control) is drawn
+     edge to edge with ONE full-width hairline above it, the same colour as the
+     section's own edge. The first entry's line is the one under the section
+     header (a minimal header draws none of its own). Two things take no line,
+     because a heading and the rows it heads read as one block: the entry right
+     under a group heading (or its subtitle), and the first row under the
+     cluster's sentence.
+
+     Rows lose their rounded hover pill and the inset hairline between them, and
+     take the section's 16px inset. Placed last so it wins over the narrow
+     rules above, which a phone-width calm form also matches. */
+  ${({ $calm, $hairline }) =>
+    $calm ?
+      css`
+        && {
+          --readfirst-row-gap: 0px;
+          gap: 0;
+        }
+        && > *,
+        && > .options-readfirst-required-cluster > * {
+          border-top: 1px solid ${$hairline};
+        }
+        && > .options-readfirst-group-label + *,
+        && > .options-readfirst-group-subtitle + *,
+        && .options-readfirst-required-cluster-header,
+        && .options-readfirst-required-cluster-header + * {
+          border-top: 0;
+        }
+        && .readfirst-row {
+          min-height: 44px;
+          padding: 10px ${CALM_SECTION_INSET}px;
+          border-radius: 0;
+        }
+        && .readfirst-row::after {
+          display: none;
+        }
+        /* The open row keeps the read row's band: 3px above the editor's 32px
+           control centres it where the read row centred its text. */
+        && .readfirst-row-editing {
+          padding-top: 3px;
+          padding-bottom: 10px;
+        }
+        /* The section's rounded bottom corners, which a full-bleed hover or an
+           open row's tint would otherwise square off. */
+        && > :last-child,
+        && > :last-child > :last-child {
+          border-bottom-left-radius: 9px;
+          border-bottom-right-radius: 9px;
+        }
+        /* "N more fields" is a quiet last row: the hairline above it says where
+           the section's fields end; a dashed box around it said it again. */
+        && .readfirst-more-row {
+          border: 0;
+          border-top: 1px solid ${$hairline};
+          margin-top: 0;
+        }
+        &&.readfirst-narrow {
+          --readfirst-row-gap: 0px;
+        }
+        &&.readfirst-narrow .readfirst-row {
+          padding: 10px ${CALM_SECTION_INSET}px;
+          min-height: 0;
+        }
+        &&.readfirst-narrow .readfirst-row-editing {
+          padding-top: 3px;
+          padding-bottom: 10px;
+        }
+        &&.readfirst-narrow .readfirst-row:not(.readfirst-row-editing) > :nth-child(3) {
+          top: 10px;
+          right: ${CALM_SECTION_INSET}px;
+        }
+        /* READ mode is one list with no section around it — usually inside a
+           card the host already drew — so it adds no panel and no inset of its
+           own: the rows sit flush with the host's content edge, split by the
+           same hairlines, with no line above the first. */
+        &&.readfirst-read-list > :first-child {
+          border-top: 0;
+        }
+        &&.readfirst-read-list .readfirst-row,
+        &&.readfirst-read-list .options-readfirst-group-label,
+        &&.readfirst-read-list .options-readfirst-group-subtitle {
+          padding-left: 0;
+          padding-right: 0;
+          margin-left: 0;
+        }
+        &&.readfirst-read-list.readfirst-narrow
+          .readfirst-row:not(.readfirst-row-editing)
+          > :nth-child(3) {
+          right: 0;
+        }
+      `
+    : ''}
 `;
 
 // One absorbed sibling, rendered inside its host row's container rather than

package/src/components/form/engine/compactToolbarContext.ts

@@ -35,6 +35,9 @@ export interface ICompactToolbarContext {
   // Completion meter
   invalidCount: number;
   attentionCount: number;
+  /** How many of `attentionCount` are faults (invalid, or a required field the person
+   *  has been to and left empty). Zero on a fresh form: the rest are only to fill in. */
+  attentionFaultCount: number;
   completion: { set: number; done: number; total: number; pct: number };
   // Invalid-fields banner (pinned in the sticky header)
   showInvalidOnly: boolean;

package/src/components/form/engine/formAppearance.ts

@@ -0,0 +1,78 @@
+import { IReqoreTheme } from '@qoretechnologies/reqore/dist/constants/theme';
+import {
+  changeDarkness,
+  changeLightness,
+  getMainBackgroundColor,
+} from '@qoretechnologies/reqore/dist/helpers/colors';
+import { createContext, useContext } from 'react';
+
+/**
+ * How a form looks. The look only: which fields exist, how they bucket, what a
+ * click does and what is validated are identical in every appearance.
+ *
+ * - `'default'` — the established read-first look: tinted status boxes, an
+ *   intent-coloured completion meter, a status dot on every row.
+ * - `'calm'` — colour only where something needs a person. The status boxes are
+ *   plain panels on the theme's panel surface with label/value rows split by
+ *   hairlines; labels are grey; a missing required value is an amber word
+ *   instead of a red asterisk and message; counts are quiet numbers; a healthy
+ *   row carries no dot; Yes/No are plain words; nothing is forced into
+ *   uppercase. Opt-in, so an app that has not asked for it does not change.
+ */
+export type TFormEngineAppearance = 'default' | 'calm';
+
+/**
+ * The appearance in force for everything below it: the engine's own rows and
+ * toolbar, every field editor it mounts, and every nested (`arg_schema`)
+ * sub-form, which inherits it unless it is given one of its own.
+ *
+ * `FormEngine` provides it from its `appearance` prop. A host may also wrap
+ * its whole tree in it, to set the appearance once for every form — and for
+ * the field components it renders outside a form.
+ */
+export const FormAppearanceContext = createContext<TFormEngineAppearance | undefined>(undefined);
+
+export const FormAppearanceProvider = FormAppearanceContext.Provider;
+
+/** The appearance in force here; `'default'` when nothing set one. */
+export const useFormAppearance = (): TFormEngineAppearance =>
+  useContext(FormAppearanceContext) ?? 'default';
+
+/** Shorthand for the one question most call sites ask. */
+export const useIsCalmForm = (): boolean => useFormAppearance() === 'calm';
+
+/** The theme's own panel surface, when it declares one (Reqore >= 0.78.6). */
+const getDeclaredPanelSurface = (
+  theme: IReqoreTheme
+): { main?: string; border?: string } | undefined => {
+  const themed = theme as IReqoreTheme & {
+    panel?: { main?: string; border?: string };
+    originalMain?: string;
+  };
+  // Same rule as Reqore's `getThemePanelSurface`: a component whose `main` was
+  // moved off the original (a custom theme, an intent) keeps deriving its own.
+  return themed.panel && (!themed.originalMain || themed.main === themed.originalMain) ?
+      themed.panel
+    : undefined;
+};
+
+/**
+ * The surface a calm section paints, matching the one Reqore gives a panel:
+ * `theme.panel.main` when the theme declares one, else the panel shade Reqore
+ * derives from `main`. Read here rather than through Reqore's own helper so the
+ * whole peer range keeps working — the helper arrived after the floor.
+ */
+export const getCalmPanelSurface = (theme: IReqoreTheme): string =>
+  getDeclaredPanelSurface(theme)?.main ?? changeDarkness(getMainBackgroundColor(theme), 0.03);
+
+/** The neutral 1px edge of a calm section, and of every row inside it. */
+export const getCalmPanelHairline = (theme: IReqoreTheme): string =>
+  getDeclaredPanelSurface(theme)?.border ?? changeLightness(getMainBackgroundColor(theme), 0.08);
+
+/**
+ * What a calm form writes in place of an empty required value. Editable: what
+ * to do about it. Read-only: only what is the case, because the reader cannot
+ * add anything.
+ */
+export const CALM_REQUIRED_LABEL = 'Required · add a value';
+export const CALM_REQUIRED_READ_LABEL = 'Required · not set';

package/src/components/form/engine/readFirst.ts

@@ -854,9 +854,13 @@ export interface IReadFirstCompletion {
  * status BOX bucketing (FormEngine) so the two can never disagree:
  *   invalid  — a value fails validation, or a danger message is present (red)
  *   todo     — empty & required (or has a warning message), needs a value (amber)
+ *   pending  — empty & required, but the person has not been to it yet: still to
+ *              fill in, not yet a fault (neutral). A new form is not already wrong;
+ *              the field becomes `todo` once they open it and leave it empty, or the
+ *              host reports a submit attempt (`revealRequired`)
  *   set      — has a valid value (green)
  *   optional — empty & not required, or covered by a one-of sibling (calm) */
-export type TReadFirstStatus = 'invalid' | 'todo' | 'set' | 'optional';
+export type TReadFirstStatus = 'invalid' | 'todo' | 'pending' | 'set' | 'optional';
 
 export const getReadFirstStatus = (s: {
   empty: boolean;
@@ -867,17 +871,26 @@ export const getReadFirstStatus = (s: {
   invalid: boolean;
   /** A warning message is attached (surfaces an empty field for attention). */
   warned: boolean;
+  /**
+   * Whether the person has been to this field (opened it and left it), or the host
+   * reported a submit attempt. Until then an empty required field is `pending`, not
+   * `todo`. Unset means visited, the behaviour before this existed.
+   */
+  visited?: boolean;
 }): TReadFirstStatus => {
   if (s.invalid) return 'invalid';
   if (!s.empty) return 'set';
   // A one-of member covered by a satisfied sibling reads as "set" (green) — the
   // requirement is met; the row just shows a "Covered by …" note.
   if (s.covered) return 'set';
-  if (s.required || s.warned) return 'todo';
+  if (s.warned) return 'todo';
+  if (s.required) return s.visited === false ? 'pending' : 'todo';
   return 'optional';
 };
 
-/** Coarse bucket for the three status boxes (Needs attention / Set / Optional). */
+/** Coarse bucket for the three status boxes (Needs attention / Set / Optional). A
+ *  `pending` field is in the first box too: it still has to be filled in. The box only
+ *  reads "To fill in" instead of "Needs attention" while nothing in it is a fault. */
 export const getReadFirstBucket = (status: TReadFirstStatus): 'attention' | 'set' | 'optional' =>
   status === 'set' ? 'set'
   : status === 'optional' ? 'optional'

package/src/components/form/engine/rowFocus.ts

@@ -15,9 +15,11 @@
  * focusable element" would answer a text field with a button beside it.
  */
 
-/** Controls the reader types into. */
+/** Controls the reader types into. `role="textbox"` is how an editor that is neither
+ *  an input nor contenteditable says so: Monaco's edit area is a focusable div with that
+ *  role (its own `<textarea>` is an `aria-hidden` IME helper). */
 const TEXT_ENTRY_SELECTOR =
-  'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), [contenteditable="true"]';
+  'input:not([type="hidden"]):not([disabled]), textarea:not([disabled]), [contenteditable="true"], [role="textbox"]:not([aria-disabled="true"])';
 
 /**
  * Everything else a row can offer. `[tabindex]` is what carries reqore's own
@@ -58,17 +60,26 @@ const firstMatch = (container: HTMLElement, selector: string): HTMLElement | und
  * a read-only preview, or an editor that has not mounted yet (see the caller,
  * which watches for it to arrive).
  *
+ * `textEntryOnly` is for a field that opens as a CARD (a long text, a list, source
+ * code). A card is a form in its own right, so its first button is one of several —
+ * a toolbar's "fullscreen", a list's "add" — and nobody asked for it; a caret there
+ * turns the next space typed into a press. A card takes the caret only where text
+ * goes, and waits for it when its editor mounts late (a code editor does).
+ *
  * @param container the row's value cell
  */
 export const findRowFocusTarget = (
-  container: HTMLElement | null | undefined
+  container: HTMLElement | null | undefined,
+  { textEntryOnly = false }: { textEntryOnly?: boolean } = {}
 ): HTMLElement | undefined => {
   if (!container) {
     return undefined;
   }
-  return (
-    firstMatch(container, TEXT_ENTRY_SELECTOR) ?? firstMatch(container, OTHER_CONTROL_SELECTOR)
-  );
+  const textEntry = firstMatch(container, TEXT_ENTRY_SELECTOR);
+  if (textEntry || textEntryOnly) {
+    return textEntry;
+  }
+  return firstMatch(container, OTHER_CONTROL_SELECTOR);
 };
 
 /**

package/src/components/form/expressions/renderExpressionToText.ts

@@ -4,6 +4,7 @@
 // can wait uses it: Explain and the Text view's Preview wait for the server's
 // `dpql/renderExpression` (see `useRenderExpression`). Pure: no
 // transport/socket import, so it stays out of the LSP/nanoid dependency graph.
+import { richtextToString } from '../../../helpers/common';
 import { IExpression, IExpressionSchema, IExpressionValue } from './types';
 
 /** A symbol made only of non-word characters renders infix (`a == b`). */
@@ -72,8 +73,22 @@ const readArgValue = (arg: unknown): unknown =>
     ? (arg as { value: unknown }).value
     : arg;
 
+/** A rich-text value: the editor's document, a list of element nodes with children. */
+const isRichTextDocument = (value: unknown): value is unknown[] =>
+  Array.isArray(value) &&
+  value.length > 0 &&
+  value.every(
+    (node) =>
+      !!node && typeof node === 'object' && Array.isArray((node as { children?: unknown }).children)
+  );
+
 const renderLiteral = (value: unknown): string => {
   if (value === undefined || value === null) return 'null';
+  /* Rich text is the string it reads as, its template references written out as `$…`.
+     Printed as an object it was the editor's node tree — `+([{"type":"paragraph",
+     "children":[…]}], …)` on a Qog's Message Content row — which is no value anyone
+     wrote, and not what the server renders either. */
+  if (isRichTextDocument(value)) return JSON.stringify(richtextToString(value as never));
   if (typeof value === 'string') return JSON.stringify(value);
   if (typeof value === 'object') return JSON.stringify(value);
   return String(value);

package/src/components/form/fields/ChoiceGroupHeading.tsx

@@ -0,0 +1,38 @@
+import { ReqoreSpan } from '@qoretechnologies/reqore';
+import { memo } from 'react';
+import { useIsCalmForm } from '../engine/formAppearance';
+
+/**
+ * The heading over a small group of choices (the checkboxes a field with three
+ * or fewer allowed values renders) — the field's own name, or "Select one:"
+ * when it has none.
+ *
+ * One component so both choice editors head their groups the same way, in
+ * either appearance: an upper-case micro label by default; in the calm look the
+ * words as written, at the small text size, because nothing in a calm form is
+ * forced into capitals.
+ */
+export const ChoiceGroupHeading = memo(({ children }: { children: React.ReactNode }) => {
+  const calm = useIsCalmForm();
+
+  return (
+    <ReqoreSpan
+      className='reqraft-choice-group-heading'
+      effect={calm ? { opacity: 0.7, weight: 'bold' } : { opacity: 0.6, uppercase: true, weight: 'bold' }}
+      size={calm ? 'small' : 'tiny'}
+    >
+      {children}
+    </ReqoreSpan>
+  );
+});
+
+/**
+ * The intent a picked choice in those groups takes. Blue by default; none in
+ * the calm look, where blue says only "a filter is on" and the checked mark
+ * already says which choice is picked.
+ */
+export const useSelectedChoiceIntent = (): ((selected: boolean) => 'info' | undefined) => {
+  const calm = useIsCalmForm();
+
+  return (selected) => (selected && !calm ? 'info' : undefined);
+};