Add propel-docs: an Astro documentation site for @makeplane/propel#233
Merged
Conversation
Documents the apps/propel-docs plan: Astro 7 + React islands + MDX, modeled on cloudflare/kumo's docs site but simplified (in-app react-docgen-typescript instead of a published registry, one-file- per-demo instead of AST-sliced snippets), scoped to 6 representative component pages for the first pass.
10-task plan scaffolding apps/propel-docs and building 6 representative component doc pages (button, input-field, select, dialog, table, accordion), following the approved design spec.
Adds the Dialog component-example page reusing the existing docs plumbing (ComponentLayout, ComponentExample, PropsTable), composing Button/IconButton triggers via propel's behavior-part-outer render pattern. Claude-Session: https://claude.ai/code/session_016gp5LnkAn3fkQ3woL4Z7Hi
|
📚 Storybook preview: https://pr-233-propel-storybook.vamsi-906.workers.dev |
There was a problem hiding this comment.
Pull request overview
This PR introduces apps/propel-docs, a new Astro-based documentation site intended to be the public-facing, navigable reference for @makeplane/propel’s components layer (with live demos and generated props tables), while keeping Storybook as the internal workshop.
Changes:
- Adds a new Astro 7 docs app with Tailwind v4 +
@makeplane/propel/styles, layouts, navigation, and initial landing/installation pages. - Implements build-time prop extraction via
react-docgen-typescript(reading propel source) and renders props tables + “show code” demo panels. - Adds 6 representative component pages (button, input-field, select, dialog, table, accordion) with demo variants and install snippets.
Reviewed changes
Copilot reviewed 31 out of 34 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| docs/superpowers/specs/2026-07-14-propel-docs-app-design.md | Design spec for the Propel docs Astro app scope and architecture. |
| docs/superpowers/plans/2026-07-15-propel-docs-app.md | Implementation plan detailing tasks, constraints, and verification steps. |
| apps/propel-docs/astro.config.mjs | Astro config + Tailwind plugin + dev-mode Vite aliasing to propel source. |
| apps/propel-docs/package.json | New app package definition and scripts (including packing propel before build/typecheck). |
| apps/propel-docs/tsconfig.json | TypeScript config for the docs app (adds ~/* path alias). |
| apps/propel-docs/wrangler.jsonc | Cloudflare Workers static-assets deployment config (placeholder TODOs). |
| apps/propel-docs/README.md | Usage/build notes, including the “build propel before site” deploy seam. |
| apps/propel-docs/public/favicon.svg | Site favicon asset. |
| apps/propel-docs/src/styles/global.css | Tailwind + propel styles entrypoint. |
| apps/propel-docs/src/layouts/BaseLayout.astro | Base HTML layout wiring global styles and tokens. |
| apps/propel-docs/src/layouts/ComponentLayout.astro | Sidebar + content layout for MDX pages using frontmatter. |
| apps/propel-docs/src/lib/components-registry.ts | Static registry of the initial 6 documented components. |
| apps/propel-docs/src/lib/props-schema.ts | react-docgen-typescript integration to extract props from propel source. |
| apps/propel-docs/src/components/SidebarNav.astro | Sidebar navigation component. |
| apps/propel-docs/src/components/CodeBlock.astro | Syntax-highlighted code block component. |
| apps/propel-docs/src/components/ComponentExample.astro | Live demo frame + “Show code” disclosure panel. |
| apps/propel-docs/src/components/PropsTable.astro | Props-table renderer using extracted docgen schema. |
| apps/propel-docs/src/pages/index.astro | Landing page listing initial components and entry links. |
| apps/propel-docs/src/pages/installation.mdx | Installation guide page. |
| apps/propel-docs/src/pages/components/button.mdx | Button docs page (demos + install + props). |
| apps/propel-docs/src/pages/components/input-field.mdx | Input Field docs page (demo + install + props). |
| apps/propel-docs/src/pages/components/select.mdx | Select docs page (demo + install + props). |
| apps/propel-docs/src/pages/components/dialog.mdx | Dialog docs page (demo + install + props). |
| apps/propel-docs/src/pages/components/table.mdx | Table docs page (demo + install + props). |
| apps/propel-docs/src/pages/components/accordion.mdx | Accordion docs page (demo + install + props). |
| apps/propel-docs/src/demos/button/basic.tsx | Button basic demo variant (used live + via ?raw). |
| apps/propel-docs/src/demos/button/with-icon.tsx | Button “with icon” demo variant. |
| apps/propel-docs/src/demos/input-field/basic.tsx | Input Field demo variant. |
| apps/propel-docs/src/demos/select/basic.tsx | Select demo variant. |
| apps/propel-docs/src/demos/dialog/basic.tsx | Dialog demo variant. |
| apps/propel-docs/src/demos/table/basic.tsx | Table demo variant. |
| apps/propel-docs/src/demos/accordion/basic.tsx | Accordion demo variant. |
| .gitignore | Ignores Astro build cache directory (.astro). |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
The Check & Test & Build job failed on `vp check`'s formatting step for these two markdown files (prose wrapping + table alignment). No content changes.
- props-schema: cache `parser.parse` results per source file so pages/parts sharing a source don't rebuild TS program state repeatedly (identical output). - CodeBlock: type `lang` as `CodeLanguage` directly instead of `string` + cast, so invalid values are caught by `astro check`.
`vp run -w check` type-checks apps/propel-docs's demos, which import `@makeplane/propel/components/*` — resolvable only through propel's built `dist` (its published `exports`). `dist` is gitignored and CI never built it before checking, so the lint failed with TS2307. Pack propel first. Also switch the docs `build`/`typecheck` scripts from `pnpm --filter …` to `vp run @makeplane/propel#build`: `vp` is always on PATH under setup-vp (pnpm is not), and it keeps the scripts self-contained for standalone/deploy builds while participating in Vite Task caching.
- props-schema: only memoize parse results in production builds. In `astro dev` the module persists across requests, so a permanent cache showed a stale props table after editing a propel component's types; dev now always re-parses while builds keep the caching win. - SidebarNav: set `aria-current="page"` on the active link so screen readers announce the current page, not just the visual highlight.
The workspace lint (`vp run -w check`) type-checks props-schema.ts as plain TS, where `import.meta.env` isn't declared (Astro's client types only augment ImportMeta via the generated .astro/types.d.ts, absent in CI at check time) — so it failed with TS2339. `process.env.NODE_ENV` is typed by @types/node (already in scope) and Astro sets it to "production" for `astro build` / "development" for `astro dev`, giving the same build-only-cache behavior without depending on Astro's type augmentation.
anmolsinghbhatia
approved these changes
Jul 16, 2026
Comment on lines
+21
to
+28
| import { | ||
| Select, | ||
| SelectContent, | ||
| SelectItem, | ||
| SelectLabel, | ||
| SelectList, | ||
| SelectTrigger, | ||
| } from "@makeplane/propel/components/select"; |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Adds
apps/propel-docs, a new Astro 7 documentation site for the@makeplane/propelcomponent library docs site, scoped to a lean first pass. Storybook remains the internal dev/test workshop; this is the public-facing, navigable reference.This is the template + 6 representative pages; the remaining ~59 component pages follow the same pattern (see follow-ups).
What's included
@astrojs/reactislands (hydrated only for live demos viaclient:visible) +@astrojs/mdx(one.mdxpage per component) + Tailwind v4, wired to propel's real design tokens via@makeplane/propel/styles.props-schema.ts— runsreact-docgen-typescriptagainst propel's source at build/prerender time (same extraction options proven in.storybook/main.ts), so props tables show real literal unions ("primary" | "secondary" | …), not placeholders. No new public export from propel.PropsTable.astro,ComponentExample.astro(live demo + "Show code"),CodeBlock.astro,SidebarNav.astro,BaseLayout/ComponentLayout.?rawfor the code panel.astro devresolves propel from source (instant HMR via a dev-only Vite alias);astro check/astro buildresolve propel through its real builtdist(thebuild/typecheckscripts runvp packon propel first) — preserving the real consumer experience.docs/superpowers/.Verification
astro check— 0 errors / 0 warnings / 0 hints (18 files)astro build— succeeds, static HTML for all 8 pages (/,/installation, 6 components)vp checkclean for the app; workspace unit tests 12/12 (no regression)astro dev/preview: demos render, "Show code" matches source, props tables populate with real typesDeploy notes (placeholders intact — see
apps/propel-docs/README.md)astro.config.mjssiteandwrangler.jsoncaccount_id/routesare intentional TODO placeholders — fill in when a real domain + Cloudflare account are assigned.packages/propel/distis gitignored): use the packagebuildscript, not a bareastro build.Follow-ups (out of scope, per the design spec)
The remaining ~59 component pages; site search; changelog; a "blocks" section; an agent-queryable CLI;
elements-layer docs; promotingprops-schema.tsinto a real exported registry.