feat(docs): colocate component docs and redesign UX#634
Merged
Conversation
Contributor
|
🚀 VitePress preview is ready: |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
This comment was marked as outdated.
This comment was marked as outdated.
Sorry, something went wrong.
- Redesign sidebar to pill-style items with uppercase section headers and h-7 row height - Move homepage into sidebar layout with Overview as first item - Redesign hero with left-aligned split layout and Shiki syntax highlighting - Refactor showcase to CSS columns masonry layout with fragment col files - Remove VitePress page transition animation - Add `kbd` global styles to Tailwind plugin - Fix horizontal overflow from grid min-width default Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Replaces VitePress's MiniSearch-based doc-content search with a focused page-navigation palette built on the frappe-ui Dialog: - Sidebar list extracted to a shared module; search and sidebar now share the same source of truth and only sidebar entries are searchable (no doc content) - Fuzzy matching via fuzzysort; results regrouped by sidebar section - Client-side navigation via VitePress router; "Current" badge on the active page - Cmd/Ctrl+Enter (or modifier-click) opens the result in a new tab - Navbar z-index lowered so the dialog overlay sits above it Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
- Restore the dedicated home layout (no sidebar, centered hero, grid showcase) by reverting the relevant parts of the homepage redesign - Drop the "Overview" link from the sidebar (only made sense when the homepage lived inside the sidebar layout) - Move the dev-branch badge before the "Docs" link in the navbar so the layout reads naturally on the homepage Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace hand-rolled keyboard navigation, active-index state, and ARIA wiring with ListboxRoot / ListboxFilter / ListboxContent / ListboxGroup / ListboxItem. Reka now owns roving focus, arrow-key navigation, aria-activedescendant, role="option", and aria-selected; we keep only the bits it can't infer: - onItemSelect calls router.go() instead of letting reka commit a modelValue, so navigation is client-side - onFilterKeydown intercepts Cmd/Ctrl+Enter — reka's synthetic click for keyboard Enter drops modifier flags, so we open in a new tab by reading the [data-highlighted] item ourselves - Each item renders `as="a"` with an href, so Cmd/Ctrl+click opens a new tab natively Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Move each component's docs page and auto-generated API table from docs/content/docs/components/<name>.md + docs/meta/<Name>.md to src/components/<Name>/<Name>.md + <Name>.api.md, so a component's implementation, stories, types, and docs all live in one folder. A small Vite plugin (colocatedComponentDocs.ts) writes a thin @include proxy into docs/content/docs/components/ before VitePress scans srcDir, so the existing URL structure is unchanged. Proxies are gitignored; legacy.md (the only hand-written file left in that dir) is preserved via a negation. propsgen now emits <Folder>.api.md alongside the component. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
Replace the regex pair that drove ComponentPreview/PropsTable detection with @vue/compiler-dom's baseParse. Attribute order no longer matters, `:data` is now properly recognised as a directive rather than a magic attribute name, and a malformed tag falls through cleanly instead of silently mismatching. Token mutation now walks state.tokens directly in reverse, and the script-setup unshift is deferred until after the iteration loop — doing it mid-loop shifted every captured tokenIdx by +1 and caused writes to land on the wrong token (latent in the old code, surfaced once Calendar.md's two previews were both routed through this path). Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
netchampfaris
force-pushed
the
v1-release/docs-ux
branch
from
e50b4c3 to
5461189
Compare
netchampfaris
changed the title
Contributor
Author
|
/barista review |
|
Re-reviewing per @netchampfaris — focused on correctness and API surface. Concerns — one public-API side-effect in the Tailwind plugin.
Minor nits — nothing blocking.
|
Replace the per-tag `css` prop on `<ComponentPreview>` with a sensible default in Demo.vue (`flex flex-wrap gap-3 items-center`) plus per-story wrappers where the layout differs. - Demo.vue: remove the `css` prop; preview area is just a styled canvas with the default flex layout. - 24 component docs: strip `class=` / `css=` from every preview tag. - 38 stories: explicit wrapper for the non-default cases. Grid-display overrides get a plain `<div class="grid …">`; additive overrides (`justify-center !py-20`, `h-screen overflow-hidden`, `!p-0`) are self-sufficient and include the flex base so the wrapper carries its own layout. Toast's `flex-wrap` is now covered by the default. The 94 stories with no override no longer need a wrapper at all. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The grid-override wrappers lost their gap and item-alignment when the class prop went away, because the original Demo.vue used to append the user's class after `flex gap-3 items-center` — so even when display flipped to grid, those two utilities still applied. And every wrapper sat as a flex child of Demo.vue, so `justify-center` only centered content within the wrapper's content width, not the preview area. - Prepend `gap-3 items-center` to grid wrappers (skipped when the override already pins its own gap). - Add `w-full` to every story wrapper so `justify-center` and grid layouts span the preview area. - Sidebar's `!p-0` couldn't cancel Demo.vue's outer p-8 from a child; replaced with `!-m-8` so the sidebar sits flush. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
The global kbd base rule in tailwind/plugin.js was overriding the browser-default monospace styling for every kbd element in consumer projects. Move the styles inline onto the search popup's kbd elements.
Use reka-ui's `@highlight` event to track the highlighted item instead of probing the DOM, and let the anchor's native modifier-click behavior handle new-tab opens — only intercept plain clicks for SPA navigation. Drop the "Current" page marker. Untrack the auto-generated `docs/content/components.d.ts` so the existing gitignore rule applies. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
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
1 participant
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
Docs UX overhaul. Four layers of change:
Authoring layout — colocate component docs
src/components/<Name>/<Name>.md(hand-written) +<Name>.api.md(auto-generated bypropsgen).docs/.vitepress/plugins/colocatedComponentDocs.ts) writes a thin@includeproxy intodocs/content/docs/components/<name>.mdat config-load time so URLs are unchanged. Proxies are gitignored;legacy.mdis preserved via a negation.docs/scripts/propsgen.tsnow emits<Folder>.api.mdnext to the component.Component transformer — parse with Vue compiler instead of regex
componentTransformer.tsrewritten to use@vue/compiler-dom'sbaseParsefor<ComponentPreview>/<PropsTable>tags. Attribute order no longer matters and:datais properly recognised as a directive.unshiftwas happening mid-loop, shifting every capturedtokenIdxby +1. Imports are now collected during iteration and applied once after the loop.Story layout — drop the
cssprop, default in Demo.vue, override in stories<ComponentPreview>no longer accepts a layout-shaping prop (wascss).flex flex-wrap gap-3 items-center— covers 94 stories with no boilerplate.<div>wrapper. Grid overrides get<div class="grid …">; additive overrides (justify-center !py-20,h-screen overflow-hidden,!p-0) are self-sufficient and include the flex base.Visual redesign
h-7rows, homepage moved into the sidebar layout with Overview as the first item.kbdTailwind styles, fixed horizontal overflow from grid min-width default.Test plan
yarn docs:buildsucceeds and renders all 38 component pagesyarn docs:devserves colocated docs at unchanged URLs (/docs/components/<name>)yarn docs:gen:allwrites<Name>.api.mdfiles next to their components, leavesdocs/meta/empty🤖 Generated with Claude Code
Coverage
mainBaseline pulled from the latest successful
mainrun.