feat(props): add props data gathering and table rendering support by wise-king-sullyman · Pull Request #40 · patternfly/patternfly-doc-core

wise-king-sullyman · 2025-04-09T16:39:34Z

Closes #41

To test this PR:

pull this branch
install the deps
run build:props (this will happen automatically when the server is started via the CLI)
start the dev server
go to http://localhost:4321/get-started/contribute
verify that the props table renders
go to the contribute.md file in textContent
add other components to the propComponents array (or add that entry to other files)
verify that those other components start showing too.

wise-king-sullyman · 2025-04-09T16:46:36Z

astro.config.mjs

+
+  adapter: node({
+    mode: 'standalone'
+  })


These changes enable astro to run a node server for the custom endpoint below in props.json.ts

wise-king-sullyman · 2025-04-09T16:55:05Z

cli/buildPropsData.ts

@@ -0,0 +1,94 @@
+/* eslint-disable no-console */


This file ingests the files which should have their props parsed, parses the props out using tsDocGen, compiles that data into a single object, then writes that object to a json file.

wise-king-sullyman · 2025-04-09T16:55:51Z

cli/cli.ts

+try {
+  astroRoot = import.meta
+    .resolve('@patternfly/patternfly-doc-core')
+    .replace('dist/cli/cli.js', '')
+    .replace('file://', '')
+} catch (e) {
+  if (e.code === 'ERR_MODULE_NOT_FOUND') {
+    astroRoot = process.cwd()
+  } else {
+    console.error('Error resolving astroRoot', e)
+  }
+}


This change just makes it so that we can run the docs-core locally more easily

wise-king-sullyman · 2025-04-09T16:56:55Z

cli/tsDocGen.ts

@@ -0,0 +1,207 @@
+import { readFile } from 'fs/promises'


This file is 99% just tsDocGen from the current docs framework. I'd like us to clean this up at some point, but that that is best left for further down the road.

wise-king-sullyman · 2025-04-09T16:57:42Z

pf-docs.config.mjs

@@ -0,0 +1,31 @@
+export const config = {


This top level config files is also something that I just added to make running this repo locally easier.

wise-king-sullyman · 2025-04-09T16:58:08Z

src/components/PropsTable.tsx

 }

-type PropsTableProps = {
+interface PropsTableProps extends React.HTMLProps<HTMLDivElement> {


I needed to make this change so that we could pass a key prop to the tables without TS throwing an error.

wise-king-sullyman · 2025-04-09T16:59:57Z

src/pages/[section]/[...id].astro

+async function getPropsData(propComponents: string[]) {
+  if (!propComponents.length) {
+    return []
+  }
+
+  const url = new URL(`/props?components=${propComponents}`, Astro.url)
+  const response = await fetch(url)
+  const propsData = await response.json()
+
+  return propsData
+}


At its root the new process works by the frontend hitting the backend /props route with its propComponents value as a query param. The backend then returns only the requested components prop data in json.

wise-king-sullyman · 2025-04-09T17:00:46Z

src/pages/props.ts

+import { readFileSync } from 'fs'
+import { join } from 'path'
+
+const propsFilePath = join(process.cwd(), 'dist', 'props.json')
+const propsData = readFileSync(propsFilePath)
+const props = JSON.parse(propsData.toString())
+
+export const prerender = false
+
+export async function GET({ request }: { request: Request }) {
+  const queryParams = new URL(request.url).searchParams
+  const components = queryParams.get('components')
+  const componentsArray = components?.split(',')
+  const propsData = componentsArray?.map((component) => props[component])
+
+  return new Response(JSON.stringify(propsData))
+}


This is what creates the custom endpoint to get the props data from the frontend.

wise-king-sullyman · 2025-04-09T17:01:13Z

textContent/contribute.md

 id: Contribute
 title: Contribute to PatternFly
 section: get-started
+propComponents: ['Button', 'BadgeCountObject']


This is just for testing/demo purposes.

thatblindgeye · 2025-04-15T12:46:25Z

cli/cli.ts

-  .resolve('@patternfly/patternfly-doc-core')
-  .replace('dist/cli/cli.js', '')
-  .replace('file://', '')
+async function generateProps(program: Command, forceProps: boolean = false) {


Just curious, what would the expected use case of forceProps be?

Whenever we want to enforce the props being generated on the CLI internals side regardless of if the user passes the --props flag, such as for when doing a production build.

thatblindgeye · 2025-04-15T12:57:24Z

cli/templates/pf-docs.config.mjs

+    // {
+    //   include: ['*/@patternfly/react-core/src/**/*.tsx'],
+    //   exclude: [
+    //     '/**/examples/**',
+    //     '/**/__mocks__/**',
+    //     '/**/__tests__/**',
+    //     '/**/*.test.tsx',
+    //   ],
+    // },


Is this expected to be removed or uncommented before merging?

Nope I was planning to leave it commented in the template file like the content entry, but I'm not dead set on that.

thatblindgeye · 2025-04-15T13:14:05Z

cli/tsDocGen.ts

+      (type && type.name) ||
+      (type && (type.raw || type.name)) ||
+      (tsType && (tsType.raw || tsType.name)) ||
+      'No type info',


Could either remove this or update the PropsTable since I had included a fallback there with a similar string.

Yeah we can if you want, I just wasn't trying to mess with tsDocGen any more than I needed to at the moment.

thatblindgeye · 2025-04-15T13:21:09Z

src/pages/[section]/[...id].astro

+    propsData
+      .filter((comp: any) => !!comp)
+      .map((component: any) => (


Would be something in a future update, but wondering if we want to tweak the order the prop tables get rendered. Believe currently it's just based on whatever order the propComponents array in frontmatter is written, but would sorting alphabetically make more sense? Or some other way to dictate what the order should be rather than manually having to know "Component X should be rendered before Component C because Reasons"

I think I lean towards just letting the order be dictated by the propsData order? Just because it's the simplest solution and lets the order be dictated consumer side. But I'm not firmly against us sorting it some way theoretically.

github-actions · 2025-05-01T13:20:55Z

🎉 This PR is included in version 1.3.0 🎉

The release is available on:

Your semantic-release bot 📦🚀

feat(props): add props data gathering and table rendering support

3331d6d

thatblindgeye self-requested a review April 9, 2025 16:49

rename custom props endpoint to just props instead of props.json

7183400

wise-king-sullyman commented Apr 9, 2025

View reviewed changes

thatblindgeye reviewed Apr 15, 2025

View reviewed changes

wise-king-sullyman added 4 commits April 16, 2025 16:25

Refine, add tests, update documentation

3fc15bf

Merge branch 'main' into add-props-data-gathering

c13287c

Fix type error

b3514e5

Update snapshot

ed7b44e

wise-king-sullyman marked this pull request as ready for review April 16, 2025 20:45

wise-king-sullyman requested review from dlabaj and thatblindgeye April 16, 2025 20:46

wise-king-sullyman added 2 commits April 29, 2025 16:33

Add props table rendering to tabs pages

c12ebd7

Fix build error

40ec0c0

thatblindgeye approved these changes Apr 30, 2025

View reviewed changes

dlabaj approved these changes May 1, 2025

View reviewed changes

dlabaj merged commit fb6a78e into main May 1, 2025
1 check passed

github-actions bot added the released label May 1, 2025

Conversation

wise-king-sullyman commented Apr 9, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

wise-king-sullyman Apr 16, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

github-actions bot commented May 1, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

wise-king-sullyman commented Apr 9, 2025 •

edited

Loading

wise-king-sullyman Apr 16, 2025 •

edited

Loading