Feature: Add closeOnSelect & onSelect to Navbar API with tests & docs #2280

kevinzwhuang · 2016-10-12T10:02:10Z

Update 10/28: closeOnSelect has been renamed to collapseOnSelect to fit better semantically, given that it changes on the expanded prop and not open.
Update 10/27:
Several improvements have been made on this API since the last update on 10/17.
The demo of the latest build can be run here: https://plnkr.co/edit/SNvGZyLkiBmWOnyT86yG
A summary of what it looks like now is as follows:

onSelect: React.PropTypes.func
A callback fired when a descendant of a child <Nav> is selected. Should
be used to execute complex closing or other miscellaneous actions desired
after selecting a descendant of <Nav>. Does nothing if no <Nav> or <Nav>
descendants exist. The callback is called with an eventKey, which is a
prop from the selected <Nav> descendant, and an event.
function (
  Any eventKey,
  SyntheticEvent event?
)
For basic closing behavior after all <Nav> descendant onSelect events in
mobile viewports, try using closeOnSelect.

Note: If you are manually closing the navbar using this OnSelect prop,
ensure that you are setting expanded to false and not toggling between
true and false.

closeOnSelect: React.PropTypes.bool

Sets expanded to false after the onSelect event of a descendant of a
child <Nav>. Does nothing if no <Nav> or <Nav> descendants exist.

The onSelect callback should be used instead for more complex operations
that need to be executed after the select event of <Nav> descendants.

Update 10/17:
This PR has been improved from its original implementation. To see a running demo of the current iteration, you can run this Plunker here: https://plnkr.co/edit/43i4XA

The proposal has been simplified and improved with these two new props to the <Navbar> API:

onSelect: React.PropTypes.func
A callback fired when a <NavItem> grandchild is selected inside a child
<Nav>. Should be used to execute complex toggling or other miscellaneous
actions desired after selecting a <NavItem>. Does nothing if no <Nav>
& <NavItem> children exist. The callback is called with an eventKey,
which is a prop from the <NavItem>, and an event.
function (
   Any eventKey,
   SyntheticEvent event?
)
For basic toggling after all <NavItem> select events, try using
toggleOnSelect.

toggleOnSelect: React.PropTypes.bool

Fires the onToggle callback whenever a <NavItem> inside the child <Nav> is
selected. Does nothing if no <Nav> & <NavItem> children exist.

The onSelect callback should be used instead for more complex operations
desired for after <NavItem> select events.

/Update

Description:

Auto toggling as a behavior in react-bootstrap has been discussed at length in #1301 & #1692. @jquense and @taion have made good points against implementing it into the API due to complexities of different cases. There have also been valid arguments made for a simple version of this behavior to have available for users that does not need to catch every edge case. I think there is value to having a simple implementation of this expected behavior (normal click menus) for many users.

After reading over the discussion, I'd like to propose a simple addition to the Navbar API - lazyAutoToggle. I thought of naming it lazy to make it very apparent that it goes about autotoggling in a nondiscriminant & noncomplex way on <Navbar.Collapse> and its subcomponents. It does not attempt to be an omni-solution for all toggling needs.

Demo:

I've written a demo of this functionality in the plnkr. You can run the example at the link below:
https://plnkr.co/edit/vDejOB

There you can compare the functionality of a <Navbar> with & without lazyAutoToggle on.
It uses the built version of react-bootstrap from this PR.

How to use:

Simply add lazyAutoToggle to a <Navbar> with a child <Navbar.Collapse>.

Changes Proposed:

Add lazyAutoToggle prop to Navbar
Add lazyAutoToggle to childContext of Navbar
Check for lazyAutoToggle and onToggle from this.context.$bs_navbar in <Navbar.Collapse> to fire onToggle when both exist

This solution is fairly straightforward. It involves adding the prop value of lazyAutoToggle to the childContext of <Navbar> and its children - particularly for use by <Navbar.Collapse>.

<Navbar.Collapse> will then fire onToggle from its parent <Navbar> if and only if lazyAutoToggle && onToggle exist in this.context.$bs_navbar.

To support this new prop, I've also added:

Test for lazyAutoToggle on Navbar.Collapse clicks
Test for lazyAutoToggle on Navbar.Collapse subcomponent click + onClick events
Documentation for lazyAutoToggle in Navbar propTypes.

Not included:

Since this is a simple solution, this will not attempt to cover any complex cases where individual items might need to prevent toggling. I can foresee a roadmap towards providing an array prop of components that should be ignored by lazyAutoToggle, but that is not a part of this PR.

As a single prop solution, lazyAutoToggle works extremely well with regular links, buttons, etc. (normal click-related menu items).

cc: @jquense and @taion

taion · 2016-10-12T16:13:10Z

I don't think this is the right approach. I think you should hook into onSelect in <Nav>.

kevinzwhuang · 2016-10-12T16:57:16Z

Hooking into onSelect in <Nav> is a good idea, I'll look into that later today.

… lazyAutoToggle hook

codecov-io · 2016-10-14T09:19:04Z

Current coverage is 93.34% (diff: 100%)

Merging #2280 into master will increase coverage by <.01%

@@             master      #2280   diff @@
==========================================
  Files            94         94          
  Lines          1683       1684     +1   
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
+ Hits           1571       1572     +1   
  Misses          112        112          
  Partials          0          0

Powered by Codecov. Last update 61fe9e1...861e154

kevinzwhuang · 2016-10-14T09:24:19Z

You were totally right @taion, the hook on <Nav> is a much better approach. Overall, a way simpler strategy compared to the <Navbar.Collapse> idea and needs only 3 lines of code in Nav.js

I also updated the docs & test for this approach in the latest commit.
Here is an updated working demo in Plunker for you to run in your browser: https://plnkr.co/edit/AYyb2G

taion · 2016-10-14T17:07:58Z

src/Nav.js

@@ -93,6 +93,8 @@ const defaultProps = {
 const contextTypes = {
  $bs_navbar: React.PropTypes.shape({
    bsClass: React.PropTypes.string,
+    lazyAutoToggle: React.PropTypes.bool,


i'd just pass down an onSelect here

taion · 2016-10-14T17:08:11Z

src/Navbar.js

+   * Does nothing if no child <Nav> is present. lazyAutoToggle should not be used
+   * for complex nav menus.
+   */
+  lazyAutoToggle: React.PropTypes.bool,


I'd call this toggleOnSelect (or maybe autoToggle)

kevinzwhuang · 2016-10-15T00:44:02Z

toggleOnSelect sounds good with me. Could you clarify a bit more on the onSelect, it doesn't seem $bs_navbar has an onSelect set from <NavBar>'s getChildContext()

taion · 2016-10-15T06:27:59Z

@kevinzwhuang I mean add one. @jquense wdyt?

kevinzwhuang · 2016-10-15T07:15:49Z

@taion ah I see what you mean. 👍

In that case we might not even need a toggleOnSelect/autoToggle flag, since the exposed onSelect hook into <Nav>'s chained onSelect function provides even more flexibility and allows users to do the exact same autoToggle functionality themselves by passing in the same callback for onToggle for the onSelect context (or whatever modified toggle function they want). No need for prescribing behavior into the API and lets users handle their own edge cases!

Though I think maybe it should be named onNavSelect or onNavSelectCompleted to denote that it's a hook into <Nav>'s onSelect chain and not just an onSelect callback meant for <NavBar> itself (which is what I thought you meant at first)

taion · 2016-10-15T17:29:53Z

Personally I think onSelect is fine. I think it's pretty clear in context that onSelect on a <Navbar> would refer to the <NavItem>s under it.

I feel like this "toggle on select" behavior you're describing is common enough that it'd make sense to have as an option. It may not account for all edge cases, but it's probably what most users want.

kevinzwhuang · 2016-10-15T19:56:19Z

Sounds good @taion. I'll work on updating this PR with that approach sometime this weekend.

kevinzwhuang · 2016-10-17T09:35:41Z

Updated to the latest changes as discussed with toggleOnSelect & onSelect. I made it so that when an onSelect callback is provided, toggleOnSelect will be ignored (makes sense if you view onSelect as a more complex option to toggleOnSelect).

Docs & tests have been updated to reflect this new API.

Also I've created an updated Plunker with the latest build of this PR. Works well with NavItems & NavDropdown/MenuItems mixed in. (I believe NavDropdown's are ignored by toggleOnSelect & onSelect due to it not having a select event inherently).

In this latest demo, I've added a particular example using the onSelect callback to skip toggling for eventKey 2 - the potential for this callback is promising given it gives users access to the eventKey + event. You can try it out here: https://plnkr.co/edit/cOc8ZI

Let me know what you think @taion @jquense

taion · 2016-10-17T16:35:53Z

src/Nav.js

@@ -319,6 +322,7 @@ class Nav extends React.Component {
          const childOnSelect = createChainedFunction(
            child.props.onSelect,
            onSelect,
+            navbar && (navbar.onSelect || navbar.toggleOnSelect && navbar.onToggle) || null,


can you put all this logic in e.g. a handleSelect on <Navbar>?

kevinzwhuang · 2016-10-17T17:24:54Z

Folded the navbar && (navbar.onSelect || navbar.toggleOnSelect && navbar.onToggle) || null logic into handleSelect in <Navbar>.

Tests did not need to be modified since it's the same behaviour, updated plunker with latest build continues to work, which you can run here: https://plnkr.co/edit/PZhOUx

taion · 2016-10-17T17:30:18Z

src/Navbar.js

@@ -100,6 +126,7 @@ class Navbar extends React.Component {
        bsClass,
        expanded,
        onToggle: this.handleToggle,
+        onSelect: this.handleSelect,


sorry, one last thing – i think it might be better to make this just

createChainedFunction(onSelect, toggleOnSelect && this.handleToggle)

I think it's pretty unlikely that users will specify both toggleOnSelect and onSelect, and I think it'd be a bit cleaner this way.

Otherwise, this is looking really good. Thanks!

taion · 2016-10-17T17:57:29Z

Thanks!

kevinzwhuang · 2016-10-22T21:53:53Z

Thanks for your guidance on this @taion! Any more thoughts on this @jquense, @taion?

jquense

navbar-btn Buttons aren't going to work correctly with this. it doesn't fail, but it may be unexpected that they don't work? do we care?

jquense · 2016-10-25T16:15:56Z

src/Navbar.js


    return {
      $bs_navbar: {
        bsClass,
        expanded,
        onToggle: this.handleToggle,
+        onSelect: createChainedFunction(onSelect, toggleOnSelect && this.handleToggle || null),


should this actually toggle or only close the navbar? Theoretically you can't select something if its collapsed, but double clicks may get through, or other weird races.

It should toggle, only after the NavBar's onSelect if it exists and the Nav/NavItem's onSelect (the sequence is on Nav.js line 320). The race with double clicks is inevitable with the current API, since it happens with Navbar.Toggle already currently.

jquense · 2016-10-25T16:16:52Z

test/NavbarSpec.js

+  });
+
+  it('Should fire onSelect with eventKey for nav children', () => {
+    const selectSpy = sinon.spy();


does this work correctly with a NavDropdown?

NavDropdown's are ignored by onSelect & toggleOnSelect and their subcomponent MenuItems fire those callbacks correctly. I think this is the correct behavior out of the box - you can see it demonstrated here:
https://plnkr.co/edit/4sn165?p=preview (when you click the NavDropdown, no onSelect or onToggle callbacks are fired for either configuration).

…o function

…gleOnSelect

kevinzwhuang · 2016-10-26T07:18:31Z

I added a condition for toggleOnSelect to fire this.handleToggle only if window is not undefined(i.e. within a node build/test env) && window.innerWidth < 768 in Navbar.js, since it doesn't make sense for it to toggle when in a viewport larger than a mobile screen. Hope that makes sense @taion @jquense

Updated plunker with this build version: https://plnkr.co/edit/4sn165?p=preview

Update: Changed the condition to a function that evaluates innerWidth on runtime(whereas before it only being evaluated when getChildContext was run. This seems to be the better way to do it, so it can handle changes in browser width. See b9e0895. The plunker has also been updated with this new build.

Update on this: Checking innerWidth has been dropped an approach to handling different viewports. Rather, simply setting the state of expanded to false to close the Navbar is more important than toggling. View this discussion for the newest approach: #2280 (comment)

…w.innerWidth on runtime

jquense · 2016-10-26T12:54:15Z

src/Navbar.js

-    const { bsClass, expanded } = this.props;
+    const { bsClass, expanded, onSelect, toggleOnSelect } = this.props;
+    const mobileToggle = () => {
+      if (typeof(window) !== 'undefined' && window.innerWidth < 768) {


I don't think we need this check. it's too brittle anyway as a user can change the navbar collapse breakpoint to whatever they want so hard coding a pixel width here isn't ideal.

I do think that it illustrates a more general problem with this feature tho, you don't really want to be toggling expanded state while the expansion is not relevant, however there isn't really any way to know that from JS

Yeah it's brittle hard-coded as is.

One approach I can think of dealing with is is exposing a prop toggleOnSelectMaxWidth. It's of React.PropTypes.number and defaults to 768. So then when toggleOnSelect == true the window.innerWidth check would compare with toggleOnSelectMaxWidth.

Or toggleOnSelect could be the numeric value itself, and default to 0, so it's falsey when not set. When set, it can serve as the maxWidth itself.

Does anything bad happen if we unnecessarily toggle collapsed state? The styling is a no-op on desktop views, plus the user has to opt-in to this behavior anyway.

The whole navbar looks like it sort of re-renders when it tries to collapse while in a non-mobile viewport.

Here's an older plunker that demonstrates this: https://plnkr.co/edit/PZhOUx?p=preview
(make sure to resize the iframe to greater than 768px)

If we can figure out a way to fix this behavior in the lifecycle of the navbar, then we could get away with not having to deal with a arbitrary innerWidth breakpoint.

I'm really against users needing to input there grid breakpoint in order for this to work well. IMO it defeats the value of having this "add on" functionality if is comes with config, or a gotcha.

The only way i can think of tho to handle this is some sort of computedStyle sniffing to detect if the nav is in the right media query...that's not much less brittle tho :/

I agree - users shouldn't have to set a breakpoint.

I think I found a solution to this problem. It goes back to the point you mentioned about toggling vs closing the navbar! We were tackling it from the wrong angle with toggleOnSelect, which is causing the navbar to toggle between expanded states even when the screen size is not appropriate. In fact, screen size should not matter - only the value of expanded should really matter.

The right functionality should be something more like a closeOnSelect or collapseOnSelect, which will set expanded to false, only if it was true. If expanded is false, then it does nothing. I'll update this PR with a commit to demonstrate this new approach shortly.

taion · 2016-10-26T14:59:28Z

@jquense I don't care about Navbar buttons. How do those even show up on mobile/collapsed anyway? IMO it's a non-problem.

taion · 2016-10-27T16:37:03Z

That's a great idea. closeOnSelect sounds better, too. 😄

kevinzwhuang · 2016-10-27T17:19:52Z

Latest commit adds closeOnSelect. Works as expected :)
Here's a demo of the new build: https://plnkr.co/edit/SNvGZyLkiBmWOnyT86yG

taion

We can deal with the comment nits later

taion · 2016-10-27T19:15:30Z

src/Navbar.js

@@ -57,7 +58,36 @@ const propTypes = {
   * @controllable navExpanded
   */
  onToggle: React.PropTypes.func,
-
+  /**
+   * A callback fired when a `<NavItem>` grandchild is selected inside a child


"descendant" rather than "grandchild" (since it's actually Navbar > Navbar.Collapse > Nav > NavItem, and there might even be a LinkContainer or so in there)

What about "...when a descendant of a child <Nav> is selected..."? This might refer to NavItem, LinkContainer, etc., basically any descendants that can be selected without referring to any specific ones.

Sounds great.

taion · 2016-10-27T19:16:28Z

src/Navbar.js

+  /**
+   * Sets `expanded` to false after the onSelect event of a child of `<Nav>`
+   * (such as `<NavItem>` or `<MenuItem>`). Does nothing if no `<Nav>` or
+   * `<NavItem>`/`<MenuItem>` children exist.


<MenuItem> only goes under dropdowns actually

Working off of what I brainstormed in the comment above, how's this?
"
Sets expanded to false after the onSelect event of a descendant of a child <Nav>. Does nothing if no <Nav> or <Nav> descendants exist.
"

jquense · 2016-10-27T20:28:25Z

looks good to me. Thanks for the great work. Let me know @kevinzwhuang if you've like to be part of the react-bootstrap organization*. Its really low commitment, contribute as you have time.

(baring unlikely disagreement from other @react-bootstrap/collaborators)

kevinzwhuang · 2016-10-27T21:07:53Z

Just updated the PR with those comment improvements discussed.

@taion @jquense Thank you for the help on this. I'd be glad to be a part of the org and contribute. 😄

GerardoMachadoGandaria · 2016-10-31T09:39:03Z

Does not seem to work on mobile device?

kevinzwhuang · 2016-10-31T14:48:13Z

@GerardoMachadoGandaria could you provide some more details? I use this in my own apps and just tested this again myself on Android and iPhone and there's no problem.

Are you using react-bootstrap@0.30.6? What device are you using? Are you using the closeOnSelect or collapseOnSelect prop? The API has since been renamed to collapseOnSelect in #2308 - there's also a note about this at the top of this PR, so using closeOnSelect will be the incorrect prop. If you have some code you could share that would be great.

GerardoMachadoGandaria · 2016-10-31T15:49:36Z

Sorry my fault. Works fine.
Something was probably buffering an old version of the app.
Restart of the server did the trick. Also. Thank you for this change!

kevinzwhuang · 2016-10-31T16:27:51Z

Glad it worked out 😄

Add lazyAutoToggle to Navbar with tests & docs

ecbf66b

Add Nav lazyAutoToggle hook with tests & docs. Reverts NavbarCollapse…

861e154

… lazyAutoToggle hook

taion reviewed Oct 14, 2016

View reviewed changes

Add toggleOnSelect & onSelect to Navbar API

95a5c46

kevinzwhuang changed the title ~~Feature: Add lazyAutoToggle to Navbar with tests & docs~~ Feature: Add toggleOnSelect & onSelect to Navbar API with tests & docs Oct 17, 2016

taion reviewed Oct 17, 2016

View reviewed changes

Fold Nav onSelect logic into handleSelect in NavBar

8b494da

taion reviewed Oct 17, 2016

View reviewed changes

Chain handleSelect logic directly in childContext declaration in Navbar

e62bf45

taion approved these changes Oct 17, 2016

View reviewed changes

Add missing back-ticks to Navbar onSelect documentation

a7f42c6

jquense reviewed Oct 25, 2016

View reviewed changes

kevinzwhuang added 4 commits October 25, 2016 23:24

Add condition for innerWidth to be less than 768 for toggleOnSelect t…

120f545

…o function

Add documentation about mobile viewport conditions for onSelect & tog…

a116b91

…gleOnSelect

Fix test by faking smaller window.innerWidth for toggleOnSelect

1c88b38

Better mobile viewport handling with node checks for window on Navbar

461323e

Change the toggleOnSelect callback to a function that evaluates windo…

b9e0895

…w.innerWidth on runtime

jquense reviewed Oct 26, 2016

View reviewed changes

Create closeOnSelect prop & handleClose method for Navbar

1ecb6ca

kevinzwhuang changed the title ~~Feature: Add toggleOnSelect & onSelect to Navbar API with tests & docs~~ Feature: Add closeOnSelect & onSelect to Navbar API with tests & docs Oct 27, 2016

taion reviewed Oct 27, 2016

View reviewed changes

Refine the comments for closeOnSelect & onSelect for Navbar

bcf396d

taion merged commit 7d342c3 into react-bootstrap:master Oct 27, 2016

This was referenced Oct 27, 2016

Fix for a responsive and collapsive navbar on item select event #1692

Closed

Add option to collapse Navbar when item is selected #1301

Closed

renovate bot mentioned this pull request Oct 10, 2018

Update dependency react-bootstrap to ^0.33.0 neolanders/min-starter-react-redux-axios#13

Open

1 task

Feature: Add closeOnSelect & onSelect to Navbar API with tests & docs #2280

Feature: Add closeOnSelect & onSelect to Navbar API with tests & docs #2280

Conversation

kevinzwhuang commented Oct 12, 2016 • edited Loading

Description:

Demo:

How to use:

Changes Proposed:

Not included:

taion commented Oct 12, 2016

kevinzwhuang commented Oct 12, 2016

codecov-io commented Oct 14, 2016 • edited Loading

Current coverage is 93.34% (diff: 100%)

kevinzwhuang commented Oct 14, 2016

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kevinzwhuang commented Oct 15, 2016

taion commented Oct 15, 2016

kevinzwhuang commented Oct 15, 2016 • edited Loading

taion commented Oct 15, 2016

kevinzwhuang commented Oct 15, 2016

kevinzwhuang commented Oct 17, 2016

Choose a reason for hiding this comment

kevinzwhuang commented Oct 17, 2016

Choose a reason for hiding this comment

taion commented Oct 17, 2016

kevinzwhuang commented Oct 22, 2016

jquense left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kevinzwhuang Oct 26, 2016 • edited Loading

Choose a reason for hiding this comment

kevinzwhuang commented Oct 26, 2016 • edited Loading

Choose a reason for hiding this comment

kevinzwhuang Oct 26, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

kevinzwhuang Oct 26, 2016 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

taion commented Oct 26, 2016

taion commented Oct 27, 2016

kevinzwhuang commented Oct 27, 2016 • edited Loading

taion left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jquense commented Oct 27, 2016 • edited Loading

kevinzwhuang commented Oct 27, 2016

GerardoMachadoGandaria commented Oct 31, 2016

kevinzwhuang commented Oct 31, 2016

GerardoMachadoGandaria commented Oct 31, 2016

kevinzwhuang commented Oct 31, 2016

kevinzwhuang commented Oct 12, 2016 •

edited

Loading

codecov-io commented Oct 14, 2016 •

edited

Loading

kevinzwhuang commented Oct 15, 2016 •

edited

Loading

kevinzwhuang Oct 26, 2016 •

edited

Loading

kevinzwhuang commented Oct 26, 2016 •

edited

Loading

kevinzwhuang Oct 26, 2016 •

edited

Loading

kevinzwhuang Oct 26, 2016 •

edited

Loading

kevinzwhuang commented Oct 27, 2016 •

edited

Loading

jquense commented Oct 27, 2016 •

edited

Loading