React-dates: Please provide clearer documentation

[thedanchez]

I'm working on using react-dates for a project but I'm having a very difficult time understanding many of the props and their purposes. It would be really great if you were able to provide a complete breakdown of all the props, such as what affect they have and what possible values they could be. Especially if they are functions which you can override -- give us insight into what args are fed to the functions and what they should be returning.

[imadmk]

First of all, thanks for this great library.
Maybe one example is this
SDP - Day Props - with some blocked dates

The story source contains only <SingleDatePickerWrapper isDayBlocked={anonymous()} autoFocus />
So in order to know what anonymous is, i have to look inside the repo until i found the right file, which is
SingleDatePicker_day.js.

[caub]

This is what I get following the instructions in README: https://codesandbox.io/s/nln9n86np

[abrad45]

http://airbnb.io/react-dates/?selectedKind=DRP%20-%20Day%20Props&selectedStory=with%20some%20blocked%20dates&full=0&addons=1&stories=1&panelRight=0&addonPanel=kadirahq%2Fstorybook-addon-actions%2Factions-panel on this URL, I have a full table of all the properties of DateRangePickerWrapper.

• None of the properties define their type. When the default is of a clear type such as {onClose()}, that omission is not a big deal. When the default is {null}, the omission is glaring.
• The "code sample" at the explains nothing: <DateRangePickerWrapper isDayBlocked={isDayBlocked()} autoFocus /> does not help me to know what isDayBlocked() does or how to use it.

It's only by searching the code or issues that I'm able to find anything useful.

[ljharb]

@abrad45 does the name "is day blocked?" not indicate that it's a predicate (a function returning a boolean) that determines if a day is blocked (from picking, since it's a datepicker) or not?

I do agree that the propType tables definitely need improvement.

[abrad45]

@ljharb That it's a function and its goal are fairly straightforward. What's arguments does isDayBlocked receive? What type are those arguments? Documentation should remove ambiguity and not ask the developer to assume these things.

I'm not super familiar with the storybooks and have never cared for them as documentation, so I may be unfamiliar with a way to see something in its UI, but the storybook as it stands doesn't work well because it doesn't demonstrate isDayBlocked={isDayBlocked()} being used. In the example, March 1, 2, 4, and 10-14 are all blocked. What code produces that output? That would be useful as well rather than writing out something that explains all of this.

Judging by https://github.com/airbnb/react-dates/blob/master/stories/DateRangePicker_day.js#L109 it seems like the code that generates this is

    <DateRangePickerWrapper
      isDayBlocked={day1 => datesList.some(day2 => isSameDay(day1, day2))}
      autoFocus
    />

This could all be explained more clearly in the storybook so that users don't need to delve into the code that generates it to understand what to do.

[abrad45]

Also, @ljharb I should note. I really like this package. It seems like it _can_ do everything, and I use it on an important project at work. I am disappointed in the docs because I feel they hamstring the project in a major way.

EDIT: Thanks for your and others' work on this project.

[ljharb]

Makes sense.

Any specific PRs are very welcome; the only concrete thing I can think of right now is to explore making those propType tables be more useful.

[abrad45]

@ljharb I can give the propType tables a shot, but I can't find how / where they're generated. Might you know?

[majapw]

@abrad45 I think that's currently based on the storybook info addon. It may not be optimized for functions... maybe we can upstream that?

https://github.com/storybooks/storybook/tree/master/addons/info

[majapw]

Also, I just want to say, I hear you @abrad45 and agree that our... documentation is somewhat lacking. I would really love to revisit it and somehow make it better explain the customizability of this library, because I really think that's our greatest strength! :) It's been on my mind for a while and I wonder if there's a way to better leverage storybook for this or if there's something better we can do to showcase all of the options you can customize in this library.

[ljharb]

fwiw, all the airbnb-prop-types do add extra debugging info as properties onto the validators (following react's conventions) so we should be able to extract usable information out of them at runtime.

[abrad45]

Thanks both of you for your responses.

I'm sorry, @majapw, I'm still struggling to find the source of the data table. I can see addWithInfo:

storiesOf('DRP - Input Props', module)
  .addWithInfo('default', () => (...

But not where the info that gets added is from. https://github.com/storybooks/storybook/tree/master/addons/info#deprecated-usage shows the usage of addWithInfo and the examples here show more info about usage, but in each example, it looks like the info is included inline. Where are we getting this props table from?

Examples: https://github.com/storybooks/storybook/blob/master/addons/info/example/story.js

[abrad45]

By trial and error, I can see that the way to inject values into the tables in the storybook are by modifying defaultProps in, for instance, /examples/DateRangePickerWrapper.jsx. It also seems to pull required status from /src/shapes/DateRangePickerShape.js (as that's pulled into the example wrapper component above) but not propTypes, for reasons I cannot figure out. It doesn't seem related to "custom prop types" versus default, as even bools or functions don't appear in this column.

[ljharb]

We may have some code internally that works better with proper tables; I’ll take a look and see if we can publish it.

[abrad45]

@ljharb Thanks. I'm not sure if this was clear but I was just documenting everything I learned here while going through. Sorry to bombard you with all of it.

I also started screwing around with babel-plugin-react-docgen and trying to get that working, but it seemed to screw the tables up more than help (it replaced the defaults null with "null" and false with "false" which does not help the confusion around propType).

It feels like the storybook info addon tries to be very cute and figure everything out automatically, which is great if it works, but a bit of a black box in the event that it doesn't. The fact that it pulls props from the propTypes objects, but doesn't insert their... prop... types... is baffling to me.

[buildbreakdo]

Anyone else lands here, best documentation have found so far is here:

https://airbnb.io/projects/react-dates/

It's incomplete, does not cover all the props. But is as good as it seems to get. Storybook docs are great for boolean or numerical props; outside of that for something like a function there is not enough detail to determine the structure of arguments passed in and what is expected return value. Additionally, keep seeing a reference to <t /> component, no idea what that is supposed to be.

Great looking component.. real fight to understand how to configure.