npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

@solid-aria/menu

v0.2.0

Published

Primitives for building accessible menu component.

Downloads

5,023

Readme

@solid-aria/menu

pnpm turborepo size version stage

Menu displays a list of actions or options that a user can choose.

  • createMenu - Provides the behavior and accessibility implementation for a menu component.
  • createMenuTrigger - Provides the behavior and accessibility implementation for a menu trigger.

Installation

npm install @solid-aria/menu
# or
yarn add @solid-aria/menu
# or
pnpm add @solid-aria/menu

createMenu

Provides the behavior and accessibility implementation for a menu component.

Features

There is no native element to implement a menu in HTML that is widely supported. createMenu helps achieve accessible menu components that can be styled as needed.

ℹ️ Note: createMenu only handles the menu itself. For a dropdown menu, combine with createMenuTrigger.

  • Exposed to assistive technology as a menu with menuitem children using ARIA
  • Support for single, multiple, or no selection
  • Support for disabled items
  • Support for sections
  • Complex item labeling support for accessibility
  • Support for mouse, touch, and keyboard interactions
  • Tab stop focus management
  • Keyboard navigation support including arrow keys, home/end, page up/down
  • Automatic scrolling support during keyboard navigation
  • Typeahead to allow focusing items by typing text

How to use it

This example uses HTML <ul> and <li> elements to represent the menu with the first item disabled, and applies props from createMenu and createMenuItem.

import { ForItems, Item } from "@solid-aria/collection";
import { AriaMenuItemProps, AriaMenuProps, createMenu, createMenuItem } from "@solid-aria/menu";
import { ParentProps } from "solid-js";

function Menu(props: AriaMenuProps) {
  let ref: HTMLUListElement | undefined;

  // Get props for the menu element
  const { MenuProvider, menuProps, state } = createMenu(props, () => ref);

  return (
    <MenuProvider>
      <ul
        {...menuProps}
        ref={ref}
        style={{
          padding: 0,
          "list-style": "none",
          border: "1px solid gray",
          "max-width": "250px"
        }}
      >
        <ForItems in={state.collection()}>
          {item => (
            <MenuItem key={item().key} onAction={props.onAction}>
              {item().children}
            </MenuItem>
          )}
        </ForItems>
      </ul>
    </MenuProvider>
  );
}

function MenuItem(props: ParentProps<AriaMenuItemProps>) {
  let ref: HTMLLIElement | undefined;

  // Get props for the menu item element
  const { menuItemProps, isFocused, isDisabled } = createMenuItem(props, () => ref);

  return (
    <li
      {...menuItemProps}
      ref={ref}
      style={{
        background: isFocused() ? "gray" : "transparent",
        color: isFocused() ? "white" : null,
        padding: "2px 5px",
        outline: "none",
        cursor: isDisabled() ? "default" : "pointer"
      }}
    >
      {props.children}
    </li>
  );
}

function App() {
  return (
    <Menu onAction={key => alert(key)} aria-label="Actions" disabledKeys={["one"]}>
      <Item key="one">One</Item>
      <Item key="two">Two</Item>
      <Item key="three">Three</Item>
    </Menu>
  );
}

Menu sections

This example shows how a menu can support sections with separators and headings using props from createMenuSection. This is accomplished using three extra elements: an <li> to contain the heading <span> element, and a <ul> to contain the child items. This structure is necessary to ensure HTML semantics are correct.

import { ForItems, Item, Section } from "@solid-aria/collection";
import {
  AriaMenuItemProps,
  AriaMenuProps,
  AriaMenuSectionProps,
  createMenu,
  createMenuItem,
  createMenuSection
} from "@solid-aria/menu";
import { ParentProps, Show } from "solid-js";

function Menu(props: AriaMenuProps) {
  let ref: HTMLUListElement | undefined;

  // Get props for the menu element
  const { MenuProvider, menuProps, state } = createMenu(props, () => ref);

  return (
    <MenuProvider>
      <ul
        {...menuProps}
        ref={ref}
        style={{
          padding: 0,
          "list-style": "none",
          border: "1px solid gray",
          "max-width": "250px"
        }}
      >
        <ForItems in={state.collection()}>
          {section => (
            <MenuSection heading={section().title}>
              <ForItems in={section().childNodes}>
                {item => (
                  <MenuItem key={item().key} onAction={props.onAction}>
                    {item().children}
                  </MenuItem>
                )}
              </ForItems>
            </MenuSection>
          )}
        </ForItems>
      </ul>
    </MenuProvider>
  );
}

function MenuSection(props: ParentProps<AriaMenuSectionProps>) {
  const { itemProps, headingProps, groupProps } = createMenuSection(props);

  return (
    <li {...itemProps}>
      <Show when={props.heading}>
        <span
          {...headingProps}
          style={{
            "font-weight": "bold",
            "font-size": "1.1em",
            padding: "2px 5px"
          }}
        >
          {props.heading}
        </span>
      </Show>
      <ul
        {...groupProps}
        style={{
          padding: 0,
          "list-style": "none"
        }}
      >
        {props.children}
      </ul>
    </li>
  );
}

function MenuItem(props: ParentProps<AriaMenuItemProps>) {
  let ref: HTMLLIElement | undefined;

  // Get props for the menu item element
  const { menuItemProps, isFocused, isDisabled } = createMenuItem(props, () => ref);

  return (
    <li
      {...menuItemProps}
      ref={ref}
      style={{
        background: isFocused() ? "gray" : "transparent",
        color: isFocused() ? "white" : null,
        padding: "2px 5px",
        outline: "none",
        cursor: isDisabled() ? "default" : "pointer"
      }}
    >
      {props.children}
    </li>
  );
}

function App() {
  return (
    <Menu onAction={key => alert(key)} aria-label="Actions">
      <Section key="section1" title="Section 1">
        <Item key="section1-item1">One</Item>
        <Item key="section1-item2">Two</Item>
        <Item key="section1-item3">Three</Item>
      </Section>
      <Section key="section2" title="Section 2">
        <Item key="section2-item1">One</Item>
        <Item key="section2-item2">Two</Item>
        <Item key="section2-item3">Three</Item>
      </Section>
    </Menu>
  );
}

createMenuTrigger

Provides the behavior and accessibility implementation for a menu trigger.

Features

There is no native element to implement a menu in HTML that is widely supported. createMenuTrigger combined with createMenu helps achieve accessible menu components that can be styled as needed.

  • Exposed to assistive technology as a button with a menu popup using ARIA (combined with createMenu)
  • Support for mouse, touch, and keyboard interactions
  • Keyboard support for opening the menu using the arrow keys, including automatically focusing the first or last item accordingly

How to use it

This example shows how to build a menu button using createMenuTrigger, createButton, and createMenu.

The menu popup uses createMenu and createMenuItem to render the menu and its items. In addition, a <FocusScope> is used to automatically restore focus to the trigger when the menu closes. A hidden <DismissButton> is added at the start and end of the menu to allow screen reader users to dismiss it easily.

This example does not do any advanced popover positioning or portaling to escape its visual container.

import { createButton } from "@solid-aria/button";
import { ForItems, Item } from "@solid-aria/collection";
import { FocusScope } from "@solid-aria/focus";
import { createFocus } from "@solid-aria/interactions";
import {
  AriaMenuItemProps,
  AriaMenuProps,
  AriaMenuTriggerProps,
  createMenu,
  createMenuItem,
  createMenuTrigger
} from "@solid-aria/menu";
import { AriaOverlayProps, createOverlay, DismissButton } from "@solid-aria/overlays";
import { combineProps } from "@solid-primitives/props";
import { createSignal, FlowProps, JSX, ParentProps, Show } from "solid-js";

type MenuButtonProps = FlowProps<AriaMenuTriggerProps & AriaMenuProps & { label: JSX.Element }>;

function MenuButton(props: MenuButtonProps) {
  let ref: HTMLButtonElement | undefined;

  // Get props for the menu trigger and menu elements
  const { menuTriggerProps, menuProps, state } = createMenuTrigger({}, () => ref);

  // Get props for the button based on the trigger props from createMenuTrigger
  const { buttonProps } = createButton(menuTriggerProps, () => ref);

  return (
    <div style={{ position: "relative", display: "inline-block" }}>
      <button {...buttonProps} ref={ref} style={{ height: "30px", "font-size": "14px" }}>
        {props.label}
        <span aria-hidden="true" style={{ "padding-left": "5px" }}>
          ▼
        </span>
      </button>
      <Show when={state.isOpen()}>
        <MenuPopup
          {...props}
          {...menuProps}
          autofocus={state.focusStrategy()}
          onClose={() => state.close()}
        />
      </Show>
    </div>
  );
}

function MenuPopup(props: AriaMenuProps & AriaOverlayProps) {
  let ref: HTMLUListElement | undefined;

  // Get props for the menu element
  const { MenuProvider, menuProps, state } = createMenu(props, () => ref);

  // Handle events that should cause the menu to close,
  // e.g. blur, clicking outside, or pressing the escape key.
  let overlayRef: HTMLDivElement | undefined;
  const { overlayProps } = createOverlay(
    {
      onClose: props.onClose,
      shouldCloseOnBlur: true,
      isOpen: true,
      isDismissable: true
    },
    () => overlayRef
  );

  // Wrap in <FocusScope> so that focus is restored back to the
  // trigger when the menu is closed. In addition, add hidden
  // <DismissButton> components at the start and end of the list
  // to allow screen reader users to dismiss the popup easily.
  return (
    <MenuProvider>
      <FocusScope restoreFocus>
        <div {...overlayProps} ref={overlayRef}>
          <DismissButton onDismiss={props.onClose} />
          <ul
            {...menuProps}
            ref={ref}
            style={{
              position: "absolute",
              width: "100%",
              margin: "4px 0 0 0",
              padding: 0,
              "list-style": "none",
              border: "1px solid gray",
              background: "lightgray"
            }}
          >
            <ForItems in={state.collection()}>
              {item => (
                <MenuItem key={item().key} onAction={props.onAction} onClose={props.onClose}>
                  {item().children}
                </MenuItem>
              )}
            </ForItems>
          </ul>
          <DismissButton onDismiss={props.onClose} />
        </div>
      </FocusScope>
    </MenuProvider>
  );
}

function MenuItem(props: ParentProps<AriaMenuItemProps>) {
  let ref: HTMLLIElement | undefined;

  // Get props for the menu item element
  const { menuItemProps } = createMenuItem(props, () => ref);

  // Handle focus events so we can apply highlighted
  // style to the focused menu item
  const [isFocused, setIsFocused] = createSignal(false);
  const { focusProps } = createFocus({ onFocusChange: setIsFocused });

  const rootProps = combineProps(menuItemProps, focusProps);

  return (
    <li
      {...rootProps}
      ref={ref}
      style={{
        background: isFocused() ? "gray" : "transparent",
        color: isFocused() ? "white" : "black",
        padding: "2px 5px",
        outline: "none",
        cursor: "pointer"
      }}
    >
      {props.children}
    </li>
  );
}

function App() {
  return (
    <MenuButton label="Actions" onAction={key => alert(key)}>
      <Item key="copy">Copy</Item>
      <Item key="cut">Cut</Item>
      <Item key="paste">Paste</Item>
    </MenuButton>
  );
}

Internationalization

createMenu handles some aspects of internationalization automatically. For example, type to select is implemented with an Intl.Collator for internationalized string matching. You are responsible for localizing all menu item labels for content that is passed into the menu.

RTL

In right-to-left languages, the menu items should be mirrored. Ensure that your CSS accounts for this.

Changelog

All notable changes are described in the CHANGELOG.md file.