Auro Sidenav Mobile Discussion

[DukeFerdinand]

Mobile Sidenav refactor

This is related to -> #18

What are we discussing?

How much JS is too much JS for the mobile sidenav? Can we use a combination of window.innerWidth + css breakpoints to render out different "branches" to avoid rapidly increasing complexity?

We'd like to propose using window resize events in addition to some heavier CSS lifts where possible to avoid problems in the future.

Context

@rsstdd and I (@DukeFerdinand ) have been working toward as close to a CSS-only solution as possible for the auro sidenav accordion wrapper on mobile. We had a great discussion yesterday after standup with @jason-capsule42 regarding some concerns about using JavaScript to detect window resizing. The main concern is using too much JS and trying to find CSS-only or mostly-CSS solutions to let the browser handle as much as we can since it's far faster to use media queries than window.innerWidth at scale.

Another concern we're trying to address is using too many if/else branching logic points, resulting in a harder-to-maintain component down the line. Wrapping everything in an accordion 100% of the time is a direct result of this concern and attempts to mitigate that by always having an accordion and just disabling certain features like click handlers when we aren't on a mobile screen size.

Assumptions (as of yesterday)

1. Slots with the same name can be "disabled" in a sense using CSS to hide and show them.
2. Window resize event handlers will not be needed as the Auro Accordion wrapper will always be in the template/tree.
3. Adding a manual prop or similar to the Accordion component will allow us to avoid any heavy JavaScript operations by leveraging the above "css hide/show" techniques.

Realities (as of today)

1. Slots with the same name will be ignored after the first unless you explicitly disable default browser features and start rendering slot content manually in JS.
2. CSS cannot disable slots. Setting a slot to display: none does nothing functionally and the first slot will always be selected regardless of visibility.
3. Multiple slots can inhabit the same wrapper element (ex: two slot elements in one div) but cannot be kept in-sync except by way of some JavaScript element cloning. This ultimately means you'd need to clone a slot with JS on first render and subsequent renders if you need reactivity.

• Cloning ends up presenting a much more difficult testing scenario than a "simple" if/else branch in the render tree.

6. Adding a manual prop to Auro Accordion would not reduce the amount of JS needed in a significant way and might actually just act as a further complication if wrapping/unwrapping template string manipulation is on the table :)

Proposed solution

Ultimately, even though we had concerns with it at the beginning, dynamically wrapping the sidenav in an accordion based on a debounced window.resize event listener does seem to be the best solution here. It feels really jank at times, but the only other solutions presently available are actually worse in a number of ways :(

We actually just got done with a largely similar problem HERE for Auro Card where we needed to wrap or unwrap a card in an auro-hyperlink based on an href attribute using JS. The difference here of course is when the wrap/unwrap happen but debouncing is a common solution for reducing event side effects.

I think there's merit to leveraging much of our CSS solutions here, but leaning on the window resize event seems like a way smaller lift.

Recommended reading (unverified statistics)

• What percentage of users resize their browser?
• What percentage of internet traffic is mobile?

[jason-capsule42]

Hey Doug, I just read through that. Good writeup. I'm not fully understanding very well the actually code issue you are trying to solve from the description here.

However, I suspect that you are running into a problem with what we had outlined yesterday when we met where you would then have two HTML elements in the accordion trigger that both need to render the "trigger" slot content. Is that correct?

[DukeFerdinand]

That's correct, having two elements rendering the same slot content just isn't possible without some serious hacks that are worse than just debouncing a window resize event handler and showing or hiding an accordion wrapper component

Edit: to clarify, we've solved this problem on our branch so that's how we came to the conclusion that the solutions are hacky :)

[blackfalcon]

This is a very well-written summary of events. Thanks for that. @DukeFerdinand when we briefly went over the spec for this work, this is the very thing that I assumed would throw us a big wrench. So... how to dodge?

I am interested in your event resize solution, but I will throw another wrench at you. Our components need to also meet a ESM/SSR spec, and Node has no concept of window. That being said, the browser does when the component is loaded into it. E.g. the window event could be hidden from the SSR rendering, but exposed to the browser.

[jason-capsule42]

That's correct, having two elements rendering the same slot content just isn't possible without some serious hacks that are worse than just debouncing a window resize event handler and showing or hiding an accordion wrapper component

Edit: to clarify, we've solved this problem on our branch so that's how we came to the conclusion that the solutions are hacky :)

Let's schedule some time for another pair programing session. This is a challenge we have faced before.

[blackfalcon]

Post-meeting notes.

A clear takeaway from this is that neither a 100% CSS or JS solution was really the best answer. Looking at something more of a hybrid is a strong recommendation.

The crux of the conversation was how to handle the switch between a mobile feature and desktop. Referencing the new auro-card solution where there is an option to have the card wrapped in a <a> tag based on the href attribute being true really works well. In this case, having the nav render inside an accordion or not and if that header trigger was clickable or not could be solved in a similar way.

Having an attribute on sidenav that renders the component one way versus another seems appropriate. Whether or not to put the management of this attribute in the hands of the consumer versus having the component being self-aware to some extent is at the heart of this issue.

There is a strong argument to be had that if the attribute is simply made available and it's up to the consumer to carry the last mile, that feels appropriate. This allows the consumer control over how this works versus the component owning a visual state.

There is also an argument to be had for the 'out of box' experience and the consumer expecting that the component will react appropriately based on window controls.

That statement alone has a smell to it. For a component to be aware of the environment outside its immediate concern is troubling and typically what we DO NOT want to do. However, in the case of visual responsivness, that is absolutely what we do. Thus the paradox.

Recommendation: Use CSS where warranted. Best tool for the job, as we say.

Regarding responsiveness, the requirement is past simple CSS @media queries due to functional requirements. Following a declarative option, I am leaning towards supporting the attribute, post decoration on the DOM node. But not supporting how the attribute is applied and leaving that onus on the consumer. There is plenty of precedent for that. Using standardized breakpoints can be accessed via JavaScripit if needed via the gridBreakpoint object from Design Tokens.

Going down this route would require that we clearly define the API, what it does, and how it can be used.

Test the theory: Once this has been engineered into a demonstratable version, the engineers will set up a meeting, specifically with the Content engineers, to discuss the API expectations and get feedback.

re: design tokens. While you can technically access breakpoint via the gridBreakpoint that is accessible via the allTokens file https://cdn.jsdelivr.net/npm/@aurodesignsystem/design-tokens@latest/dist/tokens/JSObject--allTokens.js, it would make sense to update design tokens to have this as an individual output.

[DukeFerdinand]

Sidenav Update Mar 7 2024

This is our update after speaking with @marnel-mangrubang and @blackfalcon on the JS-backed attribute solution over a deeply-integrated CSS media query solution for converting the Sidenav from desktop to mobile, and vice versa.

What's the verdict?

We've decided to proceed with having the sidenav essentially "not care" what size screen it's on and only listen to a passed attribute on how it should render. We recognize that this is not ideal in the short term, but we have some far better long term solutions that should make using and developing for Auro a far better experience for everyone.

Why did you decided not to use the CSS only solution?

To summarize: complexity and ownership. We determined that any solution we chose here has the potential to bite us in the butt in one way or another, so we chose the most common approach we could find among popular frameworks (like MUI - see below media query solutions).

The only CSS solution we landed on with @jason-capsule42 involves rendering an auro-accordion wrapper 100% of the time, and "deactivating" or otherwise disabling default functionality if certain conditions are met - via hiding or showing different cloned slots based on screen size.

This seemed fine on the surface (and actually does work in practice) until we considered future maintainability. Cloning slots and managing breakpoint selection based on an attribute works fine for this one use case, but it's strictly limited to exactly those breakpoints defined as design tokens and limited to exactly this use case.

Ultimately, we decided that including breakpoint specific styling is too close to an "application component" pattern than a library component pattern because it makes the above assumptions. While we don't want to hinder content producers or anyone else who wants to use a Sidenav, there are better and more reliable ways to get an easy boolean operation done than including it as part of a strict enumerated attribute in every component that needs responsive wrappers.

What do you propose then for CSS media query rendering in Auro?

Many of the popular libraries out today use media query "hooks" or equivalent reactive functions from their respective parent frameworks.

• MUI useMediaQuery
• Polymer's media query
• For @blackfalcon: Spectrum Web Component's match-media
  • Direct code example of how spectrum uses media matching

We'd love to see an auro-mediaquery that leverages window.matchMedia under the hood to facilitate these sort of transformations based on screen size rather than including very specific styling assumptions baked into components directly.

We both believe that using these media query exposure solutions can be a far larger lift for responsive design than having to implement media query solutions for every component that needs it.

Feedback

Please let us know if you have any opinions on this as we are extremely interested in feedback. We want to introduce standard solutions that people enjoy using to avoid ending up like this:

[blackfalcon]

The conversation with Marnel went well and he provided a lot of really great feedback leaving us with the question of, "How can we deliver this in a way that doesn't paint us in a corner, making it easy to install and allow for maximum flexibility?" Really a wholly grail of a solution.

The pattern to already support this is with the auro-dialog and auro-toast elements allowing for a core element that has enhanced capabilities when coupled with a wrapper element.

Interestingly, you brought up the old iron Polymer solution. Similarly, there is https://www.npmjs.com/package/lit-media-query (last published a year ago, dependency on "lit-element": "^2.0.1") which literally says...

Web component for media queries (like iron-media-query) implemented with LitElement.

Given this example. this really fits our use case of the mobile rendering toggle. The scope of auro-sidenav only needs to internally respond to the attribute. It need not be aware of any conditions outside the scope of the element.

The proposed auro-mediaquery element would manage the understanding of the screen size and then can communicate down to any element within its scope, e.g. auro-sidenav, and toggle the attribute.

Spectrum's match-media solution I am less familiar with, would want to look into that more. But I really like this idea and recommend doing this.

In summery

The work on auro-sidenav can move forward with a solid solution of appending an attribute will change behavior of the nav element. This will reduce scope and complexity. A solid win.

A new element is being proposed for auro-mediaquery which will require some more discussion and POC work, but there are clear examples we can pull from and the use case is solid and highly reusable.

Great work guys!

[blackfalcon]

A thought just came to be as well. Regarding the proposed media element, I am wondering if it is appropriate to open the scope of this to also include language.

Consider this https://github.com/AlaskaAirlines/auro-input/blob/main/src/i18n.js#L19-L38

Due to current constraints, we had to solve a loc problem for content that was managed within the scope of the element. This will of course be nullified once we have moved to supporting Content Stack, so we hope.

That being said, this is a clear example of an element having to be aware of what is OUTSIDE the element, versus only being concerned with that is INSIDE the element.

I am wondering about the concept of this higher-order component owning responsibility for this and then instructing elements within on the lang status?

[rsstdd]

@blackfalcon, I think that would be an excellent use case for using context and a higher-order component to abstract and reuse this logic.

[rsstdd]

Post Meeting Notes

auro-sidenav/pull/20
auro-sidenav/issues/13

Summary/Context:

We propose a generalized solution for managing state, content, and/or structural changes based on variable screen resolutions. We suggest that library components not endeavor to media match nor show or hide DOM nodes via CSS for the following reasons:

• Cloning slots and managing breakpoint selection based on an attribute are limited to the breakpoints defined as design tokens, which is restricting due to that specificity.
• Including breakpoint-specific styling produces an "application" -- or use-case-specific -- component. The more specific (i.e., the more like an "application component") this becomes, the less flexible and general a library component becomes.
• Provides a more optimal DOM tree by rendering the minimum elements necessary for the design.

Instead, we've proposed that components with variable structure should contain a Boolean attribute to dictate the rendering path.

Topics discussed:

• The Auro team is focused on other business-critical priorities, so the proposed auro-media-query component will be delayed in development. In the meantime, the auro-sidenav should be available to our users with the "mobile/accordion" feature functional.
• We understand the need to include methods for achieving the desired behavior (toggling this attribute) in the documentation. We currently include an example, but we can draw greater attention to this and improve the documentation in our PR.
  • @jason-capsule42, I think you mentioned auro-dialog as an example of good documentation. Can you identify the specific content that we should use as an example?
• We need to define the specific API and behavior of the proposed auro-media-query.
  • We need a better answer to the question, "How would the proposed auro-media-query work?"
  • Answering this question will require more discussion and POC work, but we are confident in this approach.
  • We must identify, document, and implement the best way to standardize this pattern across all components.

@blackfalcon @DukeFerdinand @jason-capsule42

[blackfalcon]

@rsstdd re: documentation

The documentation around auro-dialog, please see https://auro.alaskaair.com/components/auro/dialog, specifically the sections on the setup and the structure.