Docs: SubComponents (some?/all?) shown on a Component's doc page don't appear in search
xml opened this issue · 10 comments
Description
When I search for "NavItem" or "NavGroup" in the SaasUI docs site, I expect to find it in the results. Instead, I have to infer from the sample app that, since the NavItem is used within the Sidebar, I should go look there for its docs, even though its component name wouldn't imply that's the place to look.
Related: I'd expect the structure of Storybook to similarly make it clear how to find docs on such a component. Instead, the 'NavItem' and 'NavGroup' are under a heading called 'Navigation' which has a heading in the docs... but these components aren't there.
Link to Reproduction
https://saas-ui.dev/docs/components/layout/sidebar
Steps to reproduce
- Go to the Docs site
- Find a component which contains subcomponents shown on its 'Usage' tab, but which are not shown in the left sidebar
- Search for that subcomponent name using the "Search Docs" feature
- Get no results, even though you're looking right at it on the page of its parent component
Saas UI Version
2.8.7
Chakra UI Version
2.8.2
Browser
All
Operating System
- macOS
- Windows
- Linux
Additional Information
If nothing else, it would help to change the name of all sub-components so that they're at least namespaced to the parent component where I can find the docs. For instance: Sidebar-NavItem instead of NavItem tells me where to look for docs. That would at least solve 80% of the problem, if there's a logical way to do that, and if some of the problem components don't belong to multiple parents. (But... that's a workaround. They should still show up in search.)
(P.S. I'm a paid user of SaasUI-pro for a prototype. I love where it's headed in many ways, but spending 10 minutes scratching my head looking for docs on a basic component makes me loath to scale it across my company. I know you might be focused on other key features, but for an enterprise product, complete docs are a key feature.)
BTW, many thanks for this product. There's a lot of work and love shown in here. If I can be productive in supporting, and if you could direct me how to contribute a solution for this, I'd be happy to pitch in some sweat equity. However, I'm sure you'd have strong thoughts on right way to go about this, especially if it meant creating new component names and aliasing to old ones, etc.
This is great feedback, really appreciate it, it’s a massive help.
i agree with all your points, and they will be addressed in v3. It’s been a huge undertaking to get everything to the level you (and i) are expecting, so i can use all help i can get.
Now is a great time to help tinker about api and docs improvements as we’re preparing for v3.
How about i create a shared document and outline all changes for v3, on which you can give feedback and proposals?
A roadmap. Great way to rally contributors.
Here's a rough start:
https://dynamic-link-427.notion.site/Saas-UI-v3-10b7bf58b71a8033be0bdb3e6989759a
I can also invite you to the notion page so you can comment on there directly.
That'd be great. Some early suggestions until I can comment, which I recognize reflect some personal pain-points and may not be aligned to your long-term investment in the project:
-
Decouple the example apps from the monorepo so that people can use them as project starters without a ton of re-coding/re-pathing
- Eliminate any direct references from apps to parent/sibling folders in the monorepo, and instead use aliasing so that the example apps can stand alone: copying the folder and running
yarn/npm installshould be fully-functional - Either make the "packages" and "lib" stuff a real npm package that can be imported, or create a one-step 'eject' command which copies it all to the same basic end
- Eliminate any direct references from apps to parent/sibling folders in the monorepo, and instead use aliasing so that the example apps can stand alone: copying the folder and running
-
Consider adopting an opinionated TS-first lint config like Tim James', to ensure greater consistency of style across the example apps, to identify TS problems a bit sooner, and to minimize the amount of recoding necessary when adopted by a user who likes strong lint configs.
- Salient Example: after porting the app to Vite, it throws on all the imports of types which aren't explicitly imported as types. There's a linter rule for that.
- It's easy to stop using an opinionated config if a user doesn't like it, but difficult for user to adopt one in a project that hasn't been using one
-
Adopt the Chakra 3.0 approach to namespacing and dot-notation (and relocate orphans like NavItem, NavGroup, etc.). Begin adopting this approach on the current version by using aliases to the current names/locations, and publish a schedule to deprecate the aliases and make the moves permanent.
Stuff that I know gets into opinion-land, about using more standard tech for a library:
-
Consider going with npm to make this product a zero-complication first install and learning experience.
- Yarn is amazing but I just do not see the community using it much for libraries. I think it's a bit unfriendly to the average adopter to force them to switch to it immediately, just to mess with this library and its sample apps. It's a good tool, but 'idiosyncratic' in a library. If we want saas-ui to truly be plug-and-play, I'd suggest going with the grain of npm's usage numbers.
- Especially since the use of yarn/npm workspaces and aliases is so essential to monorepos, and to making good use of the example apps, it's ideal to go with the tool people use most and most comfortably.
- And, it's very easy for people to switch to Yarn later if that's what benefits their scale. Whereas the amount of effort involved in making every single person install Yarn just to demo this...
-
Consider whether building the next version's sample app with Vite and React-Router would accomplish the same goals (easy adoption, rapid education) in a more readable and framework-neutral way.
- Next, like Yarn, is amazing but a double-edged sword: while it's really awesome for certain use-cases like retail and publishing, it's very idiosyncratic in its syntax, router-configuration, etc. It's definitely not what passes for "plain-vanilla react". Which I think defeats your goal of using the sample apps for educational purposes.
- The app router, whatever its virtues, is just plain difficult to read and reason about re: paths, default renders, etc. Even if you know Next, which many potential users do not.
- Next is a huge PITA with Cordova, Electron, etc. It has made progress and is at least possible there, but not easy.
- And, it immediately forces you into deploying to a node server rather than just deploying artifacts on a service like Cloudflare or Vercel. Fine for larger organizations, very bad for people just getting started with a SaaS startup and still iterating rapidly.
Can you share you email address for notion? you can mail it to eelco@saas-ui.dev
That'd be great. Some early suggestions until I can comment, which I recognize reflect some personal pain-points and may not be aligned to your long-term investment in the project:
Decouple the example apps from the monorepo so that people can use them as project starters without a ton of re-coding/re-pathing
- Eliminate any direct references from apps to parent/sibling folders in the monorepo, and instead use aliasing so that the example apps can stand alone: copying the folder and running
yarn/npm installshould be fully-functional
I assume you mean alias everything uses tsconfig path aliases?
- Either make the "packages" and "lib" stuff a real npm package that can be imported, or create a one-step 'eject' command which copies it all to the same basic end
Assuming you mean the saas-ui-pro repo here. I thinking about doing some serious refactoring after the new next.js starter is ready. Moving the starter into it's own repo, keeping it as minimal as possible, it will stay a monorepo though.
Add more basic templates in the saas-ui-pro that can run on their own, without any external monorepo packages.
As well as a new CLI that can install components / blocks / templates into existing projects (including installing required dependencies, etc)
Consider adopting an opinionated TS-first lint config like Tim James', to ensure greater consistency of style across the example apps, to identify TS problems a bit sooner, and to minimize the amount of recoding necessary when adopted by a user who likes strong lint configs.
- Salient Example: after porting the app to Vite, it throws on all the imports of types which aren't explicitly imported as types. There's a linter rule for that.
- It's easy to stop using an opinionated config if a user doesn't like it, but difficult for user to adopt one in a project that hasn't been using one
I'm not a big fan of too much linting rules, so I kept it fairly simple. But I do agree we could settle on a popular config that works well across typescript frameworks. I think the Epic web configs are good too: https://github.com/epicweb-dev/config
- Adopt the Chakra 3.0 approach to namespacing and dot-notation (and relocate orphans like NavItem, NavGroup, etc.). Begin adopting this approach on the current version by using aliases to the current names/locations, and publish a schedule to deprecate the aliases and make the moves permanent.
Great idea, although I lack development bandwidth for this myself and need all the time I have to start the v3 migration.
Stuff that I know gets into opinion-land, about using more standard tech for a library:
Consider going with npm to make this product a zero-complication first install and learning experience.
- Yarn is amazing but I just do not see the community using it much for libraries. I think it's a bit unfriendly to the average adopter to force them to switch to it immediately, just to mess with this library and its sample apps. It's a good tool, but 'idiosyncratic' in a library. If we want saas-ui to truly be plug-and-play, I'd suggest going with the grain of npm's usage numbers.
Unfortunately I find npm very lacking in some features and not very suitable for managing a repo for library of packages. A lot of projects have switched to PNPM.
- Especially since the use of yarn/npm workspaces and aliases is so essential to monorepos, and to making good use of the example apps, it's ideal to go with the tool people use most and most comfortably.
Yes I rather make this happen with the CLI that can eject examples into stand alone projects that could use NPM by default.
- And, it's very easy for people to switch to Yarn later if that's what benefits their scale. Whereas the amount of effort involved in making every single person install Yarn just to demo this...
Not sure if this is a valid argument, since Yarn is embedded in the repository and doesn't require any installation.
In any case npx create-sui-app --example vite-react-route to get up and running will make this more convenient.
- Consider whether building the next version's sample app with Vite and React-Router would accomplish the same goals (easy adoption, rapid education) in a more readable and framework-neutral way.
Absolutely, I already started experimenting with Vite and Tanstack Router, I'm finding Next.js becoming too complex and slow as well.
- Next, like Yarn, is amazing but a double-edged sword: while it's really awesome for certain use-cases like retail and publishing, it's very idiosyncratic in its syntax, router-configuration, etc. It's definitely not what passes for "plain-vanilla react". Which I think defeats your goal of using the sample apps for educational purposes.
Agreed.
- The app router, whatever its virtues, is just plain difficult to read and reason about re: paths, default renders, etc. Even if you know Next, which many potential users do not.
Agreed.
- Next is a huge PITA with Cordova, Electron, etc. It has made progress and is at least possible there, but not easy.
It's definitely possible, but with the move to a more SSR based framework it is becoming cumbersome.
- And, it immediately forces you into deploying to a node server rather than just deploying artifacts on a service like Cloudflare or Vercel. Fine for larger organizations, very bad for people just getting started with a SaaS startup and still iterating rapidly.
Next.js actually kinda locks you in to Vercel if you want to have best support for features like edge routes, etc.
I assume you mean alias everything uses tsconfig path aliases?
Ah! Sorry, I used a generic but incorrect term. I meant using yarn link during development, so that: if you are developing within the main repo, you can link such that saas-ui and saas-ui-pro dependencies needed by the sample app will just pull from the local repo. But, if a user just copies the whole sample app to another folder and runs yarn install and starts fresh from there, it will install the deps from npm registry without requiring any further magic.
That's slightly more work for contributors, but good general hygiene, and it makes the sample app a usable template for users without any manual port-ins from the monorepo.
If you're already planning to move it to a separate repo, then you'll end up in the same place anyway! But it could be a nice bridging step as you gradually decouple...
Unfortunately I find npm very lacking in some features and not very suitable for managing a repo for library of packages. A lot of projects have switched to PNPM.
Tell me more, please! I've found the npm workspaces feature to very easily let me embed multiple deployable packages within a single monorepo, and then some npm link commands just to keep me productive while working on all at the same time. However, I may not have all the same requirements as you do, so it'd be very educational for me to know what problems it can't solve...
Not sure if this is a valid argument, since Yarn is embedded in the repository and doesn't require any installation.
In any casenpx create-sui-app --example vite-react-routeto get up and running will make this more convenient.
That's a super-cool idea. My suggestions were focused on the baseline assumption you didn't want to add any new kinds of magic/tooling. But if you're going down that road, I completely agree that the package-manager shouldn't matter much.