docs: improve docs for shorthand props #751
Conversation
kuzhelov
requested review from
dvdzkwsk,
layershifter,
levithomason,
miroslavstastny and
mnajdova
as code owners
docs/src/views/ShorthandProps.tsx
Outdated
|
|
||
| <p> | ||
| So, what this string value (i.e. {code("'chess rook'")}) means for {code('Button')}{' '} | ||
| component and, essentially, how it transforms into rendered {code('<Icon />')} element? |
There was a problem hiding this comment.
In my opinion, this question doesn't bring any value to the user. Let's try to remove it and maybe provide bullet points for explaining this points below.
docs/src/views/ShorthandProps.tsx
Outdated
| <p> | ||
| There is even shorter way to define default element's props - by using a primitive value. | ||
| In that case provided shorthand value will be taken as a value for 'default prop' of this | ||
| default element. |
There was a problem hiding this comment.
'default prop' of this default element => 'default prop' of this element. Would avoid the default for the element as well...
docs/src/views/ShorthandProps.tsx
Outdated
| ])} | ||
| <p> | ||
| This works because {code('name')} is the default prop of slot's {code('<Icon />')}{' '} | ||
| element. |
There was a problem hiding this comment.
This works because {code('name')} is the default prop of the {code('')} component.
There was a problem hiding this comment.
a bit reluctant to use this terminology, as default props for Component may lead to false associations. Essentially, default element's prop is even more correct, given how this default prop's value is handled
docs/src/views/ShorthandProps.tsx
Outdated
| {code('accessibility')}). | ||
| </strong>{' '} | ||
| This is because, in contrast to other forms of shorthand values, Stardust-evaluated props | ||
| cannot be unsafely passed to the element which type is, generally, doesn't allow Stardust |
docs/src/views/ShorthandProps.tsx
Outdated
|
|
||
| <p>Thus, in its simplest form, it could be used the following way:</p> | ||
|
|
||
| {codeExample([`<Button icon={() => <Icon name='chess rook' />} />`])} |
There was a problem hiding this comment.
Not sure that this example brings any value... Let's try not to add examples which should never be used.
There was a problem hiding this comment.
this one provides a visibility of what does it mean to satisfy criterias of this function. If we will start right with the render callback stuff, it won't be absolutely clear what is going on - there might be a false assumption from the client that this 'render' function is, actually, triggers rendering somewhere, while, in fact, it just returns an element.
I would really like to leave this simple explanation of what does it mean to pass function as a shorthand value, and what Stardust expects from this function.
What do you think?
docs/src/views/ShorthandProps.tsx
Outdated
| ` /* how to render */`, | ||
| ` (ComponentType, props) => (`, | ||
| ` <div class='my-icon-container'>`, | ||
| ` <i {...props} />`, |
There was a problem hiding this comment.
Maybe we can showcase here the usage of the styles and accessibility, like spreading the accessbility.root elements on the i element or using the classes generated?
docs/src/views/ShorthandProps.tsx
Outdated
| const subheader = content => <Header as="h3">{content}</Header> | ||
|
|
||
| const code = content => <code>{content}</code> | ||
| const codeExample = snippet => <CodeSnippet value={joinToString(snippet)} /> |
There was a problem hiding this comment.
I have a strange feeling about there helpers I understand why there are there, but I also should mention that they are not looking friendly for newcomers 🤔
TODO