Forem: Hari Bhandari

Composing Events, Composing Refs

Hari Bhandari — Tue, 23 Jan 2024 04:31:46 +0000

Polymorphic types

If you are following me along, you may have noticed some bugs.

      <Accordion onClick={() =>{}} className='someClass'>
        <Accordion.Item onBlur={() => {}}>
          <Accordion.Button onClick={() => {}}>Button 1</Accordion.Button>
          <Accordion.Panel>Panel 1</Accordion.Panel>
        </Accordion.Item>

Here, even though our Accordion, Accordion.Item, Accordion.Button are essentially HTML elements, we will get type errors when we pass HTML attributes and synthetic event props, as shown above. Hardcoding all the HTML attributes and synthetic events as props is not the Typescript way. What we want here is a way to merge the props defined by us with the HTML-derived attributes/props.

For this typescript wizardry, I copied types from reach-ui/polymorphic package.

Checkpoint: 754d0d7ac0f48366ebdb9b26e70bf6b85a98cf66

Composing Events

In AccordionButton we have handled the onClick, onKeyDown events ourselves. What if the users using our component pass their event handlers?

export function composeEventHandlers<E>(
  theirEventHandler?: (event: E) => void,
  ourEventHandler?: (event: E) => void
) {
  return function handleEvent(event: E) {
    theirEventHandler?.(event);

    if (!(event as unknown as Event).defaultPrevented) {
      return ourEventHandler?.(event);
    }
  };
}

If the users provide their event handler, we call that event handler first and then call our event handler. If a user wishes to prevent our event handler from firing, they can simply do event.preventDefault() in their event handler.

Now, wrap the event handlers with composeEventHandler

function AccordionButton({ onClick, onKeyDown, ...})
    const handleKeyDown = (e) => {.....}

    const handleClick = (e) => {.....}
    ....
    return (
        <Comp
            onClick={composeEventHandlers(onClick, handleClick)}
            onKeyDown={composeEventHandlers(onKeyDown, handleKeyDown)}
            ...
}

Checkpoint fa99abd82b7ce8c3e10a87b77f40f706a968ede9

Composing Refs

In the Keyboard navigation section, I discarded the forwardedRef and used internal ref to maintain focus on the active accordion button. We need to handle the refs provided by users and the refs that we create.

If you check the type signature of ref, you can see something like this:

type Ref<T> = RefCallback<T> | RefObject<T> | null;

i.e. we can pass a callback function, or ref object from useRef in ref.

Infact,

const inputRef = useRef(null)
....
<input ref={inputRef} />

and

const inputRef = useRef(null)
...
<input ref={(node) => { inputRef.current = node }} />

are the same. All ref props are just functions. For more info regarding callback refs, check this nice blog post by Dominik

Assigning/merging multiple refs to a single DOM node will look something like this:

// Contrived example
const = DummyComponent({props}, forwadedRef) => {
    const ref1 = useRef(null)
    const ref2 = (node) => console.log(node)
    ...
    return (
        <h2
            ref={(node) => {
              ref1.current = node;
              ref2(node);
              forwardedRef.current = node;
            }} 
        >
            Dummy Component
        </ h2>
    )
})

If we extract this into a custom hook it will look something like this:

export function useComposedRefs<T>(...refs: PossibleRefs<T>[]) {
  return React.useCallback((node: T) => {
    refs.forEach((ref) => {
      if (typeof ref === "function") {
        ref(node);
      } else if (ref != null) {
        (ref as React.MutableRefObject<T>).current = node;
      }
    });
    // eslint-disable-next-line react-hooks/exhaustive-deps
  }, refs);
}

Checkpoint fbcccd29838e4e3c468f407c0c17c68c0285ac25

The End

Our Accordion is now complete.

If I were building a component library, it would be a mono repo, and I would use tools like turbo repo or yarn workspace. Each component would be a package, so if I need to use a component in some project I would have to install just the component rather than the entire library. Notably, Reach UI uses Turbo repo and Radix UI uses yarn workspace.

For documenting component variants, I would use Storybook. For testing, I'd use Jest and React Testing Library.

I hope this blog series inspired you to explore open-source software. Happy Coding 💻.

Accessibility

Hari Bhandari — Tue, 23 Jan 2024 04:30:18 +0000

For accessibility, we will follow w3org aria practices.

WAI-ARIA Roles, States, and Properties:

According to WAI/ARIA,

for a visible accordion panel the corresponding header button should have aria-expanded=true, and for a non-visible panel, aria-expanded=false
each accordion header should be contained in an element with role=button
The accordion header button element should have aria-controls set to the ID of the corresponding accordion panel

There are more aria guidelines and for more please check this link.

function Accordion(..) {
    const id = useId()
    ....
    <AccordionContext.Provder value={{accordionId: id, ...}}>
    ..
}
function AccordionItem(....) {
      const itemId = makeId(accordionId, index);
      const panelId = makeId("panel", itemId);
      const buttonId = makeId("button", itemId);
      //
    <Comp
        data-state="open" // "open" or "closed"
        data-disabled={disabled}
        data-disabled={disabled ? "" : undefined}
        data-read-only={readOnly ? "" : undefined}
    >
...
}
function AccordionButton(..) {
    ....
    return (
        <Com
            aria-controls={panelId}
            aria-expanded={state === AccordionStates.Open}
            ...
    />
}
function AccordionPanel(..) {
    <Comp
        role="region"
        aria-labelledby={buttonId}
        data-disabled={disabled || undefined}
        data-state={getDataState(state)}
/>
}

Here, along with the aria attributes I have added data-* attributes that can be used as CSS selectors. Unique IDs are being used for accessibility to point out related accordion buttons and panels.

Checkpoint 33715f20ee90cd5db009647ef747fabf48b0bd87

Keyboard navigation

For Keyboard navigation, we will implement the following feature:

(assuming the accordion is already focused)

Up Arrow: Move focus to the previous focusable accordion header
Down Arrow: Move focus to the next focusable accordion header
Home: Move focus to the first focusable accordion header
End: Move focus to the last focusable accordion header
Enter or Space: Open collapsed accordion panel and vice-versa
Tab: Move focus to the next focusable element
Shift + Tab: Move focus to the previous focusable element

For more info check WAI Aria Keyboard Interaction section

Breaking down the problem: if a user presses Up Arrow, we get the index of the previous focusable AccordionItem and the focus on its AccordionButton. If a user presses Down Arrow, we get the index of the next focusable AccordionItem and the focus on its AccordionButton. Since we already keep track of AccordionItems index in the Descendants map, we can also store the corresponding AccordionButton ref along with the index.

function AccordionItem(....) {
    const buttonRef = useRef<HTMLElement>(null);
    const index = useDescendant({ element: buttonRef.current });

    <AccordionItemContext.Provider value={{buttonRef, ....}} />
}

function AccordionButton(....) {
    const { buttonRef } = useAccordionItemContext()
    const { map } = useDescendantContext()

    const handleKeyDown = (e) => {
        // handle keyboard navigation
        ....
        map.current[elementId].props.element.focus()
    }
    return (
        <Comp ref={buttonRef} onKeyDown={handleKeyDown} ...../>
}

Here, the Descendants map.ref.current will look something like:

{
    'id1': { index: 0, props: { element: button#button--sdf..},
    'id2': { index: 1, props: { element: button#button--kj...},
...
}

Checkpoint 4ddd6a2c39c9e93b70732014948a316f1c568baa

Descendants pattern

Hari Bhandari — Tue, 23 Jan 2024 04:28:46 +0000

Up until now, we have been passing index in AccordionItem to keep track of each accordion item (children/descendants). It's time to get rid of them.

We need to find a way to get and keep track of each AccordionItem index in the Accordion component.

  const index = useRef(-1);
  ...
  <div ref={() => {
      index.current++;
      console.log(index.current, "first");
    }}>
    First
  </div>
  <div ref={() => {
      index.current++;
      console.log(index.current, "second");
    }}>
    Second
  </div>
  <div ref={() => {
      index.current++;
      console.log(index.current, "third");
    }}>
    Third
  </div>

If you check console, it will be

0 'first'
1 'second'
2 'third'

Here, we have an index counter, and with each div render we are increasing the index counter. If you check the console and correlate it with the corresponding div, the first div has an index of 0, the second div an index of 1, and the third div an index of 2.

We can apply the same logic to keep track of each AccordionItem index. By having an index counter in Accordion and incrementing the index every time AccordionItem is called/rendered.

const Accordion = forwardRef(function (
 ....
) {
  ....
  const indexCounter = useRef(-1); // descendants counter
  const descendantsMap = useRef<Record<string, number>>({}); // keep track of descends in format { 'id1': 0, 'id2': 1,...}

  const getIndex = useCallback((id: string) => {
    if (!descendantsMap.current[id]) {
      descendantsMap.current[id] = ++indexCounter.current;
    }
    return descendantsMap.current[id];
  }, []);

  const context = {
    ....
    getIndex,
  };

  return (
    <AccordionContext.Provider value={context}>
     ...
    </AccordionContext.Provider>
  );
});

const AccordionItem = forwardRef(function (
  ...
) {
  const { openPanels, getIndex } = useAccordionContext();

  const itemId = useRef<string>(useId());
  const [index, setIndex] = useState(-1);

  useLayoutEffect(() => {
    setIndex(getIndex(itemId.current));
  }, [getIndex]);

  .....
});

Here,

When an AccordionItem is mounted, it's assigned a unique ID and index of -1.
Subsequently, AccordionItem registers itself with getIndex. At this point, descendantsMap retrieves the ID of the AccordionItem, records that ID, and returns the index.
With each call to getIndex (with each render of AccordionItem), indexCounter increments by 1.
In this way descendantMap of Accordion will keep track of each AccordionItem and its index.

Checkpoint: 50c3a0b5f8d7c880b11f30080531b60aba8178ec

The descendant pattern can be applied to other components as well. So, we will extract it into separate hooks and providers.

const DescendantContext = createContext<DescendantProviderProps>(
  {} as DescendantProviderProps
);

export const Descendants = ({
  children,
  value,
}: {
  children: ReactNode;
  value: DescendantProviderProps;
}) => {
  value.reset();

  return (
    <DescendantContext.Provider value={value}>
      {children}
    </DescendantContext.Provider>
  );
};

export const useDescendants = () => {
  const indexCounter = useRef(0);
  const map = useRef<Record<string, any>>({});

  const getIndex = useCallback((id: string, props?: IgetIndexProps) => {
    const hidden = props ? props.hidden : false;
    if (!map.current[id]) {
      map.current[id] = { index: hidden ? -1 : indexCounter.current++ };
    }
    map.current[id].props = props;
    return map.current[id].index;
  }, []);

  // reset the counter and map
  const reset = useCallback(() => {
    indexCounter.current = 0;
    map.current = {};
  }, []);

  return { getIndex, map, reset };
};

export const useDescendant = (props?: Record<string, any>) => {
  const context = useContext(DescendantContext);
  const descendantId = useRef<string>();
  if (!descendantId.current) {
    descendantId.current = randomId();
  }

  const [index, setIndex] = useState(-1);

  useIsomorphicLayoutEffect(() => {
    setIndex(context?.getIndex(descendantId.current as string, props));
  }, []);

  return index;
};

Here, the logic implemented in Accordion and AccordionItem is kept inside the useDescendants hook and useDescendant hook, respectively. Additionally, a separate context for descendants is created. Here, we have created an open-source use-descendants hook library.

Checkpoint: 9dd86997b99951fa035be73230f8381d3ea189ba

Uncontrolled components, Controlled components

Hari Bhandari — Tue, 23 Jan 2024 04:26:59 +0000

Uncontrolled components are the components that manage their internal state independently. For eg; HTML <input /> manages its state, and is an uncontrolled component. If we provide value and manage/set the state it becomes controlled.

<input value={someValue} />

To clarify more, we can think of an uncontrolled component as a component whose state is not controlled/managed by the parent. While a controlled component is a component controlled by the parent through props.

<input /> // uncontrolled

<input defaultValue='John Doe' /> // uncontrolled

<input defaultValue='John Doe' onChange={doSomething} /> // uncontrolled

<input value='John Doe' /> // controlled

<input value={value} onChange={doSomething} /> // controlled

<input value={value} defaultValue="John doe" onChange={doSomething} />
// controlled, but not a good practice. Console Warning: Decide between using a controlled or uncontrolled input element and remove one of these props.

The uncontrolled initial value of a component is usually prefixed with default.

Our component should handle both controlled and uncontrolled states gracefully. But keep in mind that An instance of a component can be either controlled or uncontrolled, not both simultaneously. If both controlled and uncontrolled states are passed, the component becomes Controlled component and the uncontrolled states are discarded.

Accordion Props

index?: number | number[] // The index or array of indices for open accordion panels, should be used along onChange to create a controlled accordion
onChange?: (index: number) => void // callback that is fired when an accordion item's open state is changed.
collapsible?: boolean //Whether or not all panels of an uncontrolled accordion can be closed. Defaults to false.
defaultIndex:?: number | number[] // default value for open panel's index in an uncontrolled accordion. If collapsible is set to true, without a defaultIndex no panels will initially be open. Otherwise, the first panel at index 0 will initially be open.
multiple?: boolean // In uncontrolled accordion, multiple panels can be opened at the same time. Defaults to false
readOnly?: boolean // Whether or not an uncontrolled accordion is read-only i.e. the user cannot toggle its state. Default false

Here, the Accordion will take props to handle both controlled and uncontrolled states: defaultIndex, multiple, collapsible, readOnly, and onChange are the uncontrolled state props, while index is the controlled state props. Keep in mind that if onChange is provided it should get fired for both controlled state and uncontrolled state changes.

AccordionItem should add disabled?: boolean props to disable an accordion item from user interaction. Defaults to false.

For more info regarding the props, please check this Reach UI Accordion docs

const Accordion = forwardRef(function (
  {
    children,
    as: Comp = "div",
    defaultIndex,
    index: controlledIndex,
    onChange,
    multiple = false,
    readOnly = false,
    collapsible = false,
    ...props
  }: AccordionProps,
  forwardedRef
) {
....

const AccordionItem = forwardRef(function (
  {
    children,
    as: Comp = "div",
    disabled = false,
    ...props
  }: AccordionItemProps,
  forwardedRef
) {
....

Checkpoint: e20149f8f297add2fd03dc2064c961da5ea250e7

Handling uncontrolled state

First, we will handle the uncontrolled state (i.e. defaultIndex, multiple, collapsible, and not index, onChange)

For now, we will provide an index to each AccordionItem. This will be handled properly later in the Descendants section.

  <Accordion defaultIndex={[0, 1]} multiple collapsible>
    <Accordion.Item index={0}>   // <= index
      ....
    </Accordion.Item>
    <Accordion.Item index={1}>  // <= index
      ....
    </Accordion.Item>
      .... 
  </Accordion>

const Accordion = (...) => {
  const [openPanels, setOpenPanels] = useState(() => {
    // Set initial open panel state according to multiple, collapsible props
  });

  const onAccordionItemClick = (index) => {
    setOpenPanels(prevOpenPanels => { // updater logic})
  }

  const context = {
    openPanels,
    onAccordionItemClick
  };

  return (
    <AccordionContext.Provider value={context}>
     ....
    </AccordionContext.Provider>
  );
};

const AccordionItem = ({ index, ...props }) => {
  const { openPanels } = useAccordionContext();

  const state = openPanels.includes(index) ? 'open' : 'closed'

  const context = {
    index,
    state,
  };

  return (
    <AccordionItemContext.Provider value={context}>
        ....
    </AccordionItemContext.Provider>
  );
};

const AccordionButton = () => {
  const { onAccordionItemClick } = useAccordionContext();
  const { index } = useAccordionItemContext();

  const handleTriggerClick = () => {
    onAccordionItemClick(index);
  };

  return (
    <Comp
      ....
      onClick={handleTriggerClick}
    >
      {children}
    </Comp>
  );
};

const AccordionPanel = (...) => {
  const { state } = useAccordionItemContext();

  return (
    <Comp
      ....
      hidden={state === 'closed' }
    >
      {children}
    </Comp>
  );
});

Here,

The Accordion component manages the list of open panels and its updater function.
The list of open panels and its updater function is handled by the parent Accordion component.
AccordionButton updates the list of open panels in According using the updater function from the context
AccordionPanel hides the panel whose index is not included in the open panel list.

Checkpoint 4e43a301c322b8b2d7c6de5a6282700753353fa4

Controlled state

Handling the controlled state in our component is easy, as all the state handling would be done by the parent/consuming component.

const Accordion = forwardRef(function ({
+  index: controlledIndex,
+  onChange,
....
  const onAccordionItemClick = useCallback(
    (index: number) => {
+     onChange && onChange(index);

      setOpenPanels((prevOpenPanels) => {
       ...
  );

  const context = {
+    openPanels: controlledIndex ? controlledIndex : openPanels,
    .....
  };

Here, the controlled state controlledIndex overrides the uncontrolled state in openPanels as it should. Regarding onChange, it doesn't determine if our component is controlled or uncontrolled. onChange can be passed with or without the controlled index prop. The purpose of the onControlled prop is to inform the parent component about the changed state.

function App() {
  const [openAccordions, setOpenAccordion] = useState([0, 2]);

  const handleAccordionChange = (index: number) => {
    setOpenAccordion((prev) => {
      if (prev.includes(index)) {
        return prev.filter((i) => i !== index);
      } else {
        return [...prev, index].sort();
      }
    });
  };

  return (
    <>
      <Accordion index={openAccordions} onChange={handleAccordionChange}>
        <Accordion.Item index={0}>
          <Accordion.Button>Button 1</Accordion.Button>
          <Accordion.Panel>Panel 1</Accordion.Panel>
        </Accordion.Item>
        ...
      </Accordion>
    </>
  );
}

Checkpoint: ed4fcfc4d79c6b5148c1e7e4f484392f2abcaf23

If you check the code base of Radix UI, Reach UI they are using a custom hook (named useControlledState or similar) to handle both controlled and uncontrolled states.

Radix UI, useControllableState
Reach UI, useControlledState

The custom hook useControlledState will look something like this:

export function useControlledState(controlledValue, defaultValue) {
  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
  const effectiveValue =
    controlledValue !== undefined ? controlledValue : uncontrolledValue;

  const set = ((newValue) => {
      if (!controlledValue) {
        setUncontrolledValue(newValue);
      }
    }
  return [effectiveValue, set];
}

The signature of useControlledState is similar to useState. It takes an initial value (along with other things) and returns the current state and an updater function.
Here, for the controlled value, we are doing nothing and just returning it, while for the uncontrolled value, we are returning the state and state updater function.

The actual hook implementation looks like this:

export function useControlledState<T>({
  controlledValue,
  defaultValue,
  calledFrom = "A component",
}: UseControlledStateParams<T>): [T, React.Dispatch<React.SetStateAction<T>>] {
  const isControlled = controlledValue !== undefined;
  const wasControlledRef = useRef(isControlled);

  if (isDev()) {
    if (wasControlledRef.current && !isControlled) {
      console.warn(
        `${calledFrom} is changing from controlled to uncontrolled. Components should not switch from controlled to uncontrolled (or vice versa). Decide between using a controlled or uncontrolled value for the lifetime of the component.`
      );
    }
    if (!wasControlledRef.current && isControlled) {
      console.warn(
        `${calledFrom} is changing from uncontrolled to controlled. Components should not switch from uncontrolled to controlled (or vice versa). Decide between using a controlled or uncontrolled value for the lifetime of the component.`
      );
    }
  }

  const [uncontrolledValue, setUncontrolledValue] = useState(defaultValue);
  const effectiveValue =
    controlledValue !== undefined ? controlledValue : uncontrolledValue;

  const set: React.Dispatch<React.SetStateAction<T>> = useCallback(
    (newValue) => {
      if (!controlledValue) {
        setUncontrolledValue(newValue);
      }
    },
    []
  );
  return [effectiveValue, set];
}

Here, I have

wrapped the set state updater in useCallback to make it referentially equal when using it
log a warning if the component changes from controlled to uncontrolled and vice-versa in the dev environment. You may have noticed a similar kind of warning like A component is changing an uncontrolled input to be controlled..... For eg <input value={something} /> here if something changes from undefined to some string, <input /> changes from uncontrolled to controlled and this should not happen. So, we are logging a warning for this check in our hook. For more info regarding this, check this out

You can see a slightly different implementation of this hook in Adobe's React Aria/Spectrum here

Now, replace the useState in Accordion with this useControlledState hook.

Checkpoint: 52075e2eff2f4f9ffaf7bd865b24547df040346a

If you check other component libraries like Chakra UI, Radix UI, and others, useControlledState hook signature may be slightly different according to requirement:

export function useControlledState(controlledValue, defaultValue, onChange) {
  const [stateValue, setState] = useState(defaultValue);
  const effectiveValue = controlledValue !== undefined ? controlledValue : stateValue;

  const set = (newValue) => {
    if (onChange) {
      onChange(newValue);
    }
    setState(newValue);
  };

  return [effectiveValue, set];
}

React: Build your own composable, headless components

Hari Bhandari — Tue, 23 Jan 2024 04:24:51 +0000

Some time ago (maybe a year or two), in some podcast (maybe from Kent C. Dodds) I heard something along the lines of "Rich UI codebase has the best resource for learning react composition...".

What kind of name, "Rich Ui"? Is this supposed to be only used by rich people? 🤔 With a quick Google search (rich ui react), I found Reach UI.

Fast forward to a week ago, I cloned the Reach UI and Radix UI codebase and started exploring. Large codebases are always difficult to comprehend. With some digging around and reverse engineering, I was able to create the first component listed in the Reach UI docs, the Accordion.

In this blog series, I will reverse-engineer Reach UI Accordion (mostly) and Raxix UI Accordion, and build a headless, composable Accordion from scratch while documenting the progress. Although we are building an Accordion, the primary purpose of the blog is to explore how open-source composable components are built. The techniques and patterns you learn here will be useful when creating React components like Tabs, Menu, etc. and hence the title Build your own composable, headless component

Along the process we will learn something about:

component composition,
compound components,
descendants pattern (don't know if it's called a pattern),
controlled and uncontrolled components,
composing refs,
composing event handlers,
accessibility and keyboard navigations

Disclaimer: This tutorial is not intended for beginners in React. If you are not comfortable with context, states(useState, useRef), and effects (useEffect) you may find it challenging to follow along. Please note that the code presented here may not be suitable for production use.

This series can be beneficial if you are:

Trying to create your component library
Curious to learn how composable components are built in the OSS libraries like reach ui, radix-ui

God Component

In your job, when creating a component (accordion in this case), you may have done something like this:

const accordionData = [
    { id: 1, headingText: 'Heading 1', panel: 'Panel1 Content' },
    { id: 2, headingText: 'Heading 2', panel: 'Panel2 Content' },
    { id: 3, headingText: 'Heading 3', panel: 'Panel3 Content' },
]
const SomeComponent = () => {
    const [activeIndex, setActiveIndex] = useState(0)

    return (
        <div>
            <Accordion
                data={accordionData}
                activeIndex={activeIndex}
                onChange={setActiveIndex}
            />
        </div>
    )
}

function Accordion({ data, activeIndex, onChange }) {
    return (
        <div>
            {data.map((item, idx) => (
                <div key={item.id}>
                    <button onClick={() => onChange(idx)}>
                        {item.headingText}
                    </button>
                    <div hidden={activeIndex !== idx}>{item.panel}</div>
                </div>
            ))}
        </div>
    )
}

Suppose the requirement changes, and now you need to add support for an icon in the accordion button/ heading, some different styling, or some other requirements.

- function Accordion({ data, activeIndex, onChange }) {
+ function Accordion({ data, activeIndex, onChange, displaySomething, doNothing }) {
+ if (doNothing) return
  return (
    <div>
      {data.map((item, idx) => (
        <div key={item.id}>
          <button onClick={() => onChange(idx)}>
            {item.headingText}
+            {item.icon? (
+              <span className='someClassName'>{item.icon}</span>
+            ) : null}
          </button>
-          <div hidden={activeIndex !== idx}>{item.panel}</div>  
+          <div hidden={activeIndex !== idx}>
+            {item.panel}
+            {displaySomething}
+          </div>
        </div>
      ))}
    </div>
  )
}

With every changing requirement, you will need to refactor your "God Component" to meet the needs of the consuming components. And if you are building a component to be used in multiple projects with different requirements, or an OSS component library this kind of "God Component" approach will most likely fail. This is just a contrived example but it highlights the issues that can arise from using this approach.

Compound Components

So, what's a compound component? "Compound components" is a pattern for creating a meaningful component by putting together smaller nonsensical components.

Think of compound components like the <select> and <option> elements in HTML. Apart they don't do too much, but together they allow you to create the complete experience. The way they do this is by sharing an implicit state between the components. Compound components allow you to create and use components that share this state implicitly.— Kent C. Dodds

Some html examples:

<select>
    <option>Option1</option>
    <option>Option2</option>
</select>

<ul>
  <li>Item 1</li>
  <li>Item 2</li>
  <li>Item 3</li>
</ul>

<table>
    <tr>
    <thead>....
    <tbody>
        <tr>...
        <td>..
    ...
</table>

Using compound components, the accordion that we built above in the God component section would look something like this:

<Accordion>
    <AccordionItem>
        <AccordionButton>Heading 1</AccordionButton>
        <AccordionPanel>
            Panel 1
        </AccordionPanel>
    </AccordionItem>
    <AccordionItem>
        <AccordionButton>Heading 2</AccordionButton>
        <AccordionPanel>
           Panel 2
        </AccordionPanel>
    </AccordionItem>
    <AccordionItem>
        <AccordionButton>Heading 3</AccordionButton>
        <AccordionPanel>
           Panel 3
        </AccordionPanel>
    </AccordionItem>
</Accordion>

Here, using Accordion alone, or AccordionButton alone, won't work. To get a fully functional Accordion you would need to compose Accordion, AccordionItem, AccordionButton, AccordionPanel together as shown above.

Compound components can be created using either the combination of React.Children + React.cloneElement or the Context API. But React.Children + React.cloneElement combo is not as flexible, and its API is deprecated. So, we will be using the Context API.

Getting Started

Set up a react app using vite, or you can clone this repo and get started from the initial commit

File: Accordion.tsx

const Accordion = forwardRef(function (
  { children, as: Comp = "div", ...props }: AccordionProps,
  forwardedRef
) {
  return (
    <Comp {...props} ref={forwardedRef} data-hb-accordion="">
      {children}
    </Comp>
  );
});

const AccordionItem = forwardRef(function (
  { children, as: Comp = "div", ...props }: AccordionItemProps,
  forwardedRef
) {
  return (
    <Comp {...props} ref={forwardedRef} data-hb-accordion-item="">
      {children}
    </Comp>
  );
});

const AccordionButton = forwardRef(function (
  { children, as: Comp = "button", ...props }: AccordionButtonProps,
  forwardedRef
) {
  return (
    <Comp {...props} ref={forwardedRef} data-hb-accordion-button="">
      {children}
    </Comp>
  );
});

const AccordionPanel = forwardRef(function (
  { children, as: Comp = "div", ...props }: AccordionPanelProps,
  forwardedRef
) {
  return (
    <Comp {...props} ref={forwardedRef} data-hb-accordion-panel="">
      {children}
    </Comp>
  );
});

CheckPoint: 93875c6e51b3e4c063cd2cf017ddaf002785bfb6

Here, I have:

Created Accordion element components: Accordion, AccordionItem, AccordionButton, and AccordionPanel. These components will be used to compose the Accordion
Wrapped each Accordion Element Component in forwardRef to expose the DOM node of the respective Accordion Element. For more information regarding forward ref, check here.
as props representing an HTML element or a React component that will tell the Accordion what element to render. The default value of as used is div and for AccordionButton a button.
data-* attribute is used for each Accordion element component. This can be used as a CSS selector to provide styling or when writing tests for the component.

Now, the composed accordion will look something like this:

  <Accordion>
    <Accordion.Item>
      <Accordion.Button>Button 1</Accordion.Button>
      <Accordion.Panel>Panel 1</Accordion.Panel>
    </Accordion.Item>
    <Accordion.Item>
      <Accordion.Button>Button 2</Accordion.Button>
      <Accordion.Panel>Panel 2</Accordion.Panel>
    </Accordion.Item>
    <Accordion.Item>
      <Accordion.Button>Button 3</Accordion.Button>
      <Accordion.Panel>Panel 3</Accordion.Panel>
    </Accordion.Item>
  </Accordion>

To keep track of open/closed accordion items and manage state updates between these Accordion elements, we will use the Context API.

const AccordionContext = createContext({});
const AccordionItemContext = createContext({});

const useAccordionContext = () => {
  const context = useContext(AccordionContext);
  if (!context) {
    throw Error("useAccordionContext must be used within Accordion.");
  }
  return context;
};

const useAccordionItemContext = () => {
  const context = useContext(AccordionItemContext);
  if (!context) {
    throw Error("useAccordionItemContext must be used within AccordionItem.");
  }
  return context;
};
.......
const Accordion = forwardRef(function (
  .....  
  return (
    <AccordionContext.Provider value={{}}>
     .....
    </AccordionContext.Provider>
  );
});

const AccordionItem = forwardRef(function (
   .....  
  return (
    <AccordionItemContext.Provider value={{}}>
      ....
    </AccordionItemContext.Provider>
  );
});

CheckPoint: e26e87e8407a08949898f356d7d9c274c97e46a1

Here,

I have created two contexts AccordionContext, and AccordionItemContext, along with their respective useContext hooks: useAccordionContext, useAccordionItemContext
AccordionContext will be used for global accordion states like keeping track of open/closed panels, and the corresponding updater function. While AccordionItemContext will be used for individual accordion item states like if an accordion item is disabled, item index, etc.

Reach UI and Radix UI use their context package (a wrapper on Context API) to create contexts for the components, but I won't be doing that here. You can check it out here: Radix UI, Reach UI

Performance Testing with k6 - 02 - Multiple Tasks

Hari Bhandari — Wed, 05 May 2021 09:35:22 +0000

In the first part of this series we learnt about creating a very basic k6 test. In this tutorial we will create some more realistic and interesting tests.
For that we better have a real App to test. For simplicity and because I'm familiar with it I've chosen ownCloud, a file hosting and sharing
solution similar to Dropbox.

The easiest way to get a test ownCloud instance up and running is to use docker.

Just run: docker run -p 8080:8080 --name owncloud owncloud/server.

This magic docker run command should give you a fresh ownCloud installation that can be reached at http://localhost:8080.

There is one user pre-setup called admin with the super-secure password admin. You can login into the UI and upload files, create new users, share files and folders, etc.
After having played a bit with ownCloud itself, let's get back to k6.

Test Creating file

Create a file (script.js) and add the following contents

import http from 'k6/http'
import encoding from 'k6/encoding'
import { check } from 'k6'
import { uuidv4 } from 'https://jslib.k6.io/k6-utils/1.0.0/index.js'

export let options = {
  iterations: 100,
  vus: 10
}

export default function() {
  const fileName = `${uuidv4()}.txt`
  const url = `http://localhost:8080/remote.php/webdav/${fileName}`
  const body = 'some content'
  const headers = {
    'Authorization': 'Basic ' + encoding.b64encode('admin:admin'),
    'Content-Type': 'application/x-www-form-urlencoded'
  }

  const response = http.request('PUT', url, body, { headers: headers })
  check(response, {
    'status is 201': (r) => r.status === 201 || 204
  })
}

Here, in the options object we are providing iterations: 100 and vus: 10 i.e. 100 test runs will be divided among 10 vus. To specify how iterations is divided among vus we can provide executor options. For more details about executors check https://k6.io/docs/using-k6/scenarios/executors/
We are sending a PUT request to the owncloud endpoint to create a file. For authorization header we are using user admin with password admin that we created. So, basically the 10 vus in options will be using admin user authorization
Since it's not possible to create multiple files with the same name in owncloud, we are using uuid in fileName

Test deleting file

import http from 'k6/http'
import encoding from 'k6/encoding'
import { check } from 'k6'
import { uuidv4 } from 'https://jslib.k6.io/k6-utils/1.0.0/index.js'

export let options = {
  iterations: 100,
  vus: 10
}

const createFile = url => {
  const body = 'some content'
  const headers = {
    'Authorization': 'Basic ' + encoding.b64encode('admin:admin'),
    'Content-Type': 'application/x-www-form-urlencoded'
  }

  const response = http.request('PUT', url, body, { headers: headers })
  check(response, {
    'status is 201': (r) => r.status === 201 || 204
  })
}

const deleteFile = (url) => {
  const headers = {
    'Authorization': 'Basic ' + encoding.b64encode('admin:admin')
  }
  const response = http.request('DELETE', url, undefined, { headers: headers })
  check(response, {
    'status is 204': (r) => r.status === 204
  })
}

export default function() {
  const fileName = `${uuidv4()}.txt`
  const url = `http://localhost:8080/remote.php/webdav/${fileName}`
  createFile(url)
  deleteFile(url)
}

Here, we are adding code to delete a file. Also, I have separated the logic for file creation and deletion into two separate functions createFile and deleteFile.

Settings Stages

We can ramp up/down the VU level during the test using stages The options.stages property allows you to configure ramping behaviour.

...
export let options = {
  stages: [
    { duration: '30s', target: 20 },
    { duration: '1m30s', target: 10 },
    { duration: '20s', target: 0 }
  ]
}
...

First Stage(30s duration): Initially at the start will have 1 VU and then k6 will linearly ramp up from 1VU to 20VUs during the span of 30 seconds.
Second Stage(1m30s duration): At the start of this stage we will have 20Vus from the first stage, but it will linearly ramp down to 10Vus at the end of the duration of this stage.
Third Stage(20s duration): During this stage 10Vus from the second stage will linearly ramp down to zero at the end of 20 seconds.

Now if we run the test using k6 run script.js:

As shown in above screenshot our test runs for a total duration of 2m20s(30s + 1m30s + 20s), while vus max is 20 (end of the first stage) and it's min is 1 which happens at the beginning of the first stage.

Performance Testing with k6 - 01 - Getting Started

Hari Bhandari — Wed, 05 May 2021 09:32:17 +0000

Let's suppose your website/web-app/blog gets popular overnight ( Imagine Elon Musk tweeting about your web app ) and there's a massive spike in the number of visitors/users
accessing your web app. This swelling traffic can overwhelm the web server causing an unintentional distributed denial of service (DDOS) attack. This is a nightmare scenario as people cannot access your web-app.

Now, how do we determine how many users your backend infrastructure can handle?

To answer that, and other performance questions, we have a couple of great performance-testing tools available out there. One of them is k6

What is k6?

k6 is a free and open-source load testing tool written in Go programming language. But you don't need to know Go to write tests using k6.
If you are familiar with the basics of ES2015/ES6, you won't have any headache writing k6 tests.

Installation

To install k6 in your local machine follow the instructions provided here https://k6.io/docs/getting-started/installation/

I am using ubuntu 18.04 but even if you are using another operating system you can follow along.

Your first test:

k6 is based on the concept of virtual users (VUs) that is supposed to simulate the real-time traffic and then execute the script in parallel.

As a rule of thumb, each k6 script must contain at least an exported default function, unless you are using Scenarios.
This default function is the entry point for the VUs, similar to the main() function in Java and other programming languages.

Let's write a simple k6 script that makes a GET request to a test website:

Disclaimer: Make sure load testing is allowed by your web host so that you don't violate their terms of service. In our example, we will be testing a test website https://test.loadimpact.com/

Create a file test.js and add the following content:

import { check } from "k6";
import http from "k6/http";

export default function() {
  let response = http.get("https://test.loadimpact.com/");
  check(response, {
    "is status 200": (r) => r.status === 200
  });
};

Unlike many other JavaScript runtimes, most of the operations in k6 are synchronous i.e. no need to use callbacks and promises.
For example;

http.get(...).then(res =>....)

let response = await http.get(....)

is not needed and we can use synchronous code mentioned in test.js of our example.

Running tests

Then run the k6 script using this command:

k6 run test.js

By default, if nothing is specified (as in the above command), k6 runs a script with only 1 VU and for 1 iteration only. It is useful for debugging, but it's not load testing.

Here a virtual user sends a get request to https://test.loadimpact.com/ and the response status code is checked.

Now we'll run a k6 test with more than 10 virtual users and for a duration of 5 seconds:

 k6 run --vus 10 --duration 5s test.js

From the above screenshot:

checks = 100%: all of the test run passed
vus = 10: 10 virtual users (as provided in the run command)
iterations = 126: total number of iterations the test ran. This may vary with each run as we didn't specify the iterations ourself

Now, instead of doing --vus ... --durations .... --iterations.... we can also export an options object to set any options that we want. For example:

export let options = {
    vus: 10,
    duration: 5s
};
export default function() { .... }

What's next?

That all was nice and easy, but not very realistic. It does not matter if you want to test a web frontend or an API, just sending a GET requests does not simulate the user's behavior. In the next parts of this series, we will learn more about k6 in a more realistic way.

CodeceptJs Setup & BDD

Hari Bhandari — Tue, 02 Jun 2020 08:04:31 +0000

CodeceptJS is a modern end to end testing framework. In this tutorial we will setup BDD end-to-end testing using CodeceptJS along with Puppeteer.

Requirements:

npm
An app to write tests to: If you already have an app you can use that OR you can just clone this basic todo app https://github.com/taniarascia/react-hooks and follow along

If you cloned the above app please browse inside the cloned directory and run the following commands to set it up:

npm install
npm run start

CodeceptJS Setup

Browse inside your project directory
1) Install CodeceptJS with Puppeteer

npm install codeceptjs puppeteer --save-dev

2) Initialize CodeceptJS in the current directory by running:

npx codeceptjs init
You will be asked some questions as shown below:

When asked to select helpers choose Puppeteer but in other cases take the default (i.e. hit Enter).

3) The above initialization of codeceptjs will create some files:

codecept.conf.js : main configuration file
_test.js
jsconfig.json
steps.d.ts
steps_file.js
output: a directory that will contain screenshot of failed tests

We only need condecept.conf.js as it is the main configuration file. The rest of the files are not needed so you can delete them.

4) We can enable Gherkin for the current project by running:

npx codeceptjs gherkin:init

It will add a gherkin section to the codecept.conf.js file and create directories for features and step definitions.

5) Now edit codecept.conf.js file according to your testing infrastructure so it looks similar to:

  exports.config = {
    output: './output', // screenshot directory and contains screenshot of failed tests
    helpers: {
      Puppeteer: {
        url: 'http://localhost:3000', // host url
        show: true,
        windowSize: '1200x900'
      }
    },
    gherkin: {
      features: './features/*.feature',   // feature files location
      steps: ['./step_definitions/steps.js']  // step definitions location
    },
    plugins: {
      screenshotOnFail: { // if true take screenshot of failed scenarios
        enabled: true
      },
      retryFailedStep: { // if true rerun failed tests
        enabled: true
      }
    },
    name: 'react-hooks' // name of the application folder
  }

Note: React applications by default run on port 3000. So, if you cloned the application from Requirements section don't forget to include the port in url section of Puppeteer object.

6) After you create a feature file and write some scenarios, to generate gherkin snippets run:

`npx codeceptjs gherkin:snippets`

Writing Tests with CodeceptJS

1) Let's create a basic test scenario to add a user

File: features/basic.feature

  Feature: add user
    As a user
    I want to be able to create other users
    So that different people can have individual data

    Scenario: signup a user
      Given the user has browsed to the homepage
      When the user adds user with name "Hari Bhandari" and username "hari" using the webUI
      Then user with name "Hari Bhandari" and username "hari" should be listed on users table

2) After you wrote some scenarios, to generate gherkin snippets run:

npx codeceptjs gherkin:snippets

Now edit the generated step definitions so that it looks like:

File: step_definitions/steps.js

  const { I } = inject();

  Given('the user has browsed to the homepage', () => I.amOnPage('/'));

  When('the user adds user with name {string} and username {string} using the webUI', (name, username) => {
      I.waitForVisible("//input[@name='name']");
      I.fillField("name", name)
      I.fillField("username", username)
      I.click("//button[contains(text(),'Add new user')]")
  });

  Then('user with name {string} and username {string} should be listed on users table', (name, username) => {
      I.see(name);
      I.see(username);
  });

In CodeceptJS tests are written as a sequence of actions performed by an actor. So, the I object is an actor, an abstraction for a testing user. The I is also a proxy object for the currently enabled Helper(Puppeteer).

So basically in the above step definitions, I browse to the homepage(http://localhost:3000), wait until the name input field is visible, fill the fields, click on the Add new user button and check if the user I added is listed on the View users table.

3) To run the test and see step-by step output use --steps option:

`npx codeceptjs run --steps`

To see not only the business steps but the actual performed steps use the --debug flag:

`npx codeceptjs run --debug`

By using the `debug` flag you can see the execution of step definitions and it is very useful for debugging purposes.

Page object

A page object is basically a wrapper around an HTML page, or a fragment of the page that provides an access to the state of the underlying page/fragment. A page object provides a separation between the test code and the locators and makes our code more DRY.

If an application has different pages (login, admin, etc.) you should use a page object. Even though our example app doesn't have different pages we are going to create a page object.

To get more ideas about page objects and page objects in CodeceptJS check the following links:

https://github.com/SeleniumHQ/selenium/wiki/PageObjects

https://codecept.io/pageobjects/

CodeceptJS can generate a sample template for a page object with the command:

npx codeceptjs gpo

In the above screenshot, I am creating a page object with the name dashboardPage.js

Now, include the page object section in your config file. codecept.conf.js should now look similar to:

  exports.config = {
        .....
        include: {
        Page: './pages/dashboardPage.js'  // page object location
      },
      .....
  }

Edit pages/dashboardPage.js so that it looks like:

  const { I } = inject();

  module.exports = {
      elements: {
          addNewUserButton: '//button[contains(text(),"Add new user")]',
          name: String('name'),
          username: String('username')
      },
      addUser(name, username) {
          I.waitForVisible(this.elements.addNewUserButton);
          I.fillField(this.elements.name, name)
          I.fillField(this.elements.username, username)
          I.click(this.elements.addNewUserButton)
      }
  }

CodeceptJS provides flexible strategies for locating elements. Here, I have used xpath for
Add new user button and semantic locator(name) for name and username.

Edit the When step in step_definitions/steps.js to include the pageObject's function

File: step_definitions/steps.js

  ....
  const dashboard = require('../pages/dashboardPage');
  ....

  When('the user adds user with name {string} and username {string} using the webUI', (name, username) => {
      dashboard.addUser(name, username)
  });
  ...

Now, run your test again with npx codeceptjs run --steps

In this way we have set up BDD end-to-end testing using CodeceptJS. Happy Testing.

How to use selenium in docker?

Hari Bhandari — Thu, 23 Apr 2020 08:29:48 +0000

What is docker?

Can you recall how many times you face an issue where code runs in another developer's machine but doesn't work on yours? Docker at a very basic level resolves this issue of an application working on one platform and not working on some other platform.

Docker is a tool which is used to automate the deployment of applications in lightweight containers so that applications can work efficiently in different environments. It does this by virtualizing the operating system of the computer on which it is installed and running. A docker container is basically a software package that consists of all the dependencies required to run an application.

Why docker?

Let’s say you have three different nodejs applications that you plan to host on a single server. Each of these applications makes use of a different version of nodejs and mongodb, as well as the associated libraries and dependencies, which differ from one application to another.

Now, we cannot host all three applications on the same machine as different versions of nodejs and other dependencies are required.

We can solve this problem either by having three different machines, or a single machine, which is powerful enough to host and run three virtual machines on it.

But both solutions are quite cumbersome. In this case, docker is an efficient and cost-effective solution to this problem. With docker, we are able to run all the three apps in a separate container with its own dependencies and libraries, all within a single machine. Containers are completely isolated environments that can have their own processes, services, and network interfaces just like virtual machines except they all share the same OS kernel.

Docker Installation

Follow the installation instructions given in https://docs.docker.com/install/ to install docker according to your operating system. But, I suggest you use Linux, preferably Ubuntu for this blog/tutorial as later we will use a docker network command that works only on Linux.

And follow docker post-install instructions given usually at the end of the "installation instructions" page to create a docker group.

Selenium

Usually, for running tests using selenium we download selenium standalone server JAR file and chrome driver and start selenium server with a command which usually looks like:

java -jar selenium-server-standalone-<selenium version>.jar -port <port-no>

Now, let's suppose we want to run tests with different browsers or various browser versions. Here, we have to install all the browsers and the versions we want to test on our development environment. We also need to find the corresponding selenium and the webdriver version for it. Ever tried to install multiple versions of the same browser on your machine?

In this case too, docker comes to the rescue.

Selenium provides Docker images out of the box to test with one or several browsers. The images spawn a Selenium server and a browser underneath. It can work with different browsers.

Now to run selenium using docker we just need to run selenium/standalone-chrome or selenium/standalone-firefox as:

docker run -d -v /dev/shm:/dev/shm selenium/standalone-chrome-debug

Here

-d runs the container in the background (detached)
-v /dev/shm:/dev/shm adds a volume mount to use the host’s shared memory. There is no requirement for a volume mount but it is recommended.

Once you run the command, Docker will download the selenium image and run the container straight away (port: 4444).

Networking using the host network

When the docker container is running it has its own localhost which is relative to its container and it has no awareness of localhost running on the host OS. Because of this, we cannot access the selenium container at localhost:4444. Also, the selenium container won't be able to access the apps running on localhost of the host OS.

How do we solve this problem?

The answer is simple - we use docker option --network="host" in docker run command. If we use the host network mode for a container, that container’s network stack is not isolated from the docker host, and the container does not get its own IP-address allocated. Now, the selenium container will be available on port 4444 on the localhost.

Now, the docker run command should basically look like:

docker run -d --network="host" -v /dev/shm:/dev/shm selenium/standalone-chrome-debug

docker run -d --network host -v /dev/shm:/dev/shm selenium/standalone-chrome-debug

The host networking driver only works on Linux hosts and is not supported on Docker Desktop for Mac, Docker Desktop for Windows, or Docker EE for Windows Server.

Run test from the docker host, using selenium within a docker container

Requirements:

chrome
nodejs and yarn
linux (to use --network="host" in docker run command)

Clone this basic todo app: https://github.com/HariBhandari07/todo-with-tests
This is a single page todo app with basic acceptance tests

Install the necessary dependencies using the following command inside the project directory:

yarn install
Start the development server at localhost:3000 using command:

yarn start
Run selenium in docker with

docker run --network="host" -v /dev/shm:/dev/shm selenium/standalone-chrome-debug
Run the acceptance tests using command:

yarn acceptance-tests

The full script to run the acceptance tests is specified in scripts object of package.json file inside the project's root directory.

The above commands run our test at localhost:3000.

After you run the above command, you can see the tests running on the selenium docker container by using VNC.

If you are on Ubuntu:

open Remmina (Remmina is a Remote Desktop Client and comes installed with Ubuntu)
choose VNC and enter localhost on the address bar
enter secret as the password

Now, you should see the test running on VNC