npm package: @ngrdt/menu
Description: This package provides two desktop first components - nested menu `rdt-menu` which is activated by your own `rdt-button` and `rdt-menu-bar` which uses custom buttons.
Latest version: 0.0.99

# @ngrdt/menu

This package provides two desktop first components - nested menu `rdt-menu` which is activated by your own `rdt-button` and `rdt-menu-bar` which uses custom buttons.

The point of this library is to provide fully customizable and accessible menu compliant with ARIA standards, compatible with custom shortcuts as well as tab key, arrows etc according to [Mozilla guidelines](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/menubar_role).

## General usage

For menu to work you need to define and provide `rdt-button`. See component `ngrdt-demo/src/app/test-menu-button` for basic instructions on how to do that. This only applies to menu, not menu bar.


## Styling

Setting `background` and `color` properties directly is not recommended. Instead set CSS variables. You may use custom styles for menu bar or menu overlay for extra spacing, `border-radius`, icons etc.

For ergonomics you should always use different colors or borders for different states. Use semi transparent versions of one color if you don't know which colors to pick.

### State order

Menu items can be in various overlapping states. Here is order of importance:

1. focus - User navigates to button using arrows or `tab` key.
2. hover
3. expanded - Submenu opened by this item is currently active and visible.
4. route-active - Either menu itself or one of its submenus contains link to current page.

### Leveraging overriden CSS variables

Component styles are designed in a way which lets you use variables for multiple purposes.

```css
.menu-bar-item .menu-bar-item-content:hover {
    --rdt-menu-bar-item-background: var(--rdt-menu-bar-item-hover-background);
    --rdt-menu-bar-item-text-color: var(--rdt-menu-bar-item-hover-text-color);
    --rdt-menu-bar-item-border: var(--rdt-menu-bar-item-hover-border);
  }
```

For instance the default icons are made purely in CSS and use this pattern to always have the same color as the button label.

```css
.menu-bar-item-icon.rdt-menu-icon-down {
  width: 0;
  height: 0;
  border-left: var(--rdt-menu-default-icon-size) solid transparent;
  border-right: var(--rdt-menu-default-icon-size) solid transparent;
  border-top: var(--rdt-menu-default-icon-size) solid
    var(--rdt-menu-bar-item-text-color);
}
```

### Playground theme

I recommend using this theme to understand all different variables.

```css
:root {
  /*************************************************/
  /************** Menu overlay styles **************/
  /*************************************************/

  // Minimum width of menu overlay
  --rdt-menu-min-width: 12rem;

  // Border radius of menu overlay
  --rdt-menu-border-radius: 5px;

  // Background color of menu overlay - mainly color of horizontal padding.
  --rdt-menu-background: black;

  // Horizontal padding of menu overlay (above and below the menu items)
  --rdt-menu-padding-horizontal-padding: 0.75rem;

  // Box shadow of menu overlay
  --rdt-menu-box-shadow: 0px 5px 6px -3px rgba(0, 0, 0, 0.2),
    0px 9px 12px 1px rgba(0, 0, 0, 0.14), 0px 3px 16px 2px rgba(0, 0, 0, 0.12);

  // Margin of menu overlay (distance from bottom of menu (bar) button to top of menu overlay)
  // If you set higher value than 10, then adjust [hitboxMargin] accordingly.
  --rdt-menu-overlay-margin-x: 0px;
  --rdt-menu-overlay-margin-y: 5px;

  // Size of default arrows
  --rdt-menu-default-icon-size: 0.3rem;

  /**********************************************/
  /************** Menu item styles **************/
  /**********************************************/
  // These only change styles of items within popup. NOT the menu bar items.

  // Default menu item style
  --rdt-menu-item-background: white;
  --rdt-menu-item-text-color: black;
  --rdt-menu-item-padding: 0.5rem 1rem;
  --rdt-menu-item-border: none;
  --rdt-menu-item-outline: none;

  // Hover styles
  --rdt-menu-item-hover-background: green;
  --rdt-menu-item-hover-text-color: green;
  --rdt-menu-item-hover-border: none;
  --rdt-menu-item-hover-outline: none;

  // Expanded styles
  --rdt-menu-item-expanded-background: cyan;
  --rdt-menu-item-expanded-text-color: cyan;
  --rdt-menu-item-expanded-border: none;
  --rdt-menu-item-expanded-outline: none;

  // Focus styles
  --rdt-menu-item-focus-background: red;
  --rdt-menu-item-focus-text-color: red;
  --rdt-menu-item-focus-border: none;
  --rdt-menu-item-focus-outline: none;

  // Route active styles
  --rdt-menu-item-route-active-background: lightblue;
  --rdt-menu-item-route-active-text-color: lightblue;
  --rdt-menu-item-route-active-border: none;
  --rdt-menu-item-route-active-outline: none;

  // Disabled styles
  --rdt-menu-item-disabled-background: gray;
  --rdt-menu-item-disabled-text-color: gray;
  --rdt-menu-item-disabled-border: none;
  --rdt-menu-item-disabled-outline: none;

  /**********************************************/
  /************ Menu bar item styles ************/
  /**********************************************/

  --rdt-menu-bar-padding: 0 0.5rem;

  // Default menu bar item style
  --rdt-menu-bar-item-background: transparent;
  --rdt-menu-bar-item-text-color: black;
  --rdt-menu-bar-item-padding: 0.5rem;
  --rdt-menu-bar-item-border-radius: 5px;
  --rdt-menu-bar-item-border: none;
  --rdt-menu-bar-item-outline: none;
  --rdt-menu-bar-item-margin: 0 0.5rem;

  // Hover styles
  --rdt-menu-bar-item-hover-background: lightgreen;
  --rdt-menu-bar-item-hover-text-color: lightgreen;
  --rdt-menu-bar-item-hover-border: none;
  --rdt-menu-bar-item-hover-outline: none;

  // Expanded styles
  --rdt-menu-bar-item-expanded-background: blue;
  --rdt-menu-bar-item-expanded-text-color: blue;
  --rdt-menu-bar-item-expanded-border: none;
  --rdt-menu-bar-item-expanded-outline: none;

  // Focus styles
  --rdt-menu-bar-item-focus-background: orange;
  --rdt-menu-bar-item-focus-text-color: orange;
  --rdt-menu-bar-item-focus-border: none;
  --rdt-menu-bar-item-focus-outline: none;

  // Route active styles
  --rdt-menu-bar-item-route-active-background: pink;
  --rdt-menu-bar-item-route-active-text-color: pink;
  --rdt-menu-bar-item-route-active-border: none;
  --rdt-menu-bar-item-route-active-outline: none;

  // Disabled styles
  --rdt-menu-bar-item-disabled-background: gray;
  --rdt-menu-bar-item-disabled-text-color: gray;
  --rdt-menu-bar-item-disabled-border: none;
  --rdt-menu-bar-item-disabled-outline: none;
}
```