vaadin/vaadin-app-layout

The Web Component for a common application layout. Part of the Vaadin components.

<vaadin-app-layout>

⚠️ Starting from Vaadin 20, the source code and issues for this component are migrated to the vaadin/web-components monorepository. This repository contains the source code and releases of <vaadin-app-layout> for the Vaadin versions 10 to 19.

<vaadin-app-layout> is a Web Component providing a quick and easy way to get a common application layout structure done, part of the Vaadin components.

Live Demo ↗ | API documentation ↗

<vaadin-app-layout>
  <vaadin-drawer-toggle slot="navbar touch-optimized"></vaadin-drawer-toggle>
  <h3 slot="navbar touch-optimized">Application Name</h3>
  <vaadin-tabs orientation="vertical" slot="drawer">
    <vaadin-tab>
      <a href="/profile">
        <iron-icon icon="lumo:user"></iron-icon>
        Profile
      </a>
    </vaadin-tab>
    <vaadin-tab>
      <a href="/contact">
        <iron-icon icon="lumo:phone"></iron-icon>
        Contact
      </a>
    </vaadin-tab>
  </vaadin-tabs>
  <div>Page content</div>
</vaadin-app-layout>

Installation

The Vaadin components are distributed as Bower and npm packages. Please note that the version range is the same, as the API has not changed. You should not mix Bower and npm versions in the same application, though.

Unlike the official Polymer Elements, the converted Polymer 3 compatible Vaadin components are only published on npm, not pushed to GitHub repositories.

Polymer 2 and HTML Imports compatible version

Install vaadin-app-layout:

bower i vaadin/vaadin-app-layout --save

Once installed, import it in your application:

<link rel="import" href="bower_components/vaadin-app-layout/vaadin-app-layout.html">
<link rel="import" href="bower_components/vaadin-app-layout/vaadin-drawer.toggle.html">

Polymer 3 and ES Modules compatible version

Install vaadin-app-layout:

npm i @vaadin/vaadin-app-layout --save

Once installed, import it in your application:

import '@vaadin/vaadin-app-layout/vaadin-app-layout.js';
import '@vaadin/vaadin-app-layout/vaadin-drawer-toggle.js';

Getting Started

Vaadin components use the Lumo theme by default.

To use the Material theme, import the correspondent file from the theme/material folder.

Entry points

• The components with the Lumo theme:

  theme/lumo/vaadin-app-layout.html theme/lumo/vaadin-drawer-toggle.html

• The components with the Material theme:

  theme/material/vaadin-app-layout.html theme/material/vaadin-drawer-toggle.html

• Aliases for theme/lumo/vaadin-app-layout.html theme/lumo/vaadin-drawer-toggle.html

  vaadin-app-layout.html vaadin-drawer-toggle.html

Running demos and tests in browser

1. Fork the vaadin-app-layout repository and clone it locally.

2. Make sure you have npm installed.

3. When in the vaadin-app-layout directory, run npm install and then bower install to install dependencies.

4. Make sure you have polymer-cli installed globally: npm i -g polymer-cli.

5. Run polymer serve --open, browser will automatically open the component API documentation.

6. You can also open demo or in-browser tests by adding demo or test to the URL, for example:

• http://127.0.0.1:8080/components/vaadin-app-layout/demo
• http://127.0.0.1:8080/components/vaadin-app-layout/test

Running tests from the command line

1. When in the vaadin-app-layout directory, run polymer test

Following the coding style

We are using ESLint for linting JavaScript code. You can check if your code is following our standards by running npm run lint, which will automatically lint all .js files as well as JavaScript snippets inside .html files.

Contributing

• Make sure your code is compliant with our code linters: npm run lint
• Check that tests are passing: polymer test
• Submit a pull request with detailed title and description
• Wait for response from one of Vaadin components team members

License

Apache License 2.0

Vaadin collects development time usage statistics to improve this product. For details and to opt-out, see https://github.com/vaadin/vaadin-usage-statistics.

vaadin-app-layout's Issues

mention breaking changes in 2.0.0+ release notes

https://github.com/vaadin/vaadin-app-layout/releases/tag/v2.0.0

Supports vaadin-router

• Works with Vaadin Router
• Easy to take into use in a Polymer project

The relevant parts of the component should be exposed as stylable parts

• It is possible to style the “navigation bar” (containing the branding and menu areas)
• It is possible to style the menu area
• It is possible to style the branding area
• It is possible to style the content area

Inheritance is not supported for `--vaadin-app-layout-navbar-height`

Custom CSS properties are expected to inherit, i. e.:

:root {
  --vaadin-app-layout-navbar-height: 100px;
}

should result in 100px navbar.

Actual: not inherited, results in default height instead.

App Layout with drawer slot

Next major version for vaadin-app-layout
Includes slots for drawer and navigation bar
Has API to change precedence mode between drawer and navigation bar as shown in following mockups:

• Full height drawer
  
• Full width navigation bar
  

Close drawer when navigation occurs in mobile

App Layout in mobile screen shows the drawer as overlay, hiding the content.

When the user opens the drawer and clicks in an item which triggers a navigation (that don't trigger a full page reload), then drawer keeps itself opened, and the user would have to tap on the backdrop in order to close it.

It would be a better UX if the drawer would be closed by the component when such thing happens.

See this behavior in action below:

I am not sure if this can be easily achieved in the WC part, but probably could be implemented in the flow element, so I decided to create it here first. If this turns out to be rather too complicated, then we can move this issue to vaadin-app-layout-flow repo.

Material: drawer toggle does not match the style guide

Expected

Specs: https://material.io/design/components/app-bars-top.html#specs

Implementation: https://material-components.github.io/material-components-web-catalog/#/component/top-app-bar

Actual

Problems

• Icon size is not correct (dimensions are too big)
• Hover outline should be round and have 48px size
• Padding is not aligned

Code: https://glitch.com/edit/#!/app-layout-material?path=app.js:18:0
Demo: https://app-layout-material.glitch.me/

Remove navbar slot wrappers?

Having every navbar slot wrapped in a dedicated part is surely very flexible for the theming, as it allows the individual alignment and spacing control.

However, not having wrapper slots over the flex children brings more sizing and alignment control for developers. For example, the following would be possible without having to define a theme module:

<!-- Stretch my logo vertically -->
<img slot="branding" style="align-self: stretch;">

<!-- Center the tabs -->
<vaadin-tabs slot="menu" style="margin: auto;"></vaadin-tabs>

Undocumented and untested `secondary` part

The secondary part is not tested and not listed anywhere in the docs or demos. Should it be removed altogether, perhaps?

Rename drawer-first property

drawer-first does not give a good idea of what it does.

The proposal is to rename it to a String property that accepts two values primary-section="navbar|drawer".

DX test getting started experience

• The component is successfully taken into use (the component is visible in the app) in a frontend starter (from vaadin.com/start) project in under 5 minutes.

• The component is successfully taken into use (the component is visible in the app) in a Flow starter (from vaadin.com/start) project in under 5 minutes

• 3 test subjects

Show how to create a real menu using app-layout

The demos currently demonstrate that you should create a menu as

  <vaadin-tabs slot="menu">
    <vaadin-tab theme="icon-on-top">
      <iron-icon icon="vaadin:home"></iron-icon>
      Page 1
    </vaadin-tab>
    <vaadin-tab theme="icon-on-top">
      <iron-icon icon="vaadin:list"></iron-icon>
      Page 2
    </vaadin-tab>
</vaadin-tabs>

While this looks nice, the menu does not work because there are no <a href> links in it. If you do add <a> tags, you have two options:

1. Wrap the <vaadin-tab> element so you have

<a>
  <vaadin-tab theme="icon-on-top">
    <iron-icon icon="vaadin:home"></iron-icon>
    Page 1
  </vaadin-tab>
</a>

This renders the options correctly, the link works but keyboard navigation (right-left arrows) and highlighting of vaadin-tabs no longer works. Navigating between the items using tab works and a menu item can be activated using enter.

2. Wrap the contents of <vaadin-tab>

<vaadin-tab theme="icon-on-top">
  <a>
    <iron-icon icon="vaadin:home"></iron-icon>
    Page 1
  </a>
</vaadin-tab>

This breaks the theme (icon is not on top). Keyboard navigation (left-right) works but selecting/navigating using enter does not.

Please add a demo showing how you should use app-layout in a real application. A workaround using click listeners is not preferable as you then prevent opening the item in a new tab etc.

Keep drawer state on resize

Scenario

• Drawer is opened
• User resize window until it hits the overlay breakpoint and drawer gets closed
• User resize window back to its original position

Expected

• Drawer restore its previous state and appears opened

Actual

• Drawer is kept closed

Minor Material theme UI tweak

👎

👍

[part="navbar"] {
  z-index: 1;
}

Release 1.0.0-beta1 and create a checklist

Force flex layout

App Layout makes assumes that the host element is always display: flex.

If a user uses <vaadin-app-layout> as the root element of a design in Vaadin Designer, the tool will override the host with display: block, causing unexpected results.

We could prevent this by enforcing display: flex !important.

New Component <vaadin-app-layout>

Add Material support

Menu item should support text, href, iron-icon and having an on-click

• Menu items supports text, href and
• You can specify on-click for a menu item

IE11: Updating custom CSS variables

And updating those at the right time when sizes can be measured

Improve documentation

• Add a comment about usage of the default slot for content
• do not include the functional API, like connectedCallback etc.
• Add notes about using the component on the root level (Where in the DOM it is supposed to be used)

Create secondary slot in navbard

Secondary slot would add a possibility for the user to add an extra component at the right side of the navbar.

Should/could provide a way to define the behavior in small screens.

iPhone initial load drawer is always open and it closes when scrolling

Lumo drawer toggle has arbitrary size and doesn't look nice

This is the issue similar to #106 but now for Lumo.

Let me suggest an improvement which is expected to make drawer toggle look better.

:host {
  width: var(--lumo-size-l);
  height: var(--lumo-size-l);
  min-width: auto;
  margin: 0 var(--lumo-space-m);
  padding: 0;
  background: transparent;
}

See the original code in my webpack starter.

Will submit a PR and update visual tests accordingly.

Verify component is compatible with screen readers

• Announce page content after navigation

Make part=content take the full available height

Though the component takes the full height, part="content" is not forced to take the available height.

So if developer declares a <vaadin-app-layout> like this:

<style>
  .page {
    display: flex;
  }
  
  .content {
    flex: 1; 
  }
  
  .menu {
    background: lightgrey;
    width: 200px;
  }
</style>
<!-- ... -->
<vaadin-app-layout>
  <h3 slot="branding">Application Name</h3>
  <vaadin-tabs slot="menu">
      <vaadin-tab>Page 1</vaadin-tab>
      <vaadin-tab>Page 2</vaadin-tab>
  </vaadin-tabs>
  <div class="page">
    <div class="content">
      Page content
    </div>
    <div class="menu">
      <ul>
        <li>Side menu item</li>
        <li>Side menu item</li>
        <li>Side menu item</li>
        <li>Side menu item</li>
      </ul>
    </div>  
  </div>
</vaadin-app-layout>

This would be what they get:

iPhone landscape doesn’t use full width (doesn’t go into notch area in iPhone X)

HTML API Documentation

• Document methods, how to style.
• Update README

It should be possible to show branding text or an image in the app menu

Navbar does not apply vertical alignment to items

As a user, I expect vertical alignment in navbar to be supported out of the box.

Currently, part="navbar" is a flex container but it doesn't set alitn-items: center.
Instead we introduce another flex container in the demos, which looks weird:

<style>
  nav {
    display: flex;
    align-items: center;
  }
</style>

Let's consider adding align-items: center to the navbar part for simplicity and better DX.

Make the component P3 compatible

Dark Theme is broken in Safari and Edge

Steps to reproduce

1. Create view that extends from AppLayout and have dark Lumo theme
2. Add tabs.

@Route
@PWA(name = "Project Base for Vaadin Flow with Spring", shortName = "Project Base")
@Theme(value = Lumo.class, variant = Lumo.DARK)
public class MainView extends AppLayout {

    public MainView(@Autowired MessageBean bean) {
        Tabs tabs = new Tabs(new Tab("Home"), new Tab("About"));
        tabs.setOrientation(Tabs.Orientation.HORIZONTAL);
        addToNavbar(tabs);
    }

}

In Chrome tabs have dark background:

but in Safari and Edge tabs have light background:

Material theme in IE11 adds a extra space under the menu

It's not sure whether this is a problem with vaadin-app-layout styles or vaadin-tabs that could be handled in the material theme configuration for vaadin-app-layout.

This is how it looks like in IE11:

This is how it looks like in Edge (and other browsers):

touch-optimized docs and demo improvements

• App layout in mobile demo shows touch-optimized content on top
• Improve docs for the slot.

ARIA attributes, drawer should act as modal when overlay mode

Screen readers should announce the content on the drawer when it's open on overlay mode

Hard-coded branding size constrains

Currently, in the core styles, there are hard-coded size constrains for the branding: max-width: 20%; max-height: 100%;.

This could become problematic for certain scenarios, for example, produce accidental text wrapping or downscaling for long images. Applying arbitrary browser scaling for logos often results in a blurry or rough-edged output.

I would suggest to not constrain the developer-provided content whenever possible. Sure any size exceeds and overlaps are problematic, but in case if they are not shown, it is even harder to notice and fix that. The height constrain makes more sense for the navbar content, but the width constrain — looks like it could be removed altogether.

Another idea to consider is to have the navbar height: auto;, so that the height is automatically determined from the content. This guarantees to not produce any height overlaps (since the height would be increased instead), and we would have less magic numbers to maintain.

Related issue: the branding image used in the demo does not have a size defined. With the built-in constrains removed, the image is so big, it exceeds the navbar height and overlaps the content. Suggestion: specify width and height attributes on the image with a suitable size in the demo. It is a generally good practice for the developers to follow.

Change argument name 'touchOptimized' to a more fitting name

I was a bit confused about the parameter touchOptimized of the method addToNavbar(boolean touchOptimized, Component... components). I thought this parameter would improve the handling of the navbar a lot on mobile devices for example or does something very special on mobile.

In the end the API documentation tells:

touchOptimized - if true, the components will be moved to the bottom navbar area on mobile devices.

Maybe a different name for the parameter would be more fitting because it only changes the navbar to bottom on mobile devices?

Menu interfers with iPhone X swipebar

When installed as a PWA the menu-items are lying below the iPhone X swipebar, and therefore the menu cant be scrolled horizontally

Remove unused styling parts and slots

Remove the styling parts: content, secondary
Remove the slot: secondary

Verify integration with Vaadin Router

Prepare for alpha

Current implementation is based on prototype
Tests and demos are missing

Component works with Lumo and Material

It is possible to choose which theme to use as a starting point
The components adapt to the theme’s properties (colors, typography, sizing, spacing, style)

Create use case demos to vaadin.com

• An example with a large viewport
• An example with a small viewport
• An example with a large number of menu items
• An example with text as the logo/branding
• An example with an image as the logo/branding

Add support for RTL

Though it can be achieved by adding some styles to navbar and branding parts, App layout could have support by default to RTL.

I have a main layout with my apps name/logo (“branding”), a menu and a content area.

Mobile responsive?

Thanks for publishing this. I was expecting more of a result like https://jelements.netlify.com/app-layout but it seems like vaadin-app-layout is still in an "early" phase. Is a mobile responsive iteration in the pipeline here?

CSS Rule destroys pointer events on touch devices.

I have a <canvas> element behind the <vaadin-app-layout> slot.
On a touch device, the canvas will only get pointerdown events. pointermove and pointerup events won't get called. When the canvas is located outside of the slot, the events work fine.

I do not understand why, but it seems that the overflow:auto rule on div[part="content"] seems to cause the issue.

[part="content"] {
   flex: auto;
   height: 100%;
   /* overflow: auto; */
   -webkit-overflow-scrolling: touch;
}

In my case replacing the overflow with height: -webkit-fill-available; height: -moz-fill-available; fill-available solved the issue without changing the ui.
But i didn't check that on other examples.

Remove orientation property

iOS scrolling - support both body and content area scrolling

With “body scrolling” we get the collapsing navbars on iOS (and some other small UX details) and the content scrolling under the app layout navbar (so that we can apply the iOS looking backdrop blur).

With “content area scrolling” we can support full height views that contain their own scrolling regions, like grids for example.

Rename branding to banner

Update flow integration