npm - @lutra-ui-system/react - Versions diffs - 0.2.0 → 0.3.0 - Mend

@lutra-ui-system/react 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/README.md +32 -6
package/dist/components/field/field.d.ts +16 -9
package/dist/components/field/field.d.ts.map +1 -1
package/dist/components/field/field.js +6 -4
package/dist/components/field/field.js.map +1 -1
package/dist/components/input/input.d.ts +19 -6
package/dist/components/input/input.d.ts.map +1 -1
package/dist/components/input/input.js +42 -9
package/dist/components/input/input.js.map +1 -1
package/dist/components/input/overflow.d.ts +68 -0
package/dist/components/input/overflow.d.ts.map +1 -0
package/dist/components/input/overflow.js +111 -0
package/dist/components/input/overflow.js.map +1 -0
package/dist/components/select-field/select-field.d.ts +9 -6
package/dist/components/select-field/select-field.d.ts.map +1 -1
package/dist/components/select-field/select-field.js +6 -4
package/dist/components/select-field/select-field.js.map +1 -1
package/dist/internal/field-support.d.ts +38 -6
package/dist/internal/field-support.d.ts.map +1 -1
package/dist/internal/field-support.js +36 -8
package/dist/internal/field-support.js.map +1 -1
package/dist/styles.css +255 -55
package/dist/tokens.json +15 -1
package/package.json +3 -2

package/README.md CHANGED Viewed

@@ -82,6 +82,29 @@ The library does **not** read `prefers-color-scheme`. Deciding when an applicati
 the application, and plenty have no dark design at all — so set `data-theme` from your own theme
 logic, where a user's explicit choice can still win over the system preference.
+### Density
+A second, independent axis. Spacious is the default; Condensed is one attribute, on any element:
+```html
+<html data-theme="dark" data-density="condensed"></html>
+```
+Density tightens the vertical rhythm and supporting-text indent of Field and Select Field (8px →
+4px) and lowers the control text of Input and Select (16px → 14px). It does **not** change control
+heights, inline padding or target geometry — those belong to `size` and are identical in both modes.
+It is global and inherited, so a dense region inside a comfortable page is a wrapper:
+```html
+<section data-density="condensed">…</section>
+```
+There is deliberately **no `density` prop** on Field, Select Field, Input or Select. Density is one
+decision that applies to a whole subtree, which a prop cannot express. Note that Condensed control
+text is 14px, and Mobile Safari zooms the page when a focused field's text is below 16px — keep
+Spacious for anything filled in on a phone.
 ### Overriding a token
 Override on any element below the root and it wins outright, because a declaration on an element
@@ -94,7 +117,7 @@ beats one inherited into it:
 ```
 Overriding at `:root` also works, but your stylesheet must load **after** `@lutra-ui-system/react/styles.css`
-— `:root` and `[data-theme]` have equal specificity, so source order decides.
+— `:root`, `[data-theme]` and `[data-density]` all have equal specificity, so source order decides.
 ### Tokens as data
@@ -102,8 +125,9 @@ Overriding at `:root` also works, but your stylesheet must load **after** `@lutr
 import tokens from '@lutra-ui-system/react/tokens.json' with { type: 'json' };
 ```
-Each entry carries its Figma name, whether it is themed, and its value or its light/dark pair. Useful
-for tooling; components should read the CSS custom properties.
+Each entry carries its Figma name, whether it is themed, and its value or its light/dark pair. A
+density token carries `spacious` and `condensed` instead of a single value, and is marked
+`density: true`. Useful for tooling; components should read the CSS custom properties.
 ## Public API
@@ -201,9 +225,11 @@ requests. The build fails if an import survives.
 Rules for anything added to the stylesheet:
 - prefix every selector with `lutra-`
-- the only global selectors permitted are the token layer's `:root` and `[data-theme]` blocks, and
-  they declare custom properties and nothing else — a stylesheet must not restyle a page it was
-  merely imported into, and a custom property declaration paints nothing
+- the only global selectors permitted are the token layer's `:root`, `[data-theme]` and
+  `[data-density]` blocks, and they declare custom properties and nothing else — a stylesheet must
+  not restyle a page it was merely imported into, and a custom property declaration paints nothing
+- a component rule never matches on `data-theme` or `data-density`; it reads the tokens those blocks
+  declare
 - take every value from a design token; no raw colours, sizes, or type
 - size in `rem` with unitless line heights, so the library respects user font size and zoom; border
   and outline widths stay in `px`

package/dist/components/field/field.d.ts CHANGED Viewed

@@ -16,8 +16,9 @@ export interface FieldProps extends ForwardedInputProps {
      */
     label: ReactNode;
     /**
-     * Supporting text shown above the control and connected with `aria-describedby`. Use it for
-     * format guidance the person needs before they start typing.
+     * Supporting text shown below the control and connected with `aria-describedby`. Use it for
+     * format guidance — a screen reader reads it as part of the control's description, so it is
+     * available before the field is filled in even though it is drawn underneath.
      */
     hint?: ReactNode;
     /**
@@ -27,18 +28,23 @@ export interface FieldProps extends ForwardedInputProps {
      */
     error?: ReactNode;
     /**
-     * The word shown after the label text and included in the accessible name.
+     * The indicator shown immediately after the label text.
      *
-     * Defaults to `'required'` when the native `required` attribute is set, and `'none'` otherwise,
-     * so the visible word and the announced state agree by default. Pass `'optional'` to mark
-     * optional fields in a form where most are required.
+     * Defaults to `'required'` when the native `required` attribute is set, and `'none'` otherwise.
+     * Pass `'optional'` to mark optional fields in a form where most are required.
+     *
+     * Drawn as `(required *)` or `(optional)`. When the control is natively `required`, the indicator
+     * is hidden from assistive technology because the attribute already carries that state; the
+     * word stays in the accessible name whenever nothing else conveys it. See
+     * `internal/field-support.tsx`.
      */
     indicator?: FieldIndicator;
     /** Extra class on the field wrapper, not on the control. */
     className?: string;
 }
 /**
- * A labelled text field: label, optional hint, an `Input`, and an optional error message.
+ * A labelled text field: label, an `Input`, optional supporting text, and an optional error
+ * message.
  *
  * This is the ordinary way to render an Input. The primitive deliberately does not manufacture a
  * label; Field is what supplies one, associates it with `for`/`id`, and wires the hint and error to
@@ -48,8 +54,9 @@ export interface FieldProps extends ForwardedInputProps {
  * `placeholder`, `required`, `readOnly`, `autoComplete`, `size`, `fullWidth`, the event handlers and
  * `data-*` all behave exactly as they do there. A `ref` reaches the native `<input>`.
  *
- * Order is label → hint → control → error. The hint is above the control so it is read before the
- * control is operated; the error is below it, matching the Figma annotation and Field Group.
+ * Order is label → control → hint → error. Supporting text sits below the control, which is what
+ * the Figma component draws and what its accessibility annotation describes; `aria-describedby`
+ * lists the hint then the error, so the description order matches the reading order.
  */
 export declare const Field: import("react").ForwardRefExoticComponent<FieldProps & import("react").RefAttributes<HTMLInputElement>>;
 //# sourceMappingURL=field.d.ts.map

package/dist/components/field/field.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/components/field/field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAEvD,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACrD;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB~~;;;OAGG~~;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB~~;;;;;;OAMG~~;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED~~;;;;;;;;;;;;;GAaG~~;AACH,eAAO,MAAM,KAAK,~~yGA4ChB~~,CAAC"}
1	+ {"version":3,"file":"field.d.ts","sourceRoot":"","sources":["../../../src/components/field/field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAEpD,YAAY,EAAE,cAAc,EAAE,CAAC;AAE/B;;;;;GAKG;AACH,KAAK,mBAAmB,GAAG,IAAI,CAAC,UAAU,EAAE,SAAS,CAAC,CAAC;AAEvD,MAAM,WAAW,UAAW,SAAQ,mBAAmB;IACrD;;;OAGG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;;;;OAUG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,KAAK,yGA6ChB,CAAC"}

package/dist/components/field/field.js CHANGED Viewed

@@ -3,7 +3,8 @@ import { forwardRef } from 'react';
 import { FieldShell, useFieldIds } from '../../internal/field-support.js';
 import { Input } from '../input/index.js';
 /**
- * A labelled text field: label, optional hint, an `Input`, and an optional error message.
+ * A labelled text field: label, an `Input`, optional supporting text, and an optional error
+ * message.
  *
  * This is the ordinary way to render an Input. The primitive deliberately does not manufacture a
  * label; Field is what supplies one, associates it with `for`/`id`, and wires the hint and error to
@@ -13,14 +14,15 @@ import { Input } from '../input/index.js';
  * `placeholder`, `required`, `readOnly`, `autoComplete`, `size`, `fullWidth`, the event handlers and
  * `data-*` all behave exactly as they do there. A `ref` reaches the native `<input>`.
  *
- * Order is label → hint → control → error. The hint is above the control so it is read before the
- * control is operated; the error is below it, matching the Figma annotation and Field Group.
+ * Order is label → control → hint → error. Supporting text sits below the control, which is what
+ * the Figma component draws and what its accessibility annotation describes; `aria-describedby`
+ * lists the hint then the error, so the description order matches the reading order.
  */
 export const Field = forwardRef(function Field({ label, hint, error, indicator, className, id, required = false, disabled = false, 'aria-describedby': describedBy, ...inputProps }, ref) {
     const hasHint = hint !== undefined && hint !== null && hint !== false;
     const hasError = error !== undefined && error !== null && error !== false;
     const ids = useFieldIds({ id, hasHint, hasError, describedBy });
     const resolvedIndicator = indicator ?? (required ? 'required' : 'none');
-    return (_jsx(FieldShell, { controlId: ids.controlId, label: label, indicator: resolvedIndicator, hint: hint, hintId: ids.hintId, error: error, errorId: ids.errorId, disabled: disabled, className: className, children: _jsx(Input, { ...inputProps, ref: ref, id: ids.controlId, required: required, disabled: disabled, invalid: hasError, "aria-describedby": ids.describedBy }) }));
+    return (_jsx(FieldShell, { controlId: ids.controlId, label: label, indicator: resolvedIndicator, required: required, hint: hint, hintId: ids.hintId, error: error, errorId: ids.errorId, disabled: disabled, className: className, children: _jsx(Input, { ...inputProps, ref: ref, id: ids.controlId, required: required, disabled: disabled, invalid: hasError, "aria-describedby": ids.describedBy }) }));
 });
 //# sourceMappingURL=field.js.map

package/dist/components/field/field.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"field.js","sourceRoot":"","sources":["../../../src/components/field/field.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;~~AA0C1C;;;;;;;;;;;;;GAaG~~;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,UAAU,CAA+B,SAAS,KAAK,CAC1E,EACE,KAAK,EACL,IAAI,EACJ,KAAK,EACL,SAAS,EACT,SAAS,EACT,EAAE,EACF,QAAQ,GAAG,KAAK,EAChB,QAAQ,GAAG,KAAK,EAChB,kBAAkB,EAAE,WAAW,EAC/B,GAAG,UAAU,EACd,EACD,GAAG;IAEH,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,CAAC;IACtE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,CAAC;IAE1E,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAmB,SAAS,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAExF,OAAO,CACL,KAAC,UAAU,IACT,SAAS,EAAE,GAAG,CAAC,SAAS,EACxB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,iBAAiB,EAC5B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,YAEpB,KAAC,KAAK,OACA,UAAU,EACd,GAAG,EAAE,GAAG,EACR,EAAE,EAAE,GAAG,CAAC,SAAS,EACjB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,QAAQ,sBACC,GAAG,CAAC,WAAW,GACjC,GACS,CACd,CAAC;AACJ,CAAC,CAAC,CAAC"}
1	+ {"version":3,"file":"field.js","sourceRoot":"","sources":["../../../src/components/field/field.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AA+C1C;;;;;;;;;;;;;;;GAeG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,UAAU,CAA+B,SAAS,KAAK,CAC1E,EACE,KAAK,EACL,IAAI,EACJ,KAAK,EACL,SAAS,EACT,SAAS,EACT,EAAE,EACF,QAAQ,GAAG,KAAK,EAChB,QAAQ,GAAG,KAAK,EAChB,kBAAkB,EAAE,WAAW,EAC/B,GAAG,UAAU,EACd,EACD,GAAG;IAEH,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,CAAC;IACtE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,CAAC;IAE1E,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAmB,SAAS,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAExF,OAAO,CACL,KAAC,UAAU,IACT,SAAS,EAAE,GAAG,CAAC,SAAS,EACxB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,YAEpB,KAAC,KAAK,OACA,UAAU,EACd,GAAG,EAAE,GAAG,EACR,EAAE,EAAE,GAAG,CAAC,SAAS,EACjB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,QAAQ,sBACC,GAAG,CAAC,WAAW,GACjC,GACS,CACd,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/components/input/input.d.ts CHANGED Viewed

@@ -81,12 +81,25 @@ export interface InputProps extends NativeInputProps {
  * Hover and focus are browser states expressed in CSS, not props. The only states
  * Input models are the ones a consumer owns: `disabled`, `readOnly` and `invalid`.
  *
- * **Every rendered Input must have an accessible name.** This primitive does not
- * manufacture one, because the name normally comes from a visible `<label>` that
- * the surrounding field composition owns. Until that component exists, associate
- * a real `<label htmlFor>` yourself, or pass `aria-label` / `aria-labelledby`. A
- * `placeholder` is not a name — it disappears on the first keystroke. See
- * `input.md`.
+ * One state is neither: **whether part of the value is scrolled out of sight**.
+ * A single-line input scrolls rather than wraps, and gives no sign that it is
+ * doing so, so the control measures itself and marks its top-right corner when
+ * some of the value is not visible. It is derived rather than passed — there is
+ * no `overflow` prop, because whether a value fits depends on the container
+ * width, the density-driven text size and the reader's font size, none of which
+ * a consumer can know. See `overflow.ts` and `input.md`.
+ *
+ * **Use `Field` for an ordinary labelled text input.** It is the recommended
+ * composition and owns the label, the required or optional indicator, the
+ * supporting text, the error message and the ARIA wiring between them. Reach for
+ * this primitive directly only when another composition already owns all of
+ * that — a table's filter cell, a toolbar search box.
+ *
+ * **Every rendered Input must have an accessible name**, and this primitive does
+ * not manufacture one: the name belongs to whatever composition wraps it. Give it
+ * an associated `<label htmlFor>`, or `aria-label` / `aria-labelledby` where
+ * there is genuinely no visible label. A `placeholder` is not a name — it
+ * disappears on the first keystroke. See `input.md`.
  *
  * `forwardRef` rather than a plain `ref` prop: this package supports React 18.3
  * as well as 19, and ref-as-a-prop only works in 19.

package/dist/components/input/input.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../../src/components/input/input.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;~~AAEjD~~,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,OAAO,GACP,UAAU,GACV,QAAQ,GACR,KAAK,GACL,KAAK,GACL,QAAQ,GACR,MAAM,GACN,gBAAgB,GAChB,OAAO,GACP,MAAM,GACN,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,KAAK,gBAAgB,GAAG,IAAI,CAC1B,mBAAmB,CAAC,gBAAgB,CAAC,EACrC,MAAM,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,CAC9C,CAAC;~~AAEF~~,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAClD;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sBAAsB;IACtB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED~~;;;;;;;;;;;;;;;;;;;GAmBG~~;AACH,eAAO,MAAM,KAAK,~~yGAkBhB~~,CAAC"}
1	+ {"version":3,"file":"input.d.ts","sourceRoot":"","sources":["../../../src/components/input/input.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,OAAO,CAAC;AAIjD,sEAAsE;AACtE,MAAM,MAAM,SAAS,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3C;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,SAAS,GACjB,MAAM,GACN,OAAO,GACP,UAAU,GACV,QAAQ,GACR,KAAK,GACL,KAAK,GACL,QAAQ,GACR,MAAM,GACN,gBAAgB,GAChB,OAAO,GACP,MAAM,GACN,MAAM,CAAC;AAEX;;;;;;;;;;;;;;;GAeG;AACH,KAAK,gBAAgB,GAAG,IAAI,CAC1B,mBAAmB,CAAC,gBAAgB,CAAC,EACrC,MAAM,GAAG,MAAM,GAAG,cAAc,GAAG,UAAU,CAC9C,CAAC;AAaF,MAAM,WAAW,UAAW,SAAQ,gBAAgB;IAClD;;;;;;;;OAQG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;;;;;;;;;;OAcG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,sBAAsB;IACtB,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,eAAO,MAAM,KAAK,yGA0DhB,CAAC"}

package/dist/components/input/input.js CHANGED Viewed

@@ -1,5 +1,6 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { forwardRef } from 'react';
+import { forwardRef, useCallback, useRef } from 'react';
+import { useValueOverflow } from './overflow.js';
 /**
  * A single-line text entry control.
  *
@@ -10,17 +11,49 @@ import { forwardRef } from 'react';
  * Hover and focus are browser states expressed in CSS, not props. The only states
  * Input models are the ones a consumer owns: `disabled`, `readOnly` and `invalid`.
  *
- * **Every rendered Input must have an accessible name.** This primitive does not
- * manufacture one, because the name normally comes from a visible `<label>` that
- * the surrounding field composition owns. Until that component exists, associate
- * a real `<label htmlFor>` yourself, or pass `aria-label` / `aria-labelledby`. A
- * `placeholder` is not a name — it disappears on the first keystroke. See
- * `input.md`.
+ * One state is neither: **whether part of the value is scrolled out of sight**.
+ * A single-line input scrolls rather than wraps, and gives no sign that it is
+ * doing so, so the control measures itself and marks its top-right corner when
+ * some of the value is not visible. It is derived rather than passed — there is
+ * no `overflow` prop, because whether a value fits depends on the container
+ * width, the density-driven text size and the reader's font size, none of which
+ * a consumer can know. See `overflow.ts` and `input.md`.
+ *
+ * **Use `Field` for an ordinary labelled text input.** It is the recommended
+ * composition and owns the label, the required or optional indicator, the
+ * supporting text, the error message and the ARIA wiring between them. Reach for
+ * this primitive directly only when another composition already owns all of
+ * that — a table's filter cell, a toolbar search box.
+ *
+ * **Every rendered Input must have an accessible name**, and this primitive does
+ * not manufacture one: the name belongs to whatever composition wraps it. Give it
+ * an associated `<label htmlFor>`, or `aria-label` / `aria-labelledby` where
+ * there is genuinely no visible label. A `placeholder` is not a name — it
+ * disappears on the first keystroke. See `input.md`.
  *
  * `forwardRef` rather than a plain `ref` prop: this package supports React 18.3
  * as well as 19, and ref-as-a-prop only works in 19.
  */
-export const Input = forwardRef(function Input({ size = 'md', invalid = false, fullWidth = false, type = 'text', className, ...nativeProps }, ref) {
-    return (_jsx("input", { ...nativeProps, ref: ref, type: type, className: className === undefined ? 'lutra-input' : `lutra-input ${className}`, "aria-invalid": invalid || undefined, "data-size": size, "data-full-width": fullWidth ? 'true' : undefined }));
+export const Input = forwardRef(function Input({ size = 'md', invalid = false, fullWidth = false, type = 'text', className, onInput, ...nativeProps }, ref) {
+    // The component needs the element to measure it, and the consumer's `ref` still has to reach the
+    // same element. One callback ref feeds both, rather than the consumer losing their ref or the
+    // measurement reaching into the DOM by selector.
+    const inputRef = useRef(null);
+    const { overflowing, remeasure } = useValueOverflow(inputRef);
+    const attachRef = useCallback((element) => {
+        inputRef.current = element;
+        if (typeof ref === 'function')
+            ref(element);
+        else if (ref)
+            ref.current = element;
+    }, [ref]);
+    // `onInput` rather than wrapping `onChange`: React dispatches both from the same native event, so
+    // taking the one consumers reach for less often leaves their handler untouched. An uncontrolled
+    // input is the case that needs it — its value changes with no re-render to measure after.
+    const handleInput = useCallback((event) => {
+        onInput?.(event);
+        remeasure();
+    }, [onInput, remeasure]);
+    return (_jsx("input", { ...nativeProps, ref: attachRef, type: type, className: className === undefined ? 'lutra-input' : `lutra-input ${className}`, onInput: handleInput, "aria-invalid": invalid || undefined, "data-size": size, "data-full-width": fullWidth ? 'true' : undefined, "data-overflow": overflowing ? 'true' : undefined }));
 });
 //# sourceMappingURL=input.js.map

package/dist/components/input/input.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"input.js","sourceRoot":"","sources":["../../../src/components/input/input.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;~~AA8FnC;;;;;;;;;;;;;;;;;;;GAmBG~~;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,UAAU,CAA+B,SAAS,KAAK,CAC1E,~~EAAE~~,IAAI,GAAG,IAAI,~~EAAE~~,OAAO,GAAG,KAAK,~~EAAE~~,SAAS,GAAG,KAAK,~~EAAE~~,IAAI,GAAG,MAAM,EAAE,SAAS,EAAE,GAAG,WAAW,EAAE,~~EAC7F~~,GAAG;~~IAEH~~,OAAO,CACL,mBACM,WAAW,EACf,GAAG,EAAE,~~GAAG~~,~~EACR~~,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,SAAS,EAAE,~~kBAIjE~~,OAAO,IAAI,SAAS,eACvB,IAAI,qBACE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,GAC/C,CACH,CAAC;AACJ,CAAC,CAAC,CAAC"}
1	+ {"version":3,"file":"input.js","sourceRoot":"","sources":["../../../src/components/input/input.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAGxD,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAwGjD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,CAAC,MAAM,KAAK,GAAG,UAAU,CAA+B,SAAS,KAAK,CAC1E,EACE,IAAI,GAAG,IAAI,EACX,OAAO,GAAG,KAAK,EACf,SAAS,GAAG,KAAK,EACjB,IAAI,GAAG,MAAM,EACb,SAAS,EACT,OAAO,EACP,GAAG,WAAW,EACf,EACD,GAAG;IAEH,iGAAiG;IACjG,8FAA8F;IAC9F,iDAAiD;IACjD,MAAM,QAAQ,GAAG,MAAM,CAA0B,IAAI,CAAC,CAAC;IACvD,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,GAAG,gBAAgB,CAAC,QAAQ,CAAC,CAAC;IAE9D,MAAM,SAAS,GAAG,WAAW,CAC3B,CAAC,OAAgC,EAAE,EAAE;QACnC,QAAQ,CAAC,OAAO,GAAG,OAAO,CAAC;QAC3B,IAAI,OAAO,GAAG,KAAK,UAAU;YAAE,GAAG,CAAC,OAAO,CAAC,CAAC;aACvC,IAAI,GAAG;YAAE,GAAG,CAAC,OAAO,GAAG,OAAO,CAAC;IACtC,CAAC,EACD,CAAC,GAAG,CAAC,CACN,CAAC;IAEF,kGAAkG;IAClG,gGAAgG;IAChG,0FAA0F;IAC1F,MAAM,WAAW,GAAG,WAAW,CAC7B,CAAC,KAAyB,EAAE,EAAE;QAC5B,OAAO,EAAE,CAAC,KAAK,CAAC,CAAC;QACjB,SAAS,EAAE,CAAC;IACd,CAAC,EACD,CAAC,OAAO,EAAE,SAAS,CAAC,CACrB,CAAC;IAEF,OAAO,CACL,mBACM,WAAW,EACf,GAAG,EAAE,SAAS,EACd,IAAI,EAAE,IAAI,EACV,SAAS,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,SAAS,EAAE,EAC/E,OAAO,EAAE,WAAW,kBAIN,OAAO,IAAI,SAAS,eACvB,IAAI,qBACE,SAAS,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,mBAKhC,WAAW,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,GAC/C,CACH,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/components/input/overflow.d.ts ADDED Viewed

@@ -0,0 +1,68 @@
+import type { RefObject } from 'react';
+/**
+ * Overflow smaller than this is ignored.
+ *
+ * NO FIGMA VARIABLE, and not a design value — it is a measurement guard. Browsers disagree about
+ * sub-pixel rounding of `scrollWidth` on a text control, and a field whose value exceeds its box by
+ * a fraction of a pixel is a field whose value fits as far as any reader is concerned. Without this,
+ * the mark could appear on an ordinary filled input for no visible reason, which is worse than
+ * missing a one-pixel truncation.
+ */
+export declare const OVERFLOW_TOLERANCE_PX = 1;
+/**
+ * The three facts the decision is made from. Kept as data so the rule is testable without a DOM.
+ *
+ * Not exported: nothing outside this module names it — the tests pass object literals — and an
+ * exported type with no consumer is surface a reader has to account for.
+ */
+interface OverflowMeasurement {
+    /** The control's current value. */
+    value: string;
+    /** Total scrollable width of the control's content. */
+    scrollWidth: number;
+    /** Width of the visible content area. */
+    clientWidth: number;
+}
+/**
+ * Whether some of the value is outside the visible area.
+ *
+ * **An empty control never overflows, however long its placeholder is.** That is a decision, not a
+ * side effect of the arithmetic. The mark says "there is content you cannot see", and a placeholder
+ * is not content — it is a format example that vanishes on the first keystroke, so a mark pointing
+ * at it would promise a value that does not exist. Browsers do not generally make a long placeholder
+ * scrollable either, so this mostly agrees with the measurement; the explicit check is here so the
+ * behaviour is ours and stated rather than inherited and assumed.
+ */
+export declare function hasHiddenValue({ value, scrollWidth, clientWidth }: OverflowMeasurement): boolean;
+/**
+ * Tracks whether the referenced input is hiding part of its value.
+ *
+ * Three triggers, chosen to be the smallest set that covers the real causes, and no polling:
+ *
+ * 1. **After every render**, in a layout effect. This is what catches a controlled input whose value
+ *    changed from above, a `size` change, a `type` change, and a density switch that re-rendered the
+ *    tree. It runs before paint, so the mark never appears a frame late. Two DOM reads per render is
+ *    cheap enough not to warrant a dependency list that would have to enumerate every prop that can
+ *    move the text.
+ * 2. **`ResizeObserver` on the control**, for the width changing without React knowing — a container
+ *    that reflowed, a window resize, a sibling that grew. This is the one cause no render can catch.
+ * 3. **The `input` event**, via the caller. An *uncontrolled* input's value changes with no re-render
+ *    at all, so typing would otherwise go unnoticed until something else re-rendered.
+ *
+ * Density is worth a note: it is a CSS axis, so switching it re-resolves `control/text-size` and
+ * changes how wide the value draws without changing the control's box. `ResizeObserver` does not
+ * fire for that, and neither does a render unless the application re-rendered to flip the attribute
+ * — which is what happens in practice, because something has to set `data-density`. A page that
+ * changed the attribute from outside React entirely would keep a stale mark until its next render.
+ * That is measured rather than assumed, and bounded rather than solved: `contract.md` §12 has the
+ * numbers and §14 records why a `MutationObserver` was rejected.
+ *
+ * @param inputRef the control to measure
+ * @returns the current state, and a `remeasure` for the caller to run on `input`
+ */
+export declare function useValueOverflow(inputRef: RefObject<HTMLInputElement | null>): {
+    overflowing: boolean;
+    remeasure: () => void;
+};
+export {};
+//# sourceMappingURL=overflow.d.ts.map

package/dist/components/input/overflow.d.ts.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"overflow.d.ts","sourceRoot":"","sources":["../../../src/components/input/overflow.ts"],"names":[],"mappings":"AA2BA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC;;;;;;;;GAQG;AACH,eAAO,MAAM,qBAAqB,IAAI,CAAC;AAEvC;;;;;GAKG;AACH,UAAU,mBAAmB;IAC3B,mCAAmC;IACnC,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,yCAAyC;IACzC,WAAW,EAAE,MAAM,CAAC;CACrB;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAE,EAAE,mBAAmB,GAAG,OAAO,CAGhG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,gBAAgB,CAAC,QAAQ,EAAE,SAAS,CAAC,gBAAgB,GAAG,IAAI,CAAC,GAAG;IAC9E,WAAW,EAAE,OAAO,CAAC;IACrB,SAAS,EAAE,MAAM,IAAI,CAAC;CACvB,CAoCA"}

package/dist/components/input/overflow.js ADDED Viewed

@@ -0,0 +1,111 @@
+/**
+ * Detecting that some of an Input's value is not currently visible.
+ *
+ * A single-line `<input>` scrolls its own value rather than wrapping, which is correct native
+ * behaviour — but it gives no sign that it is doing so. A field showing `…@an-unusually-long-` looks
+ * exactly like a field whose value ends there. The earmark this module drives is a sighted-user
+ * discoverability cue for that one situation, and nothing more.
+ *
+ * ## What the state means
+ *
+ * **"There is value content outside the currently visible portion of this control."** Not "the value
+ * is long", and not "there is more text to the right" — while someone edits a long value the browser
+ * scrolls horizontally to keep the caret visible, so hidden content can be on either side or both.
+ * One corner mark for "some of it is not visible" is the deliberate first implementation. Splitting
+ * it into left and right marks would need `scrollLeft` and a scroll listener, and would say more than
+ * the design has asked for.
+ *
+ * ## Why it is derived, never passed
+ *
+ * There is no `overflow` prop and there must not be one. Whether a value fits is a fact about the
+ * rendered control — it depends on the container width, the density-driven text size, the reader's
+ * font-size preference and the value itself — so a consumer could only ever guess at it, and a
+ * consumer's guess would be wrong the moment any of those changed. The component measures instead.
+ *
+ * Nothing here is exported from the package root.
+ */
+import { useCallback, useEffect, useState } from 'react';
+import { useIsomorphicLayoutEffect } from '../../internal/isomorphic-layout-effect.js';
+/**
+ * Overflow smaller than this is ignored.
+ *
+ * NO FIGMA VARIABLE, and not a design value — it is a measurement guard. Browsers disagree about
+ * sub-pixel rounding of `scrollWidth` on a text control, and a field whose value exceeds its box by
+ * a fraction of a pixel is a field whose value fits as far as any reader is concerned. Without this,
+ * the mark could appear on an ordinary filled input for no visible reason, which is worse than
+ * missing a one-pixel truncation.
+ */
+export const OVERFLOW_TOLERANCE_PX = 1;
+/**
+ * Whether some of the value is outside the visible area.
+ *
+ * **An empty control never overflows, however long its placeholder is.** That is a decision, not a
+ * side effect of the arithmetic. The mark says "there is content you cannot see", and a placeholder
+ * is not content — it is a format example that vanishes on the first keystroke, so a mark pointing
+ * at it would promise a value that does not exist. Browsers do not generally make a long placeholder
+ * scrollable either, so this mostly agrees with the measurement; the explicit check is here so the
+ * behaviour is ours and stated rather than inherited and assumed.
+ */
+export function hasHiddenValue({ value, scrollWidth, clientWidth }) {
+    if (value === '')
+        return false;
+    return scrollWidth - clientWidth > OVERFLOW_TOLERANCE_PX;
+}
+/**
+ * Tracks whether the referenced input is hiding part of its value.
+ *
+ * Three triggers, chosen to be the smallest set that covers the real causes, and no polling:
+ *
+ * 1. **After every render**, in a layout effect. This is what catches a controlled input whose value
+ *    changed from above, a `size` change, a `type` change, and a density switch that re-rendered the
+ *    tree. It runs before paint, so the mark never appears a frame late. Two DOM reads per render is
+ *    cheap enough not to warrant a dependency list that would have to enumerate every prop that can
+ *    move the text.
+ * 2. **`ResizeObserver` on the control**, for the width changing without React knowing — a container
+ *    that reflowed, a window resize, a sibling that grew. This is the one cause no render can catch.
+ * 3. **The `input` event**, via the caller. An *uncontrolled* input's value changes with no re-render
+ *    at all, so typing would otherwise go unnoticed until something else re-rendered.
+ *
+ * Density is worth a note: it is a CSS axis, so switching it re-resolves `control/text-size` and
+ * changes how wide the value draws without changing the control's box. `ResizeObserver` does not
+ * fire for that, and neither does a render unless the application re-rendered to flip the attribute
+ * — which is what happens in practice, because something has to set `data-density`. A page that
+ * changed the attribute from outside React entirely would keep a stale mark until its next render.
+ * That is measured rather than assumed, and bounded rather than solved: `contract.md` §12 has the
+ * numbers and §14 records why a `MutationObserver` was rejected.
+ *
+ * @param inputRef the control to measure
+ * @returns the current state, and a `remeasure` for the caller to run on `input`
+ */
+export function useValueOverflow(inputRef) {
+    const [overflowing, setOverflowing] = useState(false);
+    const remeasure = useCallback(() => {
+        const element = inputRef.current;
+        if (!element)
+            return;
+        // Measured against the *current* client width, which is what gives this its hysteresis: once the
+        // mark is showing it has reserved trailing space, so the value has to shrink past that reserve
+        // before the mark goes away. Without it, a value sitting exactly on the boundary would toggle
+        // the reserve, change the width, and toggle back.
+        setOverflowing(hasHiddenValue({
+            value: element.value,
+            scrollWidth: element.scrollWidth,
+            clientWidth: element.clientWidth,
+        }));
+    }, [inputRef]);
+    useIsomorphicLayoutEffect(remeasure);
+    useEffect(() => {
+        const element = inputRef.current;
+        // Not in jsdom, and not in every browser this package supports. The other two triggers still
+        // work without it; only a width change outside React goes unnoticed.
+        if (!element || typeof ResizeObserver === 'undefined')
+            return;
+        const observer = new ResizeObserver(remeasure);
+        observer.observe(element);
+        return () => {
+            observer.disconnect();
+        };
+    }, [inputRef, remeasure]);
+    return { overflowing, remeasure };
+}
+//# sourceMappingURL=overflow.js.map

package/dist/components/input/overflow.js.map ADDED Viewed

@@ -0,0 +1 @@

+ {"version":3,"file":"overflow.js","sourceRoot":"","sources":["../../../src/components/input/overflow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,OAAO,CAAC;AAGzD,OAAO,EAAE,yBAAyB,EAAE,MAAM,4CAA4C,CAAC;AAEvF;;;;;;;;GAQG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC;AAiBvC;;;;;;;;;GASG;AACH,MAAM,UAAU,cAAc,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,WAAW,EAAuB;IACrF,IAAI,KAAK,KAAK,EAAE;QAAE,OAAO,KAAK,CAAC;IAC/B,OAAO,WAAW,GAAG,WAAW,GAAG,qBAAqB,CAAC;AAC3D,CAAC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,gBAAgB,CAAC,QAA4C;IAI3E,MAAM,CAAC,WAAW,EAAE,cAAc,CAAC,GAAG,QAAQ,CAAC,KAAK,CAAC,CAAC;IAEtD,MAAM,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;QACjC,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QACjC,IAAI,CAAC,OAAO;YAAE,OAAO;QAErB,iGAAiG;QACjG,+FAA+F;QAC/F,8FAA8F;QAC9F,kDAAkD;QAClD,cAAc,CACZ,cAAc,CAAC;YACb,KAAK,EAAE,OAAO,CAAC,KAAK;YACpB,WAAW,EAAE,OAAO,CAAC,WAAW;YAChC,WAAW,EAAE,OAAO,CAAC,WAAW;SACjC,CAAC,CACH,CAAC;IACJ,CAAC,EAAE,CAAC,QAAQ,CAAC,CAAC,CAAC;IAEf,yBAAyB,CAAC,SAAS,CAAC,CAAC;IAErC,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,OAAO,GAAG,QAAQ,CAAC,OAAO,CAAC;QACjC,6FAA6F;QAC7F,qEAAqE;QACrE,IAAI,CAAC,OAAO,IAAI,OAAO,cAAc,KAAK,WAAW;YAAE,OAAO;QAE9D,MAAM,QAAQ,GAAG,IAAI,cAAc,CAAC,SAAS,CAAC,CAAC;QAC/C,QAAQ,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;QAC1B,OAAO,GAAG,EAAE;YACV,QAAQ,CAAC,UAAU,EAAE,CAAC;QACxB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,QAAQ,EAAE,SAAS,CAAC,CAAC,CAAC;IAE1B,OAAO,EAAE,WAAW,EAAE,SAAS,EAAE,CAAC;AACpC,CAAC"}

package/dist/components/select-field/select-field.d.ts CHANGED Viewed

@@ -9,7 +9,7 @@ type ForwardedSelectProps = Omit<SelectProps, 'invalid'>;
 export interface SelectFieldProps extends ForwardedSelectProps {
     /** The visible label. Always required. */
     label: ReactNode;
-    /** Supporting text shown above the control and connected with `aria-describedby`. */
+    /** Supporting text shown below the control and connected with `aria-describedby`. */
     hint?: ReactNode;
     /**
      * The error message. Its presence is what puts the field in the error state — it drives the red
@@ -17,8 +17,9 @@ export interface SelectFieldProps extends ForwardedSelectProps {
      */
     error?: ReactNode;
     /**
-     * The word shown after the label text and included in the accessible name. Defaults to
-     * `'required'` when the native `required` attribute is set.
+     * The indicator shown immediately after the label text, drawn as `(required *)` or
+     * `(optional)`. Defaults to `'required'` when the native `required` attribute is set. Its
+     * accessible-name behaviour is `Field`'s — see `internal/field-support.tsx`.
      */
     indicator?: FieldIndicator;
     /** Extra class on the field wrapper, not on the control. */
@@ -27,12 +28,14 @@ export interface SelectFieldProps extends ForwardedSelectProps {
     children: ReactNode;
 }
 /**
- * A labelled dropdown: label, optional hint, a `Select`, and an optional error message.
+ * A labelled dropdown: label, a `Select`, optional supporting text, and an optional error
+ * message.
  *
  * Identical composition to `Field`, around a different control. Both render the same shell — the
  * same label element, the same indicator placement, the same id derivation, the same
- * `aria-describedby` assembly — so a text field and a dropdown behave and read the same way in a
- * form, and a change to that behaviour lands in one place.
+ * `aria-describedby` assembly, the same label → control → hint → error order — so a text field and a
+ * dropdown behave and read the same way in a form, and a change to that behaviour lands in one
+ * place.
  *
  * Everything not listed above is forwarded to `Select`, so `name`, `value`, `defaultValue`,
  * `required`, `onChange`, `size` and `fullWidth` behave as they do there. A `ref` reaches the native

package/dist/components/select-field/select-field.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"select-field.d.ts","sourceRoot":"","sources":["../../../src/components/select-field/select-field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,KAAK,oBAAoB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAEzD,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB;IAC5D,0CAA0C;IAC1C,KAAK,EAAE,SAAS,CAAC;IACjB,qFAAqF;IACrF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB~~;;;OAGG~~;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED~~;;;;;;;;;;;GAWG~~;AACH,eAAO,MAAM,WAAW,~~gHA+CtB~~,CAAC"}
1	+ {"version":3,"file":"select-field.d.ts","sourceRoot":"","sources":["../../../src/components/select-field/select-field.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iCAAiC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAEtD;;;GAGG;AACH,KAAK,oBAAoB,GAAG,IAAI,CAAC,WAAW,EAAE,SAAS,CAAC,CAAC;AAEzD,MAAM,WAAW,gBAAiB,SAAQ,oBAAoB;IAC5D,0CAA0C;IAC1C,KAAK,EAAE,SAAS,CAAC;IACjB,qFAAqF;IACrF,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;OAIG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAC3B,4DAA4D;IAC5D,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,gDAAgD;IAChD,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;GAaG;AACH,eAAO,MAAM,WAAW,gHAgDtB,CAAC"}

package/dist/components/select-field/select-field.js CHANGED Viewed

@@ -3,12 +3,14 @@ import { forwardRef } from 'react';
 import { FieldShell, useFieldIds } from '../../internal/field-support.js';
 import { Select } from '../select/index.js';
 /**
- * A labelled dropdown: label, optional hint, a `Select`, and an optional error message.
+ * A labelled dropdown: label, a `Select`, optional supporting text, and an optional error
+ * message.
  *
  * Identical composition to `Field`, around a different control. Both render the same shell — the
  * same label element, the same indicator placement, the same id derivation, the same
- * `aria-describedby` assembly — so a text field and a dropdown behave and read the same way in a
- * form, and a change to that behaviour lands in one place.
+ * `aria-describedby` assembly, the same label → control → hint → error order — so a text field and a
+ * dropdown behave and read the same way in a form, and a change to that behaviour lands in one
+ * place.
  *
  * Everything not listed above is forwarded to `Select`, so `name`, `value`, `defaultValue`,
  * `required`, `onChange`, `size` and `fullWidth` behave as they do there. A `ref` reaches the native
@@ -19,6 +21,6 @@ export const SelectField = forwardRef(function SelectField({ label, hint, error,
     const hasError = error !== undefined && error !== null && error !== false;
     const ids = useFieldIds({ id, hasHint, hasError, describedBy });
     const resolvedIndicator = indicator ?? (required ? 'required' : 'none');
-    return (_jsx(FieldShell, { controlId: ids.controlId, label: label, indicator: resolvedIndicator, hint: hint, hintId: ids.hintId, error: error, errorId: ids.errorId, disabled: disabled, className: className, children: _jsx(Select, { ...selectProps, ref: ref, id: ids.controlId, required: required, disabled: disabled, invalid: hasError, "aria-describedby": ids.describedBy, children: children }) }));
+    return (_jsx(FieldShell, { controlId: ids.controlId, label: label, indicator: resolvedIndicator, required: required, hint: hint, hintId: ids.hintId, error: error, errorId: ids.errorId, disabled: disabled, className: className, children: _jsx(Select, { ...selectProps, ref: ref, id: ids.controlId, required: required, disabled: disabled, invalid: hasError, "aria-describedby": ids.describedBy, children: children }) }));
 });
 //# sourceMappingURL=select-field.js.map

package/dist/components/select-field/select-field.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"select-field.js","sourceRoot":"","sources":["../../../src/components/select-field/select-field.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;~~AA8B5C;;;;;;;;;;;GAWG~~;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAsC,SAAS,WAAW,CAC7F,EACE,KAAK,EACL,IAAI,EACJ,KAAK,EACL,SAAS,EACT,SAAS,EACT,EAAE,EACF,QAAQ,GAAG,KAAK,EAChB,QAAQ,GAAG,KAAK,EAChB,kBAAkB,EAAE,WAAW,EAC/B,QAAQ,EACR,GAAG,WAAW,EACf,EACD,GAAG;IAEH,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,CAAC;IACtE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,CAAC;IAE1E,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAmB,SAAS,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAExF,OAAO,CACL,KAAC,UAAU,IACT,SAAS,EAAE,GAAG,CAAC,SAAS,EACxB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,iBAAiB,EAC5B,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,YAEpB,KAAC,MAAM,OACD,WAAW,EACf,GAAG,EAAE,GAAG,EACR,EAAE,EAAE,GAAG,CAAC,SAAS,EACjB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,QAAQ,sBACC,GAAG,CAAC,WAAW,YAEhC,QAAQ,GACF,GACE,CACd,CAAC;AACJ,CAAC,CAAC,CAAC"}
1	+ {"version":3,"file":"select-field.js","sourceRoot":"","sources":["../../../src/components/select-field/select-field.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,OAAO,CAAC;AAGnC,OAAO,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,iCAAiC,CAAC;AAE1E,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AA+B5C;;;;;;;;;;;;;GAaG;AACH,MAAM,CAAC,MAAM,WAAW,GAAG,UAAU,CAAsC,SAAS,WAAW,CAC7F,EACE,KAAK,EACL,IAAI,EACJ,KAAK,EACL,SAAS,EACT,SAAS,EACT,EAAE,EACF,QAAQ,GAAG,KAAK,EAChB,QAAQ,GAAG,KAAK,EAChB,kBAAkB,EAAE,WAAW,EAC/B,QAAQ,EACR,GAAG,WAAW,EACf,EACD,GAAG;IAEH,MAAM,OAAO,GAAG,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,CAAC;IACtE,MAAM,QAAQ,GAAG,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,CAAC;IAE1E,MAAM,GAAG,GAAG,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC,CAAC;IAChE,MAAM,iBAAiB,GAAmB,SAAS,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC;IAExF,OAAO,CACL,KAAC,UAAU,IACT,SAAS,EAAE,GAAG,CAAC,SAAS,EACxB,KAAK,EAAE,KAAK,EACZ,SAAS,EAAE,iBAAiB,EAC5B,QAAQ,EAAE,QAAQ,EAClB,IAAI,EAAE,IAAI,EACV,MAAM,EAAE,GAAG,CAAC,MAAM,EAClB,KAAK,EAAE,KAAK,EACZ,OAAO,EAAE,GAAG,CAAC,OAAO,EACpB,QAAQ,EAAE,QAAQ,EAClB,SAAS,EAAE,SAAS,YAEpB,KAAC,MAAM,OACD,WAAW,EACf,GAAG,EAAE,GAAG,EACR,EAAE,EAAE,GAAG,CAAC,SAAS,EACjB,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,QAAQ,EAClB,OAAO,EAAE,QAAQ,sBACC,GAAG,CAAC,WAAW,YAEhC,QAAQ,GACF,GACE,CACd,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/dist/internal/field-support.d.ts CHANGED Viewed

@@ -44,6 +44,14 @@ interface FieldShellProps {
     controlId: string;
     label: ReactNode;
     indicator: FieldIndicator;
+    /**
+     * Whether the control carries the native `required` attribute.
+     *
+     * The shell needs this to decide whether the required indicator is redundant to a screen reader —
+     * see the note on the accessible name below. It never renders the attribute itself; that belongs
+     * to the control.
+     */
+    required: boolean;
     hint: ReactNode;
     hintId: string | undefined;
     error: ReactNode;
@@ -55,14 +63,38 @@ interface FieldShellProps {
 }
 /**
  * Renders the visible parts around a control, in the documented order:
- * label → hint → control → error.
+ * label → control → hint → error.
  *
- * The hint sits above the control so it is read before the control is operated; the error sits
- * below it, which is where the Figma annotation places it and where Field Group puts its own.
+ * **Supporting text sits below the control**, which is what the Figma component draws and what its
+ * accessibility annotation describes. An earlier implementation placed the hint above the control on
+ * the argument that guidance should be read before typing; the design system decided otherwise, and
+ * the contract is the design system's to set. The `aria-describedby` order is unchanged and now
+ * matches the DOM order exactly — consumer description, then hint, then error.
  *
- * The indicator word is rendered *inside* the `<label>`, so it becomes part of the accessible name
- * and is announced with it rather than being a separate visual flourish the label does not carry.
+ * ## The indicator and the accessible name
+ *
+ * The indicator is rendered inside the `<label>`, so whatever of it is exposed becomes part of the
+ * accessible name. Figma draws `(required *)` and `(optional)` immediately after the label text, and
+ * the visible output is exactly that in every case. What differs is how much of it assistive
+ * technology sees, and the rule is: **expose the indicator only when nothing else carries the same
+ * information.**
+ *
+ * - **`required` indicator with the native `required` attribute** — hidden entirely. The attribute
+ *   already conveys the required state, and repeating the word in the name says the same thing
+ *   twice about one control. This is the ordinary case, because `indicator` defaults to `'required'`
+ *   precisely when `required` is set.
+ * - **`required` indicator without the attribute** — the word stays in the name. A consumer may ask
+ *   for the indicator on a field that is validated elsewhere, and in that case the name is the only
+ *   thing carrying it. Hiding it there would leave the requirement visible-only, which is the defect
+ *   this rule exists to avoid.
+ * - **`optional` indicator** — always stays in the name. There is no native attribute and no ARIA
+ *   state for "optional", so nothing else conveys it and there is no duplication to remove.
+ *
+ * The asterisk is separately `aria-hidden` in the one case where the word is exposed: it is a
+ * decorative convention duplicating the word beside it, and it must never be the only signal.
+ *
+ * How any given screen reader words the required state is its own business and is not asserted here.
  */
-export declare function FieldShell({ controlId, label, indicator, hint, hintId, error, errorId, disabled, className, children, }: FieldShellProps): import("react").JSX.Element;
+export declare function FieldShell({ controlId, label, indicator, required, hint, hintId, error, errorId, disabled, className, children, }: FieldShellProps): import("react").JSX.Element;
 export {};
 //# sourceMappingURL=field-support.d.ts.map

package/dist/internal/field-support.d.ts.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"field-support.d.ts","sourceRoot":"","sources":["../../src/internal/field-support.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;;;;GAWG;AAEH,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,UAAU,aAAa;IACrB,4CAA4C;IAC5C,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,yFAAyF;IACzF,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,aAAa,GAAG,QAAQ,~~CAiB3F~~;AAED,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,cAAc,CAAC;IAC1B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED~~;;;;;;;;;GASG~~;AACH,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,KAAK,EACL,SAAS,EACT,IAAI,EACJ,MAAM,EACN,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,QAAQ,GACT,EAAE,eAAe,+~~BAmCjB~~"}
1	+ {"version":3,"file":"field-support.d.ts","sourceRoot":"","sources":["../../src/internal/field-support.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;;;;;;;;;;GAWG;AAEH,wDAAwD;AACxD,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAC;AAE9D,UAAU,aAAa;IACrB,4CAA4C;IAC5C,EAAE,EAAE,MAAM,GAAG,SAAS,CAAC;IACvB,OAAO,EAAE,OAAO,CAAC;IACjB,QAAQ,EAAE,OAAO,CAAC;IAClB,4DAA4D;IAC5D,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED,MAAM,WAAW,QAAQ;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,yFAAyF;IACzF,WAAW,EAAE,MAAM,GAAG,SAAS,CAAC;CACjC;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,EAAE,aAAa,GAAG,QAAQ,CAmB3F;AAED,UAAU,eAAe;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,SAAS,CAAC;IACjB,SAAS,EAAE,cAAc,CAAC;IAC1B;;;;;;OAMG;IACH,QAAQ,EAAE,OAAO,CAAC;IAClB,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IAC3B,KAAK,EAAE,SAAS,CAAC;IACjB,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,SAAS,EAAE,MAAM,GAAG,SAAS,CAAC;IAC9B,0EAA0E;IAC1E,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,QAAQ,GACT,EAAE,eAAe,+BAsDjB"}

package/dist/internal/field-support.js CHANGED Viewed

@@ -17,7 +17,9 @@ export function useFieldIds({ id, hasHint, hasError, describedBy }) {
     const hintId = hasHint ? `${controlId}-hint` : undefined;
     const errorId = hasError ? `${controlId}-error` : undefined;
     // Order matters: the consumer's own description first, then the hint, then the error. A screen
-    // reader reads them in this order, and the error is the thing to leave ringing in the ear.
+    // reader reads them in this order, the error is the thing to leave ringing in the ear, and since
+    // supporting text moved below the control this is also the DOM order — reading order and
+    // description order are now the same sequence rather than two orders to keep in step.
     const parts = [describedBy, hintId, errorId].filter((part) => Boolean(part));
     return {
         controlId,
@@ -28,15 +30,41 @@ export function useFieldIds({ id, hasHint, hasError, describedBy }) {
 }
 /**
  * Renders the visible parts around a control, in the documented order:
- * label → hint → control → error.
+ * label → control → hint → error.
  *
- * The hint sits above the control so it is read before the control is operated; the error sits
- * below it, which is where the Figma annotation places it and where Field Group puts its own.
+ * **Supporting text sits below the control**, which is what the Figma component draws and what its
+ * accessibility annotation describes. An earlier implementation placed the hint above the control on
+ * the argument that guidance should be read before typing; the design system decided otherwise, and
+ * the contract is the design system's to set. The `aria-describedby` order is unchanged and now
+ * matches the DOM order exactly — consumer description, then hint, then error.
  *
- * The indicator word is rendered *inside* the `<label>`, so it becomes part of the accessible name
- * and is announced with it rather than being a separate visual flourish the label does not carry.
+ * ## The indicator and the accessible name
+ *
+ * The indicator is rendered inside the `<label>`, so whatever of it is exposed becomes part of the
+ * accessible name. Figma draws `(required *)` and `(optional)` immediately after the label text, and
+ * the visible output is exactly that in every case. What differs is how much of it assistive
+ * technology sees, and the rule is: **expose the indicator only when nothing else carries the same
+ * information.**
+ *
+ * - **`required` indicator with the native `required` attribute** — hidden entirely. The attribute
+ *   already conveys the required state, and repeating the word in the name says the same thing
+ *   twice about one control. This is the ordinary case, because `indicator` defaults to `'required'`
+ *   precisely when `required` is set.
+ * - **`required` indicator without the attribute** — the word stays in the name. A consumer may ask
+ *   for the indicator on a field that is validated elsewhere, and in that case the name is the only
+ *   thing carrying it. Hiding it there would leave the requirement visible-only, which is the defect
+ *   this rule exists to avoid.
+ * - **`optional` indicator** — always stays in the name. There is no native attribute and no ARIA
+ *   state for "optional", so nothing else conveys it and there is no duplication to remove.
+ *
+ * The asterisk is separately `aria-hidden` in the one case where the word is exposed: it is a
+ * decorative convention duplicating the word beside it, and it must never be the only signal.
+ *
+ * How any given screen reader words the required state is its own business and is not asserted here.
  */
-export function FieldShell({ controlId, label, indicator, hint, hintId, error, errorId, disabled, className, children, }) {
-    return (_jsxs("div", { className: className === undefined ? 'lutra-field' : `lutra-field ${className}`, "data-invalid": error ? 'true' : undefined, "data-disabled": disabled ? 'true' : undefined, children: [_jsxs("label", { className: "lutra-field__label", htmlFor: controlId, children: [label, indicator !== 'none' && (_jsxs(_Fragment, { children: [' ', _jsx("span", { className: "lutra-field__indicator", "data-indicator": indicator, children: indicator === 'required' ? 'Required' : 'Optional' })] }))] }), hint !== undefined && hint !== null && hint !== false && (_jsx("p", { className: "lutra-field__hint", id: hintId, children: hint })), children, error !== undefined && error !== null && error !== false && (_jsx("p", { className: "lutra-field__error", id: errorId, children: error }))] }));
+export function FieldShell({ controlId, label, indicator, required, hint, hintId, error, errorId, disabled, className, children, }) {
+    // The one case where the indicator says nothing the control has not already said.
+    const indicatorIsRedundant = indicator === 'required' && required;
+    return (_jsxs("div", { className: className === undefined ? 'lutra-field' : `lutra-field ${className}`, "data-invalid": error ? 'true' : undefined, "data-disabled": disabled ? 'true' : undefined, children: [_jsxs("label", { className: "lutra-field__label", htmlFor: controlId, children: [label, indicator !== 'none' && (_jsxs(_Fragment, { children: [' ', _jsx("span", { className: "lutra-field__indicator", "data-indicator": indicator, "aria-hidden": indicatorIsRedundant || undefined, children: indicator === 'required' ? (_jsxs(_Fragment, { children: ['(required', _jsx("span", { "aria-hidden": "true", children: ' *' }), ')'] })) : ('(optional)') })] }))] }), children, hint !== undefined && hint !== null && hint !== false && (_jsx("p", { className: "lutra-field__hint", id: hintId, children: hint })), error !== undefined && error !== null && error !== false && (_jsx("p", { className: "lutra-field__error", id: errorId, children: error }))] }));
 }
 //# sourceMappingURL=field-support.js.map

package/dist/internal/field-support.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"file":"field-support.js","sourceRoot":"","sources":["../../src/internal/field-support.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAoC9B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAiB;IAC/E,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC;IAC1B,MAAM,SAAS,GAAG,EAAE,IAAI,eAAe,SAAS,EAAE,CAAC;IAEnD,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAE5D,+FAA+F;IAC/F,~~2FAA2F~~;~~IAC3F~~,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE7F,OAAO;QACL,SAAS;QACT,MAAM;QACN,OAAO;QACP,WAAW,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;KAC5D,CAAC;AACJ,CAAC;~~AAgBD;;;;;;;;;GASG~~;AACH,MAAM,UAAU,UAAU,CAAC,EACzB,SAAS,EACT,KAAK,EACL,SAAS,EACT,IAAI,EACJ,MAAM,EACN,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,QAAQ,GACQ;IAChB,OAAO,CACL,eACE,SAAS,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,SAAS,EAAE,kBACjE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,mBACzB,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,aAE5C,iBAAO,SAAS,EAAC,oBAAoB,EAAC,OAAO,EAAE,SAAS,aACrD,KAAK,EACL,SAAS,KAAK,MAAM,IAAI,CACvB,~~8BAEyF~~,GAAG,~~EAC1F~~,~~eAAM~~,SAAS,EAAC,wBAAwB,~~oBAAiB~~,SAAS,~~YAC/D~~,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,~~UAAU~~,CAAC,CAAC,CAAC,~~UAAU~~,~~GAC9C~~,IACN,CACJ,IACK,EAEP,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,IAAI,CACxD,YAAG,SAAS,EAAC,mBAAmB,EAAC,EAAE,EAAE,MAAM,YACxC,IAAI,GACH,CACL,EAEA,~~QAAQ,EAER,~~KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,IAAI,CAC3D,YAAG,SAAS,EAAC,oBAAoB,EAAC,EAAE,EAAE,OAAO,YAC1C,KAAK,GACJ,CACL,IACG,CACP,CAAC;AACJ,CAAC"}
1	+ {"version":3,"file":"field-support.js","sourceRoot":"","sources":["../../src/internal/field-support.tsx"],"names":[],"mappings":";AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,OAAO,CAAC;AAoC9B;;;;;;;;;;GAUG;AACH,MAAM,UAAU,WAAW,CAAC,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAiB;IAC/E,MAAM,SAAS,GAAG,KAAK,EAAE,CAAC;IAC1B,MAAM,SAAS,GAAG,EAAE,IAAI,eAAe,SAAS,EAAE,CAAC;IAEnD,MAAM,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,GAAG,SAAS,OAAO,CAAC,CAAC,CAAC,SAAS,CAAC;IACzD,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAC,GAAG,SAAS,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC;IAE5D,+FAA+F;IAC/F,iGAAiG;IACjG,yFAAyF;IACzF,sFAAsF;IACtF,MAAM,KAAK,GAAG,CAAC,WAAW,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAkB,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC;IAE7F,OAAO;QACL,SAAS;QACT,MAAM;QACN,OAAO;QACP,WAAW,EAAE,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS;KAC5D,CAAC;AACJ,CAAC;AAwBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,MAAM,UAAU,UAAU,CAAC,EACzB,SAAS,EACT,KAAK,EACL,SAAS,EACT,QAAQ,EACR,IAAI,EACJ,MAAM,EACN,KAAK,EACL,OAAO,EACP,QAAQ,EACR,SAAS,EACT,QAAQ,GACQ;IAChB,kFAAkF;IAClF,MAAM,oBAAoB,GAAG,SAAS,KAAK,UAAU,IAAI,QAAQ,CAAC;IAElE,OAAO,CACL,eACE,SAAS,EAAE,SAAS,KAAK,SAAS,CAAC,CAAC,CAAC,aAAa,CAAC,CAAC,CAAC,eAAe,SAAS,EAAE,kBACjE,KAAK,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,mBACzB,QAAQ,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,SAAS,aAE5C,iBAAO,SAAS,EAAC,oBAAoB,EAAC,OAAO,EAAE,SAAS,aACrD,KAAK,EACL,SAAS,KAAK,MAAM,IAAI,CACvB,8BAGoF,GAAG,EACrF,eACE,SAAS,EAAC,wBAAwB,oBAClB,SAAS,iBACZ,oBAAoB,IAAI,SAAS,YAE7C,SAAS,KAAK,UAAU,CAAC,CAAC,CAAC,CAC1B,8BACG,WAAW,EAIZ,8BAAkB,MAAM,YAAE,IAAI,GAAQ,EACrC,GAAG,IACH,CACJ,CAAC,CAAC,CAAC,CACF,YAAY,CACb,GACI,IACN,CACJ,IACK,EAEP,QAAQ,EAER,IAAI,KAAK,SAAS,IAAI,IAAI,KAAK,IAAI,IAAI,IAAI,KAAK,KAAK,IAAI,CACxD,YAAG,SAAS,EAAC,mBAAmB,EAAC,EAAE,EAAE,MAAM,YACxC,IAAI,GACH,CACL,EAEA,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,KAAK,IAAI,CAC3D,YAAG,SAAS,EAAC,oBAAoB,EAAC,EAAE,EAAE,OAAO,YAC1C,KAAK,GACJ,CACL,IACG,CACP,CAAC;AACJ,CAAC"}

package/dist/styles.css CHANGED Viewed

@@ -15,18 +15,24 @@
  * The file has two layers, and the order matters:
  *
  * 1. The generated token layer, which declares every Lutra design token as a CSS
- *    custom property on `:root`, plus the dark values on `[data-theme='dark']`.
- *    It is produced from `tokens/source.json` and is not hand-edited.
+ *    custom property on `:root`, plus the dark values on `[data-theme='dark']`
+ *    and the condensed values on `[data-density='condensed']`. Theme and density
+ *    are independent axes and compose freely. It is produced from
+ *    `tokens/source.json` and is not hand-edited.
  * 2. One file per component, which reads those tokens and never a raw value.
  *
  * Rules for anything added here:
  * - Every selector is prefixed with `lutra-`, so the library cannot collide with
  *   a consuming application's styles.
- * - The only global selectors permitted are the token layer's `:root` and
- *   `[data-theme]` blocks, and they declare custom properties and nothing else.
- *   A declaration that paints — a colour, a font, a margin on `body` — must never
- *   appear on a global selector: a library stylesheet does not get to restyle a
- *   page it was merely imported into. See `docs/decisions/0002-design-tokens.md`.
+ * - The only global selectors permitted are the token layer's `:root`,
+ *   `[data-theme]` and `[data-density]` blocks, and they declare custom properties
+ *   and nothing else. A declaration that paints — a colour, a font, a margin on
+ *   `body` — must never appear on a global selector: a library stylesheet does not
+ *   get to restyle a page it was merely imported into. See
+ *   `docs/decisions/0002-design-token-pipeline.md` and
+ *   `docs/decisions/0004-global-density-modes.md`.
+ * - A component rule never matches on `data-theme` or `data-density`. Those are
+ *   global modes resolved once in the token layer; a component reads the tokens.
  * - No component rule may reach for `:root`, an element selector, or `*`.
  * - Sizes use `rem` and unitless line heights, so the library respects the user's
  *   browser font size and keeps working under zoom. Border and outline widths are
@@ -245,6 +251,10 @@
   --lutra-layout-gutter-tablet: 1.5rem;
   --lutra-layout-section-lg: 6rem;
   --lutra-layout-section-sm: 4rem;
+  /* Lutra Density */
+  --lutra-control-text-size: 1rem;
+  --lutra-field-spacing: 0.5rem;
 }
 /* Dark mode. Every token whose value differs in dark, plus every alias that reaches one — an
@@ -494,6 +504,27 @@
   --lutra-component-tooltip-text: var(--lutra-color-background-canvas);
 }
+/* Condensed density. Every token whose value differs between the density modes, plus every
+ * alias that reaches one — an alias is substituted where it is declared, so it has to be
+ * re-declared here to resolve against condensed values rather than inheriting the spacious
+ * result from :root.
+ *
+ * Independent of theme by construction: this block declares no colour and the theme blocks
+ * declare no density value, so `data-theme` and `data-density` compose freely on the same
+ * element or on different ancestors. Density changes composition spacing and control text
+ * size only — never a control height or a target size. */
+[data-density='condensed'] {
+  --lutra-control-text-size: 0.875rem;
+  --lutra-field-spacing: 0.25rem;
+}
+/* An explicit spacious region, so a spacious island inside a condensed one is possible. Same
+ * set as above, back at their spacious values. */
+[data-density='spacious'] {
+  --lutra-control-text-size: 1rem;
+  --lutra-field-spacing: 0.5rem;
+}
 /*
  * Button.
  *
@@ -2185,10 +2216,16 @@
  * focus and disabled are selected from the platform — `:hover`, `:focus-visible`,
  * `:disabled` — never from a prop.
  *
+ * `data-overflow` is set by the component, not the consumer: it means part of the
+ * value is scrolled out of sight. See the overflow earmark near the bottom of
+ * this file, and `overflow.ts` for how the state is derived.
+ *
  * Colour comes from Figma's `component/input/*` alias layer, so the design system
  * decides what an input surface, its text, its placeholder and each of its border
- * states are. Sizes, spacing and type come from the core scales. The values with
- * no Figma variable behind them are marked.
+ * states are. Geometry and spacing come from the core scales, and the text size
+ * comes from the global density axis — `control/text-size`, inherited through
+ * `data-density`, not a prop and not a function of `size`. The values with no
+ * Figma variable behind them are marked.
  *
  * The error state is styled from `aria-invalid` rather than a `data-*` attribute
  * of its own. There is then no way for the field to look wrong while reporting
@@ -2231,18 +2268,23 @@
   --lutra-input-padding-inline-md: var(--lutra-space-md);
   --lutra-input-padding-inline-lg: var(--lutra-space-lg);
-  /* 14px, 16px, 18px. */
-  --lutra-input-font-size-sm: var(--lutra-text-body-small);
-  --lutra-input-font-size-md: var(--lutra-text-body);
-  --lutra-input-font-size-lg: var(--lutra-text-h3);
-  /* The leading paired with each size in the type ramp. Figma draws a flat 120%
-   * on this component with no variable behind it; inside a fixed-height control
-   * the two are visually identical, and using the ramp keeps the field consistent
-   * with every other piece of text at the same size. */
-  --lutra-input-line-height-sm: var(--lutra-type-line-height-body-small);
-  --lutra-input-line-height-md: var(--lutra-type-line-height-body);
-  --lutra-input-line-height-lg: var(--lutra-type-line-height-h3);
+  /* Control text size, from the global density axis rather than from `size`.
+   *
+   * Figma binds `control/text-size` to the value text of all eighteen Input
+   * variants, so `size` owns height and inline padding and density owns the
+   * type: 16px in Spacious, 14px in Condensed, the same in sm, md and lg. It is
+   * inherited from whatever `data-density` is in scope and is declared here, on
+   * the control, so a nested `[data-density]` region resolves it correctly.
+   * There is deliberately no density prop — see `docs/design-tokens.md`. */
+  --lutra-input-font-size: var(--lutra-control-text-size);
+  /* One leading for one size. Figma draws a flat 120% here with no variable
+   * behind it; the body ramp is used instead because `control/text-size`
+   * resolves to `text/body` in the default mode, and inside a min-height control
+   * the two are visually identical. Condensed keeps this ratio on 14px text,
+   * which is looser than the body-small ramp and is what lets the line still
+   * grow rather than crowd when the reader raises their font size. */
+  --lutra-input-line-height: var(--lutra-type-line-height-body);
   /* NO FIGMA VARIABLE. Figma draws inputs at a fixed 36/40/44px; these become
    * `min-block-size` instead, because a fixed height on a text-bearing control
@@ -2255,6 +2297,41 @@
    * vertical breathing room the text needs once the field is free to grow. */
   --lutra-input-padding-block: var(--lutra-space-2xs);
+  /* Trailing affordance reserve — an internal contract, not public API.
+   *
+   * Two additive slots, both `0px` unless something claims them, added to the
+   * trailing inline padding by each size rule. Additive because they answer to
+   * different owners and can apply at once, and CSS cannot let one custom
+   * property add to itself:
+   *
+   * - `--lutra-input-trailing-reserve` is for a *composition* that puts a
+   *   control at the trailing edge — the Info trigger `Input with Tooltip`
+   *   needs, a password reveal, a clear button. Nothing claims it today. A
+   *   composition sets it on the input to the width it is occupying, and the
+   *   value keeps clear of whatever it placed there.
+   * - `--lutra-input-overflow-reserve` belongs to this file and is claimed by
+   *   the `data-overflow` rule below. It is not the composition's to set.
+   *
+   * Neither is documented for consumers and neither is a prop. If a public
+   * trailing-slot API is ever wanted, it is a decision record, not a rename. */
+  --lutra-input-trailing-reserve: 0px;
+  --lutra-input-overflow-reserve: 0px;
+  /* The overflow earmark.
+   *
+   * Size: Figma draws the earmark vector at a flat 8x8 in all eighteen variants
+   * and binds no variable to it, so `space/sm` is the token that equals what is
+   * drawn — the same treatment as the 36/40/44px control heights below.
+   *
+   * Colour: Figma binds the earmark's fill to the *border* token of the current
+   * status — `component/input/border/default`, `/invalid`, and
+   * `color/border/disabled`. Code currently draws it in `color/icon/default` in
+   * every state instead. That is a real disagreement, not a tokenisation
+   * difference, and it is open rather than settled: the earmark's treatment is
+   * being revisited as its own design decision. See `contract.md` §14. */
+  --lutra-input-overflow-mark-size: var(--lutra-space-sm);
+  --lutra-input-overflow-mark: var(--lutra-color-icon-default);
   box-sizing: border-box;
   inline-size: 100%;
   max-inline-size: 100%;
@@ -2267,7 +2344,9 @@
   background-color: var(--lutra-input-surface);
   color: var(--lutra-input-text);
   font-family: var(--lutra-input-font-family);
+  font-size: var(--lutra-input-font-size);
   font-weight: var(--lutra-input-font-weight);
+  line-height: var(--lutra-input-line-height);
   /* Strips the platform's own field chrome — notably iOS Safari's inner shadow
    * and rounded corners — so the token values are what shows. */
@@ -2275,29 +2354,40 @@
 }
 /* Sizes.
+ *
+ * Geometry only — height and inline padding. Type comes from the density axis
+ * above and is identical across the three, which is what Figma encodes.
  *
  * `min-block-size` rather than `height`: it reproduces the Figma height at the
- * default font size and lets the field grow when the reader raises theirs. */
+ * default font size and lets the field grow when the reader raises theirs. That
+ * is also why Condensed cannot shrink a control: it lowers the text size inside
+ * a minimum that density never touches. */
 .lutra-input[data-size='sm'] {
   min-block-size: var(--lutra-input-min-height-sm);
-  padding-inline: var(--lutra-input-padding-inline-sm);
-  font-size: var(--lutra-input-font-size-sm);
-  line-height: var(--lutra-input-line-height-sm);
+  padding-inline-start: var(--lutra-input-padding-inline-sm);
+  padding-inline-end: calc(
+    var(--lutra-input-padding-inline-sm) + var(--lutra-input-trailing-reserve) +
+      var(--lutra-input-overflow-reserve)
+  );
 }
 .lutra-input[data-size='md'] {
   min-block-size: var(--lutra-input-min-height-md);
-  padding-inline: var(--lutra-input-padding-inline-md);
-  font-size: var(--lutra-input-font-size-md);
-  line-height: var(--lutra-input-line-height-md);
+  padding-inline-start: var(--lutra-input-padding-inline-md);
+  padding-inline-end: calc(
+    var(--lutra-input-padding-inline-md) + var(--lutra-input-trailing-reserve) +
+      var(--lutra-input-overflow-reserve)
+  );
 }
 .lutra-input[data-size='lg'] {
   min-block-size: var(--lutra-input-min-height-lg);
-  padding-inline: var(--lutra-input-padding-inline-lg);
-  font-size: var(--lutra-input-font-size-lg);
-  line-height: var(--lutra-input-line-height-lg);
+  padding-inline-start: var(--lutra-input-padding-inline-lg);
+  padding-inline-end: calc(
+    var(--lutra-input-padding-inline-lg) + var(--lutra-input-trailing-reserve) +
+      var(--lutra-input-overflow-reserve)
+  );
 }
 /* Placeholder.
@@ -2384,6 +2474,94 @@
   -webkit-text-fill-color: var(--lutra-input-disabled-text);
 }
+/* The overflow earmark.
+ *
+ * A single-line input scrolls its value rather than wrapping, and gives no sign
+ * that it is doing so — `…@an-unusually-long-` looks exactly like a value that
+ * ends there. `data-overflow` is set by the component when part of the value is
+ * outside the visible area, and this draws a small folded corner to say so.
+ *
+ * ## Why a background rather than an element
+ *
+ * An `<input>` is a replaced element and cannot render `::before` or `::after`,
+ * so a mark inside the control is either a background or a sibling in a wrapper.
+ * A background needs no wrapper, no extra node and no change to what Input
+ * renders — and it is decorative by construction: there is nothing to give a
+ * role, nothing to focus, nothing in the accessibility tree, and no way for it
+ * to touch the accessible name or value. Select has a wrapper because its
+ * chevron must be a token-coloured mask; this needs no mask.
+ *
+ * ## The shape
+ *
+ * `linear-gradient(to bottom left, … 50%, transparent 50%)` in a square placed
+ * at the top right. The gradient axis runs toward the bottom-left corner, so the
+ * hard stop at 50% is a line from the square's top-left to its bottom-right and
+ * the filled half is the one nearest the top-right corner. That yields a
+ * triangle whose two flat edges lie along the top and right edges of the field
+ * with the diagonal facing inward, toward the content — a folded corner, not an
+ * arrow pointing out of it.
+ *
+ * The size is `space/sm` (8px), which the field's own `radius/md` corner then
+ * rounds off at the tip. That is deliberate: a mark flush with a rounded corner
+ * has to follow it, and the result reads as a fold rather than a pasted-on
+ * triangle.
+ *
+ * Figma draws the same triangle: an 8x8 `Overflow earmark` vector in all
+ * eighteen variants, pinned to the top-right corner by MAX/MIN constraints,
+ * whose path `M 0 0 L 8 0 L 8 8 L 0 0 Z` has its vertices at the box's
+ * top-left, top-right and bottom-right. Flat top, flat right, diagonal facing
+ * inward — the shape this gradient produces.
+ *
+ * ## Colour — currently disagreeing with Figma
+ *
+ * Figma binds the earmark's fill to the border token of the current status, so
+ * it turns red on an invalid field. This draws it in `color/icon/default` in
+ * every state instead, on the argument that it reports a fact about the viewport
+ * rather than a problem with the value and must not read as a validation
+ * indicator.
+ *
+ * That argument may lose. The earmark's treatment has been identified as too
+ * subtle and is being revisited as its own design decision, and the state
+ * colouring belongs to that decision rather than to this file. **Do not
+ * reconcile it either way here** — `contract.md` §14 records it.
+ *
+ * ## Clearance
+ *
+ * The mark claims `--lutra-input-overflow-reserve`, which the size rules add to
+ * the trailing padding, so the value's scroll area stops before the corner
+ * instead of running under it. The reserve exists only while the mark does, so a
+ * field that fits wastes nothing. Measuring against the reduced width is what
+ * keeps that stable: once the mark is showing, the value has to shrink past the
+ * reserve to lose it, so a value sitting on the boundary cannot flicker.
+ *
+ * Figma's own Value layers are set to `textTruncation: ENDING`, which reserves
+ * no trailing space — its static text is already cut off with an ellipsis before
+ * the corner. The runtime reserves the space because its text *scrolls*, so
+ * without it the value would pass under the mark as the caret moved. See
+ * `contract.md` §6.
+ *
+ * Forced-colours modes drop background images, so the mark is absent there. It
+ * is a discoverability cue rather than information, the value is still reachable
+ * by caret and by assistive technology, and painting a substitute would mean
+ * inventing a border treatment the design system has not got. */
+.lutra-input[data-overflow='true'] {
+  --lutra-input-overflow-reserve: var(--lutra-input-overflow-mark-size);
+  background-image: linear-gradient(
+    to bottom left,
+    var(--lutra-input-overflow-mark) 50%,
+    transparent 50%
+  );
+  background-repeat: no-repeat;
+  background-position: top right;
+  background-size: var(--lutra-input-overflow-mark-size) var(--lutra-input-overflow-mark-size);
+}
+.lutra-input[data-overflow='true']:disabled {
+  --lutra-input-overflow-mark: var(--lutra-input-disabled-text);
+}
 /* Read-only keeps the normal visual treatment. It stays focusable and its value
  * stays selectable and copyable, which is the behaviour that distinguishes it
  * from disabled, so it must not be dressed up to look unavailable. */
@@ -2498,13 +2676,14 @@
   --lutra-select-padding-inline-md: var(--lutra-space-md);
   --lutra-select-padding-inline-lg: var(--lutra-space-lg);
-  --lutra-select-font-size-sm: var(--lutra-text-body-small);
-  --lutra-select-font-size-md: var(--lutra-text-body);
-  --lutra-select-font-size-lg: var(--lutra-text-h3);
-  --lutra-select-line-height-sm: var(--lutra-type-line-height-body-small);
-  --lutra-select-line-height-md: var(--lutra-type-line-height-body);
-  --lutra-select-line-height-lg: var(--lutra-type-line-height-h3);
+  /* Control text size, from the global density axis rather than from `size` —
+   * exactly as Input does it, and for the same reason: Figma binds
+   * `control/text-size` to the value text of every Select variant, so the
+   * placeholder and the selected value are 16px in Spacious and 14px in
+   * Condensed at all three sizes. Declared here on the control so a nested
+   * `[data-density]` region resolves it. There is no density prop. */
+  --lutra-select-font-size: var(--lutra-control-text-size);
+  --lutra-select-line-height: var(--lutra-type-line-height-body);
   /* NO FIGMA VARIABLE. Figma draws 36/40/44px fixed heights; these become `min-block-size` so the
    * control grows with the reader's font size instead of clipping at 200% zoom. */
@@ -2525,15 +2704,20 @@
   background-color: var(--lutra-select-surface);
   color: var(--lutra-select-text);
   font-family: var(--lutra-select-font-family);
+  font-size: var(--lutra-select-font-size);
   font-weight: var(--lutra-select-font-weight);
+  line-height: var(--lutra-select-line-height);
   cursor: pointer;
   /* Removes the platform's own dropdown arrow, so the Figma chevron is the only one drawn. */
   appearance: none;
 }
-/* Sizes. `min-block-size` rather than `height`, so the control grows with the reader's font size.
- * Trailing padding reserves room for the chevron. */
+/* Sizes. Geometry only — height, inline padding and the chevron reserve. Type comes from the density
+ * axis and is the same across the three.
+ *
+ * `min-block-size` rather than `height`, so the control grows with the reader's font size. Trailing
+ * padding reserves room for the chevron. */
 .lutra-select[data-size='sm'] {
   min-block-size: var(--lutra-select-min-height-sm);
@@ -2542,8 +2726,6 @@
       var(--lutra-select-padding-inline-sm) + var(--lutra-select-chevron-size) +
         var(--lutra-select-chevron-gap)
     );
-  font-size: var(--lutra-select-font-size-sm);
-  line-height: var(--lutra-select-line-height-sm);
 }
 .lutra-select[data-size='md'] {
@@ -2553,8 +2735,6 @@
       var(--lutra-select-padding-inline-md) + var(--lutra-select-chevron-size) +
         var(--lutra-select-chevron-gap)
     );
-  font-size: var(--lutra-select-font-size-md);
-  line-height: var(--lutra-select-line-height-md);
 }
 .lutra-select[data-size='lg'] {
@@ -2564,8 +2744,6 @@
       var(--lutra-select-padding-inline-lg) + var(--lutra-select-chevron-size) +
         var(--lutra-select-chevron-gap)
     );
-  font-size: var(--lutra-select-font-size-lg);
-  line-height: var(--lutra-select-line-height-lg);
 }
 /* The chevron sits at the same inset as the control's own padding, per size. */
@@ -3177,18 +3355,28 @@
  * These classes are shared: `Field` and `SelectField` render the same shell around different
  * controls, so both use `.lutra-field*`. The control inside brings its own styling.
  *
- * Order is label → hint → control → error, expressed as source order in a vertical stack rather
+ * Order is label → control → hint → error, expressed as source order in a vertical stack rather
  * than by any reordering property, so the visual order and the DOM order — which is the order a
- * screen reader and the Tab key follow — are the same thing.
- *
- * Figma composes the field with 4px auto-layout spacing and draws its supporting text below the
- * control, because the component models one supporting slot that becomes the error when invalid.
- * The accessibility annotation is the behavioural contract and puts the error below the control
- * while a hint is guidance read before typing, so the implementation splits them. See `field.md`.
+ * screen reader and the Tab key follow — are the same thing. Nothing here uses `order`,
+ * `flex-direction: column-reverse` or `grid-row`, and nothing should: a field whose visual order
+ * differed from its DOM order would read in one sequence and look like another.
+ *
+ * Figma binds the field's auto-layout `itemSpacing` and its supporting text's indent to
+ * `field/spacing`, the global density variable — 8px in Spacious, 4px in Condensed. Both come from
+ * the one token here, so the vertical rhythm and the indent cannot drift apart, and neither is a
+ * component property: density is inherited from `data-density`. See `docs/design-tokens.md`.
+ *
+ * Figma draws one supporting slot, below the control, that becomes the error when invalid. Code
+ * keeps hint and error as separate slots because both can be present at once, and renders them in
+ * that order underneath the control. See `field.md`.
  */
 .lutra-field {
-  --lutra-field-gap: var(--lutra-space-xs);
+  /* Density-owned. Declared on the field rather than inherited pre-resolved from `:root`, so a
+   * `[data-density]` region anywhere above it re-substitutes and takes effect. */
+  --lutra-field-gap: var(--lutra-field-spacing);
+  --lutra-field-support-indent: var(--lutra-field-spacing);
   --lutra-field-label-color: var(--lutra-color-text-primary);
   --lutra-field-label-size: var(--lutra-text-body-small);
   --lutra-field-label-line-height: var(--lutra-type-line-height-body-small);
@@ -3214,7 +3402,8 @@
 /* Normal inline flow rather than flex, so the indicator wraps inline with the label text the way
  * the annotation describes, and so the space between them is a real text space that the accessible
- * name includes. A flex `gap` would look right and read as "Email addressRequired". */
+ * name includes. A flex `gap` would look right and read as "Email address(required)". Figma builds
+ * the same result with a `Label Row` frame set to WRAP; the DOM gets it from text flow. */
 .lutra-field__label {
   display: block;
@@ -3241,9 +3430,20 @@
   color: var(--lutra-field-indicator-required-color);
 }
+/* Supporting text.
+ *
+ * The indent sets the supporting and error text in from the label and the control edge, which is
+ * what Figma draws. Figma expresses it as `paragraphIndent` because a Figma TEXT node has no
+ * padding; `padding-inline-start` is the runtime equivalent and is deliberately not `text-indent`,
+ * which would indent only the first line and leave a wrapped error message ragged against its own
+ * left edge. Logical property, so it flips with the writing mode.
+ *
+ * Nothing here sets a height or prevents wrapping — a long message grows the field. */
 .lutra-field__hint,
 .lutra-field__error {
   margin: 0;
+  padding-inline-start: var(--lutra-field-support-indent);
   font-size: var(--lutra-field-label-size);
   line-height: var(--lutra-field-label-line-height);
   font-weight: var(--lutra-field-hint-weight);

package/dist/tokens.json CHANGED Viewed

@@ -3,7 +3,7 @@
   "figma": {
     "fileKey": "3I29aswJJqsIwh8jO1uBje",
     "fileName": "Lutra UI",
-    "readAt": "2026-08-09 (dark danger ramp resynced after the contrast study)"
+    "readAt": "2026-09-02 (Lutra Density collection added; Spacious is the default mode)"
   },
   "tokens": {
     "--lutra-color-background-canvas": {
@@ -996,6 +996,20 @@
       "figmaName": "layout/section/sm",
       "value": "4rem",
       "themed": false
+    },
+    "--lutra-control-text-size": {
+      "figmaName": "control/text-size",
+      "spacious": "1rem",
+      "condensed": "0.875rem",
+      "themed": false,
+      "density": true
+    },
+    "--lutra-field-spacing": {
+      "figmaName": "field/spacing",
+      "spacious": "0.5rem",
+      "condensed": "0.25rem",
+      "themed": false,
+      "density": true
     }
   }
 }

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@lutra-ui-system/react",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Accessible React components and design tokens for Lutra UI",
   "license": "MIT",
   "repository": {
@@ -54,7 +54,8 @@
     "test:watch": "vitest",
     "lint": "eslint .",
     "storybook": "storybook dev --port 6006 --no-open",
-    "build-storybook": "storybook build"
+    "build-storybook": "storybook build",
+    "storybook:verify": "node ./scripts/verify-manager-bundle.mjs"
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",