layerchart

layerchart copied to clipboard

Sean, awesome talk! Noticed you were using different imports for your docs than users need to use. I have the same situation in Kitbook and using an alias solves it. So then you can import from layerchart which just happens to be an alias to your lib directory. In mine I do 'kitbook': 'src/lib' but in yours I had to do 'layerchart': 'src/lib/index.js'. I'm not sure why, but it works. Anyhow you can see how I changed your Arc docs to utilize it. If you like it, you can spread it across the rest of your examples. :)

And yes, let's talk more if you ever decide to use Kitbook. There's a some glaring features missing from it like view source code which would be almost trivial to add as I have the raw strings from each component already, I just haven't taken the time to do it. 1 thing at a time you know. But it sure would make it easier for you in some spots like how you're writing your getting started page in html, not markdown.

Oh, and Kitbook has no dark mode support or any theme for that matter and you've blown it out of the water. So that's another thing you might want to see in Kitbook first. Not sure what's important to you.

⚠️ No Changeset found

Latest commit: 6b4fc73082c26bb8ceaafdf8c0e95f182b1b4f4f

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

The latest updates on your projects. Learn more about Vercel for Git ↗︎

Name	Status	Preview	Comments	Updated (UTC)
layerchart	✅ Ready (Inspect)	Visit Preview	💬 Add feedback	Apr 29, 2024 1:44am

Any reason you don't add "dev": "pnpm --filter=layerchart dev", to your root package.json file and avoid the need to change directories?

Sean, awesome talk!

Thanks, and same to you! I loved your talk and looked into Kitbook, although I need to dig in deeper when things calm down (do they ever though 😁). It looks very robust and I see it solving some pain points I've encountered in LayerChart and Svlete UX's docs.

Noticed you were using different imports for your docs than users need to use. I have the same situation in Kitbook and using an alias solves it. So then you can import from layerchart which just happens to be an alias to your lib directory. In mine I do 'kitbook': 'src/lib' but in yours I had to do 'layerchart': 'src/lib/index.js'. I'm not sure why, but it works. Anyhow you can see how I changed your Arc docs to utilize it. If you like it, you can spread it across the rest of your examples. :)

Using different imports between the examples has always been a pain point and even have a note about it in the Getting Started section (which we will be able to remove 🎉)

The alias solution looks great! TBH it's something I meant to investigate as a solution but was concerned going through the top-level index with all it's re-exporting and would be painful for development and not allow Vite to optimize on initial startup (and possibly impact HMR). If it works out for you, I think proceeding with the rest of the examples would be awesome, and we'll just be mindful of any development performance regressions and evaluate solutions as needed. I know barrel index files are always a bundlers worst nightmare and typically frowned upon, but the DX is hard to beat. I used to feel this pain a lot early on in development (first with Snowpack, then early versions of Vite), but I know Vite continues to make big improvements here.

Btw, the explicit src/lib/index.js reference is needed to support NodeNext packages (see: https://github.com/techniq/svelte-ux/issues/280) and was handled in https://github.com/techniq/svelte-ux/pull/281

And yes, let's talk more if you ever decide to use Kitbook. There's a some glaring features missing from it like view source code which would be almost trivial to add as I have the raw strings from each component already, I just haven't taken the time to do it. 1 thing at a time you know. But it sure would make it easier for you in some spots like how you're writing your getting started page in html, not markdown.

That sounds great and I would love to see where each project can learn from one another. I rolled my own docs mostly because I wanted more control over the experience than I could get from other solutions at the time, but it's not without it's own challenges. I have an issue to track some of my ideas on how to improve the docs if you want to see where my head is. Documentation, types, accessibility, and internationalization are always areas that could be improved (along with making great functioning libraries 😁).

Most of the docs were in markdown originally (mdsvex with some extra processing) but I encountered challenges with working in markdown with Svelte code examples that outweighed the ergonomic benefits, but some of these are probably from my own ignorance 🤣. I ended up re-writing most back to regular old Svelte files. See the docs issue for more context, but a few of the issues were

• Type checking
• Prettier formatting
• Cryptic compile-time errors

Oh, and Kitbook has no dark mode support or any theme for that matter and you've blown it out of the water. So that's another thing you might want to see in Kitbook first. Not sure what's important to you.

Theming is very important, although it's also kind of specific to the implementation. Ultimately it's leveraging Tailwind classes driven by CSS variables and LayerChart's docs are powered by Svelte UX's theming (which is a Tailwind plugin). LayerChart isn't tied to Svelte UX in general (works with other frameworks like Skeleton or shadcn-svelte, or even standalone) but I do treat it as a companion library that complements one another.

Personally I would love to piecemeal some of the capability of kitbook (similar to how I leverage sveld ATM) to handle some of the challenging aspects but it might be difficult to fully replace the docs (at least in the relative near future).

Speaking of sveld, I use it to parse Svelte props/etc which works OK at best, but struggles more times with Typscript only types unless I also add JSDoc comments (and I really want Typescript to be the source of truth and not have to "double define"). If you have a solution here I would love to hear it :). I'm also looking to document non-components such as Svelte stores (at least until they are converted to runes), actions, and utils. These are mostly a Svelte UX need, although there are a few in LayerChart as well (some of which are undocumented at this time).

Thanks again for the PR and I would love to proceed with using the alias (and hopefully we don't hit any performance bottlenecks). Svelte UX is going to be the true test 😁

Any reason you don't add "dev": "pnpm --filter=layerchart dev", to your root package.json file and avoid the need to change directories?

Nope, feel free to add!

@jacob-8 Thanks so much for starting this effort. I finished it in https://github.com/techniq/layerchart/pull/192