Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add individual code examples for SelectNext #1340

Closed
wants to merge 1 commit into from
Closed

Conversation

acelaya
Copy link
Contributor

@acelaya acelaya commented Oct 24, 2023

This PR is an attempt to improve SelectNext's documentation, and close #1331

The primary focus is to illustrate the different ways in which the component can be used by adding smaller and individual code examples in different sections of the pages, and removing the single bigger existing code example at the bottom.

This helps referencing concepts later in the docs, making sure they have already been illustrated beforehand.

Considerations

The way this has been achieved is not ideal though (and that's why I'm creating this a draft).

The Library.Demo component already supports displaying code snippets with syntax highlight, based on code examples that are verified and we know are correct.

However, this component is limited to only render code for JSX, and not javascript, which is a problem, since in most of the SelectNext examples we need to show how different elements interact via hooks or external props.

Because of that, I have kept the interactive examples using Library.Demo and used Library.Code to illustrate the usage.

This has some drawbacks:

  • The code snippets can become outdated, as there's no static checks over them. It's even possible they have syntax errors.
  • We have to "duplicate" the code for the interactive examples and the code examples, and keep them in sync.

Testing

The changes can be seen by checking out this branch and going to http://localhost:4001/input-select-next

@codecov
Copy link

codecov bot commented Oct 24, 2023

Codecov Report

Merging #1340 (af008c7) into main (4b3fb93) will not change coverage.
The diff coverage is n/a.

@@            Coverage Diff            @@
##              main     #1340   +/-   ##
=========================================
  Coverage   100.00%   100.00%           
=========================================
  Files           62        62           
  Lines          926       926           
  Branches       354       354           
=========================================
  Hits           926       926           

📣 We’re building smart automated test selection to slash your CI/CD build times. Learn more

@acelaya acelaya removed the request for review from robertknight October 26, 2023 10:35
@acelaya
Copy link
Contributor Author

acelaya commented Oct 30, 2023

Closing this, as we have discussed some potential improvements for the pattern library that would make this easier to maintain in the long term.

The changes go in the direction of embedding some kind of interactive editor (like jsfiddle) which we can use to load individual example files that can be used as code usage examples, but at the same time they can get statically checked and tanspiled to generate the interactive examples.

This will help making sure the code examples are actually correct and up to date, while it won't require maintaining separate "snippets" for interactive examples.

@acelaya acelaya closed this Oct 30, 2023
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

SelectNext: Refine documentation
1 participant