document knobs and actions

[yanick]

I needed to understand how knobs and actions are working, so I went ahead and wrote the documentation as I went along. :grin:

Fair warning, I probably got a lot wrong. And I'm not 100% sure that should go in the docs package vs being in svench/docs, but that seemed to be the most logical place. But hey, it's a start! :-)

[vercel[bot]]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/rixodev/svench-docs/2eb7zu7WQRXbxXe6WshyXuQCnJgd
✅ Preview: Failed

[Deployment for 1faec8b failed]

[dipscom]

This is nice, thank you. I had a look and like what I see, I'm yet to build it and see it "in the flesh" as soon as I get a chance I will do so.

I don't have the power to approve and/or merge any of this but I do have the power of nagging Rixo to do it. So, leave it with me and I'll get on the case.

[yanick]

This is nice, thank you.

My pleasure. :-) I reckoned that since I was at it, and since starting docs from scratch is always a pain, I could at the very least help overcome that hurdle.

I don't have the power to approve and/or merge any of this but I do have the power of nagging Rixo to do it.

Totally next best thing. ^.^

[dipscom]

This is nice, thank you.

My pleasure. :-) I reckoned that since I was at it, and since starting docs from scratch is always a pain, I could at the very least help overcome that hurdle.

I don't have the power to approve and/or merge any of this but I do have the power of nagging Rixo to do it.

Totally next best thing. ^.^

Rixo's pretty busy these days and I'm not versed enough to make any meaningful changes other than write the documentation. By looking by the number of contributions I have made, you will see how much spare time I have had recently to add anything. So, your little addition is very welcome and encouraged. ^^

[yanick]

Rixo's pretty busy these days and I'm not versed enough to make any meaningful changes other than write the documentation.

It must be said that Svench is pretty heady stuff. Which is not a huge surprise, considering that it sits on the crossroad of a lot of (still evolving) things. Not only it auto-gather its components to display, but it has to contend with webpack/rollup/vite interactions, and the new little tweaks that svelte-kit throws in the mix. But I'm not deterred. Bit by bit, I'll grok it. :-)

The big concept I'm trying to unravel at the moment is how, or indeed if, one can call Svench purely as an UI component. I.e., assuming that we have super-vanilla svench files like:

<script>
// Foo.svench.svelte
import { View } from 'svench';
</script>

<View name="Foo!">
<button>Click me</button>
</View>

could we have a svelte-kit route that looks something like

<script>
// src/routes/svench/index.svelte

import { SvenchUI } from 'svench';
import Foo from '$lib/compontents/Foo.svench.svelte';

// table of content of svenches
const svenchies = {
  '/Foo': Foo
};

<SvenchUI  router={svenchies} /> 

?

Anyway, don't feel any need to answer, I'm mostly thinking aloud. Having Svench be usable as a component like that would be, granted, less magic (as one would have to import the svench files manually), but would take care of a lot of svelte-kit and vite interactions, as the component is called from within the svelte-kit running environment, so we'd let the big boy deal with all the vite and $lib and $app-like path aliases.

So, your little addition is very welcome and encouraged. ^^

Woo! If I can, I'll keep them coming, then. ^.^

[dipscom]

could we have a svelte-kit route that looks something like

Erm... Pass...?

Knowing Rixo, it probably already does something like that in a very black-magic sort of way. You'll have to wait until he shows up and tells you directly.

[rixo]

Hey! Thank you very much for this. I'm sorry I have so little time for everything these days... :-/

I've started to look at your PR but got sidetracked by a terrifying bug that turned out to be what looks like incompatibility between HMR and Svelte dev tools... Anyway, I'll throw a few comments and ideas to move it forward.

And I'm not 100% sure that should go in the docs package vs being in svench/docs

Yeah the docs package is the way to go. I intend to have it deployed at https://svench.dev at some point -- but still having difficulties with pnpm + Vercel... The docs folder in the svench package are more notes to help with documenting later... Actually, the closer to actual usage docs that exists in the project might be examples/rollup, that was the original example, and served a lot as a test bed as I was developing new features.

could we have a svelte-kit route that looks something like

Yes and no. At its heart, the runtime part of Svench is indeed implemented as a Svelte component. So you can do something like this:

<script>
  import { Svench } from 'svench'
  import routes from './routes.js'
  import ui from './ui.js'
</script>

<Svench {routes} {ui} />

That's kinda how Svench works actually, except the component is created with new Svench(...).

The ui prop contains Svelte components for App (menu, top bar, panels, etc.), and the UI around View. I'd like the UI to be "pluggable" via injection of custom components, eventually.

The routes are normally extracted from your filesystem by routix (a Node program that watch FS and regenerates a tree structure from it). You could theoretically generate the routes object by other means, or maybe run Routix separately. Check the .svench/src/routes.js that is generated in your project to get an idea (and maybe the svench.js file in there too, that is the entry point of your Svench app).

There would surely be some adaptations needed to support really being able to do this... Now the biggest problem if you want to put that in a Kit app is that the two will fight over client side routing (Svench's own router is a slightly tweaked version of Navaid).

What would you expect from having Svench's router in a Kit route?

I'm interesting in pursuing this discussion, or others, but I don't think we should do it here. This PR will get closed soon, I hope. I have enabled the Discussion tab in this repo, so that might be a place. Or maybe a real issue, if there's a real use case / feature to consider.

[rixo]

Actually, I have been tinkering a little with actions and knobs lately...

By using Proxy (that cannot be polyfilled, unfortunately), actions could be written like this:

<View name="actions" let:actions={{ onChange, onSubmit }}>
  <MyForm {onChange} {onSubmit} />
</View>

The benefit I see to this is how lean & clean the extract source snippet ends up being.

With knobs it's not so easy to reduce boilerplate... However, for both (knobs and actions), I have been wondering about having the possibility to rather define them globally. Something like that:

<script>
  import { View, actions, knobs } from 'svench'
  import Cmp from './Cmp.svelte'

  $: ({ value, otherValue } = knobs({
    value: "some text",
    otherValue: { type: "checkbox", writable: true },
  }))

  $: ({ onSomething, onSomethingElse } = actions())
</script>

<View name="foo">
  <Cmp variant="foo" {value} {onSomething} />
</View>

<View name="bar">
  <Cmp variant="bar" {value} bind:otherProp={$otherValue} {onSomething} {onSomethingElse} />
</View>

Just a bunch of ideas thrown together, if you see where I want to go and want to share a though...

[yanick]

By using Proxy (that cannot be polyfilled, unfortunately), actions could be written like this:

<View name="actions" let:actions={{ onChange, onSubmit }}>
  <MyForm {onChange} {onSubmit} />
</View>

Witchcraft! Very, very slick witchcraft! ^.^

With knobs it's not so easy to reduce boilerplate... However, for both (knobs and actions), I have been wondering about having the possibility to rather define them globally. Something like that:

I can see the attraction. The boilerplate is indeed reduced. But I'm not sure. I guess it depends how many knobs you have and how much they are shared across the different Views. I see some advantages in declaring the knobs/actions at the View level: that way you can directly see what are the inputs of the View, and there is no possibility to have knobs values getting mixed up in different views (actually, hmmm.... yeah, if you declare them globally, all knobs then have to be shown for all Views of the page, right? There is no magic way to determine which of them are used within a specific View, right?).

[yanick]

could we have a svelte-kit route that looks something like

Erm... Pass...?

Heh heh. I think I audibly heard the bead of sweat roll down your cheek as you froze in horror. :joy:

[yanick]

I'm interesting in pursuing this discussion, or others, but I don't think we should do it here.

Say no more; chatter moved to https://github.com/rixo/svench/discussions/33 :-)

[rixo]

@yanick Operational notice: you should merge origin/main in this branch. I have pushed the docs/config.svench.js fix on it.

Oh, turns out I can do it :sweat_smile:

[yanick]

Oh, turns out I can do it :sweat_smile:

And I did a quick rebase so the history is all straight and simple.

I think I still have two comments to address in the PR. Let's see if I can do that before my coffee is done...

[yanick]

Aaaand I think I addressed all points. Let me know if I'm mistaken. :-)

[dipscom]

May I butt in and suggest that the commits be squashed into a single one pertaining these changes before merge?

[yanick]

May I butt in and suggest that the commits be squashed into a single one pertaining these changes before merge?

No problem at all. I'll leave the commits as they are until I get the +1 from Rixo, as he might prefer to just see the delta of stuff I did since last time instead of re-started at the beginning, but then I'll do a big happy squash of the whole branch.

[rixo]

@yanick Thanks again. I've harmonized the coding style, and simplified the action examples a little bit. I think showing the code of dummy example components is a bit confusing to the matter.

Also (butcherly) fixed the Vercel deploy. So, hopefully, this should be on https://svench-docs.vercel.app/ a few secs after I hit the merge button!