@poppy-ui/vue 0.5.6 → 0.5.7-beta.0

package/src/components/data/checkbox/Checkbox.story.vue

@@ -0,0 +1,156 @@
+<script lang="ts">
+import Form from '@/components/data/form/Form.vue'
+import FormField from '@/components/data/form-field/FormField.vue'
+import { reactive, ref } from 'vue'
+import { createI18n } from 'vue-i18n'
+import Checkbox from './Checkbox.vue'
+import type { CheckboxProps } from './checkbox.props'
+</script>
+
+<script setup lang="ts">
+const model = ref<boolean>(false)
+
+const state = reactive<CheckboxProps>({
+  size: 'md',
+  indeterminate: false,
+})
+
+const formData = ref<Record<string, unknown>>({ agree: false })
+</script>
+
+<template>
+  <Story group="components" title="Data/Checkbox" auto-props-disabled :setup-app="({ app }) => {
+    app.use(createI18n({}))
+  }">
+
+    <Variant title="Default" id="default">
+      <template #controls>
+        <HstSelect
+          v-model="state.color"
+          title="color"
+          :options="[undefined, 'neutral', 'primary', 'secondary', 'accent', 'info', 'success', 'warning', 'error']"
+        />
+        <HstSelect
+          v-model="state.size"
+          title="size"
+          :options="['xs', 'sm', 'md', 'lg']"
+        />
+        <HstCheckbox v-model="(state.indeterminate as boolean)" title="indeterminate" />
+        <HstCheckbox v-model="state.disabled" title="disabled" />
+        <HstCheckbox v-model="state.required" title="required" />
+        <HstText v-model="state.description" title="description" />
+      </template>
+
+      <Checkbox v-model="model" v-bind="state" />
+    </Variant>
+
+    <Variant title="Colors" id="colors">
+      <div class="flex flex-wrap gap-4 p-4">
+        <Checkbox v-model="model" color="neutral" />
+        <Checkbox v-model="model" color="primary" />
+        <Checkbox v-model="model" color="secondary" />
+        <Checkbox v-model="model" color="accent" />
+        <Checkbox v-model="model" color="info" />
+        <Checkbox v-model="model" color="success" />
+        <Checkbox v-model="model" color="warning" />
+        <Checkbox v-model="model" color="error" />
+      </div>
+    </Variant>
+
+    <Variant title="Sizes" id="sizes">
+      <div class="flex items-center gap-4 p-4">
+        <Checkbox v-model="model" size="xs" />
+        <Checkbox v-model="model" size="sm" />
+        <Checkbox v-model="model" size="md" />
+        <Checkbox v-model="model" size="lg" />
+      </div>
+    </Variant>
+
+    <Variant title="Indeterminate" id="indeterminate">
+      <Checkbox v-model="model" indeterminate />
+    </Variant>
+
+    <Variant title="Disabled" id="disabled">
+      <div class="flex gap-4">
+        <Checkbox v-model="model" disabled />
+        <Checkbox :model-value="true" disabled />
+      </div>
+    </Variant>
+
+    <Variant title="With Description" id="with-description">
+      <div class="flex flex-col gap-3">
+        <Checkbox v-model="model" description="Enable notifications for new messages" />
+        <Checkbox v-model="model" color="primary" description="Subscribe to the newsletter" />
+      </div>
+    </Variant>
+
+    <Variant title="Inside FormField" id="inside-form-field">
+      <Form v-model="formData">
+        <FormField name="agree" label="Terms & conditions">
+          <Checkbox required />
+        </FormField>
+      </Form>
+    </Variant>
+
+  </Story>
+</template>
+
+<docs lang="md">
+# Checkbox
+
+## Description
+
+Checkbox component built on the DaisyUI `checkbox` element.
+Works standalone with `v-model` or inside `<FormField />` for full form integration (validation, required indicator).
+
+## API
+
+### v-model
+
+| Name      | Type      | Modifiers | Description          |
+|-----------|-----------|-----------|----------------------|
+| `v-model` | `boolean` | `-`       | Bound checked state. |
+
+### Props
+
+| Prop            | Type            | Default     | Configurable       | Description                                                |
+|-----------------|-----------------|-------------|--------------------|------------------------------------------------------------|
+| `color`         | `CheckboxColor` | `undefined` | :white_check_mark: | Color variant.                                             |
+| `size`          | `CheckboxSize`  | `'md'`      | :white_check_mark: | Size.                                                      |
+| `indeterminate` | `Booleanish`    | `false`     | :x:                | Renders the indeterminate visual state.                    |
+| `description`   | `string`        | `undefined` | :x:                | Secondary text displayed next to the checkbox.             |
+| `disabled`      | `boolean`       | `undefined` | :x:                | Native disabled.                                           |
+| `required`      | `boolean`       | `undefined` | :x:                | Native required. Signals `<FormField />` to display `"*"`. |
+
+### Events
+
+| Event     | Payload | Description                                                                             |
+|-----------|---------|-----------------------------------------------------------------------------------------|
+| `@change` | `Event` | Emitted when the checked state changes (native change event).                           |
+| `@blur`   | `Event` | Emitted when the checkbox loses focus. Triggers validation when inside `<FormField />`. |
+
+### Slots
+
+| Slot          | Scope     | Description                                    |
+|---------------|-----------|------------------------------------------------|
+| `description` | `-`       | Secondary text displayed next to the checkbox. |
+
+> **Configurable** props can be configured in the Poppy Plugin `install` function via the `Poppy` object. See [Plugin Configuration](../../../stories/Configuration.story.md) for more information.
+
+## Usage
+```vue
+<!-- Standalone -->
+<Checkbox v-model="accepted" color="primary" />
+
+<!-- With description -->
+<Checkbox v-model="accepted" description="Subscribe to the newsletter" />
+
+<!-- Indeterminate -->
+<Checkbox v-model="partialSelection" indeterminate />
+
+<!-- Inside FormField -->
+<FormField name="agree" label="Terms & conditions">
+  <Checkbox required />
+</FormField>
+```
+</docs>

package/src/components/data/checkbox/Checkbox.vue

@@ -0,0 +1,119 @@
+<script lang="ts">
+import { useComponentConfig } from '@/composables/use-component-config'
+import { useFormField } from '@/composables/use-form-field'
+import type { ComponentClass } from '@/types/utils.type'
+import { getClass } from '@/utils/build-class.util'
+import { isTrue } from '@/utils/is-true'
+import { computed, useSlots, useTemplateRef, watchEffect } from 'vue'
+import { CHECKBOX_CONFIG } from './checkbox.context'
+import type { CheckboxProps } from './checkbox.props'
+import type { CheckboxColor, CheckboxSize } from './checkbox.types'
+
+const colors: ComponentClass<'checkbox', CheckboxColor> = {
+  neutral: 'checkbox-neutral',
+  primary: 'checkbox-primary',
+  secondary: 'checkbox-secondary',
+  accent: 'checkbox-accent',
+  info: 'checkbox-info',
+  success: 'checkbox-success',
+  warning: 'checkbox-warning',
+  error: 'checkbox-error',
+}
+
+const sizes: ComponentClass<'checkbox', CheckboxSize> = {
+  xs: 'checkbox-xs',
+  sm: 'checkbox-sm',
+  md: 'checkbox-md',
+  lg: 'checkbox-lg',
+  xl: 'checkbox-xl',
+}
+</script>
+
+<script setup lang="ts">
+const props = defineProps<CheckboxProps>()
+const model = defineModel<boolean>()
+const config = useComponentConfig(CHECKBOX_CONFIG, props, { size: 'md' })
+
+const inputEl = useTemplateRef('inputEl')
+
+const slots = useSlots()
+
+// ── Indeterminate — must be set imperatively on the DOM node ─────────────────
+
+watchEffect(() => {
+  if (inputEl.value) {
+    inputEl.value.indeterminate = isTrue(props.indeterminate)
+  }
+})
+
+// ── Form field ───────────────────────────────────────────────────────────────
+
+const { field, onBlur, clearError } = useFormField<boolean>({
+  required: computed(() => isTrue(props.required)),
+  inputEl,
+})
+
+// ── Value resolution ─────────────────────────────────────────────────────────
+
+const resolvedValue = computed(() =>
+  field ? field.value.value : model.value,
+)
+
+function handleChange(event: Event): void {
+  const checked = (event.target as HTMLInputElement).checked
+  model.value = checked
+  field?.setValue(checked)
+  field?.setDirty(true)
+  clearError()
+}
+
+// ── Error ────────────────────────────────────────────────────────────────────
+
+const hasError = computed(() => !!field?.error.value)
+
+// ── Description presence ─────────────────────────────────────────────────────
+
+const hasDescription = computed(() => !!(props.description || slots.description))
+</script>
+
+<template>
+  <!-- Bare checkbox — no description -->
+  <input
+    v-if="!hasDescription"
+    ref="inputEl"
+    type="checkbox"
+    class="checkbox"
+    :class="[
+      getClass(colors, config.color),
+      getClass(sizes, config.size),
+      { 'checkbox-error': hasError },
+    ]"
+    :checked="resolvedValue"
+    :disabled="disabled"
+    :required="isTrue(required)"
+    @change="handleChange"
+    @blur="onBlur"
+  />
+
+  <!-- Checkbox with description -->
+  <label v-else class="flex cursor-pointer items-start gap-2">
+    <input
+      ref="inputEl"
+      type="checkbox"
+      class="checkbox mt-0.5"
+      :class="[
+        getClass(colors, config.color),
+        getClass(sizes, config.size),
+        { 'checkbox-error': hasError },
+      ]"
+      :checked="resolvedValue"
+      :disabled="disabled"
+      :required="isTrue(required)"
+      @change="handleChange"
+      @blur="onBlur"
+    />
+    <span class="label-text text-base-content/60">
+      <slot name="description">{{ description }}</slot>
+    </span>
+  </label>
+</template>

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

@@ -0,0 +1,3 @@
+import { createComponentConfigKey } from '@/symbol'
+
+export const CHECKBOX_CONFIG = createComponentConfigKey('checkbox')

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

@@ -0,0 +1,38 @@
+import type { Booleanish } from '@/types/utils.type'
+import type { InputHTMLAttributes } from 'vue'
+import type { CheckboxColor, CheckboxSize } from './checkbox.types'
+
+export interface CheckboxConfigurableProps {
+  /**
+   * Color of the checkbox.
+   */
+  color?: CheckboxColor
+
+  /**
+   * Size of the checkbox.
+   *
+   * @default 'md'
+   */
+  size?: CheckboxSize
+}
+
+interface NativeCheckbox {
+  /** Disables the checkbox. */
+  disabled?: InputHTMLAttributes['disabled']
+  /** Marks the field as required — signals FormField to display "*". */
+  required?: InputHTMLAttributes['required']
+}
+
+export interface CheckboxProps extends CheckboxConfigurableProps, NativeCheckbox {
+  /**
+   * Renders the checkbox in an indeterminate visual state.
+   *
+   * @default false
+   */
+  indeterminate?: Booleanish
+
+  /**
+   * Secondary description displayed below the checkbox.
+   */
+  description?: string
+}

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

@@ -0,0 +1,5 @@
+import type { ComponentSize } from '@/types/size.type'
+
+export type CheckboxColor = 'neutral' | 'primary' | 'secondary' | 'accent' | 'info' | 'success' | 'warning' | 'error'
+
+export type CheckboxSize = ComponentSize

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`       | `Booleanish`           | `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      | Scope                            | 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,222 @@
+<script lang="ts">
+import type { CounterFn } from '@/types/utils.type'
+import { isTrue } from '@/utils/is-true'
+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 = JSON.parse(JSON.stringify(unref(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 ? isTrue(props.counter) : undefined,
+)
+const counterFormat = shallowRef<string | CounterFn | undefined>(props.counterFormat)
+
+watch(() => props.counter, val => {
+  counter.value = val !== undefined ? isTrue(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
+}
+
+function validate(): boolean {
+  let allValid = true
+  for (const [, validateFn] of validators) {
+    if (!validateFn()) allValid = false
+  }
+  return allValid
+}
+
+// Registered validate callbacks from child inputs (via useFormField)
+const validators: Map<string, () => boolean> = new Map()
+
+function reset(): void {
+  Object.assign(data, {})
+  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,
+}
+
+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>