@nil-/doc 1.0.0 → 2.0.0

package/src/routes/3-Components/1-Layout/3-Title/3-title-misc/MD.svx

@@ -0,0 +1,26 @@
+# title-misc
+
+title-misc slot allows injection of components to the right side of the title bar.
+
+If not provided, it contains Theme Icon.
+
+```svelte
+<script>
+    let dark = true;
+</script>
+
+<Layout
+    theme={dark ? "dark" : "light"}
+    data={[ "/group1", "/group2", "/group1/subgroup/group1" ]}
+    current={"/group1"}
+    on:navigate
+>
+    <div slot="title">Layout Component - title-misc</div>
+    <svelte:fragment slot="title-misc">
+        <div style="outline: solid 1px red; text-align: center;">A</div>
+        <Icon on:click={() => dark = !dark}><Theme {dark} /></Icon>
+        <div style="outline: solid 1px red; text-align: center;">B</div>
+    </svelte:fragment>
+    <div>content {current}</div>
+</Layout>
+```

package/src/routes/3-Components/1-Layout/MD.svx

@@ -0,0 +1,49 @@
+# Layout component
+
+Layout component comprises of three sections:
+- title bar
+- navigation panel
+- content
+
+## Size
+
+Layout component will simply fill its parent using `width: 100%; height: 100%;`.
+
+To control its size, simply wrap it in a container and set that container's width and length.
+Check the parent whenever the size is not as displayed as expected.
+
+```svelte
+<div style="width: 500px; height: 500px;"><Layout/></div>
+```
+
+## Collapsing
+
+Double clicking on the vertical divider will collapse the left side panel.
+
+## Properties
+
+<div class="center">
+
+| prop    | type                                     |           | purpose                                                                                           |
+| ------- | ---------------------------------------- | --------- |-------------------------------------------------------------------------------------------------- |
+| data    | `string[]`                               | mandatory | List of routes                                                                                    |
+| current | `string`                                 | mandatory | Current route                                                                                     |
+| offset  | `number`                                 | optional  | Nav panel width. Defaults to 250px.                                                               |
+| theme   | `"dark" or "light"`                      | optional  | If not provided `dark` is selected.<br/>Clicking on the theme icon will not update bound property |
+| sorter  | `(l: string, r: string) => -1 or 0 or 1` | optional  | See [Sorting](/3-Components/1-Layout/1-Sorting)                                                   |
+| renamer | `(s: string) => string`                  | optional  | See [Renaming](/3-Components/1-Layout/2-Renaming)                                                 |
+
+</div>
+
+<br/>
+
+```svelte
+<Layout
+    data={[ "/group1", "/group2", "/group1/subgroup/group1" ]}
+    current={"/group1"}
+    {onnavigate}
+>
+    <div slot="title">Layout Component</div>
+    <div>content {current}</div>
+</Layout>
+```

package/src/routes/3-Components/2-DocLayout/+page.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+    import { Layout, Block, Instance } from "$lib";
+
+    import MD from "./MD.svx";
+
+    const routes = ["/group1", "/group2", "/group1/subgroup/group1"];
+    let current = $state(routes[0]);
+</script>
+
+<MD></MD>
+
+<!-- example is using Layout but displayed as DocLayout           -->
+<!-- intentionally done this way because I can't call build herer -->
+<Block>
+    <Instance noreset>
+        {#snippet children()}
+            <div class="layout">
+                <Layout
+                    data={routes}
+                    current={current}
+                    onnavigate={e => current = e.detail}
+                >
+                    {#snippet title()}
+                        <div>DocLayout Component</div>
+                    {/snippet}
+                    <div class="content">content {current}</div>
+                </Layout>
+            </div>
+        {/snippet}
+    </Instance>
+</Block>
+
+<style>
+    .layout {
+        height: 500px;
+    }
+
+    .content {
+        width: 100%;
+        height: 100%;
+        padding: 10px;
+        box-sizing: border-box;
+    }
+
+    .center {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+    }
+</style>

package/src/routes/3-Components/2-DocLayout/MD.svx

@@ -0,0 +1,27 @@
+# DocLayout component
+
+DocLayout component is a component to simplify Layout Component and the utility library (like @nil-/doc-kit)
+
+## Properties
+
+<div class="center">
+
+| prop     | type                                     |           | purpose                                                                                                             |
+| -------- | ---------------------------------------- | --------- |-------------------------------------------------------------------------------------------------------------------- |
+| settings | `Settings`                               | mandatory | Settings requirement of Layout Component<br/> See [Layout](/3-Components/1-Layout) or [@nil-/doc-kit](/2-Overview)   |
+| sorter   | `(l: string, r: string) => -1 or 0 or 1` | optional  | See [Sorting](/3-Components/1-Layout/1-Sorting)                                                                     |
+| renamer  | `(s: string) => string`                  | optional  | See [Renaming](/3-Components/1-Layout/2-Renaming)                                                                   |
+
+</div>
+
+<br/>
+
+```svelte
+<script >
+    const settings = build(import.meta.glob(["./**/+page.svelte"]))
+</script>
+<DocLayout {settings}>
+    <div slot="title">DocLayout Component</div>
+    <div>content {settings.current}</div>
+</DocLayout>
+```

package/src/routes/3-Components/3-Block/+page.svx

@@ -0,0 +1,65 @@
+<script lang="ts">
+    import { Block } from "$lib";
+</script>
+
+# Block component
+
+Block component is used to setup/group dynamic examples through param customization.
+
+A Block may consist of the following:
+- Content which is either:
+    - 1 [Instance](/3-Components/3-Block/1-Content/1-Instance) component or
+    - 1 [Template](/3-Components/3-Block/1-Content/2-Template) component and at least 1 [Params](/3-Components/3-Block/1-Content/2-Template/1-Params) component
+- At most 1 [Controls](/3-Components/3-Block/2-Controls) component
+
+Subsequent examples will use the component below:
+
+```svelte
+<script>
+    export let tag;
+    export let vText;
+    export let vColor;
+    export let vNumber;
+    export let vRange;
+    export let vSelect;
+    export let vToggle;
+    export let vArray;
+
+    export let vObject = undefined;
+    export let vDefaulted = "default value";
+
+    import { createEventDispatcher } from "svelte";
+    const dispatch = createEventDispatcher();
+</script>
+
+<div
+    on:click={(e) => dispatch("left_click", "l_click_detail")}
+    on:contextmenu|preventDefault={(e) => dispatch("right_click", "r_click_detail")}
+>
+    <table>
+        <tr><th>{tag}</th><th>Value</th></tr>
+        <tr><td>vText</td><td>{vText}</td></tr>
+        <tr><td>vColor</td><td>{vColor}</td></tr>
+        <tr><td>vNumber</td><td>{vNumber}</td></tr>
+        <tr><td>vRange</td><td>{vRange}</td></tr>
+        <tr><td>vSelect</td><td>{vSelect}</td></tr>
+        <tr><td>vToggle</td><td>{vToggle}</td></tr>
+        <tr><td>vArray</td><td>{JSON.stringify(vArray)}</td></tr>
+        <tr><td>vDefaulted</td><td>{vDefaulted}</td></tr>
+    </table>
+</div>
+
+<style>
+    div {
+        width: 100%;
+        height: 100%;
+        display: grid;
+        justify-items: center;
+        align-items: center;
+    }
+
+    div > table {
+        margin: 20px;
+    }
+</style>
+```

package/src/routes/3-Components/3-Block/1-Content/1-Instance/+page.svx

@@ -0,0 +1,60 @@
+<script lang="ts">
+    import { Block, Instance } from "$lib";
+    import Component from "../../Component.svelte";
+
+    const defaults = {
+        vText: "text",
+        vColor: "#ffffff",
+        vNumber: 1,
+        vRange: 3,
+        vSelect: "select",
+        vToggle: true,
+        vArray: [1, "string", false] as [number, string, boolean]
+    };
+</script>
+
+# Instance component
+
+Instance component populates the "content".
+- available properties
+    - `defaults`
+        - values are used to populate the prop forwarded to slot
+        - use `undefined` to indicate optional property
+    - [`noreset`](/3-Components/3-Block/1-Content/3-props/1-noreset)
+- available slot properties
+    - [`let:props`](/3-Components/3-Block/1-Content/3-props/3-let:props)
+        - properties derived from `defaults` and props from `Params`
+        - any unknown properties from params are disregarded.
+        - only keys from defaults are honored.
+    - [`let:key`](/3-Components/3-Block/1-Content/3-props/2-let:key)
+        - Flag that is flipped during svelte's `beforeRender`
+        - Can be used together with `noreset` to granularly control which part of the template needs to be re-rendererd.
+
+```svelte
+<Block>
+    <Instance
+        defaults={{
+            vText: "text",
+            vColor: "#ffffff",
+            vNumber: 1,
+            vRange: 0,
+            vSelect: "select",
+            vToggle: true,
+            vArray: [1, "string", false]
+        }}
+        let:props
+    >
+        <Component {...props} tag={"tag"}/>
+    </Instance>
+</Block>
+```
+
+> Result
+
+<Block>
+    <Instance {defaults}>
+        {#snippet children({ values })}
+            <Component {...values} tag={"tag"}/>
+        {/snippet}
+    </Instance>
+</Block>

package/src/routes/3-Components/3-Block/1-Content/2-Template/+page.svx

@@ -0,0 +1,74 @@
+<script lang="ts">
+    import { Block, Template, Params } from "$lib";
+    import Component from "../../Component.svelte";
+
+    const defaults = {
+        vText: "text",
+        vColor: "#ffffff",
+        vNumber: 1,
+        vRange: 3,
+        vSelect: "select",
+        vToggle: true,
+        vArray: [1, "string", false] as [number, string, boolean]
+    };
+</script>
+
+# Template component
+
+Template component populates the same "content" for every Param component inside the Block
+- available properties
+    - `defaults`
+        - values are used to populate the prop forwarded to slot
+        - use `undefined` to indicate optional property
+    - [`noreset`](/3-Components/3-Block/1-Content/3-props/1-noreset)
+    - [`columns`](/3-Components/3-Block/1-Content/2-Template/2-columns)
+- available slot properties
+    - [`let:props`](/3-Components/3-Block/1-Content/3-props/3-let:props)
+        - properties derived from `defaults` and props from `Params`
+        - any unknown properties from params are disregarded.
+        - only keys from defaults are honored.
+    - [`let:key`](/3-Components/3-Block/1-Content/3-props/2-let:key)
+        - Flag that is flipped during svelte's `beforeRender`
+        - Can be used together with `noreset` to granularly control which part of the template needs to be re-rendererd.
+    - `let:tag` (string)
+        - Param tag
+        - Not guaranteed to be unique
+        - If not provided, stringified `id` is used
+    - `let:id` (number)
+        - Param identifier
+        - index indicating in which order the Params are declared
+
+Works hand in hand with [Params](/3-Components/3-Block/1-Content/2-Template/1-Params) component
+
+```svelte
+<Block>
+    <Template
+        defaults={{
+            vText: "text",
+            vColor: "#ffffff",
+            vNumber: 1,
+            vRange: 0,
+            vSelect: "select",
+            vToggle: true,
+            vArray: [1, "string", false]
+        }}
+        let:props
+        let:tag
+        let:id
+    >
+        <Component {...props} tag={`${id}-${tag}`}/>
+    </Template>
+    <Params tag="first"/>
+</Block>
+```
+
+> Result
+
+<Block>
+    <Template {defaults}>
+        {#snippet children({ id, tag, values })}
+            <Component {...values} tag={`${id}-${tag}`}/>
+        {/snippet}
+    </Template>
+    <Params tag="first"/>
+</Block>

package/src/routes/3-Components/3-Block/1-Content/2-Template/1-Params/+page.svx

@@ -0,0 +1,55 @@
+<script lang="ts">
+    import { Block, Template, Params } from "$lib";
+    import Component from "../../../Component.svelte";
+
+    const defaults = {
+        vText: "text",
+        vColor: "#ffffff",
+        vNumber: 1,
+        vRange: 0,
+        vSelect: "select",
+        vToggle: true,
+        vArray: [1, "string", false] as [number, string, boolean]
+    };
+</script>
+
+# Params component
+
+Params component is used to "repeat" the content of the Template component with different props
+
+```svelte
+<Block>
+    <Template
+        defaults={{
+            vText: "text",
+            vColor: "#ffffff",
+            vNumber: 1,
+            vRange: 0,
+            vSelect: "select",
+            vToggle: true,
+            vArray: [1, "string", false]
+        }}
+        columns
+        let:props
+        let:tag
+    >
+        <Component {...props} {tag}/>
+    </Template>
+    <Params tag="first"/>
+    <Params tag="second" props={{ vNumber: 2 }}/>
+    <Params tag="third" props={{ vText: "overridden text", vToggle: false }}/>
+</Block>
+```
+
+> Result
+
+<Block>
+    <Template {defaults} columns>
+        {#snippet children({ values, tag })}
+            <Component {...values} {tag}/>
+        {/snippet}
+    </Template>
+    <Params tag="first"/>
+    <Params tag="second" props={{ vNumber: 1000 }}/>
+    <Params tag="third" props={{ vText: "overridden text", vToggle: false }}/>
+</Block>

package/src/routes/3-Components/3-Block/1-Content/2-Template/2-columns/+page.svx

@@ -0,0 +1,62 @@
+<script lang="ts">
+    import { Block, Template, Params, Controls } from "$lib";
+    import Component from "../../../Component.svelte";
+
+    const defaults = {
+        vText: "text",
+        vColor: "#ffffff",
+        vNumber: 1,
+        vRange: 0,
+        vSelect: "select",
+        vToggle: true,
+        vArray: [1, "string", false] as [number, string, boolean],
+        vDefaulted: "initial_value"
+    };
+</script>
+
+# columns
+
+By default, a Template component will layout the content (instances) vertically in one column.
+
+To override this behavior, enable `columns` for the template.
+
+This is most useful when comparing different instances side by side.
+
+```svelte
+<Block>
+    <Template
+        defaults={{
+            vText: "text",
+            vColor: "#ffffff",
+            vNumber: 1,
+            vRange: 0,
+            vSelect: "select",
+            vToggle: true,
+            vArray: [1, "string", false],
+            vDefaulted: "initial_value"
+        }}
+        let:props
+        let:tag
+        columns
+    >
+        <Component {...props} {tag} />
+    </Template>
+    <Params />
+    <Params />
+    <Controls props={[[ "vDefaulted", "text" ]]}/>
+</Block>
+```
+
+> Result
+
+<Block>
+    <Template {defaults} columns >
+        {#snippet children({values, tag})}
+            <Component {...values} {tag} />
+        {/snippet}
+    </Template>
+
+    <Params />
+    <Params />
+    <Controls props={[["vDefaulted", "text"]]}/>
+</Block>

package/src/routes/3-Components/3-Block/1-Content/3-props/1-noreset/+page.svx

@@ -0,0 +1,68 @@
+<script lang="ts">
+    import { Block, Instance, Controls } from "$lib";
+    import Component from "../../../Component.svelte";
+
+    const defaults = {
+        vText: "text",
+        vColor: "#ffffff",
+        vNumber: 1,
+        vRange: 0,
+        vSelect: "select",
+        vToggle: true,
+        vArray: [1, "string", false] as [number, string, boolean],
+        vDefaulted: "initial_value"
+    };
+</script>
+
+# noreset
+
+By default, any change in the properties will result in re-rendering the whole component. For more details, see <a href="https://github.com/sveltejs/svelte/issues/4442" target="_blank" rel="noopener noreferrer">issue</a>.
+
+To override this, enable `noreset` for the template.
+
+This is most useful for components needs to retain state between each prop update.
+
+```svelte
+<Block>
+    <Instance
+        defaults={{
+            vText: "text",
+            vColor: "#ffffff",
+            vNumber: 1,
+            vRange: 0,
+            vSelect: "select",
+            vToggle: true,
+            vArray: [1, "string", false],
+            vDefaulted: "initial_value"
+        }}
+        let:props
+        noreset
+    >
+        <Component {...props} tag={"tag"} />
+    </Instance>
+    <Controls
+        props={[{
+            name: "vDefaulted",
+            type: "text"
+        }]}
+    />
+</Block>
+```
+
+> Result
+
+<Block>
+    <Instance
+        {defaults}
+        let:props
+        noreset
+    >
+        <Component {...props} tag={"tag"} />
+    </Instance>
+    <Controls
+        props={[{
+            name: "vDefaulted",
+            type: "text"
+        }]}
+    />
+</Block>

package/src/routes/3-Components/3-Block/1-Content/3-props/2-let:key/+page.svx

@@ -0,0 +1,72 @@
+<script lang="ts">
+    import { Block, Instance, Controls } from "$lib";
+    import Component from "../../../Component.svelte";
+
+    const defaults = {
+        vText: "text",
+        vColor: "#ffffff",
+        vNumber: 1,
+        vRange: 0,
+        vSelect: "select",
+        vToggle: true,
+        vArray: [1, "string", false] as [number, string, boolean],
+        vDefaulted: "initial_value"
+    };
+</script>
+
+# let:key
+
+Using [noreset](/3-Components/3-Block/1-Content/3-props/1-noreset) prevents the whole slot of Instance/Template component not to be re-created.
+
+If in case some of the components in the slot needs to be re-rendered, `key` slot is provided. It is a flag (boolean) that is flipped during svelte's `beforeRender`.
+
+```svelte
+<Block>
+    <Instance
+        defaults={{
+            vText: "text",
+            vColor: "#ffffff",
+            vNumber: 1,
+            vRange: 0,
+            vSelect: "select",
+            vToggle: true,
+            vArray: [1, "string", false],
+            vDefaulted: "initial_value"
+        }}
+        let:props
+        let:key
+        noreset
+    >
+        {#key key}
+            <Component {...props} tag={"tag"} />
+        {/key}
+    </Instance>
+    <Controls
+        props={[{
+            name: "vDefaulted",
+            type: "text"
+        }]}
+    />
+</Block>
+```
+
+> Result
+
+<Block>
+    <Instance
+        {defaults}
+        let:props
+        let:key
+        noreset
+    >
+        {#key key}
+            <Component {...props} tag={"tag"} />
+        {/key}
+    </Instance>
+    <Controls
+        props={[{
+            name: "vDefaulted",
+            type: "text"
+        }]}
+    />
+</Block>