Reakit v1 roadmap

Hi guys,

Since last year I’ve been experimenting with different implementations and APIs for Reakit v1. I just published an alpha version that can be installed via npm install reakit@next and put together this sandbox so people can play with it.

Docs are far from being ready, but you can access pages like https://next.reakit.io/docs/popover, which have some examples.

I want to list here what has been done and what is left.

Main goals

• Remove dependency on styled-components

  The core package should have only absolutely necessary styles, and those should be inline.

  Done: There's almost zero styles, only `Backdrop`s and `Popover`s have default styles.

  See DialogBackdrop.

• Empower themes

  Even without a styling mechanism built in the core package, themes should be able to inject styles into Reakit components.

  Done: Introduced experimental "systems". They can hook into components and change their options and props, which means they can add `style`, `className` etc. The styling approach (CSS in JS, inline style, css files etc.) is up to the system.

  See reakit-system-bootstrap.

• useHooks

  The current containers should be replaced by hooks. Also, the library should expose a hook version for each component as a low-level API.

  Done: Every component has a hook that returns its props (`Button` -> `useButton`). Components have a very minimal implementation and use their respective hooks underneath.

  See Box/useBox.

• Focus on accessibility

  The main focus of the library should be accessibility. All components must be in compliance with WAI-ARIA spec.

  Done: Components now are fully accessible. Some have been renamed to conform to the spec.

  See Dialog.

---

The following sections are related to bugs or missing stuff that should be addressed before the official release.

Branding

• New logo

  Done: Logo by @leonardoelias

• Thumbnail

  A standard image for use in website's thumbnail, twitter cover etc. I'm thinking on a component showcase in perspective.

Repo

• Write migration guide

• Update CONTRIBUTING.md

  With new instructions.

Reakit

• Write prop descriptions

  There's a few props with /** TODO: Description **/ in the code.

  Done: ad742bc0211690b89333cf47889d43284a363926

• Add aria-descriptions for keyboard shortcuts

  Some components like Dialog have keyboard shortcuts that aren't announced by assistive technologies by default, like <kbd>Esc</kbd> to close the dialog.

• Improve Menu

  • Hover should focus menu items.
  • Hover should open submenus keeping focus on menu item disclosure.

  Done: cf7426f0cb35c2ed4a02308cc426d247b3145ad2

• Fix Dialog’s outside click when it’s on an element inside the disclosure

  The hideOnClickOutside feature of Dialog ignores clicks on DialogDisclosure, since it will hide the dialog anyway. However, clicking on elements inside the DialogDisclosure is still caught and this must be fixed.

  Done: 93072cb75d742bd9947141274d5127e4e3b6d606

• as/use

  The use prop introduced in v0.16.0 has been rolled back to the as prop. The main reason is that it now behaves the same as in other libraries, accepting a single component, and not an array anymore.

  For composing multiple components, there are now two options:

  1. Render props

  import { TooltipReference, ToolbarItem, Button } from "reakit";
  
  <TooltipReference>
    {referenceProps => (
      <ToolbarItem {...referenceProps}>
        {itemProps => (
          <Button {...referenceProps} />
        )}
      </ToolbarItem>
    )}
  </TooltipReference>
  

  1. Hooks

  import { useTooltipReference, useToolbarItem, Button, mergeProps } from "reakit";
  
  // hooks used internally by TooltipReference and ToolbarItem
  const referenceProps = useTooltipReference();
  const itemProps = useToolbarItem();
  
  <Button {...mergeProps(referenceProps, itemProps)} />
  

  Unlike as, both approaches work really well. They are only more verbose.

  as is full of bugs when used to combine components that share props (like Reakit components), since the first component will “consume” them and not pass to the other one. I guess it should be used only for changing the underlying HTML element. That’s probably something that should be addressed in the docs.

  This works in v0 because components don’t consume their props. They are passed down and filtered in the base component (Box). v1 doesn’t need this filter.

Website/docs

• Automatically inject prop types into README.md files

  I've been doing some tests here.

  Done: 3d3329e8a7b3fdc38ffc326d800e7213bd7768e4

• Write docs

• Design home page

  The playground on home should be tabbed, with different "files" and a more realistic example.

  

• Design docs page

  Unlike the current website, there should be only one page for documentation, with guide and components in the sidebar.

  There should be a secondary sidebar for content headings and other options (like Edit on GitHub).

  There should be space for "Ads by Carbon"

  

• Design playground

  

[StorytellerCZ]

@lluia Take a look on Reach menu: https://ui.reach.tech/menu-button

[lluia]

I’ll try to continue/finish the accessibility stuff for the PR I made for <Menu /> 👍🏻