ui-inputs: align nullable contract with emmie — widen TextInput, drop Date/Textarea coercion

Recon of emmie (our highest-compliance Laravel territory, which runs the same
TextInput/NumberInput component pair) settled the null-vs-empty-string contract:
nullable columns serialize to literal null, FE types string|null, the component
binds null directly (no ?? '' inside), and a cleared input emits '' — the
ConvertEmptyStringsToNull middleware (Kernel.php:58) maps it back to null on submit.

Adopt that convention wholesale:
- TextInput: widen defineModel<string> -> <string|null> so a null backend field
  binds directly, killing the call-site ?? '' friction (breaking type-widen,
  absorbed here; only BIO consumes it, fixed at its 0.3.0 adoption bump).
- DateInput / Textarea: drop the empty->null coercion I'd added; emit the raw
  native '' like TextInput. Thinner, matches the fleet.
- NumberInput: keep the NaN->null guard — a number model cannot hold '' honestly,
  so null is the type-honest empty and round-trips without relying on middleware.

100% component coverage retained; README gains a Nullable values section;
CLAUDE.md row + package description updated.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01JUvgVSQr81z4BqP5KcrJE6

Author: Goosterhof

CLAUDE.md

@@ -62,7 +62,7 @@ Consumer territories must apply per-call timeouts at instantiation OR rely on th
 | fs-form                 | Yes | One-call `useForm`: double-submit guard + `submitting` loading flag + 422 validation-error binding (guarded fs-http middleware); `keyMapper` seam for raw/camel field keys. `useValidationErrors`/`useFormSubmit` primitives still exported |
 | fs-translation          | Yes | Type-safe reactive i18n with dot-notation keys                                                                   |
 | fs-router               | Yes | Type-safe router service factory with CRUD navigation, middleware pipeline, and custom components for Vue Router |
-| ui-inputs               | Yes | Headless, themeable form inputs (`FormField`/`FormLabel`/`FormError`/`TextInput`/`NumberInput`/`DateInput`/`Textarea`/`SingleSelect`) styled purely through `--ui-*` CSS vars; error-as-prop, `aria-*` a11y wiring. The nullable atoms (Number/Date/Textarea) own their empty-value→`null` coercion once. First `ui-*`-family package (ADR-0043); SFC + coverage-only gate (Stryker mutates `.ts`, so the mutation gate is a no-op for this package) |
+| ui-inputs               | Yes | Headless, themeable form inputs (`FormField`/`FormLabel`/`FormError`/`TextInput`/`NumberInput`/`DateInput`/`Textarea`/`SingleSelect`) styled purely through `--ui-*` CSS vars; error-as-prop, `aria-*` a11y wiring. All inputs model a nullable value (`string \| null` / `number \| null`) so a null backend column binds directly; string inputs emit `''` on clear (fleet `ConvertEmptyStringsToNull` maps it back), `NumberInput` emits `null` (the honest-number exception). Matches emmie's live convention. First `ui-*`-family package (ADR-0043); SFC + coverage-only gate (Stryker mutates `.ts`, so the mutation gate is a no-op for this package) |
 
 ## Conventions
 

packages/ui-inputs/README.md

@@ -23,9 +23,9 @@ import '@script-development/ui-inputs/style.css';
 | `FormField`               | Label + error + required-marker composition wrapper (error-as-prop)                |
 | `FormLabel` / `FormError` | The atoms `FormField` composes                                                     |
 | `TextInput`               | Native `text` / `email` / `password` / `search` / `tel` / `url` input              |
-| `NumberInput`             | Native `number` input; nullable model, owns the `NaN`→`null` empty-value coercion  |
-| `DateInput`               | Native `date` input; nullable model, coerces a cleared date to `null`              |
-| `Textarea`                | Native `textarea`; nullable model, coerces a cleared value to `null`               |
+| `NumberInput`             | Native `number` input; owns the `NaN`→`null` empty-value guard                     |
+| `DateInput`               | Native `date` input                                                                |
+| `Textarea`                | Native `textarea` with `rows`                                                      |
 | `SingleSelect`            | Accessible listbox/combobox over `@floating-ui/vue`, generic over your option type |
 
 ```vue
@@ -38,6 +38,10 @@ import '@script-development/ui-inputs/style.css';
 
 Every visual rule keys on a `--ui-*` custom property — colours **and** structure (`--ui-control-border-width`, `--ui-control-radius`, `--ui-control-shadow`, `--ui-label-transform`, …). Remap them under any selector to theme the whole set; the shipped defaults render out of the box. Dark/light is orthogonal — pair with `@script-development/fs-theme`'s `data-theme` switching.
 
+## Nullable values
+
+Every text-like input (`TextInput`, `DateInput`, `Textarea`) models `string | null`, and `NumberInput` models `number | null`. A `null` from a nullable backend column binds directly — the control renders empty, no `?? ''` at the call site. When the user clears the field, the string inputs emit `''` (the raw native value); a Laravel backend's `ConvertEmptyStringsToNull` middleware maps that back to `null` on submit. `NumberInput` is the one exception: an empty number input emits `null` (not `NaN`, not `''`), since a `number` model can never hold `''` honestly — so it round-trips to `null` without relying on the middleware.
+
 ## Errors are a prop, never a service
 
 The components never import an error service. Resolve the message in your app and pass `error` (to `FormField`) or `invalid` + `describedby` (to the inputs). That keeps the package agnostic to how your territory produces validation errors.

packages/ui-inputs/src/components/DateInput.vue

@@ -11,7 +11,7 @@
         :aria-required="required || undefined"
         :aria-invalid="invalid || undefined"
         :aria-describedby="describedby"
-        @input="onInput"
+        @input="model = ($event.target as HTMLInputElement).value"
     />
 </template>
 
@@ -30,12 +30,8 @@ defineProps<{
     describedby?: string;
 }>();
 
+// Accepts null so it binds a nullable date column directly (Vue renders null as an
+// empty control); a cleared date emits '', which the fleet's
+// ConvertEmptyStringsToNull middleware converts back to null on submit.
 const model = defineModel<string | null>({required: true});
-
-// Coerce a cleared date to null (not the empty string), so a nullable date column
-// receives null rather than "" — the latter fails backend date validation.
-function onInput(event: Event) {
-    const {value} = event.target as HTMLInputElement;
-    model.value = value === '' ? null : value;
-}
 </script>

packages/ui-inputs/src/components/TextInput.vue

@@ -28,5 +28,8 @@ const {type = 'text'} = defineProps<{
     describedby?: string;
 }>();
 
-const model = defineModel<string>({required: true});
+// Accepts null so it binds a nullable backend field directly (Vue renders null as
+// an empty control); a cleared input emits '', which the fleet's
+// ConvertEmptyStringsToNull middleware converts back to null on submit.
+const model = defineModel<string | null>({required: true});
 </script>

packages/ui-inputs/src/components/Textarea.vue

@@ -3,14 +3,14 @@
         :id="id"
         class="ui-control ui-textarea"
         :class="{'is-invalid': invalid}"
-        :value="model ?? ''"
+        :value="model"
         :placeholder="placeholder"
         :disabled="disabled"
         :rows="rows"
         :aria-required="required || undefined"
         :aria-invalid="invalid || undefined"
         :aria-describedby="describedby"
-        @input="onInput"
+        @input="model = ($event.target as HTMLTextAreaElement).value"
     />
 </template>
 
@@ -28,12 +28,8 @@ defineProps<{
     describedby?: string;
 }>();
 
+// Accepts null so it binds a nullable text column directly (Vue renders null as an
+// empty control); a cleared textarea emits '', which the fleet's
+// ConvertEmptyStringsToNull middleware converts back to null on submit.
 const model = defineModel<string | null>({required: true});
-
-// Coerce a cleared textarea to null (not the empty string), mirroring DateInput,
-// so a nullable text column receives null rather than "".
-function onInput(event: Event) {
-    const {value} = event.target as HTMLTextAreaElement;
-    model.value = value === '' ? null : value;
-}
 </script>

packages/ui-inputs/tests/DateInput.spec.ts

@@ -50,10 +50,10 @@ describe('DateInput', () => {
         expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['2026-03-01']);
     });
 
-    it('emits null when the date is cleared', async () => {
+    it("emits '' when the date is cleared (raw native value; middleware maps to null)", async () => {
         const wrapper = mount(DateInput, {props: {id: 'dob', modelValue: '2026-07-17'}});
         await wrapper.find('input').setValue('');
-        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual([null]);
+        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['']);
     });
 
     it('renders the disabled attribute when disabled', () => {

packages/ui-inputs/tests/TextInput.spec.ts

@@ -46,4 +46,9 @@ describe('TextInput', () => {
         const wrapper = mount(TextInput, {props: {id: 'd', disabled: true, modelValue: ''}});
         expect(wrapper.find('input').attributes('disabled')).toBeDefined();
     });
+
+    it('renders empty for a null model (binds a nullable backend field directly)', () => {
+        const wrapper = mount(TextInput, {props: {id: 'name', modelValue: null}});
+        expect((wrapper.find('input').element as HTMLInputElement).value).toBe('');
+    });
 });

packages/ui-inputs/tests/Textarea.spec.ts

@@ -50,10 +50,10 @@ describe('Textarea', () => {
         expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['a note']);
     });
 
-    it('emits null when the textarea is cleared', async () => {
+    it("emits '' when the textarea is cleared (raw native value; middleware maps to null)", async () => {
         const wrapper = mount(Textarea, {props: {id: 'notes', modelValue: 'hi'}});
         await wrapper.find('textarea').setValue('');
-        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual([null]);
+        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['']);
     });
 
     it('renders the disabled attribute when disabled', () => {