[WIP] feat: component explorer #78
Conversation
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
packages/frameworks/react-mdx/src/component-explorer/component-explorer-base.tsx
Outdated
Show resolved
Hide resolved
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
Signed-off-by: Olaf Kappes <okappes@qti.qualcomm.com>
| return link ? ( | ||
| <Link |
There was a problem hiding this comment.
I wasn't happy with the explorer displaying doc as was completely redundant with our existing API sections, so I just simplified it and just made it point to the relevant paragraphs instead.
There was a problem hiding this comment.
I'll play with the UX and see how it does
There was a problem hiding this comment.
pretty basic: runs a demo and displays a list of parts. hovering highlights the part, clicking takes you to the API doc section.
| }) | ||
|
|
||
| setParts(discovered) | ||
| }, 100) |
There was a problem hiding this comment.
there's a tiny setTimeout to make sure the demo is ready but we could really simplify even further and just trust the doc author: if we have a list of parts (which we have as partLinks) then we could just use that, no discovery needed. WDYT?
There was a problem hiding this comment.
the partLinks approach should work (accounting for the derived approach). This seems like overkill when we have that.
|
|
||
| useEffect(() => { | ||
| if (!mountedRef.current) { | ||
| if (!mountedRef.current || withoutUI) { |
There was a problem hiding this comment.
what does this flag do? Also, https://react-next.qui.qualcomm.com/patterns/typescript-style-guide#acronyms
There was a problem hiding this comment.
this is to reuse QdsDemo without the demo controls. I renamed the prop.
| partLinks={{ | ||
| root: "#q-slider-root", | ||
| label: "#q-slider-label", | ||
| "value-text": "#q-slider-value-text", | ||
| control: "#q-slider-control", | ||
| track: "#q-slider-track", | ||
| range: "#q-slider-range", | ||
| thumb: "#q-slider-thumb", | ||
| "marker-group": "#q-slider-marker-group", | ||
| marker: "#q-slider-marker", | ||
| hint: "#q-slider-hint", | ||
| "error-text": "#q-slider-error-text", | ||
| }} |
There was a problem hiding this comment.
Can we derive this? I think this is already taken care of by convention. Every part should correspond to the q-<component>-<part> directive. For outliers, we can provide overrides via this approach here.
There was a problem hiding this comment.
simplified the API again: we don't go through the markup to discover parts, we just read them from parts, which eliminates the need for excludeParts and the links are auto-generated based on that (override still possible)
There was a problem hiding this comment.
Nice, this looks much cleaner
packages/docs/angular-docs/src/routes/components+/slider+/_slider.mdx
Outdated
Show resolved
Hide resolved
| }) | ||
|
|
||
| setParts(discovered) | ||
| }, 100) |
There was a problem hiding this comment.
the partLinks approach should work (accounting for the derived approach). This seems like overkill when we have that.
| return link ? ( | ||
| <Link |
There was a problem hiding this comment.
I'll play with the UX and see how it does
WIP don't be too fussy about the details at this point. you can have a look at the Slider doc page to see it in action.
tl;dr we display a demo (leveraging Demo/QdsDemo), find
data-partin the resulting markup and highlight the matching elements + display their API.Chakra uses a pure CSS solution (using outline) but overlays only add minimal extra code and, I believe, help identifying parts much better.
the most obvious optimization is to only have a single source of truth that would map components to their API rather than manually repeating ourselves. but before I continue iterating I'd like to get your feedback first!