docs(api): add refresh button to examples

[ST-DDT]

Fixes #3287

• Add refresh button to the api docs examples #3287

---

Adds a refresh button to the examples without requiring changes to our examples.

All faker. invocations are recorded and pasted as a comment after the invocation.

Preview

[netlify]

✅ Deploy Preview for fakerjs ready!

Name	Link
🔨 Latest commit	31224ce
🔍 Latest deploy log	https://app.netlify.com/sites/fakerjs/deploys/67670eb87b8d8400088d3c44
😎 Deploy Preview	https://deploy-preview-3301.fakerjs.dev
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[ST-DDT]

This PR is ready for reviewing and feedback (except some minor details).
But I would like to create some test before merge, so I marked this as a draft for now.

[codecov]

Codecov Report

All modified and coverable lines are covered by tests ✅

Project coverage is 99.97%. Comparing base (1fd69d9) to head (31224ce).

Additional details and impacted files

@@            Coverage Diff             @@
##             next    #3301      +/-   ##
==========================================
- Coverage   99.97%   99.97%   -0.01%     
==========================================
  Files        2811     2811              
  Lines      217006   217006              
  Branches      939      938       -1     
==========================================
- Hits       216955   216953       -2     
- Misses         51       53       +2     

see 1 file with indirect coverage changes

[matthewmayer]

The quote styling for strings is different before and after pressing refresh

[ST-DDT]

The same applies to , vs , in arrays.

For the quotes it is a relatively easy fix.
Not sure for arrays.

Do you think either of the two issues should be fixed?

[matthewmayer]

The same applies to , vs , in arrays.

For the quotes it is a relatively easy fix. Not sure for arrays.

Do you think either of the two issues should be fixed?

preferably yes, the visual glitch when the first refresh happens is a little disconcerting

[matthewmayer]

Also noticed the refresh button animates weirdly (the circle moves around as its not centered). My preference would be for a more informative button like "Load more examples..." as suggested before, but welcome to suggest other wordings/placements

[ST-DDT]

Also noticed the refresh button animates weirdly (the circle moves around as its not centered).

That's one of the reasons, this PR is a draft.
I'll probably create an svg to fix that.

My preference would be for a more informative button like "Load more examples..." as suggested before, but welcome to suggest other wordings/placements

I personally prefer the icon, but that just might be because I have a hard time visualizing the text button/it's placement.
Maybe with a screenshot it would be easier to visualize.

If we go for text we should propably replace "more" with "new" because they dont get appended.

I do plan on adding a hover text/title to it though.

[ST-DDT]

How readable do you think the current implementation is?

[matthewmayer]

How readable, do you consider the current implementation?

i dont think its very intuitive what would happen if you press it (and bear in mind hover titles dont work on mobile). So i'd prefer something more explicit.

[matthewmayer]

Maybe something like this
"Load new examples"
"Load random examples"
"Randomize examples"

[xDivisionByZerox]

i dont think its very intuitive what would happen if you press it (and bear in mind hover titles dont work on mobile). So i'd prefer something more explicit.

I understand your perspective, but I respectfully disagree. The reload symbol is a widely recognized icon in UI/UX design, and it's generally understood by users. Our documentation is aimed at developers, who are likely familiar with this symbol.

Regarding the mobile issue, our primary focus has been on optimizing the desktop experience. While mobile functionality is important, the majority of our users access the documentation on desktop. Therefore, we prioritize desktop usability. I appreciate your feedback, but I believe the current design is effective for our target audience.

[ST-DDT]

How readable, do you consider the current implementation?

Well, I meant the actual source code, not the visualization. I was recently told that my code is hard to read/maintain for other developers.
So I appreciate any feedback. Is the complexity of the code appropriate for the complexity of the task?

[ST-DDT]

preferably yes, the visual glitch when the first refresh happens is a little disconcerting

Should I

• dynamically download/embed prettier to format the example results
• or should we generally switch to JSON like result examples?

[matthewmayer]

Pulling in prettier client-side for this sounds like overkill. I think using JSON-like results with double quotes in the example output sounds simpler.

[ST-DDT]

Ready for review

[xDivisionByZerox]

I did some explorative testing on the preview and found that the location.language examples produce an error in the console:

• Link to docs

framework.CKFbI6s_.js:13  TypeError: Cannot read properties of undefined (reading 'lastElementChild')
    at J (method.DAik2iG1.js:1:2549)
    at Proxy.O (method.DAik2iG1.js:1:2981)
    at a (method.DAik2iG1.js:1:1350)
    at Qt (framework.CKFbI6s_.js:13:38)
    at He (framework.CKFbI6s_.js:13:108)
    at HTMLButtonElement.n (framework.CKFbI6s_.js:18:7223)

Otherwise the experice feels pretty clean. One weird thing might be the examples of faker.seed since it is designed to return the same value for a designated seed. I don't think there is some special handling neccessary, tho.

[ST-DDT]

I did some explorative testing on the preview and found that the location.language examples produce an error in the console:

• Link to docs

framework.CKFbI6s_.js:13  TypeError: Cannot read properties of undefined (reading 'lastElementChild')
    at J (method.DAik2iG1.js:1:2549)
    at Proxy.O (method.DAik2iG1.js:1:2981)
    at a (method.DAik2iG1.js:1:1350)
    at Qt (framework.CKFbI6s_.js:13:38)
    at He (framework.CKFbI6s_.js:13:108)
    at HTMLButtonElement.n (framework.CKFbI6s_.js:18:7223)

The issue was caused by the additional property after the function call.

faker.location.language().name

For now, I added support for a single property after the function call.
(And improved the handling when no end can be detected.)

You can test this with the airline module, just add a property to one of the examples there.
(I don't know a method that has them yet other than location.language)
faker.location.language now works to a certain extend (aka it will display TypeErrors because the method does not exist in the latest release).

There are 3 ways to handle these type errors:

• disable refresh buttons on new methods (currentVersion < since)
  (This doesn't handle breaking changes/new options)
• or change the error name to "not released yet"
• or use the built version of faker instead of the released one (separate PR)

Especially for new methods/during their initial review, it might be helpful to be able to show more results with a simple click.
Note: Always review the PR code changes first, before viewing any preview.

[matthewmayer]

If we can find a way where it works for non-released methods even deploy previews I think that's a nice addition to help with QA.

[ST-DDT]

Ready for review.

[Shinigami92]

I don't know what is happening on my local machine, but the CSS animation does not get triggered 😕
However when I try the code as an example in JSFiddle, there it works?!
I currently have Chrome Version 131.0.6778.205 (Official Build) (64-Bit) and also Firefox 133.0.3 (64-Bit)
Windows Version 23H2 (Build 22631.4602)

On my iOS iPhone the animation works 👀 That is very confusing...