Reduce Boilerplate with new component functions

[NicholasBoll]

Overview

createComponent did a lot to reduce the Typescript required to create polymorphic components, but doesn't reduce boilerplate to create new components. Models have a lot of boilerplate Typescript. I'd like to introduce new components that reduce boilerplate and the amount of Typescript required. Find out more in our Compound Component Docs

Models

Models are responsible for state and events and are the shared between the subcomponents. It is the explicit interface that subcomponents use to communicate. A model's events have a contract - when an event is called, it will first call the event's guard (should* by convention) function, then the event's state-updating function, then the callback (on* by convention) function. It works like this:

const useMyModel = (config) = > {
  const [value, setValue] = React.useState('')

  const state = { value }
  const events = {
    updateValue(data: { value: string }) {
      if (!config.shouldUpdateValue?.(data, state)) {
        return;
      }
      setValue(data.value)
      config.onUpdateValue?.(data, state)
    }
  }
}

const model = useMyModel({
  shouldUpdateValue(data, state) {
    console.log('shouldUpdateValue', data.value)
    return true
  },
  onUpdateValue(data, prevState) {
    console.log('onUpdateValue', data.value)
  }
})

// later
model.events.updateValue({value: 'foo' })
// logs:
// 'shouldUpdateValue', 'foo'
// 'onUpdateValue', 'foo'
// model.state.value will be updated to 'foo' on next render

That extra tracking for guards and callbacks was a lot of boilerplate. Some utility functions were created to make it easier but had their own boilerplate. Typescript 4.1 introduces Template Literal Types that allowed us to create new utility functions that removed the boilerplate required for guards and callbacks.

Before

canvas-kit/modules/preview-react/form-field/lib/hooks/useFormFieldModel.tsx

Lines 1 to 62 in 6670776

	import {
	createEventMap,
	Model,
	ToModelConfig,
	useEventMap,
	useUniqueId,
	} from '@workday/canvas-kit-react/common';
	type FormFieldState = {
	/**
	* Optional flag to denote if this field has an error to display. When true the `FormField.Input` will have
	* `required` set to true, and usually some subcomponents will have a error color applied.
	* @default false
	*/
	hasError?: boolean;
	/**
	* Optional `id` provided to `FormField`'s subcomponents as HTML attributes:
	* - `FormField.Input` will set `aria-describedby` to `hint-${id}`
	* - `FormField.Input` will set `id` to `input-${id}`
	* - `FormField.Label` will set `htmlFor` to `input-${id}`
	* - `FormField.Hint` will set `id` to `hint-${id}`
	*
	* If a value is not provided, a unique id will be automatically created by `useUniqueId()`.
	* @default `useUniqueId()`
	*/
	id?: string;
	/**
	* Optional flag to denote if this field is required. When true the `FormField.Input` will have
	* `required` set to true, and an asterisk will be appended to the `FormField.Label`.
	* @default false
	*/
	isRequired?: boolean;
	};
	type FormFieldEvents = {};
	export type FormFieldModel = Model<FormFieldState, FormFieldEvents>;
	const formFieldEventMap = createEventMap<FormFieldEvents>()({
	guards: {},
	callbacks: {},
	});
	export type FormFieldModelConfig = FormFieldState &
	Partial<ToModelConfig<FormFieldState, FormFieldEvents, typeof formFieldEventMap>>;
	export const useFormFieldModel = (config: FormFieldModelConfig = {}): FormFieldModel => {
	const id = useUniqueId(config.id);
	const state = {
	hasError: config.hasError,
	isRequired: config.isRequired,
	id,
	};
	const events = useEventMap(formFieldEventMap, state, config, {});
	return {
	state,
	events,
	};
	};

Before we had to create types for *State, *Events, *Model, create an event map, *BaseConfig, Config, and use useEventMap for the model's events. And this doesn't solve the problem where a container component could have an element. In this case, the author would have to manually create an array of config keys to remove from props to get elemProps.

After

canvas-kit/modules/preview-react/form-field/lib/hooks/useFormFieldModel.tsx

Lines 1 to 42 in 47a167f

	import {createModelHook, useUniqueId} from '@workday/canvas-kit-react/common';
	export const useFormFieldModel = createModelHook({
	defaultConfig: {
	/**
	* Optional flag to denote if this field has an error to display. When true the `FormField.Input` will have
	* `required` set to true, and usually some subcomponents will have a error color applied.
	* @default false
	*/
	hasError: false,
	/**
	* Optional `id` provided to `FormField`'s subcomponents as HTML attributes:
	* - `FormField.Input` will set `aria-describedby` to `hint-${id}`
	* - `FormField.Input` will set `id` to `input-${id}`
	* - `FormField.Label` will set `htmlFor` to `input-${id}`
	* - `FormField.Hint` will set `id` to `hint-${id}`
	*
	* If a value is not provided, a unique id will be automatically created by `useUniqueId()`.
	* @default `useUniqueId()`
	*/
	id: '',
	/**
	* Optional flag to denote if this field is required. When true the `FormField.Input` will have
	* `required` set to true, and an asterisk will be appended to the `FormField.Label`.
	* @default false
	*/
	isRequired: false,
	},
	})(config => {
	const id = useUniqueId(config.id);
	const state = {
	hasError: config.hasError,
	isRequired: config.isRequired,
	id,
	};
	return {
	state,
	events: {},
	};
	});

The update is to drop the Typescript boilerplate and create a model's config with an object. There's defaultConfig and requiredConfig. The defaultConfig serves 2 purposes - provide default values that are easy to determine, and extract type information from the config value. requiredConfig is a little interesting though. Only the type is useful to the function and not the value.

const useMyModel = createModelHook({
  requiredConfig: {
    size: 1 // value is actually not used by anything
  }
})// ...

const model = useMyModel({
  size: 10 // Typescript knows this is required
})

If you need to use a type that isn't inferred by Typescript, you'll need to use the as keyword to cast to a narrower type.

const useMyModel = createModelHook({
  defaultConfig: {
    direction: 'vertical' as 'vertical' | 'horizontal' // Typescript infers `string`, but we're casting to `'vertical' | 'horizontal'`
  }
})// ...

If you want an optional config without a default, you'll have to cast the type to include undefined. This case isn't very common. Many times a default can be a falsey value instead and still get a type. For example, 0, false, or an empty string result in a falsey comparison but still have the correct inferred type.

const useMyModel = createModelHook({
  defaultConfig: {
    optional: undefined as string | undefined
  }
}) // ...

Container components

Container components are responsible for setting up model context for subcomponents. They may or may not represent an element.

Before:

canvas-kit/modules/preview-react/form-field/lib/FormField.tsx

Lines 1 to 58 in 6670776

	import React from 'react';
	import {createComponent, ExtractProps, useDefaultModel} from '@workday/canvas-kit-react/common';
	import {Stack, StackSpacing} from '@workday/canvas-kit-react/layout';
	import {
	useFormFieldModel,
	FormFieldModel,
	FormFieldModelConfig,
	useFormFieldOrientation,
	} from './hooks';
	import {FormFieldInput} from './FormFieldInput';
	import {FormFieldLabel} from './FormFieldLabel';
	import {FormFieldHint} from './FormFieldHint';
	export const FormFieldModelContext = React.createContext<FormFieldModel>({} as any);
	export interface FormFieldProps
	extends FormFieldModelConfig,
	Omit<ExtractProps<typeof Stack, never>, 'spacing'> {
	model?: FormFieldModel;
	/**
	* Children of the Text Input. Should contain a `<FormField.Input>`, a `<FormField.Label>` and an optional `<FormField.Hint>`
	*/
	children: React.ReactNode;
	/**
	* The direction the child elements should stack
	*/
	orientation: 'vertical' | 'horizontal';
	/**
	* Spacing between children elements
	* @default xxxs when vertical l when orientation is horizontal
	*/
	spacing?: StackSpacing;
	}
	export const FormField = createComponent()({
	displayName: 'FormField',
	Component: ({children, model, spacing, orientation, ...props}: FormFieldProps, ref) => {
	const {hasError, id, isRequired, ...elemProps} = props;
	const value = useDefaultModel(model, {hasError, id, isRequired}, useFormFieldModel);
	const layoutProps = useFormFieldOrientation(orientation);
	return (
	<FormFieldModelContext.Provider value={value}>
	<Stack ref={ref} {...layoutProps} {...elemProps}>
	{children}
	</Stack>
	</FormFieldModelContext.Provider>
	);
	},
	subComponents: {
	Input: FormFieldInput,
	Label: FormFieldLabel,
	Hint: FormFieldHint,
	},
	});

From this example shows a few main parts: Props interface, React.Context, and the component definition. The props needs to contain a model?: prop and extend the model's Config type. Then is must set up the model context and create a Provider in the render body. This is common to all container components with a model.

After:

Since all container components do the same thing, it is easier to create a custom utility function that does the boilerplate for us using a model hook as an input to both set up the model prop type and create a model context. Here's the after:

canvas-kit/modules/preview-react/form-field/lib/FormField.tsx

Lines 1 to 43 in 47a167f

	import React from 'react';
	import {createContainerComponent, ExtractProps} from '@workday/canvas-kit-react/common';
	import {Stack, StackSpacing} from '@workday/canvas-kit-react/layout';
	import {useFormFieldModel, useFormFieldOrientation} from './hooks';
	import {FormFieldInput} from './FormFieldInput';
	import {FormFieldLabel} from './FormFieldLabel';
	import {FormFieldHint} from './FormFieldHint';
	export interface FormFieldProps extends Omit<ExtractProps<typeof Stack, never>, 'spacing'> {
	/**
	* Children of the Text Input. Should contain a `<FormField.Input>`, a `<FormField.Label>` and an optional `<FormField.Hint>`
	*/
	children: React.ReactNode;
	/**
	* The direction the child elements should stack
	*/
	orientation: 'vertical' | 'horizontal';
	/**
	* Spacing between children elements
	* @default xxxs when vertical l when orientation is horizontal
	*/
	spacing?: StackSpacing;
	}
	export const FormField = createContainerComponent('div')({
	displayName: 'FormField',
	modelHook: useFormFieldModel,
	subComponents: {
	Input: FormFieldInput,
	Label: FormFieldLabel,
	Hint: FormFieldHint,
	},
	})<FormFieldProps>(({children, orientation, ...elemProps}, Element) => {
	const layoutProps = useFormFieldOrientation(orientation);
	return (
	<Stack as={Element} {...layoutProps} {...elemProps}>
	{children}
	</Stack>
	);
	});

The main differences is removing the model context reference from the container component file, and removing the Provider from the render function. Notice we've also removed ref. ref is provided on the elemProps object always. We now ensure ref is always there rather than depending on the elemPropsHook called. This gets rid of avoidable bugs.

Subcomponents

Subcomponents get their model from React's context and almost always have an elemPropsHook to get elemProps for the element in the render function. There was similar boilerplate to container components, but slightly different boilerplate.

Before

canvas-kit/modules/preview-react/form-field/lib/FormFieldInput.tsx

Lines 1 to 21 in 6670776

	import React from 'react';
	import {createComponent, ExtractProps, useModelContext} from '@workday/canvas-kit-react/common';
	import {Box} from '@workday/canvas-kit-react/layout';
	import {FormFieldModelContext} from './FormField';
	import {FormFieldModel, useFormFieldInput} from './hooks';
	export interface FormFieldInputProps extends ExtractProps<typeof Box, never> {
	model?: FormFieldModel;
	}
	export const FormFieldInput = createComponent('input')({
	displayName: 'FormField.Input',
	Component: ({model, ...elemProps}: FormFieldInputProps, ref, Element) => {
	const localModel = useModelContext(FormFieldModelContext, model);
	const props = useFormFieldInput(localModel, elemProps, ref);
	return <Box as={Element} {...props} />;
	},
	});

We can see again we need to handle the model prop and it's type. There's something weird about the model's context - it comes from the container component, but the container component imports this subcomponent creating a circular dependency. This issue resolves with Webpack, but may cause issues with other bundlers. We also have to use useModelContext and rename model to localModel to avoid linting errors... We could do better.

After

canvas-kit/modules/preview-react/form-field/lib/FormFieldInput.tsx

Lines 1 to 14 in 47a167f

	import React from 'react';
	import {createSubcomponent, ExtractProps} from '@workday/canvas-kit-react/common';
	import {Box} from '@workday/canvas-kit-react/layout';
	import {useFormFieldInput, useFormFieldModel} from './hooks';
	export const FormFieldInput = createSubcomponent('input')({
	displayName: 'FormField.Input',
	modelHook: useFormFieldModel,
	elemPropsHook: useFormFieldInput,
	})<ExtractProps<typeof Box, never>>((elemProps, Element) => {
	return <Box as={Element} {...elemProps} />;
	});

The createSubcomponent function allows us to focus more on the unique configuration of our component