DocsExample: Add dynamic loading of components and display of code blocks

[EshaanAgg]

Description

This PR introduces the dynamic loading of example components via the DocsExample component.

Issue addressed

Fixes part of #845

Changelog

• Description: Adds dynamic loading of component examples in DocsExample
• Products impact: new API
• Addresses: Further improve DocsExample visual output and API #845
• Components: -
• Breaking: no
• Impacts a11y: no
• Guidance: -

Implementation notes

I have ensured that the component follows the API specification described in this comment.

Does this introduce any tech-debt items?

No

Testing checklist

• Contributor has fully tested the PR manually
• If there are any front-end changes, before/after screenshots are included
• Critical and brittle code paths are covered by unit tests
• The change is described in the changelog section above

Reviewer guidance

• Is the code clean and well-commented?
• Are there tests for this change?
• Are all UI components LTR and RTL compliant (if applicable)?
• Add other things to check for here

[EshaanAgg]

This PR introduces a bare-bones example of the now new component that can be easily used by refactoring the KTable component and an example in the KCardGrid documentation to show its versatility. If the same seems to be satisfactory, there can be many more improvements that we can add to the same:

(I am just listing them here so that they are documented as they are fresh in my mind right now. I would be happy to address the relevant ones as per the feedback in this PR itself):

• Improve the styling of the component to match the documentation theme a bit more
• Add animations when sliding toggling code visibility
• Add animations when switching between different code blocks
• Disable ESLint rules like no-console-log for the examples directory, and then remove the eslint-disable from the KTable example
• Update the developer documentation about the API of DocsExample and how we can use it to build better documentation pages
• Add a button to link to the complete GitHub code example file alongside the code toggle button
• Migrate more documentation to make use of DocsExample and collect feedback to see if it is a satisfactory solution to avoid the problems listed in Configure prettier and eslint to treat DocsShowCode as code examples #861 to an appreciable extent!

[EshaanAgg]

Update: I have tried to address most of the points I mentioned yesterday in this PR! You can check out how the new component fits into the documentation ecosystem by browsing the following documentation pages from the deploy preview:

• KTable: Whole page
• KCardGrid: First example on the page
• KTransition: Last example on the page

You can let me know if any changes in the appearance/theme of the new component are needed! Also, as for the points left unchecked:

Add animations when switching between different code blocks

I feel that instead of introducing this functionality in the DocsExample component directly, it will be better added as a feature to the KTabs component itself. We can allow the user to configure a props like animate: true, or other custom options like animationDuration and animationEaseMode, and then use that behaviour here! If this seems like a viable plan, I can open a new issue for the same.

Migrate more documentation to make use of DocsExample and collect feedback to see if it is a satisfactory solution to avoid the problems listed in #861 to an appreciable extent!

This is more sort of a long-running change that we can open good-first issues for the it when the PR is stably merged!

PS

Now, the PR ends up actually making 3 net changes to KDS:

• Adding a new icon (github) to KDS
• Adding a new type of transition to KTransition
• Updating the API of DocsExample

We should probably add three different changelog items for the same? Does the current automated workflow support that or should I do that part manually for this PR?

[MisRob]

Hi @EshaanAgg, thanks a lot! We took a peek by chance at the example pages you prepared during one of our meetings, and lots of excitement :)

[MisRob]

@marcellamaki and/or @nucleogenesis would you be available to review as a whole? I think you both should have enough context from our meetings, but in case it's useful to sum it up - this work builds on top of #826 and resolves several issues actually #845 #861. Conversations that lead to this final interface are in many places. Based on the feedback I collected few weeks ago among team members and previous chats with @EshaanAgg, we agreed on what he proposed here and from my perspective, this PR is very well aligned with it.

[MisRob]

@ozer550 since you're familiar with the predecessor #826, you're very welcome to join the review fully or just some parts of it :)

[MisRob]

Thanks all

[nucleogenesis]

I left a question about the Github link. I think that our existing docs component hard-codes the Github SVG into the component. If we could use that, then you could avoid adding the icon to precompiled-icons/le and iconDefinitions.

Overall this is really fantastic and makes the docs page look & feel very clean. I love the approach to splitting things up and will make it easy to make updates and additions moving forward! Thanks @EshaanAgg

[nucleogenesis]

Could DocsGithubLink work here?

[EshaanAgg]

The same creates an anchor text link to a GitHub page, which is only for issues and pull requests. Here, we want to create a KIconButton, which is not possible through that component directly.

Though seeing that the GitHub SVG is inlined in the same, I can make either of the two changes:

• Change the DocsGithubLink to use this pre-compiled SVG that I have added.
• Remove the github icon from precompiled icons, and inline the same in DocsExample.

I personally would prefer the first option over the second, but I would be happy to implement the one that feels more appropriate to the team!

[EshaanAgg]

Made another minor improvement: Now the component makes use of the environment.js to get the deploy context and handles the GitHub button click appropriately:

• In local and PR environments, clicking on the button does not redirect the user anymore (to potentially broken links), and the tooltip on the button informs the user about the same.
• When targeting a branch on KDS, the same use the environment.url variable to populate the path to the example. This would be handy (in the off chance) if someone wants to deploy their own fork to Netlify

[marcellamaki]

Hi @EshaanAgg - thanks for your patience while I get to review. I'll add comments by tomorrow - this looks great and we appreciate the contribution!

[marcellamaki]

Hi @EshaanAgg - this is looking really good. Essentially, I don't really see any major issues, but since this is a documentation update, I've added a few questions/comments, and made note of a few considerations I also want to ask other reviewers (but I welcome your suggestions/perspective as well). I'll re-review next week after we've had some time for other thoughts. Thanks very much for your contributions.

[marcellamaki]

I wonder if rather than adding the caveats (not available in PRs/not available locally), we just don't display this in those environments? So, only display the icon in prod? I guess the downside of that would be confirming that it's working in develop....

[marcellamaki]

Thank you @EshaanAgg for your work here! This is a really fantastic piece of work, and I am sure that the code block display in particular will be really helpful both for our core team as well as external contributors from the open source community. We appreciate your contributions.

[MisRob]

Wonderful news! @EshaanAgg on another issue I noticed you had interest with helping to organize some work and I also see you in reviews from time to time. Refactoring KDS documentation to use this component, as you noted, would be a good source good first issues for the community. If you'd be interested in taking on responsibilities such as overseeing this refactor as a whole project (e.g. opening issues, reviewing them, suggesting more improvements that other developers can implement), I'm more than happy to chat. No pressure at all, you have volunteered so much for us already :) I thought this could be perhaps interesting new area to explore. Just message me on Slack any time if this would sound interesting.

[EshaanAgg]

Thanks, @marcellamaki @MisRob, for your guidance along the way! And, thanks @MisRob for the kind offer! I just love hanging out with the community members here, and helping in whatever small ways I can whenever I find the time. Helping to coordinate the overall documentation update is something that I would love. Will ping you soon about the same on Slack.

As a quick post-merge consideration, I would like to just redraw your attention to these two points that I mentioned earlier in the conversation:

One about opening a new issue for sliding animations:

Add animations when switching between different code blocks

I feel that instead of introducing this functionality in the DocsExample component directly, it will be better added as a feature to the KTabs component itself. We can allow the user to configure a props like animate: true, or other custom options like animationDuration and animationEaseMode, and then use that behaviour here! If this seems like a viable plan, I can open a new issue for the same.

Other about the changelog:

Now, the PR ends up actually making 3 net changes to KDS:

• Adding a new icon (github) to KDS
• Adding a new type of transition to KTransition
• Updating the API of DocsExample

We should probably add three different changelog items for the same? Does the current automated workflow support that or should I do that part manually for this PR?

Please let me know if any changes regarding the same are needed in the context of this PR.

[MisRob]

Wonderful, thank you @EshaanAgg.

Oh the changelog! I'm sorry for late reply. Yes it'd be best to have those things in the way you suggest @EshaanAgg. @AlexVelezLl uses this to create release notes - Alex, how would you recommend we proceed about the items that are missing since we merged before putting this together?

[MisRob]

@EshaanAgg I agree it'd be better to have KTabs themselves animated. Could be one of those follow-up issues, however I think it's rather a low priority. Ideally, we'd also confirm with designers what the animation should look like since this would affect experience of Kolibri learners and coaches. It's different context from KDS website that mostly LE team members use and we can improvise to some extent :)

[AlexVelezLl]

Hey @MisRob! For release notes, it will be great to have these changelog items updated in the PR description even if the PR was already merged :), and if there is something super important to have in our Changelog file, I think opening another PR introducing these items directly to the changelog also do the work. For this specific case I have introduced these missing changelog items directly to the changelog file in the bump version PR, so no action needed for this!