ui-inputs: 0.3.0 — Number/Date/Textarea atoms + control-bg state vars (WR-0460)

Add three nullable-model atoms mirroring TextInput's headless/error-as-prop
shape, each owning its empty-value coercion once so consumers stop reinventing
per-field handlers (the WR-0431 BIO pilot finding):

- NumberInput (number | null): owns the valueAsNumber NaN -> null guard; min/max/step
- DateInput (string | null): <input type="date">; clears to null; min/max
- Textarea (string | null): rows; clears to null

Add --ui-control-bg-focus / --ui-control-bg-invalid theme vars (default to
--ui-control-bg, so no-op until a territory opts in) — the --ui-* contract had
no background-on-state hook, which brick's focus/invalid fills rode as class
overrides in the BIO pilot.

100% component-test coverage (branches included) per the SFC recipe; barrel +
README + CLAUDE.md packages row updated; package description --fs-* -> --ui-*.

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`/`SingleSelect`) styled purely through `--ui-*` CSS vars; error-as-prop, `aria-*` a11y wiring. 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. 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) |
 
 ## Conventions
 

packages/ui-inputs/README.md

@@ -23,6 +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`               |
 | `SingleSelect`            | Accessible listbox/combobox over `@floating-ui/vue`, generic over your option type |
 
 ```vue

packages/ui-inputs/package.json

@@ -1,7 +1,7 @@
 {
     "name": "@script-development/ui-inputs",
-    "version": "0.2.0",
-    "description": "Headless, themeable Vue 3 form input components (field, label, error, text input, select) styled entirely through --fs-* CSS custom properties.",
+    "version": "0.3.0",
+    "description": "Headless, themeable Vue 3 form input components (field, label, error, text/number/date input, textarea, select) styled entirely through --ui-* CSS custom properties.",
     "homepage": "https://packages.script.nl/packages/ui-inputs",
     "license": "MIT",
     "repository": {

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

@@ -0,0 +1,41 @@
+<template>
+    <input
+        :id="id"
+        type="date"
+        class="ui-control ui-input"
+        :class="{'is-invalid': invalid}"
+        :value="model"
+        :disabled="disabled"
+        :min="min"
+        :max="max"
+        :aria-required="required || undefined"
+        :aria-invalid="invalid || undefined"
+        :aria-describedby="describedby"
+        @input="onInput"
+    />
+</template>
+
+<script setup lang="ts">
+defineProps<{
+    id: string;
+    disabled?: boolean;
+    /** ISO date bound (`YYYY-MM-DD`) for the native picker. */
+    min?: string;
+    max?: string;
+    /** conveys the required state to assistive tech via `aria-required`. */
+    required?: boolean;
+    /** invalid styling + aria; drive it from the field's error. */
+    invalid?: boolean;
+    /** id of the paired error element for `aria-describedby`. */
+    describedby?: string;
+}>();
+
+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/NumberInput.vue

@@ -0,0 +1,45 @@
+<template>
+    <input
+        :id="id"
+        type="number"
+        class="ui-control ui-input"
+        :class="{'is-invalid': invalid}"
+        :value="model"
+        :placeholder="placeholder"
+        :disabled="disabled"
+        :min="min"
+        :max="max"
+        :step="step"
+        :aria-required="required || undefined"
+        :aria-invalid="invalid || undefined"
+        :aria-describedby="describedby"
+        @input="onInput"
+    />
+</template>
+
+<script setup lang="ts">
+defineProps<{
+    id: string;
+    placeholder?: string;
+    disabled?: boolean;
+    min?: number;
+    max?: number;
+    step?: number;
+    /** conveys the required state to assistive tech via `aria-required`. */
+    required?: boolean;
+    /** invalid styling + aria; drive it from the field's error. */
+    invalid?: boolean;
+    /** id of the paired error element for `aria-describedby`. */
+    describedby?: string;
+}>();
+
+const model = defineModel<number | null>({required: true});
+
+// Own the empty-input coercion ONCE, so no consumer reinvents it: a native number
+// input yields NaN for an empty or unparseable value — map that to null so the
+// model is always a real number or an explicit "no value", never NaN.
+function onInput(event: Event) {
+    const {valueAsNumber} = event.target as HTMLInputElement;
+    model.value = Number.isNaN(valueAsNumber) ? null : valueAsNumber;
+}
+</script>

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

@@ -0,0 +1,39 @@
+<template>
+    <textarea
+        :id="id"
+        class="ui-control ui-textarea"
+        :class="{'is-invalid': invalid}"
+        :value="model ?? ''"
+        :placeholder="placeholder"
+        :disabled="disabled"
+        :rows="rows"
+        :aria-required="required || undefined"
+        :aria-invalid="invalid || undefined"
+        :aria-describedby="describedby"
+        @input="onInput"
+    />
+</template>
+
+<script setup lang="ts">
+defineProps<{
+    id: string;
+    placeholder?: string;
+    disabled?: boolean;
+    rows?: number;
+    /** conveys the required state to assistive tech via `aria-required`. */
+    required?: boolean;
+    /** invalid styling + aria; drive it from the field's error. */
+    invalid?: boolean;
+    /** id of the paired error element for `aria-describedby`. */
+    describedby?: string;
+}>();
+
+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/src/index.ts

@@ -2,6 +2,9 @@ export {default as FormField} from './components/FormField.vue';
 export {default as FormLabel} from './components/FormLabel.vue';
 export {default as FormError} from './components/FormError.vue';
 export {default as TextInput} from './components/TextInput.vue';
+export {default as NumberInput} from './components/NumberInput.vue';
+export {default as DateInput} from './components/DateInput.vue';
+export {default as Textarea} from './components/Textarea.vue';
 export {default as SingleSelect} from './components/SingleSelect.vue';
 
 export type {SelectItem, LabelKey} from './types';

packages/ui-inputs/styles.css

@@ -22,6 +22,10 @@
 
     /* control (input + select trigger) */
     --ui-control-bg: #ffffff;
+    /* background-on-state hooks — default to the resting background so they are a
+       no-op until a territory opts in (brick fills the control on focus/invalid). */
+    --ui-control-bg-focus: var(--ui-control-bg);
+    --ui-control-bg-invalid: var(--ui-control-bg);
     --ui-control-bg-disabled: #f3f4f6;
     --ui-control-text: #111827;
     --ui-control-text-muted: #6b7280;
@@ -97,16 +101,22 @@
 }
 .ui-control:focus-visible {
     outline: none;
+    background: var(--ui-control-bg-focus);
     box-shadow: var(--ui-focus-ring);
 }
 .ui-control.is-open {
     border-color: var(--ui-control-border-open);
     box-shadow: var(--ui-focus-ring);
 }
 .ui-control.is-invalid {
+    background: var(--ui-control-bg-invalid);
     border-color: var(--ui-danger-border);
     box-shadow: var(--ui-danger-shadow);
 }
+
+.ui-textarea {
+    resize: vertical;
+}
 .ui-control:disabled {
     background: var(--ui-control-bg-disabled);
     color: var(--ui-control-text-muted);

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

@@ -0,0 +1,63 @@
+// @vitest-environment happy-dom
+import {mount} from '@vue/test-utils';
+import {describe, expect, it} from 'vitest';
+
+import DateInput from '../src/components/DateInput.vue';
+
+describe('DateInput', () => {
+    it('renders a date input reflecting the model and valid state', () => {
+        const wrapper = mount(DateInput, {props: {id: 'dob', modelValue: '2026-07-17'}});
+        const input = wrapper.find('input');
+
+        expect(input.attributes('type')).toBe('date');
+        expect((input.element as HTMLInputElement).value).toBe('2026-07-17');
+        expect(input.classes()).toContain('ui-control');
+        expect(input.classes()).not.toContain('is-invalid');
+        expect(input.attributes('aria-invalid')).toBeUndefined();
+        expect(input.attributes('aria-required')).toBeUndefined();
+    });
+
+    it('renders empty for a null model', () => {
+        const wrapper = mount(DateInput, {props: {id: 'dob', modelValue: null}});
+        expect((wrapper.find('input').element as HTMLInputElement).value).toBe('');
+    });
+
+    it('honours min/max/required/invalid/describedby', () => {
+        const wrapper = mount(DateInput, {
+            props: {
+                id: 'dob',
+                modelValue: '2026-07-17',
+                min: '2026-01-01',
+                max: '2026-12-31',
+                required: true,
+                invalid: true,
+                describedby: 'dob-error',
+            },
+        });
+        const input = wrapper.find('input');
+
+        expect(input.attributes('min')).toBe('2026-01-01');
+        expect(input.attributes('max')).toBe('2026-12-31');
+        expect(input.classes()).toContain('is-invalid');
+        expect(input.attributes('aria-invalid')).toBe('true');
+        expect(input.attributes('aria-required')).toBe('true');
+        expect(input.attributes('aria-describedby')).toBe('dob-error');
+    });
+
+    it('emits the date string on input', async () => {
+        const wrapper = mount(DateInput, {props: {id: 'dob', modelValue: null}});
+        await wrapper.find('input').setValue('2026-03-01');
+        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual(['2026-03-01']);
+    });
+
+    it('emits null when the date is cleared', 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]);
+    });
+
+    it('renders the disabled attribute when disabled', () => {
+        const wrapper = mount(DateInput, {props: {id: 'dob', disabled: true, modelValue: null}});
+        expect(wrapper.find('input').attributes('disabled')).toBeDefined();
+    });
+});

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

@@ -0,0 +1,67 @@
+// @vitest-environment happy-dom
+import {mount} from '@vue/test-utils';
+import {describe, expect, it} from 'vitest';
+
+import NumberInput from '../src/components/NumberInput.vue';
+
+describe('NumberInput', () => {
+    it('renders a number input reflecting the model and valid state', () => {
+        const wrapper = mount(NumberInput, {props: {id: 'qty', modelValue: 5}});
+        const input = wrapper.find('input');
+
+        expect(input.attributes('type')).toBe('number');
+        expect((input.element as HTMLInputElement).value).toBe('5');
+        expect(input.classes()).toContain('ui-control');
+        expect(input.classes()).not.toContain('is-invalid');
+        expect(input.attributes('aria-invalid')).toBeUndefined();
+        expect(input.attributes('aria-required')).toBeUndefined();
+    });
+
+    it('renders empty for a null model', () => {
+        const wrapper = mount(NumberInput, {props: {id: 'qty', modelValue: null}});
+        expect((wrapper.find('input').element as HTMLInputElement).value).toBe('');
+    });
+
+    it('honours placeholder/min/max/step/required/invalid/describedby', () => {
+        const wrapper = mount(NumberInput, {
+            props: {
+                id: 'qty',
+                modelValue: 3,
+                placeholder: 'How many',
+                min: 0,
+                max: 10,
+                step: 2,
+                required: true,
+                invalid: true,
+                describedby: 'qty-error',
+            },
+        });
+        const input = wrapper.find('input');
+
+        expect(input.attributes('placeholder')).toBe('How many');
+        expect(input.attributes('min')).toBe('0');
+        expect(input.attributes('max')).toBe('10');
+        expect(input.attributes('step')).toBe('2');
+        expect(input.classes()).toContain('is-invalid');
+        expect(input.attributes('aria-invalid')).toBe('true');
+        expect(input.attributes('aria-required')).toBe('true');
+        expect(input.attributes('aria-describedby')).toBe('qty-error');
+    });
+
+    it('emits the parsed number on input', async () => {
+        const wrapper = mount(NumberInput, {props: {id: 'qty', modelValue: null}});
+        await wrapper.find('input').setValue('42');
+        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual([42]);
+    });
+
+    it('emits null when the input is cleared (NaN guard, owned once)', async () => {
+        const wrapper = mount(NumberInput, {props: {id: 'qty', modelValue: 7}});
+        await wrapper.find('input').setValue('');
+        expect(wrapper.emitted('update:modelValue')?.[0]).toEqual([null]);
+    });
+
+    it('renders the disabled attribute when disabled', () => {
+        const wrapper = mount(NumberInput, {props: {id: 'qty', disabled: true, modelValue: null}});
+        expect(wrapper.find('input').attributes('disabled')).toBeDefined();
+    });
+});