Page under construction

Heads up that this page is still under construction and is in early stages. Feedback on the flow of this doc and any missing information is welcome.

Background

Using the layering components here allows you to build overlay components (components that float over the top of other components) that are aware of their layering context, and automatically stack correctly.

This is important because:

• we want to be able to create components that exist inside portals, but stack correctly on top of their parents
• components may be used inside modals, and we want to ensure that they can stack over the top of the modal
• we want to avoid having to manually specify z-indices in components, which increases reusability

Kaleidoscope support

Auto-stacking is available for many Kaleidoscope components that have overlays; setting the autoStack prop to true for:

• Toolbar
• Tooltip
• Popover
• OptionMenu

will automatically infer the z-index that it is currently rendered in, and set the z-indices appropriately.

Example usage

Below is a complex example of several Kaleidoscope components that stack automatically over the top of each other.

Note the use of the autoStack prop set on each of the stacked components.

Editable example
() => {
  const [inputFocussed, setInputFocussed] = React.useState(false);

  const [variableMenuOpen, setVariableMenuOpen] = React.useState(false);

  const textInputRef = React.useRef();

  return (
    <Popover
      button={(buttonProps) => (
        <Button type="secondary" {...buttonProps}>
          Edit ROI formula
        </Button>
      )}
      autoStack
    >
      <h2 className="text-h4">Configure the ROI calculator</h2>
      <Toolbar
        visible={inputFocussed || variableMenuOpen}
        element={textInputRef.current}
        positionType={ToolbarPositionType.Element}
      >
        <OptionMenu button={
          <ToolbarButton
            icon={<Variables />}
            tooltip={{content: "Add variables"}}
            onClick={() => {
              setVariableMenuOpen(!variableMenuOpen)
            }}
          />
        }>
          {["A", "B", "C"].map(v => (
          <OptionMenuItem
            onClick={() => {
              setVariableMenuOpen(false);
            }}
            key={v}
          >
            Variable {v}
          </OptionMenuItem>
          ))}
        </OptionMenu>
      </Toolbar>
      <TextInput
        label="Formula"
        multiline
        onFocus={() => setInputFocussed(true)}
        onBlur={() => setInputFocussed(false)}
        ref={textInputRef}
      />
    </Popover>
  )
}
() => {
  const [inputFocussed, setInputFocussed] = React.useState(false);

  const [variableMenuOpen, setVariableMenuOpen] = React.useState(false);

  const textInputRef = React.useRef();

  return (
    <Popover
      button={(buttonProps) => (
        <Button type="secondary" {...buttonProps}>
          Edit ROI formula
        </Button>
      )}
      autoStack
    >
      <h2 className="text-h4">Configure the ROI calculator</h2>
      <Toolbar
        visible={inputFocussed || variableMenuOpen}
        element={textInputRef.current}
        positionType={ToolbarPositionType.Element}
      >
        <OptionMenu button={
          <ToolbarButton
            icon={<Variables />}
            tooltip={{content: "Add variables"}}
            onClick={() => {
              setVariableMenuOpen(!variableMenuOpen)
            }}
          />
        }>
          {["A", "B", "C"].map(v => (
          <OptionMenuItem
            onClick={() => {
              setVariableMenuOpen(false);
            }}
            key={v}
          >
            Variable {v}
          </OptionMenuItem>
          ))}
        </OptionMenu>
      </Toolbar>
      <TextInput
        label="Formula"
        multiline
        onFocus={() => setInputFocussed(true)}
        onBlur={() => setInputFocussed(false)}
        ref={textInputRef}
      />
    </Popover>
  )
}

APIs

There are two core APIs we currently have to add functionality beyond autoStack on individual components.

• Layer - for creating new autostacking components, and setting manual layers
• AngularOverlayProvider - for creating a layer that's compatible with our Angular overlay pattern

These use React's Context feature under the hood to store z-indices, but we intentionally do not export the underlying context.

Layer

The Layer component can be used to:

• create new components that stack above the current component (this is what Kaleidoscope components use under the hood to auto-stack)
• shim onto an existing layout by setting the offset prop, for when you are working with existing layers or need to set z-indices for some components manually

Creating a new component that stacks

A good example of a component that utilises the Layer under the hood to auto-apply a z-index is the Toolbar component.

Example usage of Layer to shim across legacy z-indices

Here, we have a blue rectangle with a manually set z-index, and a toolbar that is rendered inside of it.

Without autostacking of the toolbar and a Layer with an offset equivalent to the z-index of the blue rectangle, it would be behind the blue rectangle.

Editable example
() => {
  const paragraphRef = React.useRef();
  const [showToolbar, setShowToolbar] = React.useState(false);
  const [autostackToolbar, setAutostackToolbar] = React.useState(true);
  return (
    <>
      <div style={{position: "absolute", zIndex: 5, background: "lightblue", height: "150px", width: "250px", padding: "var(--space-m)"}}>
        <p style={{margin: "var(--space-m) 0"}} ref={paragraphRef}>Manually positioned layer</p>
        <Button onClick={() => setShowToolbar(true)}>Show toolbar</Button>
        <Checkbox
            item={{id: "abc123", value: "abc123", label: "Autostack toolbar"}}
            isSelected={autostackToolbar}
            onChange={() => setAutostackToolbar(!autostackToolbar)}
         />
        <Layer offset={5}>
          {() => (
            <Toolbar visible={showToolbar} positionType={ToolbarPositionType.Element} element={paragraphRef.current} autoStack={autostackToolbar}>
                <ToolbarButton
                  icon={<Variables />}
                  tooltip={{content: "Add variables"}}
                  onClick={() => {
                    setVariableMenuOpen(!variableMenuOpen)
                  }}
                />
            </Toolbar>
          )}
        </Layer>
      </div>

      // Spacer div
      <div style={{height: "200px"}}></div>
    </>
  )
}
() => {
  const paragraphRef = React.useRef();
  const [showToolbar, setShowToolbar] = React.useState(false);
  const [autostackToolbar, setAutostackToolbar] = React.useState(true);
  return (
    <>
      <div style={{position: "absolute", zIndex: 5, background: "lightblue", height: "150px", width: "250px", padding: "var(--space-m)"}}>
        <p style={{margin: "var(--space-m) 0"}} ref={paragraphRef}>Manually positioned layer</p>
        <Button onClick={() => setShowToolbar(true)}>Show toolbar</Button>
        <Checkbox
            item={{id: "abc123", value: "abc123", label: "Autostack toolbar"}}
            isSelected={autostackToolbar}
            onChange={() => setAutostackToolbar(!autostackToolbar)}
         />
        <Layer offset={5}>
          {() => (
            <Toolbar visible={showToolbar} positionType={ToolbarPositionType.Element} element={paragraphRef.current} autoStack={autostackToolbar}>
                <ToolbarButton
                  icon={<Variables />}
                  tooltip={{content: "Add variables"}}
                  onClick={() => {
                    setVariableMenuOpen(!variableMenuOpen)
                  }}
                />
            </Toolbar>
          )}
        </Layer>
      </div>

      // Spacer div
      <div style={{height: "200px"}}></div>
    </>
  )
}

Note that offset is an additive value. For example, rendering a Layer with an offset of 5 inside another Layer with an offset of 6 will add to a z-index 11 on the top Layer

AngularOverlayProvider

The AngularOverlayProvider component can wrap the root of a component tree that exists inside an Angular modal, to ensure any components using the layering context know that they should be placed above the Angular modal.

This is useful for ensuring Kaleidoscope components work in parts of our app that are using Angular modals, such as the saved block editor.