Let's reference nextra's remark plugin to automatically convert markdown images to next/image: https://github.com/shuding/nextra/blob/main/packages/nextra/src/mdx-plugins/static-image.ts

We use a few modules as placeholders that are ultimately intercepted by our loader. Currently, we manually maintain definition files for these placeholders so that type information is accurate when these modules are imported in custom themes and during usage.

Placeholder modules:

• swingset/meta
• swingset/theme

Each module should have a a .d.ts file in packages/swingset/src

Swingset should expose a small CLI with a bootstrap command to add the necessary boilerplate.

Mock output:

$ swingset bootstrap

Generating swingset route group...

Success! Route group created:

(swingset)
  ├ /layout.tsx
  └ /swingset
    ├ /page.tsx 
    └ /[...path]
      └ /page.tsx

Currently test expects an error to be thrown when one segment is the input.

This isn't accurate to desired result, an error is only desired for >3 segments.

Asana Task Summary

Ability to dismiss the left-hand navigation menu and just view markup.

An example can be found in the current version of swingset

When parsing a component's documentation file, we should read the path frontmatter property and parse out a few values.

---
path: '[category]/[folder]/[page]'
---

• [category] - optional top-level sidebar category, no URL implications
• [folder] - optional nested folder, represented in URL
• [page] - Page’s title

To start, we want to parse these values out of the path frontmatter property if it exists. Heuristic: The [page] will always be pulled from the last segment. The root [category] will always be the first segment (if > 1). [folder] is optional and will be treated as the 2nd segment if 3 are provided.

Input:

---
path: 'Components/Forms/Input'
---

output:

{
  category: 'Components',
  folder: 'Forms',
  page: 'Input'
}

Input:

---
path: 'Components/Button'
---

output:

{
  category: 'Components',
  page: 'Button'
}

Input:

---
path: 'Button'
---

output:

{
  page: 'Button'
}

Currently, themes are expected to expose a default export and a named Page export. The default export is the Layout, and the named export is used as the page component for the dynamic swingset route. It might make more sense to have both of these be named exports for clarity.

// layout.ts
import { layout } from 'swingset/theme'

export default layout

// page.ts
import { page } from 'swingset/theme'

export default page

👋 It looks like since globby doesn't support Windows paths (sindresorhus/globby#130 & sindresorhus/globby#127), the globbing and path operations across swingset silently fail on Windows machines.

To be clear, the package still compiles and no errors are thrown, yet when running on Windows, components-loader.js won't find any components to build into Next.js pages.

I've got a branch working that addresses these issues, but it's tricky since globby, path, and webpack need a variety of path styles. I have successfully run the peerComponents example with [some ugly] changes made locally 🎉

I'll have a PR up for this once I do a bit of clean up on my fork 😄

cc: @BRKalow

It seems like a swingset theme's CSS is loading after CSS modules imported into component source files, resulting in any global styles overriding the component styles. We should try and tweak this so that the theme CSS is loaded first.

When using a props.json5 file, its defaultValue property is used to control the default control value in a <KnobsComponent>. This is confusing, as the props.json5 file refers to "props" in its name, suggesting defaultValue would be the default value in the shape of the data, like defaultProps in React, or a default parameter in JS.

It might make more sense to move context-specific props into their own object.

{
  inline: {
    description: 'Determines whether to display the alert inline and only with a tagline',
    type: 'boolean',
    knob: {
      type: 'checkbox',
      defaultValue: false
    }
  }
}

Each workspace has a dev command that works, but they need to be triggered manually in order to get the example to run. We should come up with a way to encapsulate this. Current:

In three separate shells:

1. npx turbo run dev --filter 'swingset'
2. npx turbo run dev --filter 'swingset-theme-hashicorp'
3. npx turbo run dev --filter 'example-basic'

Drop in your suggestions below in this thread....

• Vote up with 👍

Hello, we were trying to integrate Swingset in our application to have a less heavy platform to display our components on.

Despite reading in your README that it is not recommended for use, we hoped to give it a shot. Unfortunately I can't seem to get it working properly.

I get the following error message:

./node_modules/swingset/page.jsx 33:6
Module parse failed: Unexpected token (33:6)
You may need an appropriate loader to handle this file type, currently no loaders are configured to process this file. See https://webpack.js.org/concepts#loaders
| 
|     return (
>       <div className={s.root}>
|         <Head>
|           <title key="title">Component Library</title>

I've tried installing next-transpile-modules to hope to fix this issue but that resulted in another error message:

Server Error
TypeError: Cannot read property 'src' of undefined

../../pages/_document.tsx (86:33) @ Function.getInitialProps

    |     }
    | 
 >  |     const { html, head } = await ctx.renderPage({ enhanceApp })
    |                                 ^
    |     const styles = [...flush()]
    |     return { html, head, styles }
    |   }

We're using the latest version of next ( 10.0.7 ) and are using TSX for all our components.

I totally understand if you'd close this issue. 😄

We should expose utilities / sensible defaults for generating page metadata. Most likely we should have default functionality baked in that can be extended as needed.

App Router metadata docs for reference: https://beta.nextjs.org/docs/api-reference/metadata

Not an issue, but discussions aren't enabled, so I'm leaving this here.

I'm currently looking for a Storybook replacement that allows for more flexibility. Am looking at building a component library site with Nextra (and a forked docs theme). Swingset looks like it might integrate well with that. I'm looking forward to seeing how/if this project progresses.

Octavo could switch from doc.mdx to README.mdx.

GitHub supports README.mdx files and gives them the same treatment as README.md files when viewing a directory. NPM also supports README.mdx files.

In both cases, they are displayed static, meaning the react components themselves are not hydrated. Self-closing elements, like the knobs component, would not be rendered at all in the static view, which may actually be ideal.

Using README.mdx seems like a better fallback pattern, and it would result in less repetition than having both docs.mdx and README.mdx files.

The Docs for the class-variance-authority package, point out that that clsx is already included under the export cx

For the sake of consistency let's ensure we're only using cx instead of having the same package twice under different names

Entities contain unnecessary that we don't need exposed to the theme.

The unneeded properties are being removed however the types don't reflect this.

See packages/swingset/src/types.ts and packages/swingset/src/get-nav-tree.ts to resolve

In the select control, Select an option... is added to the available options, even tho it is not an option.

If mdx-components.js does not exist, we fallback to @mdx-js/react. This causes problems for server components as it uses a React context internally.

We should no-op providerImportSource if mdx-components.js is not able to be resolved.

Reference: https://github.com/hashicorp/next-mdx-remote/blob/main/src/serialize.ts#L33-L34

The getNavigationTree is large and needs should have some tests to prevent regression down the line, especially for when standalone docs become more involved.

Ensure that default theme renders navigation with categories.

A quick fix would be to just use the components from hashicorp-theme

I have started seeing the following error.

error - ./node_modules/@hashicorp/octavo/__octavo_components.js
TypeError: path.replace is not a function

I have removed node_modules and started the project over. I have also inspected that file, which is nearly empty with the following contents:

// this import is always intercepted by a loader
module.exports = {}

Internally, swingset distinguishes between component documentation and standalone documentation. This is evident on the generated metadata objects for each detected document:

  "text": {
    "__type": "component", // 👈 __type property represented here
    "frontmatter": {},
    "category": "default",
    "filepath": "...",
    "relativePath": "components/text/docs.mdx",
    "normalizedPath": "text",
    "componentPath": "components/text",
    "slug": "text"
  },

We should expose a method to get metadata based on the document type and category. This will allow themes to build a navigation element that has access to all available paths.

The exported categories currently is currently indexed by insertion order.

To ensure the top level array and the children, render alphabetically, the getNavigationTree function should also contain sorting logic.

Workflow Name: Release
Branch: main
Run URL: https://github.com/hashicorp/swingset/actions/runs/4886563487

save-state deprecation warnings: 0
set-output deprecation warnings: 1
node12 deprecation warnings: 1

Please review these deprecation warnings as soon as possible and merge in the necessary updates.

GitHub will be removing support for these commands and plan to fully disable them on 31st May 2023. At this time, any workflow that still utilizes these commands will fail. See https://github.blog/changelog/2022-10-11-github-actions-deprecating-save-state-and-set-output-commands/.

GitHub have not finalized a date for deprecating node12 yet but have indicated that this will be summer 2023. So it is advised to switch to node16 asap. See https://github.blog/changelog/2022-09-22-github-actions-all-actions-will-begin-running-on-node16-instead-of-node12/.

If you need any help, please reach out to us in #team-rel-eng.