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

@lutra-ui-system/react 0.1.2 → 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 +7 -5

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