@colixsystems/widget-sdk 0.248.0 → 0.249.0

package/README.md

@@ -84,7 +84,29 @@ See the design reference for the full architecture: [`docs/architecture/widget-m
 
 ## Status
 
-`v0.248.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+`v0.249.0` — pre-publish. The package surface (types, function names, export paths) is the v1 contract; runtime behaviour for some hooks is stubbed (each hook documents what's wired and what isn't). It is **not yet published to npm**.
+
+### What's new in 0.249.0 (contract 1.203.0)
+
+**Icons inside a text field.** `<TextField>` takes `leadingIcon` and `trailingIcon`, each a lucide name, and draws the icon inside its own border with the text kept clear of it. A plain icon is hidden from screen readers and lets a tap through to the field. Pass `onTrailingPress` and `trailingAccessibilityLabel` to make the trailing icon a button (a clear control, "use my location"); it is disabled with the field. A field with an icon is no longer wrapped in a bordered row of your own, which drew a box inside a box:
+
+```jsx
+<TextField
+  label={t("pickup", "Pickup address")}
+  value={address}
+  onChangeText={setAddress}
+  leadingIcon="map-pin"
+  trailingIcon="locate"
+  onTrailingPress={useMyLocation}
+  trailingAccessibilityLabel={t("use_location", "Use my location")}
+/>
+```
+
+- A field with icon props sits in a box: `containerStyle` styles it even without a label, and the flex, margin, width and position keys of `style` move to it, so `style={{ flex: 1 }}` still sizes the field in a row. A field without icon props renders exactly as before.
+- Passing an icon prop at all keeps the box, so `trailingIcon={text ? "x" : undefined}` never rebuilds the input while someone types.
+- The slots are named `${testID}-leading-icon` / `${testID}-trailing-icon`, or `leadingTestID` / `trailingTestID`.
+- `<SearchField>` draws its glyph and clear control through these slots; it looks and behaves as before, and its `containerStyle` reaches its outermost box with or without a label.
+- **New linter rule `field-in-bordered-row` (severity `warning`, non-blocking).** It flags a `<TextField>` or `<SearchField>` that is a direct child of a row (`flexDirection: "row"`) with a non-zero `borderWidth`, read from the row's inline style and the StyleSheet entries it names. A bordered column, such as a card holding a form, is not flagged. Its sibling **`field-trailing-press-unnamed`** (also a warning) flags `onTrailingPress` with no `trailingAccessibilityLabel`, a button a screen reader can only call "button"; the types require the label too.
 
 ### What's new in 0.248.0 (contract 1.202.0)
 
@@ -3134,7 +3156,7 @@ import { defineWidget, validateManifest, useDatastoreQuery, Text, View } from "@
 - `Grid` — balanced lines of cells sized from the grid's own measured width, on both hosts. `<Grid minCellWidth gap balance>`: `balance` `"cards"` (default) fits as many cells to a line as `minCellWidth` allows (240 when unset), fills every line but the last and pads that one with empty cells; `"tiles"` spreads the remainder and stretches each line (5 at 4 per line are 3 + 2), with `maxColumns` or the width tier (4 / 3 / 2) as the ceiling. `columns` fixes the count per line; `cell={{ min, max }}` with `square` makes definite-size cells (calendar days, seats, swatches) in a centred block. It measures an inner box with no padding, and `gap` is a theme spacing name or a number. Each child keeps its own look, and a child with `flex: 1` fills its cell's height. Use it by default for card grids, tile rows and capped cells; masonry or spanning cells are yours to lay out with `useContainerWidth()`.
 - `Form`, `FieldRow`, `FormSection`, `FormActions`, `FormField` — a form laid out in width tiers from its own measured width, on both hosts: `<Form columns maxWidth gap>` puts its fields one to a line when narrow, two at medium and up to three when wide (`columns` is the wide ceiling), capped near 1000px and centred (`maxWidth={null}` for none). A `<FormField>`, or a `<TextField>`, `<Select>`, `<RadioGroup>`, `<PeoplePicker>` or `<FileUpload>` with its own label, is one field; a multiline field, `<FormField span="full">`, `<FieldRow>` (short related fields on one line, stacked when narrow), `<FormSection title description>` and `<FormActions>` (Save / Cancel in normal flow, secondary first and primary last, a trailing row or a full-width stack when narrow) take the whole line. `<FormField label required helper error>` draws the form controls' label, required mark, helper and error round any control and names it for a screen reader; a control that frames its own label is handed them instead, so one label is drawn. `required` (also on `TextField`, `Select`, `RadioGroup`, `PeoplePicker`, `FileUpload`) draws the mark and adds "Required" to the spoken name; it does not validate. Use it by default; a multi-step wizard, a form beside a live preview or fields laid over a picture are yours to lay out with `useContainerWidth()`.
 - `SortableList`, `Board` — drag and drop on both hosts. `<SortableList items onReorder renderItem>` is a list the user reorders, each row a `<ListRow>`; `<Board columns items getColumn onMove renderCard>` is cards moved between columns, each a `<Card>`. Both own the grip handle, the lifted copy, the vacated slot, the drop highlight in the soft primary, the spring back of a cancelled drag and a narrow board's sideways scroll, and give a user who cannot drag the same moves: a tap or Enter on the handle opens its move options, the arrow keys move it on the web, a screen reader gets them as actions, and each move is announced. `onReorder(nextItems, { from, to, item })` and `onMove(item, { fromColumn, toColumn, index })` run once per real change. Use them by default; a drag they cannot express (free-form positioning, a drag between two widgets) is yours to build with `Animated` + `PanResponder`.
-- `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Design > Components (Cards, Buttons, Inputs); never hand-roll one from `View` / `Pressable` / a bare `TextInput`.
+- `Card`, `Button`, `TextField` — the themed card surface, button and text field the built-in widgets render through. With no props each takes the app's look from Design > Components (Cards, Buttons, Inputs); never hand-roll one from `View` / `Pressable` / a bare `TextInput`. `<TextField leadingIcon trailingIcon onTrailingPress trailingAccessibilityLabel>` draws icons inside the field's own border.
 - `Banner` — the themed inline message. `<Banner tone message>` shows an error, warning, success or notice in place, styled by the theme's `alert` scope; `action` adds one button and `onDismiss` a close control. Use `useToast()` for a brief confirmation instead. Never hand-roll a tinted error box.
 - `Accordion`, `AccordionItem` — themed collapsible sections. `<Accordion><AccordionItem title subtitle trailing>…</AccordionItem></Accordion>` draws its surface from the theme's `card` scope and its headers and dividers from the `list` scope; one section open at a time, or `multiple`. Never hand-roll a collapsible from `Pressable` + a chevron.
 - `Spinner`, `Skeleton` — the themed loading states. `<Spinner size label>` for a pending action; `<Skeleton shape="text" | "block" | "circle" | "listRow">` (or a group of bones) for content whose layout you know. The spinner wears `colors.loader`, the skeleton follows the theme's `loading` scope; both stop under reduced motion and mark one busy region. Never use `ActivityIndicator` or hand-build placeholder bars.
@@ -3175,7 +3197,7 @@ A widget that works but looks unfinished is only half done. `useTheme()` is the
 - **Spend one gradient.** `<Gradient colors={[theme.colors.primary, theme.colors.primaryStrong]} angle={160} style={…}>` is a `View` that paints a gradient behind its children, so it replaces the `View` you'd otherwise give a flat `backgroundColor`. `angle` is CSS degrees (0 = to top, 90 = to right, default 180); text on it uses `colors.onPrimary`. Exactly **one** per widget — on the focal element — and never behind body text. Both hosts render it identically (web paints CSS, native uses `expo-linear-gradient`), so there is no per-platform branching to write; don't import `expo-linear-gradient` yourself and don't write a `backgroundImage` string.
 - **Answer the touch.** Every tappable card, row and list entry lifts while the pointer is over it (web) or it is pressed (touch). One declaration does both: give the Pressable a style FUNCTION and spread `pressableLift` — `<Pressable onPress={open} style={(state) => [styles.card, ...pressableLift(state)]}>`. The lift is a -2px nudge plus one elevation step from `theme.interaction`, with the web transition built in. Never hand-write hover logic or your own pressed shadows, and never fake feedback with `opacity` — a dimmed surface reads as disabling itself.
 - **Size to your container — measure it, don't stretch into it.** The same widget sits in a full-width desktop section (~1400px), a half-width grid cell (~700px) and a phone (~360px), so layout built only from `flex: 1` stretches to fill whatever it is handed — a month calendar ends up with 200px day cells and swallows the page. Measure your own width with `const [width, onLayout] = useContainerWidth();`, spreading `onLayout` on an unpadded root `View` (a React Native callback, so it behaves identically on both hosts). A width of `0` means "not yet measured" and the SDK helpers answer it with the wide form, so do not special-case it — except a count or size computed from the width (a calendar day, a chart, a card grid's cards per line), which renders nothing size-dependent until the width arrives: a widget gets no declared breakpoint prop, but it can always measure. **Every form, list, table and filter bar lays out in three tiers** (sc-8508): `const [width, onLayout] = useContainerWidth();` then branch on `widthTier(width)` — a form is one column narrow, paired short fields at medium, a 2–3 column grid capped near 1000px wide; a list is stacked cards, one-line cards, then real columns under a header; a filter bar is one toolbar row (search, a dropdown per facet, sort) with the active filters as removable chips beneath, and a single "Filters" button opening a panel when narrow. **Cap a repeating cell** rather than giving a grid `flex: 1` — `const cell = Math.max(32, Math.min(Math.floor((usable - gap * (columns - 1)) / columns), 64));`, with a calendar day cell topping out at 56–72px on `aspectRatio: 1`, and the grid given its exact computed width plus `alignSelf: 'center'` when the cap leaves slack. **Split two co-equal surfaces in the wide tier** (`flexDirection: widthTier(width) === 'wide' ? 'row' : 'column'`, each half `{ flex: 1, minWidth: 0 }`) — a picker beside the form it feeds on a wide canvas, stacked in reading order below it. Never hardcode a width, never put `flex: 1` / `height: '100%'` on a content widget's root, and don't read the screen with `Dimensions` — the screen is not the widget. **Whatever you narrow, you centre** — a block that caps its own measure carries all three of `{ width: '100%', maxWidth: FORM_MAX, alignSelf: 'center' }`, because `alignSelf` alone stops the block stretching and sizes it to its content instead, and `maxWidth` alone leaves the widget flush left with dead space beside it; a capped wrap row lays its cells out along the MAIN axis, so it centres with `justifyContent: 'center'` on the row instead — but a card grid or a tile row is never capped. **Lay out a card grid, a tile row or a grid of capped cells with `<Grid>` by default** — it measures its own unpadded box and applies the rules below; lay one out yourself when it needs what `<Grid>` cannot express, such as masonry or cells that span lines. **A card grid fills its lines, it never wraps freely** — a free `flexWrap` strands the remainder (six cards that fit five render 5 + 1). Count the cards that fit the measured width (`const max = Math.max(1, Math.floor((width + gap) / (CARD_MIN + gap)));`), take `const lines = Math.ceil(count / max); const cols = Math.ceil(count / lines);`, and render each slice of `cols` cards as a row of `{ flex: 1, minWidth: 0 }` cells, padding the last line with empty `{ flex: 1 }` spacers so its cards keep the width of the cards above (six that fit five are 3 + 3, ten that fit four are 4 + 4 + 2). **A short value never breaks across lines** — a time, date, price, count, percentage or code takes `numberOfLines={1}` and `flexShrink: 0`, never a fixed width narrower than it, and a narrow slot re-arranges or steps the font down instead. **A metric / stat-tile row FILLS ITS ROW** — when you know the count, balance the lines (`const lines = Math.ceil(count / max); const base = Math.floor(count / lines); const extra = count % lines; const rows = Array.from({ length: lines }, (_, i) => tiles.slice(i * base + Math.min(i, extra), (i + 1) * base + Math.min(i + 1, extra)));`, with `max` 4 / 3 / 2 by tier, each tile `{ flex: 1, minWidth: 0 }`), and when the count comes from data wrap it (`{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }`, each tile `{ flexGrow: 1, flexBasis: TILE_MIN }`, never a `maxWidth` — capped tiles cluster to one side), because a bare `flexDirection: 'row'` has no way to break and a React Native flex child defaults to `flexShrink: 0` (unlike CSS), so the tiles cannot give ground either: the row runs past its container, spilling out of the card natively and cut off by the scrolling page column on web, with nothing thrown and nothing logged, once there are enough of them (four fit where five do not). The basis is also the per-line ceiling — `Math.floor((usable + gap) / (TILE_MIN + gap))` tiles fit a line, so 240 tops out at five across a full-width ~1400px section and 320 at four; past four or five a line the tiles stop reading as cards.
-- **Compose forms — pair fields into rows, don't stack one per row.** Lay a form out with `<Form>` by default (above), which does the following for you; when it needs what `<Form>` cannot do (a multi-step wizard, a form beside a live preview, fields laid over a picture), lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. A search box is `<SearchField>`, which already carries its glyph and clear control. Put any other icon or unit beside the field as a sibling in a row (`flex: 1, minWidth: 0` on the field, so a long value shrinks instead of pushing the row past its container) rather than rebuilding the field to hold it: a hand-built bordered wrapper around a bare `TextInput` loses the app's input look and its label, focus and error handling.
+- **Compose forms — pair fields into rows, don't stack one per row.** Lay a form out with `<Form>` by default (above), which does the following for you; when it needs what `<Form>` cannot do (a multi-step wizard, a form beside a live preview, fields laid over a picture), lay the form out in three tiers and cap it near 1000px, centred with the three declarations above — never a 560–720px column alone in a wide box, which leaves a form that IS the page as a narrow strip in empty space. Put short, related fields side by side (first + last name, city + postal code, expiry + CVC): a row of `{ flexDirection: 'row', flexWrap: 'wrap', gap: theme.spacing.md }` with each field cell `{ flexGrow: 1, flexBasis: 160 }` splits the width on a wide card and wraps to stacked on a narrow phone — the right recipe for field pairs because it needs no measurement (a fixed-width column overflows a phone; when a layout needs a real column count instead of wrapping, measure your width as above). Keep wide fields (email, address, notes) full-width with `width: '100%'` — NEVER `flexBasis: '100%'`, which sizes the main axis and therefore claims the parent's whole HEIGHT in a column (sc-7274) — cap it at two–three per row, group a long form into labelled sections, and label every input above it (not placeholder-only). Give a `multiline` field BOTH a floor and a ceiling (`{ minHeight: 150, maxHeight: 260 }`) so a long value scrolls inside the box instead of growing past its card, and keep the Save / Cancel row in normal flow below the fields, never positioned over them. A search box is `<SearchField>`, which already carries its glyph and clear control. Any other icon goes inside the field through `leadingIcon` / `trailingIcon`; never wrap a `<TextField>` in a bordered row, since it draws its own border. Put a unit beside the field as a sibling in a row (`flex: 1, minWidth: 0` on the field, so a long value shrinks instead of pushing the row past its container) rather than rebuilding the field to hold it: a hand-built bordered wrapper around a bare `TextInput` loses the app's input look and its label, focus and error handling.
 - **Respond to touch.** Give every `Pressable` the lift via the function-style `style={(state) => [base, ...pressableLift(state)]}` — see "Answer the touch" above. Never dim with `opacity`, which reads as the surface disabling itself.
 - **Drag and drop — show what is being dragged.** Use `<SortableList>` for a list the user reorders and `<Board>` for cards moved between columns by default: they do everything this item describes, on both hosts, and give a user who cannot drag the same moves from the handle. When the request needs what they cannot do (free-form positioning on a canvas, a drag between two widgets), build your own as follows. A drag where the item stays put reads as broken. Three things change the moment a drag starts: the **drag proxy** (the item lifts and follows the finger — `...theme.elevation.lg`, `{ scale: 1.03 }`, `opacity: 0.9`; for a tall or full-width item drag a compact `primarySoft` pill with its icon + one line of label instead), the **source placeholder** (the vacated slot keeps its height as a quiet `colors.surfaceMuted` block so the list doesn't collapse), and the **drop target** (one slot at a time highlighted with `primarySoft` or a 2px `colors.primary` border). Always animate the release — settle into the new slot, or `Animated.spring(pan, { toValue: { x: 0, y: 0 }, useNativeDriver: false })` back to the origin on cancel. Build it with `Animated` + `PanResponder` from `react-native` (the only mechanism that behaves identically on both hosts) — never HTML5 drag events (`draggable` / `onDragStart` / `dataTransfer` are web-only, and `document` / `window` are banned) — and start the drag from a `GripVertical` grip handle whenever the row is also tappable or sits in a `ScrollView`. **A board (kanban, pipeline) drops onto ANOTHER column**, which needs four more things: the board's root renders the one proxy (a column clips whatever leaves it); you hit-test the drop yourself — `measureInWindow` every column and the board when the drag starts and compare the gesture's window `moveX` (never `onLayout` frames, which are relative to a padded or scrolled parent) — highlighting exactly one target; the drop WRITES (`update(id, { [statusField]: value })` through `useDatastoreMutation`, optimistic until `refetch()`, a toast and a spring-back on failure); and three or more columns go in a `horizontal` `ScrollView` when `widthTier(width) === "narrow"`, with the grip claiming the gesture (`onStartShouldSetPanResponder`, `onPanResponderTerminationRequest: () => false`) and carrying `touchAction: 'none'` on web so a finger drag moves the card instead of scrolling the page. And because `useRef(PanResponder.create(...))` runs ONCE, everything its callbacks read — the `useCanWrite` flag included, which starts `false` — goes through a ref refreshed every render (`latest.current.canDrag`); the publish gate `widget.staleResponder` rejects a value read directly.
 - **Use icons for clarity.** Pair a `lucide-react-native` icon with its label at a consistent size, coloured from the theme. The label never repeats the icon as a character — with a `Plus` icon the button says "Add item", never "+ Add item" (that renders a doubled plus).

package/dist/contract.cjs

@@ -3526,7 +3526,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3547,7 +3547,7 @@ const PRIMITIVES = [
   {
     name: "SearchField",
     description:
-      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
+      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it; its glyph and clear control fill the icon slots of `TextField`, so it takes no `leadingIcon` / `trailingIcon`. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6326,7 +6326,11 @@ const CONTRACT = deepFreeze({
   //    `<DataTable>`, `<FilterBar>`, `<Form>` / `<FieldRow>` / `<FormSection>`
   //    / `<FormActions>` / `<FormField>`, `<SortableList>`, `<Board>`;
   //    `required` on TextField, Select, RadioGroup, PeoplePicker, FileUpload.
-  version: "1.202.0",
+  // 1.203.0: additive (sc-12232) — `<TextField>` takes `leadingIcon`,
+  //    `trailingIcon`, `onTrailingPress`, `trailingAccessibilityLabel` and the
+  //    slots' testIDs; `<SearchField>` draws through them. New warnings
+  //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
+  version: "1.203.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/contract.js

@@ -3526,7 +3526,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3547,7 +3547,7 @@ const PRIMITIVES = [
   {
     name: "SearchField",
     description:
-      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
+      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it; its glyph and clear control fill the icon slots of `TextField`, so it takes no `leadingIcon` / `trailingIcon`. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6322,7 +6322,11 @@ const CONTRACT = deepFreeze({
   //    `<DataTable>`, `<FilterBar>`, `<Form>` / `<FieldRow>` / `<FormSection>`
   //    / `<FormActions>` / `<FormField>`, `<SortableList>`, `<Board>`;
   //    `required` on TextField, Select, RadioGroup, PeoplePicker, FileUpload.
-  version: "1.202.0",
+  // 1.203.0: additive (sc-12232) — `<TextField>` takes `leadingIcon`,
+  //    `trailingIcon`, `onTrailingPress`, `trailingAccessibilityLabel` and the
+  //    slots' testIDs; `<SearchField>` draws through them. New warnings
+  //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
+  version: "1.203.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,

package/dist/index.d.ts

@@ -4376,17 +4376,44 @@ export interface FormFieldOverrides {
   height?: number;
 }
 
+/**
+ * The icons `<TextField>` draws inside its own border. Passing either prop at
+ * all, even `undefined`, keeps the box they sit in, so an icon shown only
+ * with text never rebuilds the input.
+ */
+export type TextFieldIconProps = {
+  /** A lucide name, drawn at the start of the field. */
+  leadingIcon?: string | null;
+  /** A lucide name, drawn at the end of the field. */
+  trailingIcon?: string | null;
+  /** Default `${testID}-leading-icon`. */
+  leadingTestID?: string;
+  /** Default `${testID}-trailing-icon`. */
+  trailingTestID?: string;
+} & (
+  | { onTrailingPress?: undefined; trailingAccessibilityLabel?: string }
+  | {
+      /** Makes the trailing icon a button, disabled with the field. */
+      onTrailingPress: () => void;
+      /** Required: the icon is the button's only content. */
+      trailingAccessibilityLabel: string;
+    }
+);
+
 /**
  * Themed text-entry field (Design > Components > Inputs). Every TextInput prop
- * works.
+ * works. An icon goes inside it through `leadingIcon` / `trailingIcon`, never
+ * in a bordered row around it.
  *
  * @example
  *   <TextField label="Name" value={name} onChangeText={setName} placeholder="Your name" />
+ *   <TextField label="Pickup" value={address} onChangeText={setAddress} leadingIcon="map-pin" />
  */
-export const TextField: (props: FormControlProps & FieldRequiredProps & FormFieldOverrides & {
+export const TextField: (props: FormControlProps & FieldRequiredProps & FormFieldOverrides & TextFieldIconProps & {
   multiline?: boolean;
+  /** The input; with icon props, its flex, margin, width and position keys go to the box. */
   style?: any;
-  /** The box around a labelled field. */
+  /** The box around a labelled field, or around the field and its icons. */
   containerStyle?: any;
   [prop: string]: any;
 }) => any;
@@ -4707,7 +4734,7 @@ export const SearchField: (props: FormControlProps & {
   placeholder?: string;
   /** Default "Clear search". */
   clearAccessibilityLabel?: string;
-  /** The input. */
+  /** The input; its flex, margin, width and position keys go to the box around it. */
   style?: any;
   /** The box around it; use it for `flex: 1` in a toolbar. */
   containerStyle?: any;

package/dist/linter.cjs

@@ -1563,6 +1563,160 @@ function _fullWidthMarginRules(source) {
   return findings;
 }
 
+// sc-12232 — a field inside a bordered row draws two borders.
+// A warning: refs resolve by key name, and a bordered column is fine.
+const _FIELD_TAG_NAMES = ["TextField", "SearchField"];
+const _JSX_TOKEN_RE = /<(\/?)([A-Z][\w.]*)?/g;
+const _STYLE_ATTR_RE = /\bstyle\s*=\s*\{/;
+const _STYLE_REF_RE = /\b[A-Za-z_$][\w$]*\.([A-Za-z_$][\w$]*)/g;
+const _STYLE_ENTRY_RE = /(?<![\w$.])([A-Za-z_$][\w$]*)\s*:\s*\{/g;
+const _BORDER_WIDTH_KEY_RE = /\bborderWidth\s*:/g;
+const _ROW_KEY_RE = /\bflexDirection\s*:\s*(["'`])row(?:-reverse)?\1/;
+const _UNNAMED_PRESS_RE = /\bonTrailingPress\s*=/;
+const _PRESS_NAME_RE = /\btrailingAccessibilityLabel\s*=|\{\s*\.\.\./;
+
+// One pass over the source: the first `key: {` of each name, by offset.
+function _styleEntryOffsets(structure) {
+  const offsets = new Map();
+  _STYLE_ENTRY_RE.lastIndex = 0;
+  let entry;
+  while ((entry = _STYLE_ENTRY_RE.exec(structure))) {
+    if (!offsets.has(entry[1])) offsets.set(entry[1], entry.index + entry[0].length);
+  }
+  return offsets;
+}
+
+// The object literals a style expression spans, plus the entries it names.
+function _styleObjectSpans(scan, [from, to]) {
+  const { structure } = scan;
+  const spans = [];
+  for (let i = from + 1; i < to - 1; i++) {
+    if (structure[i] !== "{") continue;
+    const span = _enclosingObject(structure, i + 1);
+    if (!span) continue;
+    spans.push(span);
+    i = span[1] - 1;
+  }
+  if (!scan.entries) scan.entries = _styleEntryOffsets(structure);
+  const keys = new Set();
+  _STYLE_REF_RE.lastIndex = 0;
+  const refs = structure.slice(from, to);
+  let ref;
+  while ((ref = _STYLE_REF_RE.exec(refs))) keys.add(ref[1]);
+  for (const key of keys) {
+    const at = scan.entries.get(key);
+    const span = at === undefined ? null : _enclosingObject(structure, at);
+    if (span) spans.push(span);
+  }
+  return spans;
+}
+
+function _isBorderedRow(scan, tag) {
+  const { code, structure } = scan;
+  const attrs = structure.slice(tag.attrs[0], tag.attrs[1]);
+  const style = _STYLE_ATTR_RE.exec(attrs);
+  if (!style) return false;
+  const open = tag.attrs[0] + style.index + style[0].length - 1;
+  const inner = _bracedSpan(structure, open);
+  if (inner === null) return false;
+  let row = false;
+  let bordered = false;
+  // `inner` excludes its two braces.
+  for (const span of _styleObjectSpans(scan, [open, open + inner.length + 2])) {
+    const keys = _ownKeysMask(structure, span);
+    if (_ROW_KEY_RE.test(_ownKeysMask(code, span))) row = true;
+    _BORDER_WIDTH_KEY_RE.lastIndex = 0;
+    let key;
+    while ((key = _BORDER_WIDTH_KEY_RE.exec(keys))) {
+      const valueAt = span[0] + key.index + key[0].length;
+      if (!_ZERO_VALUE_RE.test(code.slice(valueAt, valueAt + 40))) bordered = true;
+    }
+  }
+  return row && bordered;
+}
+
+function _selfClosing(structure, end) {
+  let i = end - 1;
+  while (i >= 0 && /\s/.test(structure[i])) i--;
+  return structure[i] === "/";
+}
+
+function _fieldInBorderedRowRules(source) {
+  const findings = [];
+  const scan = {
+    code: _stripNonCode(source, { keepStrings: true }),
+    structure: _stripNonCode(source),
+    entries: null,
+  };
+  const { code, structure } = scan;
+  const sourceLines = source.split(/\r?\n/);
+  // Tokens arrive in source order, so one running count serves every finding.
+  let line = 1;
+  let counted = 0;
+  const lineOf = (at) => {
+    for (; counted < at; counted++) if (code[counted] === "\n") line++;
+    return line;
+  };
+  const report = (rule, at, label) => {
+    const n = lineOf(at);
+    findings.push({
+      rule,
+      severity: "warning",
+      label,
+      line: n,
+      snippet: (sourceLines[n - 1] || "").trim().slice(0, 200),
+    });
+  };
+  const open = [];
+  _JSX_TOKEN_RE.lastIndex = 0;
+  let token;
+  while ((token = _JSX_TOKEN_RE.exec(structure))) {
+    const [, closing, name] = token;
+    if (!name) {
+      // A fragment, `<>` or `</>`; any other `<` is a comparison.
+      if (structure[token.index + 1 + closing.length] !== ">") continue;
+      if (closing) open.pop();
+      else open.push(null);
+      continue;
+    }
+    if (closing) {
+      const at = open.map((tag) => tag && tag.name).lastIndexOf(name);
+      if (at >= 0) open.length = at;
+      continue;
+    }
+    const end = _tagEnd(structure, token.index);
+    if (end === -1) break;
+    const tag = { name, attrs: [token.index + token[0].length, end], borderedRow: undefined };
+    if (_FIELD_TAG_NAMES.includes(name)) {
+      const parent = open[open.length - 1];
+      if (parent && parent.borderedRow === undefined) parent.borderedRow = _isBorderedRow(scan, parent);
+      if (parent && parent.borderedRow) {
+        report(
+          "field-in-bordered-row",
+          token.index,
+          `<${name}> draws its own border, so the bordered row around it ` +
+            `shows a box inside a box. Put the icon in the field with ` +
+            `leadingIcon / trailingIcon (onTrailingPress makes it a button) ` +
+            `and drop the row's border.`,
+        );
+      }
+      const attrs = structure.slice(tag.attrs[0], tag.attrs[1]);
+      if (_UNNAMED_PRESS_RE.test(attrs) && !_PRESS_NAME_RE.test(attrs)) {
+        report(
+          "field-trailing-press-unnamed",
+          token.index,
+          `onTrailingPress makes the trailing icon a button with no name, so ` +
+            `a screen reader says only "button". Give it a translated ` +
+            `trailingAccessibilityLabel.`,
+        );
+      }
+    }
+    if (!_selfClosing(structure, end)) open.push(tag);
+    _JSX_TOKEN_RE.lastIndex = end + 1;
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding, so cells sized
 // from it overflow the content box and the last one wraps into an empty column.
 // Mirror of linter.js (see there for the full rationale).
@@ -2188,6 +2342,8 @@ function lintSource(source, options) {
   findings.push(..._flexBasisPercentRules(source));
   // sc-11277 — soft warning: a full-width box with a side margin is clipped.
   findings.push(..._fullWidthMarginRules(source));
+  // sc-12232 — soft warning: a field inside a bordered row draws two borders.
+  findings.push(..._fieldInBorderedRowRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/linter.js

@@ -1604,6 +1604,160 @@ function _fullWidthMarginRules(source) {
   return findings;
 }
 
+// sc-12232 — a field inside a bordered row draws two borders.
+// A warning: refs resolve by key name, and a bordered column is fine.
+const _FIELD_TAG_NAMES = ["TextField", "SearchField"];
+const _JSX_TOKEN_RE = /<(\/?)([A-Z][\w.]*)?/g;
+const _STYLE_ATTR_RE = /\bstyle\s*=\s*\{/;
+const _STYLE_REF_RE = /\b[A-Za-z_$][\w$]*\.([A-Za-z_$][\w$]*)/g;
+const _STYLE_ENTRY_RE = /(?<![\w$.])([A-Za-z_$][\w$]*)\s*:\s*\{/g;
+const _BORDER_WIDTH_KEY_RE = /\bborderWidth\s*:/g;
+const _ROW_KEY_RE = /\bflexDirection\s*:\s*(["'`])row(?:-reverse)?\1/;
+const _UNNAMED_PRESS_RE = /\bonTrailingPress\s*=/;
+const _PRESS_NAME_RE = /\btrailingAccessibilityLabel\s*=|\{\s*\.\.\./;
+
+// One pass over the source: the first `key: {` of each name, by offset.
+function _styleEntryOffsets(structure) {
+  const offsets = new Map();
+  _STYLE_ENTRY_RE.lastIndex = 0;
+  let entry;
+  while ((entry = _STYLE_ENTRY_RE.exec(structure))) {
+    if (!offsets.has(entry[1])) offsets.set(entry[1], entry.index + entry[0].length);
+  }
+  return offsets;
+}
+
+// The object literals a style expression spans, plus the entries it names.
+function _styleObjectSpans(scan, [from, to]) {
+  const { structure } = scan;
+  const spans = [];
+  for (let i = from + 1; i < to - 1; i++) {
+    if (structure[i] !== "{") continue;
+    const span = _enclosingObject(structure, i + 1);
+    if (!span) continue;
+    spans.push(span);
+    i = span[1] - 1;
+  }
+  if (!scan.entries) scan.entries = _styleEntryOffsets(structure);
+  const keys = new Set();
+  _STYLE_REF_RE.lastIndex = 0;
+  const refs = structure.slice(from, to);
+  let ref;
+  while ((ref = _STYLE_REF_RE.exec(refs))) keys.add(ref[1]);
+  for (const key of keys) {
+    const at = scan.entries.get(key);
+    const span = at === undefined ? null : _enclosingObject(structure, at);
+    if (span) spans.push(span);
+  }
+  return spans;
+}
+
+function _isBorderedRow(scan, tag) {
+  const { code, structure } = scan;
+  const attrs = structure.slice(tag.attrs[0], tag.attrs[1]);
+  const style = _STYLE_ATTR_RE.exec(attrs);
+  if (!style) return false;
+  const open = tag.attrs[0] + style.index + style[0].length - 1;
+  const inner = _bracedSpan(structure, open);
+  if (inner === null) return false;
+  let row = false;
+  let bordered = false;
+  // `inner` excludes its two braces.
+  for (const span of _styleObjectSpans(scan, [open, open + inner.length + 2])) {
+    const keys = _ownKeysMask(structure, span);
+    if (_ROW_KEY_RE.test(_ownKeysMask(code, span))) row = true;
+    _BORDER_WIDTH_KEY_RE.lastIndex = 0;
+    let key;
+    while ((key = _BORDER_WIDTH_KEY_RE.exec(keys))) {
+      const valueAt = span[0] + key.index + key[0].length;
+      if (!_ZERO_VALUE_RE.test(code.slice(valueAt, valueAt + 40))) bordered = true;
+    }
+  }
+  return row && bordered;
+}
+
+function _selfClosing(structure, end) {
+  let i = end - 1;
+  while (i >= 0 && /\s/.test(structure[i])) i--;
+  return structure[i] === "/";
+}
+
+function _fieldInBorderedRowRules(source) {
+  const findings = [];
+  const scan = {
+    code: _stripNonCode(source, { keepStrings: true }),
+    structure: _stripNonCode(source),
+    entries: null,
+  };
+  const { code, structure } = scan;
+  const sourceLines = source.split(/\r?\n/);
+  // Tokens arrive in source order, so one running count serves every finding.
+  let line = 1;
+  let counted = 0;
+  const lineOf = (at) => {
+    for (; counted < at; counted++) if (code[counted] === "\n") line++;
+    return line;
+  };
+  const report = (rule, at, label) => {
+    const n = lineOf(at);
+    findings.push({
+      rule,
+      severity: "warning",
+      label,
+      line: n,
+      snippet: (sourceLines[n - 1] || "").trim().slice(0, 200),
+    });
+  };
+  const open = [];
+  _JSX_TOKEN_RE.lastIndex = 0;
+  let token;
+  while ((token = _JSX_TOKEN_RE.exec(structure))) {
+    const [, closing, name] = token;
+    if (!name) {
+      // A fragment, `<>` or `</>`; any other `<` is a comparison.
+      if (structure[token.index + 1 + closing.length] !== ">") continue;
+      if (closing) open.pop();
+      else open.push(null);
+      continue;
+    }
+    if (closing) {
+      const at = open.map((tag) => tag && tag.name).lastIndexOf(name);
+      if (at >= 0) open.length = at;
+      continue;
+    }
+    const end = _tagEnd(structure, token.index);
+    if (end === -1) break;
+    const tag = { name, attrs: [token.index + token[0].length, end], borderedRow: undefined };
+    if (_FIELD_TAG_NAMES.includes(name)) {
+      const parent = open[open.length - 1];
+      if (parent && parent.borderedRow === undefined) parent.borderedRow = _isBorderedRow(scan, parent);
+      if (parent && parent.borderedRow) {
+        report(
+          "field-in-bordered-row",
+          token.index,
+          `<${name}> draws its own border, so the bordered row around it ` +
+            `shows a box inside a box. Put the icon in the field with ` +
+            `leadingIcon / trailingIcon (onTrailingPress makes it a button) ` +
+            `and drop the row's border.`,
+        );
+      }
+      const attrs = structure.slice(tag.attrs[0], tag.attrs[1]);
+      if (_UNNAMED_PRESS_RE.test(attrs) && !_PRESS_NAME_RE.test(attrs)) {
+        report(
+          "field-trailing-press-unnamed",
+          token.index,
+          `onTrailingPress makes the trailing icon a button with no name, so ` +
+            `a screen reader says only "button". Give it a translated ` +
+            `trailingAccessibilityLabel.`,
+        );
+      }
+    }
+    if (!_selfClosing(structure, end)) open.push(tag);
+    _JSX_TOKEN_RE.lastIndex = end + 1;
+  }
+  return findings;
+}
+
 // sc-4913 — a measured frame INCLUDES the element's own padding.
 //
 // `onLayout` reports the frame width, and padding sits inside that frame. A
@@ -2256,6 +2410,8 @@ export function lintSource(source, options) {
   findings.push(..._flexBasisPercentRules(source));
   // sc-11277 — soft warning: a full-width box with a side margin is clipped.
   findings.push(..._fullWidthMarginRules(source));
+  // sc-12232 — soft warning: a field inside a bordered row draws two borders.
+  findings.push(..._fieldInBorderedRowRules(source));
   // sc-4913 — soft warning: a measured width that includes the widget's own
   // padding wraps the last grid column into an empty one.
   findings.push(..._measuredPaddingRules(source));

package/dist/search-field-tokens.js

@@ -55,19 +55,17 @@ export function resolveSearchFieldTokens(theme, own) {
 }
 
 /**
- * Where the glyph and the clear control go. At the end, the clear control
+ * What fills `<TextField>`'s two icon slots. At the end, the clear control
  * takes the glyph's slot while there is text, so the two never overlap.
  *
  * @param {string} iconPosition — a resolved SEARCH_ICON_POSITIONS value.
  * @param {boolean} clearable — the field has text and is enabled.
- * @returns {{ glyph: "start"|"end"|null, padStart: boolean, padEnd: boolean }}
+ * @returns {{ leading: "glyph"|null, trailing: "glyph"|"clear"|null }}
  */
 export function searchFieldLayout(iconPosition, clearable) {
-  const glyphAtEnd = iconPosition === "end" && !clearable;
   return {
-    glyph: iconPosition === "start" ? "start" : glyphAtEnd ? "end" : null,
-    padStart: iconPosition === "start",
-    padEnd: clearable || iconPosition === "end",
+    leading: iconPosition === "start" ? "glyph" : null,
+    trailing: clearable ? "clear" : iconPosition === "end" ? "glyph" : null,
   };
 }
 

package/dist/search-field-view.js

@@ -1,41 +1,16 @@
 // The ONE implementation behind the `<SearchField>` SDK primitive. It is
-// `<TextField>` with a search glyph and a clear control, so it wears the same
-// field and takes the same props, plus the theme's `search` look; the platform
-// bindings (`search-field.js` / `search-field.native.js`) differ only in where
-// the primitives come from.
+// `<TextField>` with a search glyph and a clear control in its icon slots, so
+// it wears the same field and takes the same props, plus the theme's `search`
+// look; the platform bindings (`search-field.js` / `search-field.native.js`)
+// differ only in where the primitives come from.
 
 import React from "react";
 import { useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
-import { Icon } from "./icon.js";
-import { resolveFormControlTokens } from "./form-control-tokens.js";
 import { resolveSearchFieldTokens, searchFieldLayout } from "./search-field-tokens.js";
-import {
-  errorMessage,
-  hasNote,
-  isShown,
-  shareRef,
-  spokenLabel,
-} from "./form-control-logic.js";
-import { makeFieldFrame } from "./form-control-view.js";
+import { shareRef, spokenLabel } from "./form-control-logic.js";
 
 const h = React.createElement;
-const GLYPH_SIZE = 18;
-// The glyph and the clear control each own a strip this wide inside the field.
-const ADORNMENT_WIDTH = 40;
-// A real target: the web host ignores hitSlop, so size carries it.
-const CLEAR_MIN_SIZE = 36;
-
-function adornmentSlot(side) {
-  return {
-    position: "absolute",
-    top: 0,
-    bottom: 0,
-    alignItems: "center",
-    justifyContent: "center",
-    ...(side === "start" ? { left: 0 } : { right: 0 }),
-  };
-}
 
 /**
  * Bind the shared search field to one platform's primitives.
@@ -43,8 +18,7 @@ function adornmentSlot(side) {
  * @param {{View: any, Text: any, Pressable: any, TextField: any}} rn
  */
 export function makeSearchField(rn) {
-  const { View, Pressable, TextField } = rn;
-  const FieldFrame = makeFieldFrame(rn);
+  const { TextField } = rn;
 
   const SearchField = React.forwardRef(function SearchField(props, ref) {
     const {
@@ -54,113 +28,59 @@ export function makeSearchField(rn) {
       placeholder = "Search",
       clearAccessibilityLabel = "Clear search",
       label,
-      helper,
-      error,
       disabled = false,
       accessibilityLabel,
       iconPosition,
-      style,
-      containerStyle,
       testID,
       ...rest
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
-    const t = resolveFormControlTokens(theme);
     const search = resolveSearchFieldTokens(theme, { iconPosition });
     const inputRef = React.useRef(null);
     const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
-    const noteId = React.useId();
-    const focusInput = () => {
-      const input = inputRef.current;
-      if (input && typeof input.focus === "function") input.focus();
-    };
     const hasText = typeof value === "string" && value.length > 0;
-    const clearable = hasText && !disabled;
-    const layout = searchFieldLayout(search.iconPosition, clearable);
+    const layout = searchFieldLayout(search.iconPosition, hasText && !disabled);
+    const slotTestID = (suffix) => (testID ? `${testID}-${suffix}` : undefined);
     const clear = () => {
       if (typeof onChangeText === "function") onChangeText("");
       if (typeof onClear === "function") onClear();
-      focusInput();
+      const input = inputRef.current;
+      if (input && typeof input.focus === "function") input.focus();
     };
 
-    return h(
-      FieldFrame,
-      {
-        t,
-        label,
-        helper,
-        error: errorMessage(error),
-        disabled,
-        noteId,
-        onLabelPress: focusInput,
-        style: containerStyle,
-      },
-      h(
-        View,
-        { style: { justifyContent: "center" } },
-        h(TextField, {
-          ref: setRef,
-          value,
-          onChangeText,
-          placeholder,
-          // The frame dims the whole control, glyph included.
-          ...(disabled ? { editable: false, "aria-disabled": true } : null),
-          error: isShown(error),
-          ...(hasNote({ helper, error }) ? { "aria-describedby": noteId } : null),
-          // `role` names it on the web; `accessibilityRole` on a device.
-          role: "searchbox",
-          accessibilityRole: "search",
-          accessibilityLabel: spokenLabel(accessibilityLabel, label) || placeholder,
-          enterKeyHint: "search",
-          autoCapitalize: "none",
-          autoCorrect: false,
-          testID,
-          // The field's own props beat the theme's search look.
-          ...search.field,
-          ...rest,
-          style: [
-            layout.padStart ? { paddingLeft: ADORNMENT_WIDTH } : null,
-            layout.padEnd ? { paddingRight: ADORNMENT_WIDTH } : null,
-            style,
-          ],
-        }),
-        layout.glyph
-          ? h(
-              View,
-              {
-                testID: testID ? `${testID}-icon` : undefined,
-                style: {
-                  ...adornmentSlot(layout.glyph),
-                  width: ADORNMENT_WIDTH,
-                  pointerEvents: "none",
-                },
-              },
-              h(Icon, { name: "search", size: GLYPH_SIZE, color: t.placeholderColor }),
-            )
-          : null,
-        clearable
-          ? h(
-              Pressable,
-              {
-                onPress: clear,
-                accessibilityRole: "button",
-                accessibilityLabel: clearAccessibilityLabel,
-                testID: testID ? `${testID}-clear` : undefined,
-                style: ({ pressed }) => [
-                  {
-                    ...adornmentSlot("end"),
-                    right: 2,
-                    minWidth: CLEAR_MIN_SIZE,
-                    minHeight: CLEAR_MIN_SIZE,
-                  },
-                  pressed ? { opacity: 0.6 } : null,
-                ],
-              },
-              h(Icon, { name: "x", size: GLYPH_SIZE, color: t.placeholderColor }),
-            )
-          : null,
-      ),
-    );
+    return h(TextField, {
+      ref: setRef,
+      value,
+      onChangeText,
+      placeholder,
+      label,
+      disabled,
+      // `role` names it on the web; `accessibilityRole` on a device.
+      role: "searchbox",
+      accessibilityRole: "search",
+      accessibilityLabel: spokenLabel(accessibilityLabel, label) || placeholder,
+      enterKeyHint: "search",
+      autoCapitalize: "none",
+      autoCorrect: false,
+      testID,
+      // The field's own props beat the theme's search look.
+      ...search.field,
+      ...rest,
+      // Both slots always passed, so the clear control never rebuilds the input.
+      leadingIcon: layout.leading === "glyph" ? "search" : null,
+      leadingTestID: slotTestID("icon"),
+      ...(layout.trailing === "clear"
+        ? {
+            trailingIcon: "x",
+            onTrailingPress: clear,
+            trailingAccessibilityLabel: clearAccessibilityLabel,
+            trailingTestID: slotTestID("clear"),
+          }
+        : {
+            trailingIcon: layout.trailing === "glyph" ? "search" : null,
+            trailingTestID: slotTestID("icon"),
+          }),
+    });
   });
 
   SearchField.displayName = "SearchField";

package/dist/text-field-adornment.js

@@ -0,0 +1,93 @@
+// Where `<TextField>`'s icons sit inside its own border, and which of the
+// caller's style keys move to the box that holds the field and its icons.
+// Platform-free, so both hosts lay an iconned field out from one answer.
+
+import { flattenStyle } from "./flatten-style.js";
+
+// Each icon owns a strip this wide inside the field's border.
+export const ADORNMENT_WIDTH = 40;
+export const ADORNMENT_GLYPH_SIZE = 18;
+// A real target: the web host ignores hitSlop, so size carries it.
+export const ADORNMENT_PRESS_MIN_SIZE = 36;
+
+export const ADORNMENT_PROPS = Object.freeze(["leadingIcon", "trailingIcon"]);
+
+// Where the field sits among its siblings, not how it looks. The box takes
+// the input's place in the tree, so these must move with it.
+export const FIELD_PLACEMENT_STYLE_KEYS = Object.freeze([
+  "margin", "marginTop", "marginRight", "marginBottom", "marginLeft",
+  "marginHorizontal", "marginVertical", "marginStart", "marginEnd",
+  "marginBlock", "marginBlockStart", "marginBlockEnd",
+  "marginInline", "marginInlineStart", "marginInlineEnd",
+  "flex", "flexGrow", "flexShrink", "flexBasis", "alignSelf",
+  "width", "minWidth", "maxWidth",
+  "position", "top", "right", "bottom", "left", "start", "end", "zIndex",
+  "display",
+]);
+
+// A percentage resolves against the parent, which is now the box.
+const HEIGHT_KEYS = Object.freeze(["height", "minHeight", "maxHeight"]);
+
+function isPercent(value) {
+  return typeof value === "string" && value.trim().endsWith("%");
+}
+
+/**
+ * Whether the field draws the box its icons sit in. Keyed on the props being
+ * passed at all, not on their value: an icon that comes and goes with the
+ * text must not rebuild the input under the caret.
+ *
+ * @param {object} props — the field's props.
+ */
+export function hasAdornmentSlots(props) {
+  return ADORNMENT_PROPS.some((name) => Object.prototype.hasOwnProperty.call(props, name));
+}
+
+/** An icon prop that draws a glyph: a non-empty lucide name. */
+export function isIconName(value) {
+  return typeof value === "string" && value.trim() !== "";
+}
+
+/**
+ * Split a caller's `style` between the box and the input inside it. `fill` is
+ * whether a height moved, which the input must then fill.
+ *
+ * @param {object|Array|null|undefined|false} style
+ * @returns {{ box: object, field: object, fill: boolean }}
+ */
+export function splitFieldStyle(style) {
+  const box = {};
+  const field = {};
+  let fill = false;
+  for (const [key, value] of Object.entries(flattenStyle(style))) {
+    const percentHeight = HEIGHT_KEYS.includes(key) && isPercent(value);
+    if (percentHeight) fill = true;
+    (FIELD_PLACEMENT_STYLE_KEYS.includes(key) || percentHeight ? box : field)[key] = value;
+  }
+  return { box, field, fill };
+}
+
+/**
+ * The strip one icon is drawn in. A pressable icon is a 36px target inset from
+ * the edge; a plain glyph fills its strip and lets presses through to the
+ * field. A paragraph field keeps its icons beside its first line.
+ *
+ * @param {"start"|"end"} side
+ * @param {{ pressable?: boolean, multiline?: boolean, rowHeight: number }} opts
+ */
+export function adornmentSlotStyle(side, { pressable = false, multiline = false, rowHeight }) {
+  return {
+    position: "absolute",
+    top: 0,
+    ...(multiline ? { height: rowHeight } : { bottom: 0 }),
+    alignItems: "center",
+    justifyContent: "center",
+    ...(pressable
+      ? {
+          [side === "start" ? "left" : "right"]: 2,
+          minWidth: ADORNMENT_PRESS_MIN_SIZE,
+          minHeight: ADORNMENT_PRESS_MIN_SIZE,
+        }
+      : { [side === "start" ? "left" : "right"]: 0, width: ADORNMENT_WIDTH, pointerEvents: "none" }),
+  };
+}

package/dist/text-field-view.js

@@ -5,6 +5,7 @@
 import React from "react";
 import { useHostSharedText, useHostTheme } from "./hooks.js";
 import { DEFAULT_THEME_TOKENS } from "./_theme-tokens.js";
+import { Icon } from "./icon.js";
 import { TEXT_FIELD_TOKEN_NAMES } from "./text-field-tokens.js";
 import {
   FIELD_OUTLINE_OFF,
@@ -20,20 +21,60 @@ import {
   shareRef,
   spokenLabel,
 } from "./form-control-logic.js";
+import {
+  ADORNMENT_GLYPH_SIZE,
+  ADORNMENT_WIDTH,
+  adornmentSlotStyle,
+  hasAdornmentSlots,
+  isIconName,
+  splitFieldStyle,
+} from "./text-field-adornment.js";
 import { makeFieldFrame } from "./form-control-view.js";
 
+const h = React.createElement;
+
 // A paragraph field grows to a ceiling, then scrolls inside itself.
 const MULTILINE = { minHeight: 88, maxHeight: 220, textAlignVertical: "top" };
 
+// Hidden from a screen reader: the field's label already names it.
+const DECORATIVE = {
+  "aria-hidden": true,
+  accessibilityElementsHidden: true,
+  importantForAccessibility: "no-hide-descendants",
+};
+
 /**
  * Bind the shared field to one platform's primitives.
  *
  * @param {{TextInput: any, View: any, Text: any, Pressable: any}} rn
  */
 export function makeTextField(rn) {
-  const { TextInput } = rn;
+  const { TextInput, View, Pressable } = rn;
   const FieldFrame = makeFieldFrame(rn);
 
+  function Adornment({ side, icon, onPress, accessibilityLabel, disabled, testID, t, multiline }) {
+    const glyph = h(Icon, { name: icon, size: ADORNMENT_GLYPH_SIZE, color: t.placeholderColor });
+    const slot = { multiline, rowHeight: t.height };
+    if (typeof onPress !== "function") {
+      return h(View, { testID, ...DECORATIVE, style: adornmentSlotStyle(side, slot) }, glyph);
+    }
+    return h(
+      Pressable,
+      {
+        onPress,
+        disabled,
+        accessibilityRole: "button",
+        accessibilityLabel,
+        testID,
+        style: ({ pressed }) => [
+          adornmentSlotStyle(side, { ...slot, pressable: true }),
+          pressed ? { opacity: 0.6 } : null,
+        ],
+      },
+      glyph,
+    );
+  }
+
   const TextField = React.forwardRef(function TextField(props, ref) {
     const {
       style,
@@ -48,6 +89,13 @@ export function makeTextField(rn) {
       required = false,
       containerStyle,
       accessibilityLabel,
+      leadingIcon,
+      trailingIcon,
+      onTrailingPress,
+      trailingAccessibilityLabel,
+      leadingTestID,
+      trailingTestID,
+      testID,
       ...others
     } = props;
     const theme = useHostTheme() || DEFAULT_THEME_TOKENS;
@@ -62,13 +110,18 @@ export function makeTextField(rn) {
     const t = resolveFormControlTokens(theme, overrides);
     const invalid = isShown(error);
     const framed = needsFrame({ label, helper, error });
+    const boxed = hasAdornmentSlots(props);
+    const leading = isIconName(leadingIcon);
+    const trailing = isIconName(trailingIcon);
+    const placed = boxed ? splitFieldStyle(style) : { box: null, field: style, fill: false };
     const inputRef = React.useRef(null);
     // Stable, so the host does not detach and re-attach the node every render.
     const setRef = React.useMemo(() => shareRef(ref, inputRef), [ref]);
     const noteId = React.useId();
-    const input = React.createElement(TextInput, {
+    const input = h(TextInput, {
       ref: setRef,
       multiline,
+      testID,
       placeholderTextColor: placeholderTextColor || t.placeholderColor,
       accessibilityLabel: spokenLabel(accessibilityLabel, label, required ? requiredWord : null),
       ...(disabled ? { editable: false, "aria-disabled": true } : null),
@@ -91,9 +144,13 @@ export function makeTextField(rn) {
         },
         FIELD_OUTLINE_OFF,
         fieldStateStyle(t, { focused, invalid }),
-        // The frame dims a framed field as a whole.
-        disabled && !framed ? { opacity: t.disabledOpacity } : null,
-        style,
+        // The frame, or the icons' box, dims a field as a whole.
+        disabled && !framed && !boxed ? { opacity: t.disabledOpacity } : null,
+        // Otherwise it keeps its height, centred in a stretched box.
+        placed.fill ? { flexGrow: 1 } : null,
+        leading ? { paddingLeft: ADORNMENT_WIDTH } : null,
+        trailing ? { paddingRight: ADORNMENT_WIDTH } : null,
+        placed.field,
         // After the caller's style: a paragraph field keeps its 88px floor.
         multiline ? MULTILINE : null,
       ],
@@ -107,8 +164,45 @@ export function makeTextField(rn) {
       },
       ...rest,
     });
-    if (!framed) return input;
-    return React.createElement(
+    const slotTestID = (own, suffix) => own || (testID ? `${testID}-${suffix}` : undefined);
+    const field = boxed
+      ? h(
+          View,
+          {
+            style: [
+              { justifyContent: "center" },
+              disabled && !framed ? { opacity: t.disabledOpacity } : null,
+              placed.box,
+              // Unlabelled, the box is the field's outermost one.
+              framed ? null : containerStyle,
+            ],
+          },
+          input,
+          leading
+            ? h(Adornment, {
+                side: "start",
+                icon: leadingIcon,
+                testID: slotTestID(leadingTestID, "leading-icon"),
+                t,
+                multiline,
+              })
+            : null,
+          trailing
+            ? h(Adornment, {
+                side: "end",
+                icon: trailingIcon,
+                onPress: onTrailingPress,
+                accessibilityLabel: trailingAccessibilityLabel,
+                disabled,
+                testID: slotTestID(trailingTestID, "trailing-icon"),
+                t,
+                multiline,
+              })
+            : null,
+        )
+      : input;
+    if (!framed) return field;
+    return h(
       FieldFrame,
       {
         t,
@@ -124,7 +218,7 @@ export function makeTextField(rn) {
         },
         style: containerStyle,
       },
-      input,
+      field,
     );
   });
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@colixsystems/widget-sdk",
-  "version": "0.248.0",
+  "version": "0.249.0",
   "description": "Common widget interface for AppStudio. Implements WidgetManifest, WidgetContext, property schema, and helper hooks.",
   "homepage": "https://github.com/Colix-AB/AppStudio",
   "type": "module",

package/src/contract.js

@@ -3526,7 +3526,7 @@ const PRIMITIVES = [
   {
     name: "TextField",
     description:
-      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
+      'Themed text-entry field. `<TextField value={name} onChangeText={setName} placeholder="Your name" accessibilityLabel="Name" />` — every `TextInput` prop works, and its background, text colour, border, corner radius and height come from the app\'s input look (Design > Components > Inputs), so a widget\'s fields match the built-in forms. `multiline` grows the field to a ceiling and then scrolls inside it. Override one field with `background`, `textColor`, `borderColor`, `radius` or `height`; `style` is merged last. `label` draws a label above the field and names it for a screen reader, `helper` a hint below, `error` a message in the helper\'s place with a danger border (`true` marks it without a message), `disabled` makes it read-only and dimmed; `containerStyle` styles the box around a labelled field, or around the field and its icons. An icon goes INSIDE the field, never beside it: `leadingIcon` / `trailingIcon` take a lucide name (`<TextField trailingIcon="map-pin" … />`), and `onTrailingPress` with a `trailingAccessibilityLabel` makes the trailing one a button (a clear control, "use my location"). Never wrap a field in a bordered row of your own to put an icon or a button beside it: the field draws its own border, so that shows a box inside a box. Use it by default instead of styling a bare `TextInput`; a field it cannot draw (a one-time code split into digit boxes, an amount with a stepper inside its border) is your own build that keeps a label, the input colours of the theme and an error message.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -3547,7 +3547,7 @@ const PRIMITIVES = [
   {
     name: "SearchField",
     description:
-      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
+      'Themed search box. `<SearchField value={query} onChangeText={setQuery} placeholder="Search orders" />` — the default way to draw a field that filters or searches. It IS a `TextField` (same props, same `label` / `helper` / `error` / `disabled`, the input look restyled by Design > Components > Search fields) with a search glyph, the search key on the on-screen keyboard and a clear control that appears once there is text; clearing calls `onChangeText("")`, then `onClear` if you passed one, and keeps focus in the field. `placeholder` defaults to "Search" and `clearAccessibilityLabel` to "Clear search" — pass translated ones. `style` styles the input and `containerStyle` the box around it (use it for `flex: 1` in a toolbar). Where the glyph sits (start, end or hidden), the corner radius, background, border colour and height come from the app; `iconPosition` ("start" | "end" | "none") overrides the glyph for one field, and at the end the clear control takes the glyph\'s place while there is text. Debounce the query yourself before you fetch. Never add a magnifier of your own to it; its glyph and clear control fill the icon slots of `TextField`, so it takes no `leadingIcon` / `trailingIcon`. Use it rather than a `TextInput` + an icon of your own; when the request needs a search box it cannot draw (a scope picker inside the box, a voice button beside the clear control), build your own in the input look of the theme.',
     rnComponent: null,
     docsUrl: null,
   },
@@ -6322,7 +6322,11 @@ const CONTRACT = deepFreeze({
   //    `<DataTable>`, `<FilterBar>`, `<Form>` / `<FieldRow>` / `<FormSection>`
   //    / `<FormActions>` / `<FormField>`, `<SortableList>`, `<Board>`;
   //    `required` on TextField, Select, RadioGroup, PeoplePicker, FileUpload.
-  version: "1.202.0",
+  // 1.203.0: additive (sc-12232) — `<TextField>` takes `leadingIcon`,
+  //    `trailingIcon`, `onTrailingPress`, `trailingAccessibilityLabel` and the
+  //    slots' testIDs; `<SearchField>` draws through them. New warnings
+  //    `field-in-bordered-row`, `field-trailing-press-unnamed`.
+  version: "1.203.0",
   sharedTranslationKeys: SHARED_TRANSLATION_KEYS,
   hooks: HOOKS,
   primitives: PRIMITIVES,