Merge pull request #162 from script-development/war-room/wr0460-ui-inputs-0.3.0-atoms

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

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. 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,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; 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
@@ -35,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/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,37 @@
+<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="model = ($event.target as HTMLInputElement).value"
+    />
+</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;
+}>();
+
+// 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});
+</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/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

@@ -0,0 +1,35 @@
+<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="model = ($event.target as HTMLTextAreaElement).value"
+    />
+</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;
+}>();
+
+// 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});
+</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 '' 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(['']);
+    });
+
+    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();
+    });
+});