feat: granular field composables (#205)

* feat: initial API draft

* revert: go back to old api and refactor description props

* refactor: rename useFormField to useFieldState

* feat: second draft of the api

* feat: added injectable version

* feat: expose injectables

* feat: export useFormField from index

* feat: export types from useTextField index

* fix: provide FieldState in useFieldState

* feat: export FieldProps interface in useFormField

* chore: playground tests

* feat: added validateOn prop to text control

* refactor: generate uniq id on the control level

* refactor: only one composable for form fields

* feat: move v-model to the text control input

* feat: migrate search field to use text control

* fix: avoid mutating the model value directly

* feat: expose label property

* feat: split select into a control and field composables

* feat: introduce FieldBaseProps interface for consistent field properties

* feat: split switch into a control and field composables

* feat: split slider into a control and field composables

* feat: split the number field into a control and field composables

* feat: split file field into a control and field composables

* refactor: expose the label/description/error element props

* fix: types

* feat: split time and date fields to control composables

* feat: split combox field into control and field composables

* refactor: remove redundencies from label and radio groups

* refactor: completely deprecate field model sync

* fix: model sync

* refactor: include field as control prop

* feat: split otp to control and field pair

* chore: changeset

* refactor: all controls inject or create the field

* refactor: prop normalization

* refactor: remove redudant props

* refactor: redudant required prop

* feat: exposed ids of all fields

* feat: add controlId to date and time control elements

* refactor: streamline accessibility props handling in useCustomField

* refactor: remove optional chaining for field

* feat: expose useCustomControl

* refactor: rename and unify control id name

* refactor: restructure fields and control types

* feat: allow label components to receive for attributes

* feat: expose control id on the useFieldController

* chore: update prop types

* fix: bring back old code

* fix: types

* chore: register with devtools in `useFormField` (#214)

* chore: register with devtools in `useFormField`

* refactor: update registerField to accept Ref type and use

* feat: introduce BuiltInControlTypes for consistent control type

* chore: fix typo

* fix: types and type reactivity in devtools

---------

Co-authored-by: Abdelrahman Awad <[email protected]>

* feat: add `blurred` state (#220)

* feat: add `blurred` state

* chore: touch fields `onInput` and `onChange`

* chore: add ability to blur a field

* feat: track blurred fields

* test: update blur test to check both touched and blurred states

* test: update input test to check touched state and value updates

* feat: add clearBlurred method to reset blurred fields

* test: add tests for handling blurred state in form

* test: enhance field state tests for blurred states

* refactor: remove redundant onChange handler in useTextField

* feat: add blurred state to form transactions and field management

* chore: rebase branch

* feat: implement onBlur handler to set blurred state in useSwitchControl

* feat: manage blurred state in useSlider

* feat: enhance useSelectControl to manage touched and blurred states

* feat: update useRadio to manage blurred state in onBlur handler

* feat: manage touched and blurred states in fillSlots and onBlur handlers

* feat: update useNumberControl to manage blurred state in onBlur handler

* feat: update useFileControl to manage touched state in various handlers

* feat: manage blurred state in date and time controls

* feat: manage touched state in useComboBoxControl

* feat: manage blurred state in useCheckbox and useCheckboxGroup

* feat: manage blurred state in useCalendarControl

* test: fix failing tests and added test cases for touched

---------

Co-authored-by: Abdelrahman Awad <[email protected]>

* feat: add control element reference to useCustomControl

* chore: update changesets

---------

Co-authored-by: Eugen Istoc <[email protected]>

Author: logaretm

.changeset/eleven-keys-notice.md

@@ -0,0 +1,5 @@
+---
+'@formwerk/core': minor
+---
+
+feat(core): each field composable now has a control composable variant to allow for more granular components

.changeset/sad-mice-travel.md

@@ -0,0 +1,5 @@
+---
+'@formwerk/core': minor
+---
+
+feat(core): added `isBlurred` state to fields and forms

.oxlintrc.json

@@ -85,6 +85,7 @@
     "@typescript-eslint/triple-slash-reference": "error",
     "@typescript-eslint/explicit-function-return-type": "off",
     "@typescript-eslint/explicit-module-boundary-types": "off",
+    "no-wrapper-object-types": "off",
     "no-console": [
       "error",
       {

packages/core/src/a11y/index.ts

@@ -1,2 +1,3 @@
 export * from './useErrorMessage';
 export * from './useLabel';
+export * from './useDescription';

packages/core/src/a11y/useDescription.ts

@@ -0,0 +1,30 @@
+import { computed, MaybeRefOrGetter, shallowRef, toValue } from 'vue';
+import { useCaptureProps } from '../utils/common';
+import { AriaDescriptionProps } from '../types';
+
+export function createDescriptionProps(inputId: string): AriaDescriptionProps {
+  return {
+    id: `${inputId}-d`,
+  };
+}
+
+interface CreateDescribedByInit {
+  inputId: MaybeRefOrGetter<string>;
+  description: MaybeRefOrGetter<string | undefined>;
+}
+
+export function useDescription({ inputId, description }: CreateDescribedByInit) {
+  const descriptionRef = shallowRef<HTMLElement>();
+  const descriptionProps = useCaptureProps(() => createDescriptionProps(toValue(inputId)), descriptionRef);
+
+  const describedByProps = computed(() => {
+    return {
+      'aria-describedby': descriptionRef.value && toValue(description) ? descriptionProps.value.id : undefined,
+    };
+  });
+
+  return {
+    describedByProps,
+    descriptionProps,
+  };
+}

packages/core/src/a11y/useLabel.spec.ts

@@ -1,6 +1,6 @@
 import { render, screen } from '@testing-library/vue';
 import { useLabel } from './useLabel';
-import { shallowRef } from 'vue';
+import { defineComponent, shallowRef } from 'vue';
 
 describe('label element', () => {
   test('should render label with `for` attribute', async () => {
@@ -95,3 +95,38 @@ describe('label target (labelledBy)', () => {
     expect(screen.getByTestId('input')?.getAttribute('aria-labelledby')).toBe(`${labelFor}-l`);
   });
 });
+
+describe('label component', () => {
+  test('should render label component with `for` attribute', async () => {
+    const label = 'label';
+    const labelFor = 'input';
+    const inputRef = shallowRef<HTMLElement>();
+
+    const LabelComp = defineComponent({
+      props: ['for'],
+      template: `
+        <label data-testid="label" :for="$props.for">
+          <slot />
+        </label>
+      `,
+    });
+
+    await render({
+      components: { LabelComp },
+      setup: () => {
+        return {
+          ...useLabel({ label: label, for: labelFor, targetRef: inputRef }),
+          label,
+          inputRef,
+        };
+      },
+      template: `
+        <LabelComp v-bind="labelProps">{{ label }}</LabelComp>
+        <input data-testid="input" ref="inputRef" />
+      `,
+    });
+
+    expect(screen.getByTestId('label')).toHaveTextContent(label);
+    expect(screen.getByTestId('label')?.getAttribute('for')).toBe(labelFor);
+  });
+});

packages/core/src/reactivity/useVModelProxy.ts

@@ -0,0 +1,21 @@
+import { ref } from 'vue';
+import { FieldState } from '../useFormField';
+import { useSyncModel } from './useModelSync';
+
+/**
+ * A proxy for the model value of a field, if the field is not provided, a local ref is created.
+ */
+export function useVModelProxy<T = unknown>(field: FieldState<T>) {
+  const model = field.fieldValue ?? ref<T>();
+
+  useSyncModel({
+    model,
+    modelName: 'modelValue',
+    onModelPropUpdated: field.setValue,
+  });
+
+  return {
+    model,
+    setModelValue: field.setValue,
+  };
+}

packages/core/src/types/controls.ts

@@ -0,0 +1,65 @@
+import { FormField } from '../useFormField';
+import { StandardSchema } from './forms';
+
+export interface ControlApi {
+  getControlElement(): HTMLElement | undefined;
+  getControlId(): string | undefined;
+  getControlType(): string | undefined;
+}
+
+export interface ControlProps<TValue = unknown, TInitialValue = TValue> {
+  /**
+   * The name of the field.
+   */
+  name?: string;
+
+  /**
+   * The field to use for the control. Internal usage only.
+   */
+  _field?: FormField<TValue | undefined>;
+
+  /**
+   * Schema for field validation.
+   */
+  schema?: StandardSchema<TValue>;
+
+  /**
+   * The v-model value of the field.
+   */
+  modelValue?: TValue | undefined;
+
+  /**
+   * The initial value of the field.
+   */
+  value?: TInitialValue;
+
+  /**
+   * Whether the field is disabled.
+   */
+  disabled?: boolean;
+
+  /**
+   * Whether the field is required.
+   */
+  required?: boolean;
+}
+
+export const BuiltInControlTypes = {
+  Text: 'Text',
+  Calendar: 'Calendar',
+  Date: 'Date',
+  Time: 'Time',
+  File: 'File',
+  Select: 'Select',
+  Number: 'Number',
+  OTP: 'OTP',
+  Slider: 'Slider',
+  Switch: 'Switch',
+  Checkbox: 'Checkbox',
+  CheckboxGroup: 'CheckboxGroup',
+  RadioGroup: 'RadioGroup',
+  ComboBox: 'ComboBox',
+  Hidden: 'Hidden',
+  Search: 'Search',
+  Custom: 'Custom',
+} as const;

packages/core/src/types/forms.ts

@@ -16,6 +16,8 @@ export type TouchedSchema<TForm extends FormObject> = Simplify<Schema<TForm, boo
 
 export type DirtySchema<TForm extends FormObject> = Simplify<Schema<TForm, boolean>>;
 
+export type BlurredSchema<TForm extends FormObject> = Simplify<Schema<TForm, boolean>>;
+
 export type DisabledSchema<TForm extends FormObject> = Partial<Record<Path<TForm>, boolean>>;
 
 export type ErrorsSchema<TForm extends FormObject> = Partial<Record<Path<TForm>, string[]>>;

packages/core/src/types/index.ts

@@ -1,3 +1,4 @@
 export * from './common';
 export * from './paths';
 export * from './forms';
+export * from './controls';