@pienter/ui 0.2.0

package/components/form/date-input/DateInput.astro

@@ -0,0 +1,105 @@
+---
+import './date-input.css';
+import { generateId } from '../../../utils/a11y/id.js';
+
+interface Props {
+  id?: string;
+  label: string;
+  name?: string;
+  /**
+   * Native input type. `month` and `week` are intentionally out of
+   * scope for v1 because their browser support is uneven (notably
+   * Safari) — see CONVENTIONS DateInput audit entry.
+   */
+  type?: 'date' | 'time' | 'datetime-local';
+  /**
+   * Current ISO-formatted value. The exact shape depends on `type`:
+   *  - `date` → `YYYY-MM-DD`
+   *  - `time` → `HH:MM` (or `HH:MM:SS` when `step` enables seconds)
+   *  - `datetime-local` → `YYYY-MM-DDTHH:MM`
+   */
+  value?: string;
+  /** Lower bound, in the same ISO shape as `value`. Forwarded to native `min`. */
+  min?: string;
+  /** Upper bound, in the same ISO shape as `value`. Forwarded to native `max`. */
+  max?: string;
+  /**
+   * Native step granularity. Useful for `type="time"`:
+   * `step="60"` (default) gives minute precision; `step="1"`
+   * exposes seconds in the picker.
+   */
+  step?: number | string;
+  required?: boolean;
+  disabled?: boolean;
+  hint?: string;
+  errors?: string[];
+  status?: 'error' | 'success';
+}
+
+const {
+  id,
+  label,
+  name,
+  type = 'date',
+  value = '',
+  min,
+  max,
+  step,
+  required = false,
+  disabled = false,
+  hint,
+  errors = [],
+  status,
+  ...rest
+} = Astro.props;
+
+const inputId = id ?? generateId('input');
+const hintId = `${inputId}-hint`;
+const errorsId = `${inputId}-errors`;
+
+const hasErrors = errors.length > 0;
+const computedStatus = status ?? (hasErrors ? 'error' : undefined);
+
+const describedByIds: string[] = [];
+if (hint) describedByIds.push(hintId);
+if (hasErrors) describedByIds.push(errorsId);
+const describedBy =
+  describedByIds.length > 0 ? describedByIds.join(' ') : undefined;
+---
+
+<div class="pui-field" data-status={computedStatus}>
+  <label class="pui-field__label" for={inputId}>
+    {label}
+  </label>
+  <input
+    class="pui-input"
+    id={inputId}
+    type={type}
+    name={name}
+    value={value}
+    min={min}
+    max={max}
+    step={step}
+    required={required}
+    disabled={disabled}
+    aria-invalid={hasErrors ? 'true' : undefined}
+    aria-describedby={describedBy}
+    {...rest}
+  />
+  {
+    hint && (
+      <p id={hintId} class="pui-field__hint">
+        {hint}
+      </p>
+    )
+  }
+  {
+    hasErrors && (
+      <ul id={errorsId} class="pui-field__hint" role="alert">
+        {errors.map((error) => (
+          <li>{error}</li>
+        ))}
+      </ul>
+    )
+  }
+</div>

package/components/form/date-input/DateInput.vue

@@ -0,0 +1,121 @@
+<template>
+    <div class="pui-field" :data-status="computedStatus">
+        <label class="pui-field__label" :for="inputId">{{ label }}</label>
+        <input
+            v-bind="$attrs"
+            :id="inputId"
+            class="pui-input"
+            :type="type"
+            :name="name"
+            :value="modelValue"
+            :min="min"
+            :max="max"
+            :step="step"
+            :required="required"
+            :disabled="disabled"
+            :aria-invalid="hasErrors ? 'true' : undefined"
+            :aria-describedby="describedBy"
+            @input="
+                emit(
+                    'update:modelValue',
+                    ($event.target as HTMLInputElement).value,
+                )
+            "
+            @blur="emit('blur')"
+        />
+        <p v-if="hint" :id="hintId" class="pui-field__hint">{{ hint }}</p>
+        <ul
+            v-if="errors.length"
+            :id="errorsId"
+            class="pui-field__hint"
+            role="alert"
+        >
+            <li v-for="error in errors" :key="error">{{ error }}</li>
+        </ul>
+    </div>
+</template>
+
+<script setup lang="ts">
+import { computed } from 'vue';
+import { generateId } from '../../../utils/a11y/id.js';
+
+defineOptions({ inheritAttrs: false });
+
+const props = withDefaults(
+    defineProps<{
+        id?: string;
+        label: string;
+        /**
+         * Current ISO-formatted value. The exact shape depends on `type`:
+         *  - `date` → `YYYY-MM-DD`
+         *  - `time` → `HH:MM` (or `HH:MM:SS` when `step` enables seconds)
+         *  - `datetime-local` → `YYYY-MM-DDTHH:MM`
+         * An empty string represents an empty input.
+         */
+        modelValue: string;
+        name?: string;
+        /**
+         * Native input type. `month` and `week` are intentionally out of
+         * scope for v1 because their browser support is uneven (notably
+         * Safari) — see ./AUDIT.md.
+         */
+        type?: 'date' | 'time' | 'datetime-local';
+        /** Lower bound, in the same ISO shape as `modelValue`. Forwarded to native `min`. */
+        min?: string;
+        /** Upper bound, in the same ISO shape as `modelValue`. Forwarded to native `max`. */
+        max?: string;
+        /**
+         * Native step granularity. Useful for `type="time"`:
+         * `step="60"` (default) gives minute precision; `step="1"`
+         * exposes seconds in the picker.
+         */
+        step?: number | string;
+        required?: boolean;
+        disabled?: boolean;
+        hint?: string;
+        errors?: string[];
+        status?: 'error' | 'success';
+    }>(),
+    {
+        id: undefined,
+        name: undefined,
+        type: 'date',
+        min: undefined,
+        max: undefined,
+        step: undefined,
+        required: false,
+        disabled: false,
+        hint: undefined,
+        errors: () => [],
+        status: undefined,
+    },
+);
+
+const emit = defineEmits<{
+    'update:modelValue': [value: string];
+    blur: [];
+}>();
+
+const inputId = props.id ?? generateId('input');
+const hintId = `${inputId}-hint`;
+const errorsId = `${inputId}-errors`;
+
+const hasErrors = computed(() => props.errors.length > 0);
+
+const computedStatus = computed(() => {
+    if (props.status) return props.status;
+    if (hasErrors.value) return 'error';
+    return undefined;
+});
+
+const describedBy = computed(() => {
+    const ids: string[] = [];
+    if (props.hint) ids.push(hintId);
+    if (hasErrors.value) ids.push(errorsId);
+    return ids.length > 0 ? ids.join(' ') : undefined;
+});
+</script>
+
+<style>
+@import './date-input.css';
+</style>

package/components/form/date-input/date-input.css

@@ -0,0 +1,19 @@
+@layer components {
+    /* DateInput reuses the shared `.pui-input` rules (sizing, padding,
+   * border, focus ring, disabled, status-driven recolour) that live
+   * alongside `.pui-textarea` in `components/form/text-input/text-input.css`
+   * because the visual shell is identical to TextInput — only the
+   * native input `type` differs (`date` / `time` / `datetime-local`
+   * vs `text`). The browser owns the picker UI; we just style the
+   * input chrome consistently with the rest of the form-primitive
+   * scaffold.
+   *
+   * This file is intentionally a near-empty placeholder following the
+   * Textarea pattern — every form primitive keeps its own CSS file
+   * for layered consistency, even when there are no component-specific
+   * rules. When the fifth-plus form primitive ships and the shared
+   * `.pui-input` rules outgrow `text-input.css`, they'll move into a
+   * dedicated `form-field.css` per the deferred-extraction note in
+   * CONVENTIONS.
+   */
+}

package/components/form/form/Form.astro

@@ -0,0 +1,106 @@
+---
+import './form.css';
+import { generateId } from '../../../utils/a11y/id.js';
+
+interface Props {
+  /** Stable form ID — used by the consumer's `mountForm` script. */
+  id?: string;
+  submitLabel?: string;
+  busy?: boolean;
+  /** Top-level errors rendered in the error summary. */
+  errors?: string[];
+  /** Success/status message rendered in the polite live region. */
+  statusMessage?: string;
+}
+
+const {
+  id,
+  submitLabel = 'Submit',
+  busy = false,
+  errors = [],
+  statusMessage,
+} = Astro.props;
+
+const formId = id ?? generateId('form');
+---
+
+<form
+  class="pui-form"
+  id={formId}
+  data-pui-form
+  novalidate
+  aria-busy={busy ? 'true' : undefined}
+>
+  {
+    errors.length > 0 && (
+      <div class="pui-form__error-summary" role="alert" aria-live="assertive">
+        <p class="pui-form__error-summary-title">There was a problem</p>
+        <ul class="pui-form__error-summary-list">
+          {errors.map((error) => (
+            <li>{error}</li>
+          ))}
+        </ul>
+      </div>
+    )
+  }
+
+  <slot />
+
+  {
+    statusMessage && (
+      <div class="pui-form__status" aria-live="polite">
+        {statusMessage}
+      </div>
+    )
+  }
+
+  <div class="pui-form__actions">
+    <slot name="actions">
+      <button
+        class="pui-btn"
+        data-variant="primary"
+        type="submit"
+        disabled={busy}
+      >
+        {submitLabel}
+      </button>
+    </slot>
+  </div>
+</form>
+
+{
+  /*
+  Form.astro renders chrome only — it deliberately does NOT auto-mount
+  `mountForm`. The controller takes `validators` and an async `onSubmit`
+  handler, both of which are functions that can't be passed as Astro
+  props. Consumers wire the controller themselves from a `<script>`
+  block:
+
+      ---
+      import Form from '@pienter/ui/components/Form.astro';
+      import TextInput from '@pienter/ui/components/TextInput.astro';
+      ---
+      <Form id="signup" submitLabel="Create account">
+        <TextInput label="Email" name="email" type="email" />
+      </Form>
+      <script>
+        import { mountForm } from '@pienter/ui/utils/controllers/form.js';
+        import { isRequired, isEmail } from '@pienter/ui/utils/validation/rules.js';
+        const el = document.getElementById('signup');
+        if (el instanceof HTMLFormElement) {
+          mountForm(el, {
+            validators: { email: [isRequired(), isEmail()] },
+            onSubmit: async (data) => {
+              const res = await fetch('/api/signup', { method: 'POST', body: data });
+              if (res.ok) return { ok: true, statusMessage: 'Account created' };
+              const body = await res.json();
+              return { ok: false, fieldErrors: body.fieldErrors, errors: body.errors };
+            },
+          });
+        }
+      </script>
+
+  This explicit mount pattern is the locked Astro Form contract per the
+  Form audit entry in CONVENTIONS.md.
+*/
+}

package/components/form/form/Form.vue

@@ -0,0 +1,181 @@
+<template>
+    <form
+        ref="formRef"
+        class="pui-form"
+        novalidate
+        :aria-busy="busy ? 'true' : undefined"
+        @submit.prevent="handleSubmit"
+    >
+        <div
+            v-if="topErrors.length > 0"
+            class="pui-form__error-summary"
+            role="alert"
+            aria-live="assertive"
+        >
+            <p class="pui-form__error-summary-title">There was a problem</p>
+            <ul class="pui-form__error-summary-list">
+                <li v-for="error in topErrors" :key="error">{{ error }}</li>
+            </ul>
+        </div>
+
+        <slot />
+
+        <div v-if="statusMessage" class="pui-form__status" aria-live="polite">
+            {{ statusMessage }}
+        </div>
+
+        <div class="pui-form__actions">
+            <slot name="actions">
+                <button
+                    class="pui-btn"
+                    data-variant="primary"
+                    type="submit"
+                    :disabled="busy"
+                >
+                    {{ submitLabel }}
+                </button>
+            </slot>
+        </div>
+    </form>
+</template>
+
+<script setup lang="ts">
+import { computed, ref, watch } from 'vue';
+import { focusFirstInvalid } from '../../../utils/a11y/focus.js';
+import { announce } from '../../../utils/a11y/live-region.js';
+import { type Validator } from '../../../utils/validation/rules.js';
+import {
+    validateFormData,
+    normalizeFieldErrors,
+} from '../../../utils/validation/form.js';
+
+const props = withDefaults(
+    defineProps<{
+        submitLabel?: string;
+        busy?: boolean;
+        /** Top-level errors not tied to a specific field. */
+        errors?: string[];
+        /** Server-side per-field errors. Consumers SHALL replace the object reference rather than mutate in place. */
+        fieldErrors?: Record<string, string | string[]>;
+        /** Success/status message; announced via `announce()` when set or changed. */
+        statusMessage?: string;
+        /** Per-field client-side validators run on submit. */
+        validators?: Record<string, Validator[]>;
+    }>(),
+    {
+        submitLabel: 'Submit',
+        busy: false,
+        errors: () => [],
+        fieldErrors: () => ({}),
+        statusMessage: undefined,
+        validators: () => ({}),
+    },
+);
+
+const emit = defineEmits<{
+    /** Fired AFTER client validation passes; consumer handles the async submit. */
+    submit: [data: FormData];
+    /** Fired when client validation fails; useful for telemetry / logging. */
+    'validation-error': [errors: Record<string, string[]>];
+}>();
+
+const formRef = ref<HTMLFormElement | null>(null);
+
+// Internal client-validation errors. Merged with server-supplied
+// `fieldErrors` for display via the form-primitive children's own
+// `errors` prop pattern (consumer wires them up by name); the summary
+// above renders only top-level errors.
+const clientFieldErrors = ref<Record<string, string[]>>({});
+
+// Combined top-level errors: consumer-supplied + a synthesized count
+// summary when client validation fails. Keep simple for v1: just
+// surface consumer-supplied; the announcement carries the count.
+const topErrors = computed<string[]>(() => props.errors ?? []);
+
+// Combined field errors (server + client) — exposed via provide for any
+// future field-aware children, though the current TextInput pattern is
+// for consumers to wire `:errors` themselves. Kept here for the
+// announce + focus-first-invalid logic.
+const allFieldErrors = computed<Record<string, string[]>>(() => {
+    const server = normalizeFieldErrors(props.fieldErrors);
+    // Server errors win when both exist for the same field.
+    return { ...clientFieldErrors.value, ...server };
+});
+
+function handleSubmit(): void {
+    const formEl = formRef.value;
+    if (!formEl) return;
+
+    const formData = new FormData(formEl);
+
+    // Run client-side validators.
+    const errors = validateFormData(formData, props.validators);
+    clientFieldErrors.value = errors;
+
+    const errorCount = Object.keys(errors).length;
+    if (errorCount > 0) {
+        emit('validation-error', errors);
+        // Wait a tick for the consumer to reflect errors back into the
+        // child form-primitives' `:errors` prop (which sets aria-invalid),
+        // then move focus + announce.
+        requestAnimationFrame(() => {
+            focusFirstInvalid(formEl);
+            const message =
+                errorCount === 1
+                    ? '1 error found. Please review the form.'
+                    : `${errorCount} errors found. Please review the form.`;
+            announce(message, 'assertive');
+        });
+        return;
+    }
+
+    // Validation passed. Clear any lingering client-side errors from a
+    // prior failed submit so child form-primitives don't keep displaying
+    // them while the consumer's async submit runs (mirrors the Astro
+    // controller's `clearAllErrors(el)` between client-pass and onSubmit).
+    clientFieldErrors.value = {};
+
+    // Surface FormData to the consumer's submit handler; consumer manages
+    // the busy/response lifecycle via the `busy`, `errors`, `fieldErrors`,
+    // and `statusMessage` props.
+    emit('submit', formData);
+}
+
+// Announce the success / status message whenever it changes. Server
+// errors arriving via `fieldErrors` should also focus the first
+// invalid + announce, mirroring the controller behavior.
+watch(
+    () => props.statusMessage,
+    (msg) => {
+        if (msg) announce(msg, 'polite');
+    },
+);
+
+watch(
+    () => props.fieldErrors,
+    (newServerErrors) => {
+        const normalized = normalizeFieldErrors(newServerErrors);
+        const count = Object.keys(normalized).length;
+        if (count === 0) return;
+        requestAnimationFrame(() => {
+            const formEl = formRef.value;
+            if (!formEl) return;
+            focusFirstInvalid(formEl);
+            const message =
+                count === 1
+                    ? '1 error found. Please review the form.'
+                    : `${count} errors found. Please review the form.`;
+            announce(message, 'assertive');
+        });
+    },
+);
+
+defineExpose({
+    /** Field error map (client + server) — read-only view for consumers. */
+    fieldErrors: allFieldErrors,
+});
+</script>
+
+<style>
+@import './form.css';
+</style>

package/components/form/form/form.css

@@ -0,0 +1,46 @@
+@layer components {
+    .pui-form {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-m);
+    }
+
+    .pui-form__error-summary {
+        background: var(--bg-clr-danger-soft);
+        border: var(--stroke-sm) solid var(--border-clr-danger);
+        border-radius: var(--radius-sm);
+        padding: var(--space-s) var(--space-m);
+    }
+
+    .pui-form__error-summary-title {
+        font-weight: var(--fw-semibold);
+        color: var(--text-clr-danger);
+        margin-bottom: var(--space-xs);
+    }
+
+    .pui-form__error-summary-list {
+        list-style: disc inside;
+        padding: 0;
+        margin: 0;
+        color: var(--text-clr-danger);
+        font-size: var(--step--1);
+    }
+
+    .pui-form__error-summary-list li {
+        margin-block: var(--space-2xs);
+    }
+
+    .pui-form__status {
+        padding: var(--space-s) var(--space-m);
+        border-radius: var(--radius-sm);
+        background: var(--bg-clr-success-soft);
+        color: var(--text-clr-success);
+        font-weight: var(--fw-semibold);
+    }
+
+    .pui-form__actions {
+        display: flex;
+        gap: var(--space-s);
+        align-items: center;
+    }
+}