@poppy-ui/vue 0.0.0-dev.36.93ba5b2

package/src/components/data/form/Form.story.vue

@@ -0,0 +1,144 @@
+<script lang="ts">
+import Button from '@/components/actions/button/Button.vue'
+import Alert from '@/components/feedback/alert/Alert.vue'
+import { reactive, ref, shallowRef, useTemplateRef } from 'vue'
+import { createI18n } from 'vue-i18n'
+import Form from './Form.vue'
+import type { FormProps } from './form.props'
+import type { FormSerializer } from './form.types'
+</script>
+
+<script setup lang="ts">
+const model = ref<Record<string, unknown>>({
+  email: '',
+  name: '',
+  age: '',
+  bio: '',
+  agree: false,
+})
+
+const state = reactive<Omit<FormProps, 'serializer'>>({
+  counter: false,
+  counterFormat: '{current} / {max}',
+})
+
+const serverErrorModel = ref<Record<string, unknown>>({ email: '', password: '' })
+
+const serializedOutput = shallowRef<string>('')
+
+const serializer: FormSerializer = (data) => ({
+  ...data,
+  age: Number(data.age),
+  submittedAt: new Date().toISOString(),
+})
+
+function onSubmit(data: Record<string, unknown>) {
+  serializedOutput.value = JSON.stringify(data, null, 2)
+}
+
+const formErrorEl = useTemplateRef('form-error')
+function onFormErrorSubmit() {
+  formErrorEl.value?.setFieldError('$', 'Global Error')
+}
+</script>
+
+<template>
+  <Story group="components" title="Data/Form" auto-props-disabled :setup-app="({ app }) => {
+    app.use(createI18n({}))
+  }">
+    <!-- ── Default / playground ─────────────────────────────────────────── -->
+    <Variant title="Default" id="default">
+      <template #controls>
+        <HstCheckbox v-model="(state.counter as boolean)" title="counter" />
+        <HstText v-model="(state.counterFormat as string)" title="counterFormat" />
+      </template>
+
+      <Form v-model="model" v-bind="state" @submit="onSubmit">
+        <pre v-if="serializedOutput" class="text-xs bg-base-200 p-2 rounded mb-4">{{ serializedOutput }}</pre>
+        <Button type="submit" class="btn btn-primary w-full mt-4">Submit</Button>
+        <Button type="reset" class="btn btn-ghost w-full mt-2">Reset</Button>
+      </Form>
+    </Variant>
+
+    <!-- ── With serializer ──────────────────────────────────────────────── -->
+    <Variant title="With Serializer" id="serializer">
+      <Form
+        v-model="model"
+        :serializer="serializer"
+        @submit="onSubmit"
+      >
+        <pre v-if="serializedOutput" class="text-xs bg-base-200 p-2 rounded mb-4">{{ serializedOutput }}</pre>
+        <Button type="submit" class="btn btn-primary mt-4">Submit (age coerced to number)</Button>
+      </Form>
+    </Variant>
+
+    <!-- ── Global form error ─────────────────────────────────────────────── -->
+    <Variant title="Global Error" id="global-error">
+      <div id="top-error"></div>
+
+      <Form ref="form-error" v-model="serverErrorModel" @submit="onFormErrorSubmit">
+        <template #error="{ error }">
+          <Teleport to="#top-error">
+            <Alert color="error" class="mt-2">
+              <span>{{ error }}</span>
+            </Alert>
+          </Teleport>
+        </template>
+        <Button type="submit" class="btn btn-primary mt-4">Submit</Button>
+      </Form>
+    </Variant>
+  </Story>
+</template>
+
+<docs lang="md">
+# Form
+
+## Description
+
+The `Form` component is the root of the form system.
+It provides a `FormContext` to all descendant `FormField` and input components via Vue's `provide/inject`.
+It owns the form data object, the errors record, and all field state.
+It handles programmatic validation, serialization, and emits `submit` / `reset` events.
+
+`novalidate` is always set on the `<form />` element to suppress native browser popups. Validation is handled programmatically via the HTML5 Constraint Validation API.
+
+## API
+
+### v-model
+
+| Name         | Type                         | Modifiers | Description                      |
+|--------------|------------------------------|-----------|----------------------------------|
+| `modelValue` | `{ [key: string]: unknown }` | -         | The form data object (required). |
+
+### Props
+
+| Prop            | Type                 | Default               | Configurable | Description                                     |
+|-----------------|----------------------|-----------------------|--------------|-------------------------------------------------|
+| `counter`       | `boolean`            | `false`               | :x:          | Propagates counter display to all child inputs. |
+| `counterFormat` | `string \| Function` | `'{current} / {max}'` | :x:          | Default counter format for all child inputs.    |
+| `serializer`    | `FormSerializer`     | `undefined`           | :x:          | Transforms data before the `submit` event.      |
+
+### Events
+
+| Event    | Payload                      | Description                                          |
+|----------|------------------------------|------------------------------------------------------|
+| `submit` | `{ [key: string]: unknown }` | Fired after successful validation and serialization. |
+| `reset`  | `undefined`                  | Fired when the form is reset.                        |
+
+### Slots
+
+| Slot      | Bindings                         | Description                                                |
+|-----------|----------------------------------|------------------------------------------------------------|
+| `default` | -                                | Form content undefined FormField components, buttons, etc. |
+| `error`   | `{ error: string \| undefined }` | Global error rendering.                                    |
+
+## Usage
+```vue
+<Form v-model="formData" :serializer="mySerializer" @submit="onSubmit">
+  <FormField name="email" label="Email">
+    <Input type="email" required />
+  </FormField>
+  <button type="submit" class="btn btn-primary">Submit</button>
+</Form>
+```
+</docs>

package/src/components/data/form/Form.vue

@@ -0,0 +1,235 @@
+<script lang="ts">
+import type { CounterFn } from '@/types/utils.type'
+import { getByPath, setByPath } from '@/utils/path'
+import { provide, shallowReactive, shallowRef, watch } from 'vue'
+import type { FormContext } from './form.context'
+import { FORM_CONTEXT_KEY } from './form.context'
+import type { FormProps } from './form.props'
+import type { FieldState } from './form.types'
+</script>
+
+<script setup lang="ts">
+const props = defineProps<FormProps>()
+
+/**
+ * The form data object. All field values are stored under their name/path key.
+ * Supports nested paths and arrays via dot-notation.
+ */
+const model = defineModel<Record<string, unknown>>({ required: true })
+
+const emit = defineEmits<{
+  /**
+   * Fired on form submit after serialization.
+   * The payload is the raw data (or serialized data if `serializer` is set).
+   */
+  submit: [data: Record<string, unknown>]
+  /** Fired on form reset. Data is restored to the initial model value. */
+  reset: []
+}>()
+
+// Internal state
+
+const initialData: Record<string, unknown> = JSON.parse(JSON.stringify(model.value ?? {}))
+
+// Shallow reactive copy — mutations here don't affect the model until emitted
+const data = shallowReactive<Record<string, unknown>>({ ...model.value })
+
+const errors = shallowRef<Record<string, string | undefined>>({})
+
+const fieldStates = shallowReactive<Record<string, FieldState>>({})
+
+// Keep data in sync when the model is updated externally
+watch(model, val => Object.assign(data, val))
+
+// Counter — stored as raw boolean | undefined.
+// undefined = "no opinion": mergeProps in useComponentConfig skips it,
+// letting pluginConfig / defaults take over.
+// false = explicitly disabled: mergeProps propagates it, overriding any lower-priority true.
+
+const counter = shallowRef<boolean | undefined>(
+  props.counter !== undefined ? props.counter : undefined,
+)
+const counterFormat = shallowRef<string | CounterFn | undefined>(props.counterFormat)
+
+watch(() => props.counter, val => {
+  counter.value = val !== undefined ? val : undefined
+})
+watch(() => props.counterFormat, (val) => { counterFormat.value = val })
+
+// Field state helpers
+
+function ensureFieldState(path: string): FieldState {
+  if (!fieldStates[path]) {
+    fieldStates[path] = {
+      value: getByPath(data, path),
+      isDirty: false,
+      isTouched: false,
+      isValid: true,
+      hasError: false,
+      error: undefined,
+    }
+  }
+  return fieldStates[path]
+}
+
+// FormContext implementation
+
+function setFieldValue(path: string, value: unknown): void {
+  setByPath(data, path, value)
+  const state = ensureFieldState(path)
+  state.value = value
+  model.value = { ...data }
+}
+
+function getFieldValue(path: string): unknown {
+  return getByPath(data, path)
+}
+
+function setValues(values: Record<string, unknown>): void {
+  Object.assign(data, values)
+  model.value = { ...data }
+}
+
+function getFieldError(path: string): string | undefined {
+  return errors.value[path]
+}
+
+function setFieldError(path: string, message: string | undefined): void {
+  errors.value = { ...errors.value, [path]: message }
+  const state = ensureFieldState(path)
+  state.error = message
+  state.isValid = !message
+  state.hasError = !!message
+}
+
+function setErrors(newErrors: Record<string, string | undefined>): void {
+  errors.value = { ...newErrors }
+  for (const [path, message] of Object.entries(newErrors)) {
+    const state = ensureFieldState(path)
+    state.error = message
+    state.isValid = !message
+    state.hasError = !!message
+  }
+}
+
+function clearErrors(path?: string): void {
+  if (path != null) {
+    const { [path]: _removed, ...rest } = errors.value
+    errors.value = rest
+    const state = fieldStates[path]
+    if (state) {
+      state.error = undefined
+      state.isValid = true
+      state.hasError = false
+    }
+  } else {
+    errors.value = {}
+    for (const state of Object.values(fieldStates)) {
+      state.error = undefined
+      state.isValid = true
+      state.hasError = false
+    }
+  }
+}
+
+function getFieldState(path: string): FieldState {
+  return ensureFieldState(path)
+}
+
+function setDirty(path: string, value = true): void {
+  ensureFieldState(path).isDirty = value
+}
+
+function setTouched(path: string, value = true): void {
+  ensureFieldState(path).isTouched = value
+}
+
+// Registered validate callbacks from child inputs (via useFormField)
+const validators: Map<symbol, () => boolean> = new Map()
+
+function registerValidator(key: symbol, fn: () => boolean): void {
+  validators.set(key, fn)
+}
+
+function unregisterValidator(key: symbol): void {
+  validators.delete(key)
+}
+
+function validate(): boolean {
+  let allValid = true
+  for (const [, validateFn] of validators) {
+    if (!validateFn()) allValid = false
+  }
+  return allValid
+}
+
+function reset(): void {
+  // Clear all current keys, then restore snapshot taken at component creation
+  for (const key of Object.keys(data)) {
+    delete data[key]
+  }
+  Object.assign(data, JSON.parse(JSON.stringify(initialData)))
+  model.value = { ...data }
+  clearErrors()
+  for (const path of Object.keys(fieldStates)) {
+    fieldStates[path] = {
+      value: getByPath(data, path),
+      isDirty: false,
+      isTouched: false,
+      isValid: true,
+      hasError: false,
+      error: undefined,
+    }
+  }
+  emit('reset')
+}
+
+// Provide context
+
+const formContext: FormContext = {
+  errors,
+  data,
+  counter,
+  counterFormat,
+  setFieldValue,
+  getFieldValue,
+  setValues,
+  getFieldError,
+  setFieldError,
+  setErrors,
+  clearErrors,
+  getFieldState,
+  setDirty,
+  setTouched,
+  validate,
+  reset,
+  registerValidator,
+  unregisterValidator,
+}
+
+provide(FORM_CONTEXT_KEY, formContext)
+defineExpose(formContext)
+
+// Submit handler
+
+function handleSubmit(): void {
+  const isValid = validate()
+  if (!isValid) return
+
+  const serialized = props.serializer?.({ ...data }) ?? { ...data }
+  emit('submit', serialized)
+}
+</script>
+
+<template>
+  <form novalidate @submit.prevent="handleSubmit" @reset.prevent="reset">
+    <slot />
+    <slot
+      v-if="errors['$']"
+      name="error"
+      :error="errors['$']"
+    >
+      <p class="text-error text-sm mt-2" role="alert">{{ errors['$'] }}</p>
+    </slot>
+  </form>
+</template>

package/src/components/data/form/form.context.ts

@@ -0,0 +1,82 @@
+import type { InjectionKey, ShallowRef } from 'vue'
+import type { FieldState } from './form.types'
+
+export interface FormContext {
+  /**
+   * Unified error record.
+   * Global form error is stored under the `"$"` key.
+   * Per-field errors are stored under their dot-notation field name/path.
+   *
+   * @example { '$': 'Server error', 'email': 'Invalid email', 'address.street': 'Required' }
+   */
+  errors: ShallowRef<Record<string, string | undefined>>
+
+  /** Shallow reactive mirror of the form's v-model data. */
+  data: Record<string, unknown>
+
+  /**
+   * Counter config — exposed as raw `boolean | undefined`.
+   * `undefined` means "no opinion" — inputs resolve the final value themselves
+   * via `mergeProps` in `useComponentConfig`.
+   */
+  counter: ShallowRef<boolean | undefined>
+  counterFormat: ShallowRef<string | ((c: number, min?: number, max?: number) => string) | undefined>
+
+  // ── Field value methods ─────────────────────────────────────────────────
+
+  /** Sets a single field value by dot-notation path. Supports nested objects and arrays. */
+  setFieldValue: (path: string, value: unknown) => void
+
+  /** Returns the current value at a dot-notation path. */
+  getFieldValue: (path: string) => unknown
+
+  /** Replaces the entire data record and emits update:modelValue. */
+  setValues: (values: Record<string, unknown>) => void
+
+  // ── Field error methods ─────────────────────────────────────────────────
+
+  /** Returns the error string for a path, or "$" for the global error. */
+  getFieldError: (path: string) => string | undefined
+
+  /** Sets an error on a specific field (or "$" for global). */
+  setFieldError: (path: string, message: string | undefined) => void
+
+  /**
+   * Replaces the entire errors record.
+   * Use "$" key for the global error.
+   */
+  setErrors: (errors: Record<string, string | undefined>) => void
+
+  /**
+   * Clears all errors, or a specific field's error if `path` is provided.
+   * Pass `"$"` to clear only the global error.
+   */
+  clearErrors: (path?: string) => void
+
+  // ── Field state methods ─────────────────────────────────────────────────
+
+  /** Returns the full FieldState for a given path. */
+  getFieldState: (path: string) => FieldState
+
+  /** Marks a field as dirty (user has changed its value). */
+  setDirty: (path: string, value?: boolean) => void
+
+  /** Marks a field as touched (user has blurred the input). */
+  setTouched: (path: string, value?: boolean) => void
+
+  // ── Form-level methods ──────────────────────────────────────────────────
+
+  /** Triggers validation on all registered fields. Returns true if all valid. */
+  validate: () => boolean
+
+  /** Resets data to initial values, clears all errors and field states. */
+  reset: () => void
+
+  /** Registers a field validator (called on form submit). Key must be unique per input instance. */
+  registerValidator: (key: symbol, fn: () => boolean) => void
+
+  /** Removes a previously registered field validator. */
+  unregisterValidator: (key: symbol) => void
+}
+
+export const FORM_CONTEXT_KEY: InjectionKey<FormContext> = Symbol('FormContext')

package/src/components/data/form/form.props.ts

@@ -0,0 +1,30 @@
+import type { CounterFn } from '@/types/utils.type'
+import type { FormSerializer } from './form.types'
+
+export interface FormConfigurableProps {
+  /**
+   * Propagates a counter display to all child inputs that support it.
+   * Can be overridden at FormField or input level.
+   *
+   * @default false
+   */
+  counter?: boolean
+
+  /**
+   * Default counter format applied to all child inputs.
+   * Can be overridden at FormField or input level.
+   *
+   * @default (current, min, max) => `${current} / ${max}`
+   */
+  counterFormat?: string | CounterFn
+}
+
+export interface FormProps extends FormConfigurableProps {
+  /**
+   * Transforms the form data before it is passed to the `submit` event.
+   * If not provided, the raw data object is emitted as-is.
+   *
+   * @example (data) => ({ ...data, createdAt: new Date().toISOString() })
+   */
+  serializer?: FormSerializer
+}

package/src/components/data/form/form.types.ts

@@ -0,0 +1,25 @@
+/**
+ * Full state for a single registered field in the form.
+ */
+export interface FieldState {
+  /** Current value. */
+  value: unknown
+  /** True after the user has changed the value at least once. */
+  isDirty: boolean
+  /** True after the input has lost focus at least once. */
+  isTouched: boolean
+  /** True when the field has no active error. */
+  isValid: boolean
+  /** True when there is an active error string. */
+  hasError: boolean
+  /** The current error string, or undefined. */
+  error: string | undefined
+}
+
+/**
+ * Transforms the raw form data before it is emitted in the submit event.
+ * Use to parse, rename, or restructure fields.
+ *
+ * @example (data) => ({ ...data, age: Number(data.age) })
+ */
+export type FormSerializer<T = Record<string, unknown>> = (data: Record<string, unknown>) => T

package/src/components/data/form-field/FormField.vue

@@ -0,0 +1,176 @@
+<script lang="ts">
+import { computed, inject, provide, shallowRef, watch } from 'vue'
+import { FORM_CONTEXT_KEY } from '../form/form.context'
+import type { FieldState } from '../form/form.types'
+import type { FormFieldContext } from './form-field.context'
+import { FORM_FIELD_CONTEXT_KEY } from './form-field.context'
+</script>
+
+<script setup lang="ts">
+import type { FormFieldProps } from './form-field.props'
+
+const props = defineProps<FormFieldProps>()
+
+// Inject parent Form context (optional)
+
+const formCtx = inject(FORM_CONTEXT_KEY, null)
+
+// Required state — pushed by child inputs via setRequired()
+
+const required = shallowRef<boolean>(false)
+
+// Counter config — same lazy-undefined logic as Form.
+
+const counter = shallowRef<boolean | undefined>(
+  props.counter !== undefined ? props.counter : undefined,
+)
+const counterFormat = shallowRef<
+  string | ((c: number, min?: number, max?: number) => string) | undefined
+>(props.counterFormat)
+
+watch(() => props.counter, (val) => {
+  counter.value = val !== undefined ? val : undefined
+})
+watch(() => props.counterFormat, (val) => { counterFormat.value = val })
+
+// Counter display — pushed up by child inputs
+
+const counterText = shallowRef('')
+const counterColor = shallowRef('')
+
+function setCounterText(text: string, colorClass: string): void {
+  counterText.value = text
+  counterColor.value = colorClass
+}
+
+// Computed field state from FormContext
+
+const fieldValue = computed<unknown>(() => formCtx?.getFieldValue(props.name))
+
+const fieldError = computed<string | undefined>(() => formCtx?.getFieldError(props.name))
+
+const fieldState = computed<FieldState>(() =>
+  formCtx?.getFieldState(props.name) ?? {
+    value: undefined,
+    isDirty: false,
+    isTouched: false,
+    isValid: true,
+    hasError: false,
+    error: undefined,
+  },
+)
+
+// FormFieldContext implementation
+
+function setValue(value: unknown): void {
+  formCtx?.setFieldValue(props.name, value)
+}
+
+function setRequired(value: boolean): void {
+  required.value = value
+}
+
+function setDirty(value = true): void {
+  formCtx?.setDirty(props.name, value)
+}
+
+function setTouched(value = true): void {
+  formCtx?.setTouched(props.name, value)
+}
+
+function setError(message: string | undefined): void {
+  formCtx?.setFieldError(props.name, message)
+}
+
+function registerValidator(key: symbol, fn: () => boolean): void {
+  formCtx?.registerValidator(key, fn)
+}
+
+function unregisterValidator(key: symbol): void {
+  formCtx?.unregisterValidator(key)
+}
+
+const fieldContext: FormFieldContext = {
+  name: props.name,
+  required,
+  value: fieldValue,
+  error: fieldError,
+  state: fieldState,
+  counter,
+  counterFormat,
+  counterText,
+  counterColor,
+  setValue,
+  setRequired,
+  setDirty,
+  setTouched,
+  setError,
+  setCounterText,
+  registerValidator,
+  unregisterValidator,
+} satisfies FormFieldContext
+
+provide(FORM_FIELD_CONTEXT_KEY, fieldContext)
+
+// Bottom row visibility
+
+const showBottom = computed(() =>
+  !!(fieldError.value || props.hint || counterText.value),
+)
+</script>
+
+<template>
+  <fieldset class="fieldset w-full">
+    <!-- Floating label mode: label floats over the input -->
+    <template v-if="floating">
+      <label class="floating-label">
+        <span v-if="label || $slots.label">
+          <slot name="label" :required="required">
+            {{ label }}<span v-if="required" class="text-error ml-0.5" aria-hidden="true">*</span>
+          </slot>
+        </span>
+        <slot />
+      </label>
+    </template>
+
+    <!-- Default mode: legend above the field -->
+    <template v-else>
+      <legend v-if="label || $slots.label" class="fieldset-legend">
+        <slot name="label" :required="required">
+          {{ label }}<span v-if="required" class="text-error ml-0.5" aria-hidden="true">*</span>
+        </slot>
+      </legend>
+      <slot />
+    </template>
+
+    <!-- Bottom row: error/hint left, counter right -->
+    <div v-if="showBottom" class="flex items-center justify-between gap-2 mt-1">
+      <Transition name="field-message" mode="out-in">
+        <p v-if="fieldError" key="error" class="label text-error text-xs" role="alert">
+          <slot name="error" :error="fieldError">{{ fieldError }}</slot>
+        </p>
+        <p v-else-if="hint" key="hint" class="label text-xs">
+          <slot name="hint">{{ hint }}</slot>
+        </p>
+        <span v-else key="empty" />
+      </Transition>
+      <span
+        v-if="counterText"
+        class="label text-xs shrink-0"
+        :class="counterColor"
+      >{{ counterText }}</span>
+    </div>
+  </fieldset>
+</template>
+
+<style scoped>
+.field-message-enter-active,
+.field-message-leave-active {
+  transition: opacity 0.2s ease, transform 0.2s ease;
+}
+.field-message-enter-from,
+.field-message-leave-to {
+  opacity: 0;
+  transform: translateY(-4px);
+}
+</style>