Prototype props table for design system documentation #103561
Conversation
matticbot
added
the
[Status] Needs Review
Jetpack Cloud live (direct link)
Automattic for Agencies live (direct link)
|
| const pick = < O extends Record< string, any >, K extends Array< keyof O > >( | ||
| obj: O, | ||
| keys: K | ||
| ): Pick< O, K[ number ] > => | ||
| Object.fromEntries( Object.entries( obj ).filter( ( [ key ] ) => keys.includes( key ) ) ) as Pick< | ||
| O, | ||
| K[ number ] | ||
| >; | ||
|
|
||
| const omit = < O extends Record< string, any >, K extends Array< keyof O > >( | ||
| obj: O, | ||
| keys: K | ||
| ): Omit< O, K[ number ] > => | ||
| Object.fromEntries( | ||
| Object.entries( obj ).filter( ( [ key ] ) => ! keys.includes( key ) ) | ||
| ) as Omit< O, K[ number ] >; | ||
|
|
||
| const mapValues = < V, MV >( | ||
| obj: Record< string, V >, | ||
| fn: ( value: V ) => MV | ||
| ): Record< string, MV > => | ||
| Object.fromEntries( Object.entries( obj ).map( ( [ key, value ] ) => [ key, fn( value ) ] ) ); |
There was a problem hiding this comment.
This is a good example of where rolling our own utilities is not so fun 🙃 (Re: #103048 (comment))
| const DOCUMENTED_COMPONENTS = [ 'breadcrumbs', 'summary-button' ]; | ||
|
|
||
| const files = DOCUMENTED_COMPONENTS.map( ( component ) => `${ component }/index.tsx` ); |
There was a problem hiding this comment.
I think in the future this would ideally be something we don't maintain as a list and instead glob( 'src/*/index.tsx' ). But react-docgen-typescript is pretty slow at parsing, and we have a lot of components -- most of which we don't plan on keeping here long-term. So for now I went with an allowlist.
|
This PR does not affect the size of JS and CSS bundles shipped to the user's browser. Generated by performance advisor bot at iscalypsofastyet.com. |
packages/components/package.json
Outdated
| }, | ||
| "./styles/*": { | ||
| "calypso:src": "./styles/*" | ||
| }, | ||
| "./metadata": { | ||
| "dsdocs:src": "./dist/metadata.js", |
There was a problem hiding this comment.
This and the inline Docusaurus plugin are meant to kinda "hide" this from the public interface of the package. In the future, if we want to standardize and expose this, we should probably just have this available as "import"
There was a problem hiding this comment.
I reverted this in 7f2d6ab to use plain, "public" import. Docusaurus doesn't seem to be very compatible with using conditionNames overrides in the Webpack configuration. I was getting a bunch of errors in how the internal theme's CSS modules were being processed:
Example:
Syntax error: /Code/wp-calypso/node_modules/@docusaurus/theme-classic/lib/theme/AnnouncementBar/CloseButton/styles.module.css Unknown word "closeButton_rfix" (2:31)
1 | // extracted by mini-css-extract-plugin
> 2 | export default {"closeButton":"closeButton_rfix"};
| ^
| @@ -0,0 +1,53 @@ | |||
| import metadata from '@automattic/components/metadata'; | |||
| import { VisuallyHidden } from '@wordpress/components'; | |||
There was a problem hiding this comment.
Problem: I'm running into some strange errors when building the site, specifically during static site generation. I'm wondering if there might be some incompatibility with using WordPress components in a statically rendered context?
I don't see Gutenberg rendering this Emotion Cache provider anywhere. I also tried to "swizzle" a wrapper to provide the context, but the error persisted.
Possible solution could be to use ScreenReaderText from @automattic/components, or create a duplicate copy in this project, or avoid the visually-hidden content altogether.
[errors]: [
Error: Can't render static file for pathname "/components/summary-button"
at generateStaticFile (/Code/wp-calypso/node_modules/@docusaurus/core/lib/ssg/ssg.js:167:15)
at processTicksAndRejections (node:internal/process/task_queues:105:5)
at runNextTicks (node:internal/process/task_queues:69:3)
at process.processImmediate (node:internal/timers:459:9)
at async /Code/wp-calypso/node_modules/p-map/index.js:57:22 {
[cause]: Error: The `useCx` hook should be only used within a valid Emotion Cache Context
at server.bundle.js:7113:13
at useContextSystem (server.bundle.js:7176:19)
at UnconnectedVisuallyHidden (server.bundle.js:7608:7)
at Uc (server.bundle.js:4062:44)
at Xc (server.bundle.js:4067:395)
at Z (server.bundle.js:4070:89)
at Yc (server.bundle.js:4073:98)
at $c (server.bundle.js:4072:140)
at Z (server.bundle.js:4070:345)
at Xc (server.bundle.js:4065:476)
There was a problem hiding this comment.
I opted to replace in fcc2522 with static text. This table will need some design refinement anyways, so let's make it a future problem to solve.
|
This PR modifies the release build for the following Calypso Apps: For info about this notification, see here: PCYsg-OT6-p2
To test WordPress.com changes, run |
Closes DS-206
Proposed Changes
@automattic/componentspackage build to compile documentation metadata for documented componentsThis is meant to be an early, prototype implementation, subject to design refinement.
For review, consider:
Additional notes:
Why are these changes being made?
Testing Instructions
Packages need to be built first:
Then, start the documentation site:
Navigate to "Components" and verify that a props table is shown for Summary Button and Breadcrumbs.
Pre-merge Checklist