Development principles

Camp components are intended to be used throughout the platform by various teams. Each implementation of a Camp component will take advantage of its capabilities in different ways, and sometimes push the boundaries of what that component was originally built to accomplish.

Here are some core principles we’ve discovered that help a component step up to this challenge.

Embrace the community

When building components, always reach out to the front-end community beforehand and gather as much input as possible before solidifying the approach, properties needed, etc.

In general, get feedback as much as possible.

These efforts will not only result in better design system resources, they will engage the community and help foster adoption and advocacy.

Controlled or uncontrolled

const searchableDropdown = () => {
    const options = ['Fu', 'Bar'];
    const [selectedOption, setSelectedOption] = useState();
 
    return (
        <Dropdown
        options={options}
        optionToString={(option) => option || '')}
        onSelect={(option) => setSelectedOption(option)}
        selected={selectedOption}
        isSearchable
        />
    );
};

Of course, you’d ideally also provide a searchPlaceholder and noSearchResultsMessage.

This is great, it will use the optionToString value for each option and filter matches, as a developer I don’t have to manage state or anything else. Yay.

Now imagine I’m implementing something more complex, like a dropdown where you can pick a contact email, but you only see a subset of the massive list of emails and search needs to be performed on the server. The Camp Dropdown component needs to provide you the controls to do that, and it does!

const searchableUsersListDropdown = () => {
    const [options, setOptions] = useState(initialOptions);
    const [selectedOption, setSelectedOption] = useState();
    const [searchText, setSearchText] = useState('');
 
    const handleSearch = async (value) => {
        setSearchText(value);
        // Query the server for user emails including 'value'
        const searchedUsers = await searchUsers(value);
        setOptions(searchedUsers);
    };
 
    return (
        <Dropdown
        options={options}
        optionToString={(option) => option.email || '')}
        onSelect={(option) => setSelectedOption(option)}
        selected={selectedOption}
        isSearchable
        controlSearchValue
        onSearch={handleSearch}
        searchValue={searchText}
        />
    );
};

Be on the lookout when developing a component for any ways that you can provide helpful defaults while staying mindful that the developer needs the ability to control almost any or all state properties.

Forced accessibility

Camp components must utilize best practices when it comes to accessibility, that goes without saying. In some cases, the developer utilizing a Camp component may be required to provide some unique context to the implementation for the sake of accessibility. For example, when implementing a Multi-Action Button, context needs to be provided to assistive technology users as to what the additional button is for.

<MultiActionButton
    triggerLabel="More options"
    {...props}
>
    Edit
</MultiActionButton>

The triggerLabel is required via Typescript and is solely to provide an aria-label to the “more options” button, which sits with it’s sibling button in a div with role="group". If this prop weren’t required, it likely wouldn’t get used. Typescript comments and documentation can help communicate why it’s required. We also don’t simply provide our best guess on what that label should be because of changing context and translations, which leads us to our next principle.

Surface localization controls

Context can be a fickle thing when it comes to component implementation and how label, alt, descriptive, etc. text should read. Therefore, any language-specific strings in Camp components must be surfaced as props without defaults.

For example, we may be tempted to make the placeholder text of the search input used Dropdown component always read a translation of “Search”. This can cause problems when dropdown options are more stylized and perhaps the search input only searches one aspect of the options, like “name” in a list of users that also displays user emails, in which case you’d likely rather have placeholder text that reads “Search by Name”. Things get even trickier when accounting for all the possible languages supported by ActiveCampaign. Languages differ in how they treat context, so it’s best practice to surface these strings to the developer and enter that string into the translation pipeline with appropriate context.

Provide granular test ID props

Camp components are often used to display data in intricate ways, and testing these can become difficult, especially when considering that the specific markup or class names used should be relatively mutable.

In order to make testing easier, consider the various pieces a developer may want to easily get access to and provide specific test ID props for each. The default data-testid however, should always be assigned to the root node of the component.

For example, the Multi-Action Button component provides various test id props.

<MultiActionButton
    {...props}
    data-testid="group-container-id"
    buttonTestId="edit-button-id"
    triggerTestId="more-options-button-id"
    popoverTestId="more-options-popover-id"
>
    Edit
</MultiActionButton>

Now if the component’s markup changes, as long as these test id properties persist, tests that check for these elements should continue to pass.

Document rigorously

Quality documentation will save others, as well as yourself, lots of time when needing to use a component or simply gather context. A component, or any piece of the design system, is not completed until it has been documented. This is crucial to the longevity of the system and UI consistency at ActiveCampaign.

Support others

In order for Camp to succeed at ActiveCampaign, we must support others as they utilize Camp components and design tokens. Having this concept as top of mind will push us to provide better documentation, will build adoption and advocacy from others, and provide us insights into how better to build the system.

Smaller common patterns

Classnames must forward to the Root element

When developing a component, sometimes the additional props are spread to a child element. For example, in the Input component, additional props are passed to the form input, which allows the developer to pass props to the HTML input like value, etc.

const NewInput = ({
    label,
    ...props
}) => {
    return (
        <Container>
        <Label>{label}</Label>
        <input {...props} />
        </Container>
    );
};
 
const Container = styled('div')();
 
export default styled(NewInput)() as Input;

In this case, we need to be sure classname is extracted from ...props and specifically assigned to the containing element so that any styled properties are applied appropriately.

const NewInput = ({
    label,
    className
    ...props
}) => {
    return (
        <Container className={className}>
        <Label>{label}</Label>
        <input {...props} />
        </Container>
    );
};
 
const Container = styled('div')();
 
export default styled(NewInput)() as Input;

Now, when a developer uses this component and assigns values for shorthand styles like mx, color, etc. or even when providing styles with styles, when they’re bundled into a single class name they’ll be assigned to the parent div and function appropriately.

‘onClick’ and ‘handleClick’

This one may be obvious to some but blew my mind when someone finally explained it to me.

on should be used when an event is being called, and handle should be used to handle the actions that result.

const MyComponent = () => {
    const handleClick = (result) => console.log('I am handling the click', result);
 
    return (
         <Button onClick={handleClick}>I call for something to be handled when clicked</Button>
    );
};