Add ability to customize input ids (#31)

* Add ability to customize input ids

* Simplify formOptions.inputIds logic

* add types test

* Refactor to prevent overriding id prop when inputIds is set to false

* make generating ids disabled by default

to prevent introducing any breaking changes as the generated id is likely to override any exiting ids before calling the input props initializers

* Move id tests to a different file

* Remove input.id helper

* update README.md

* rename createIds → withIds

Author: wsmd

README.md

@@ -39,6 +39,7 @@
     - [`formOptions.onBlur`](#formoptionsonblur)
     - [`formOptions.onChange`](#formoptionsonchange)
     - [`formOptions.onTouched`](#formoptionsontouched)
+    - [`formOptions.withIds`](#formoptionswithids)
   - [`[formState, inputs]`](#formstate-inputs)
     - [Form State](#form-state)
     - [Input Types](#input-types)
@@ -208,13 +209,17 @@ function LoginForm({ onSubmit }) {
   );
 }
 ```
+
 ### Labels
 
-A label can be paired to a specific input by passing the same parameters to
-`input.label()`. This will populate the label's `htmlFor` attribute.
+As a convenience, `useFormState` provides an optional API that helps with pairing a label to a specific input.
+
+When [`formOptions.withIds`](#formoptionswithids) is enabled, a label can be paired to an [input](#input-types) by using `input.label()`. This will populate the label's `htmlFor` attribute for an input with the same parameters.
 
 ```js
-const [formState, { label, text, radio }] = useFormState();
+const [formState, { label, text, radio }] = useFormState(initialState, {
+  withIds: true, // enable automatic creation of id and htmlFor props
+});
 
 return (
   <form>
@@ -230,17 +235,10 @@ return (
 );
 ```
 
-An input's generated ID can also be queried with the `id` getter.
+Note that this will override any existing `id` prop if specified before calling the input functions. If you want the `id` to take precedence, it must be passed _after_ calling the input types like this:
 
 ```jsx
-const [formState, { id, text }] = useFormState();
-
-return (
-  <>
-    <input {...text('name')} />
-    <p>The input's ID is {id('name')}</p>
-  </>
-);
+<input {...text('username')} id="signup-username" />
 ```
 
 ## Working with TypeScript
@@ -335,6 +333,31 @@ const [formState, inputs] = useFormState(null, {
 });
 ```
 
+#### `formOptions.withIds`
+
+Indicates whether `useFormState` should generate and pass an `id` attribute to its fields. This is helpful when [working with labels](#labels-and-ids).
+
+It can be one of the following:
+
+A `boolean` indicating whether [input types](#input-types) should pass an `id` attribute to the inputs (set to `false` by default).
+
+```js
+const [formState, inputs] = useFormState(null, {
+  withIds: true,
+});
+```
+
+Or a custom id formatter: a function that gets called with the input's name and own value, and expected to return a unique string (using these parameters) that will be as the input id.
+
+```js
+const [formState, inputs] = useFormState(null, {
+  withIds: (name, ownValue) =>
+    ownValue ? `MyForm-${name}-${ownValue}` : `MyForm-${name}`,
+});
+```
+
+Note that when `withIds` is set to `false`, applying `input.label()` will be a no-op.
+
 ### `[formState, inputs]`
 
 The return value of `useFormState`. An array of two items, the first is the [form state](#form-state), and the second an [input types](#input-types) object.

package.json

@@ -57,6 +57,7 @@
     "@babel/core": "^7.1.2",
     "@babel/preset-env": "^7.1.0",
     "@babel/preset-react": "^7.0.0",
+    "@types/jest": "^24.0.11",
     "@types/react": "^16.8.4",
     "babel-core": "^7.0.0-bridge.0",
     "babel-jest": "^23.6.0",

src/constants.js

@@ -16,15 +16,13 @@ export const TEXTAREA = 'textarea';
 export const TIME = 'time';
 export const URL = 'url';
 export const WEEK = 'week';
+export const LABEL = 'label';
 
 /**
  * @todo add support for datetime-local
  */
 export const DATETIME_LOCAL = 'datetime-local';
 
-export const LABEL = 'label';
-export const ID = 'id';
-
 export const TYPES = [
   CHECKBOX,
   COLOR,
@@ -45,5 +43,3 @@ export const TYPES = [
   URL,
   WEEK,
 ];
-
-export const ID_PREFIX = '__ufs';

src/index.d.ts

@@ -32,6 +32,7 @@ interface FormOptions<T> {
   ): void;
   onBlur(e: React.FocusEvent<InputElement>): void;
   onTouched(e: React.FocusEvent<InputElement>): void;
+  withIds: boolean | ((name: string, value?: string) => string);
 }
 
 // prettier-ignore

src/useFormState.js

@@ -2,17 +2,16 @@ import { useReducer } from 'react';
 import { stateReducer } from './stateReducer';
 import { toString } from './toString';
 import { parseInputArgs } from './parseInputArgs';
+import { useInputId } from './useInputId';
 import { useMarkAsDirty } from './useMarkAsDirty';
 import {
-  ID_PREFIX,
   TYPES,
   SELECT,
   CHECKBOX,
   RADIO,
   TEXTAREA,
   SELECT_MULTIPLE,
   LABEL,
-  ID,
 } from './constants';
 
 function noop() {}
@@ -21,21 +20,17 @@ const defaultFromOptions = {
   onChange: noop,
   onBlur: noop,
   onTouched: noop,
+  withIds: false,
 };
 
-const idGetter = (name, value) =>
-  [ID_PREFIX, name, value].filter(part => !!part).join('__');
-
-const labelPropsGetter = (...args) => ({
-  htmlFor: idGetter(...args),
-});
-
 export default function useFormState(initialState, options) {
   const formOptions = { ...defaultFromOptions, ...options };
 
   const [state, setState] = useReducer(stateReducer, initialState || {});
   const [touched, setTouchedState] = useReducer(stateReducer, {});
   const [validity, setValidityState] = useReducer(stateReducer, {});
+
+  const { getIdProp } = useInputId(formOptions.withIds);
   const { setDirty, isDirty } = useMarkAsDirty();
 
   const createPropsGetter = type => (...args) => {
@@ -93,13 +88,15 @@ export default function useFormState(initialState, options) {
 
     const inputProps = {
       name,
-      id: idGetter(name, toString(ownValue)),
       get type() {
-        if (type !== SELECT && type !== SELECT_MULTIPLE && type !== TEXTAREA)
+        if (type !== SELECT && type !== SELECT_MULTIPLE && type !== TEXTAREA) {
           return type;
+        }
       },
       get multiple() {
-        if (type === SELECT_MULTIPLE) return true;
+        if (type === SELECT_MULTIPLE) {
+          return true;
+        }
       },
       get checked() {
         if (isRadio) {
@@ -176,6 +173,7 @@ export default function useFormState(initialState, options) {
           setDirty(name, false);
         }
       },
+      ...getIdProp('id', name, ownValue),
     };
 
     return inputProps;
@@ -186,13 +184,11 @@ export default function useFormState(initialState, options) {
     {},
   );
 
-  const otherCreators = {
-    [LABEL]: labelPropsGetter,
-    [ID]: idGetter,
-  };
-
   return [
     { values: state, validity, touched },
-    { ...inputPropsCreators, ...otherCreators },
+    {
+      ...inputPropsCreators,
+      [LABEL]: (name, ownValue) => getIdProp('htmlFor', name, ownValue),
+    },
   ];
 }

src/useInputId.js

@@ -0,0 +1,33 @@
+import { useCallback } from 'react';
+import { toString } from './toString';
+
+const defaultCreateId = (name, value) =>
+  ['__ufs', name, value].filter(Boolean).join('__');
+
+export function useInputId(implementation) {
+  const getId = useCallback(
+    (name, ownValue) => {
+      let createId;
+      if (!implementation) {
+        createId = () => {}; // noop
+      } else if (typeof implementation === 'function') {
+        createId = implementation;
+      } else {
+        createId = defaultCreateId;
+      }
+      const value = toString(ownValue);
+      return value ? createId(name, value) : createId(name);
+    },
+    [implementation],
+  );
+
+  const getIdProp = useCallback(
+    (prop, name, value) => {
+      const id = getId(name, value);
+      return id === undefined ? {} : { [prop]: id };
+    },
+    [getId],
+  );
+
+  return { getIdProp };
+}

test/types.tsx

@@ -34,6 +34,7 @@ const [formState, input] = useFormState<FormFields>(initialState, {
   onTouched(e) {
     const { name, value } = e.target;
   },
+  withIds: (name, value) => (value ? `${name}.${value.toLowerCase()}` : name),
 });
 
 let name: string = formState.values.name;

test/useFormState-ids.test.js

@@ -0,0 +1,86 @@
+import { useFormState } from '../src';
+import * as TestUtils from './test-utils';
+
+TestUtils.mockReactUseReducer();
+TestUtils.mockReactUseCallback();
+TestUtils.mockReactUseRef();
+
+describe('Input IDs', () => {
+  /**
+   * Label only needs a htmlFor
+   */
+  it('input method correct props from type "label"', () => {
+    const [, input] = useFormState(null, { withIds: true });
+    expect(input.label('name')).toEqual({
+      htmlFor: expect.any(String),
+    });
+  });
+
+  it('input method has an "id" prop', () => {
+    const [, input] = useFormState(null, { withIds: true });
+    expect(input.text('name')).toHaveProperty('id', expect.any(String));
+  });
+
+  it('generates unique IDs for inputs with different names', () => {
+    const [, input] = useFormState(null, { withIds: true });
+    const { id: firstId } = input.text('firstName');
+    const { id: lastId } = input.text('lastName');
+    expect(firstId).not.toBe(lastId);
+  });
+
+  it('generates unique IDs for inputs with the same name and different values', () => {
+    const [, input] = useFormState(null, { withIds: true });
+    const { id: freeId } = input.radio('plan', 'free');
+    const { id: premiumId } = input.radio('plan', 'premium');
+    expect(freeId).not.toBe(premiumId);
+  });
+
+  it('sets matching IDs for inputs and labels', () => {
+    const [, input] = useFormState(null, { withIds: true });
+    const { id: inputId } = input.text('name');
+    const { htmlFor: labelId } = input.label('name');
+    expect(labelId).toBe(inputId);
+  });
+
+  it('sets matching IDs for inputs and labels with non string values', () => {
+    const [, input] = useFormState(null, { withIds: true });
+    const { id: inputId } = input.checkbox('name', 0);
+    const { htmlFor: labelId } = input.label('name', 0);
+    expect(labelId).toBe(inputId);
+  });
+
+  it('sets a custom id when formOptions.withIds is set to a function', () => {
+    const customInputFormat = jest.fn((name, value) =>
+      value ? `form-${name}-${value}` : `form-${name}`,
+    );
+    const [, input] = useFormState(null, { withIds: customInputFormat });
+
+    // inputs with own values (e.g. radio button)
+
+    const radioProps = input.radio('option', 0);
+    expect(radioProps.id).toEqual('form-option-0');
+    expect(customInputFormat).toHaveBeenCalledWith('option', '0');
+
+    const radioLabelProps = input.label('option', 0);
+    expect(radioLabelProps.htmlFor).toEqual('form-option-0');
+    expect(customInputFormat).toHaveBeenNthCalledWith(2, 'option', '0');
+
+    // inputs with no own values (e.g. text input)
+
+    const textProps = input.text('name');
+    expect(textProps.id).toEqual('form-name');
+    expect(customInputFormat).toHaveBeenLastCalledWith('name');
+
+    const textLabelProps = input.label('name');
+    expect(textLabelProps.htmlFor).toEqual('form-name');
+    expect(customInputFormat).toHaveBeenNthCalledWith(3, 'name');
+  });
+
+  it('does not return IDs when formOptions.withIds is set to false', () => {
+    const [, input] = useFormState();
+    const nameInputProps = input.checkbox('name', 0);
+    const nameLabelProps = input.label('name', 0);
+    expect(nameInputProps).not.toHaveProperty('id');
+    expect(nameLabelProps).not.toHaveProperty('htmlFor');
+  });
+});