@nil-/doc 1.0.0 → 2.0.0

package/src/routes/3-Components/3-Block/2-Controls/3-props/Detail.svelte

@@ -0,0 +1,20 @@
+<div class="center">
+    <div>
+        <slot />
+    </div>
+</div>
+
+<style>
+    .center {
+        font-family: "Fira Code";
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+    }
+
+    .center > div {
+        display: grid;
+        place-items: center;
+        grid-auto-flow: column;
+    }
+</style>

package/src/routes/3-Components/3-Block/2-Controls/3-props/Layout.svelte

@@ -0,0 +1,86 @@
+<script lang="ts" generics="Info, V">
+    import Styler from "$lib/components/block/controls/Styler.svelte";
+    import Detail from "./Detail.svelte"
+
+    let {
+        component: C,
+        info,
+        name1,
+        name2,
+        name3,
+        stringify = false
+    }: {
+        component: any;
+        info: (n: string) => Args;
+        name1?: V | undefined;
+        name2?: V | undefined;
+        name3?: V | undefined;
+        stringify?: boolean;
+    } = $props();
+</script>
+
+<Detail>
+    <table>
+        <thead>
+            <tr>
+                <th>variable</th>
+                <th>value</th>
+            </tr>
+        </thead>
+        <tbody>
+            <tr>
+                <td>name1</td>
+                <td><pre><code>{stringify ? JSON.stringify(name1) : name1}</code></pre></td>
+            </tr>
+            <tr>
+                <td>name2</td>
+                <td><pre><code>{stringify ? JSON.stringify(name2) : name2}</code></pre></td>
+            </tr>
+            <tr>
+                <td>name3</td>
+                <td><pre><code>{stringify ? JSON.stringify(name3) : name3}</code></pre></td>
+            </tr>
+        </tbody>
+    </table>
+</Detail>
+
+<hr />
+
+<Detail>
+    <Styler type={"props"}>
+        <div>
+            <div>Name</div>
+            <div>Value</div>
+            <div>Use</div>
+        </div>
+        <C
+            info={info("name1")}
+            bind:value={name1}
+            depth={1}
+            disabled={false}
+            visible
+        />
+        <C
+            info={info("name2")}
+            bind:value={name2}
+            depth={2}
+            disabled={false}
+            visible
+        />
+        <C
+            info={info("name3")}
+            bind:value={name3}
+            depth={3}
+            disabled
+            visible
+        />
+    </Styler>
+</Detail>
+
+<style>
+    tr > td > pre {
+        background-color: transparent;
+        margin: 0;
+        padding: 10px;
+    }
+</style>

package/src/routes/3-Components/3-Block/2-Controls/3-props/MD.svx

@@ -0,0 +1,150 @@
+<script>
+    let { children } = $props();
+</script>
+
+# props
+
+Controls allows to override the data passed to Instance/Template Props through their slot props.
+
+Schema follows two format:
+- more verbose object key-value structure
+- flattened array
+
+Mixing and matching of schema should work well.
+
+To customize the controls, the following are the types that are currently supported by `@nil-/doc`.
+- [Text](/3-Components/3-Block/2-Controls/3-props/1-Text)
+- [Number](/3-Components/3-Block/2-Controls/3-props/2-Number)
+- [Range](/3-Components/3-Block/2-Controls/3-props/3-Range)
+- [Toggle](/3-Components/3-Block/2-Controls/3-props/4-Toggle)
+- [Select](/3-Components/3-Block/2-Controls/3-props/5-Select)
+- [Tuple](/3-Components/3-Block/2-Controls/3-props/6-Tuple)
+- [Object](/3-Components/3-Block/2-Controls/3-props/7-Object)
+- [Color](/3-Components/3-Block/2-Controls/3-props/8-Color)
+
+Special controls:
+- [Button](/3-Components/3-Block/2-Controls/3-props/9-Button)
+
+
+<div class="root">
+
+```svelte
+<Block>
+    <Instance
+        defaults={{
+            vText: "text",
+            vColor: "#ffffff",
+            vNumber: 1,
+            vRange: 3,
+            vSelect: "select",
+            vToggle: true,
+            vArray: [1, "string", false, undefined],
+            vObject: {
+                vText: "world",
+                vAny: undefined
+            }
+        }}
+        let:props
+    >
+        <Component {...props} tag={"tag"}/>
+    </Instance>
+    <Controls
+        props={[
+            [ "Click Me!", "button", () => () => alert('Button Is Clicked') ],
+            [ "vText", "text" ],
+            [ "vColor", "color", "hex" ],
+            [ "vNumber", "number" ],
+            [ "vRange", "range", 0, 10, 1 ],
+            [ "vSelect", "select", ["A", "B", "C"] ],
+            [ "vToggle", "toggle" ],
+            {
+                name: "vArray",
+                type: "tuple",
+                values: [
+                    [ "number" ],
+                    [ "text" ],
+                    [ "toggle" ],
+                    [ "tuple", [["text"]] ]
+                ]
+            },
+            {
+                name: "vObject",
+                type: "object",
+                values: [
+                    [ "vText", "text" ],
+                    [ "vAny", "object", [[ "vText", "text" ]] ]
+                ]
+            }
+        ]}
+    />
+</Block>
+```
+
+    <div>
+    {@render children()}
+    </div>
+</div>
+
+---
+
+## Helper Types
+
+`@nil-/doc` provides helper types to help intellisense. The following are exported by the library:
+
+<table>
+    <thead>
+        <tr>
+            <th>Type</th>
+            <th>Purpose</th>
+            <th>Example</th>
+            <th>Expanded Type</th>
+        </tr>
+    </thead>
+    <tbody>
+        <tr>
+            <td>Prop</td>
+            <td>Union of all Prop Types.</td>
+            <td></td>
+            <td></td>
+        </tr>
+        <tr>
+            <td>PropType</td>
+            <td>Use to select specific prop type.<br/>Works with the next types.<br/>Expects to receive the "type" to select.</td>
+            <td></td>
+            <td></td>
+        </tr>
+        <tr>
+            <td>Detailed</td>
+            <td>Vebose Prop structure.</td>
+            <td><pre><code>{"type T = Detailed<PropType<\"object\">>;"}</code></pre></td>
+            <td><pre><code>{"type T = {\n    name: string;\n    type: \"object\";\n    values: Prop[];\n};"}</code></pre></td>
+        </tr>
+        <tr>
+            <td>Flattened</td>
+            <td>Arrayed Prop structure.</td>
+            <td><pre><code>{"type T = Flattened<PropType<\"object\">>;"}</code></pre></td>
+            <td><pre><code>{"type T = [\n    name: string,\n    type: \"object\",\n    values: Prop[]\n];"}</code></pre></td>
+        </tr>
+        <tr>
+            <td>Unionized</td>
+            <td>Union of Detailed and Flattened type</td>
+            <td><pre><code>{"type T = Unionized<PropType<\"object\">>;"}</code></pre></td>
+            <td><pre><code>{"type T =\n    | Detailed<PropType<\"object\">>\n    | Flattened<PropType<\"object\">>;"}</code></pre></td>
+        </tr>
+    </tbody>
+</table>
+
+---
+<style>
+    .root {
+        display: grid;
+        grid-auto-flow: column;
+        gap: 10px;
+    }
+
+    tr > td > pre {
+        background-color: transparent;
+        padding: 5px;
+        margin: 0px;
+    }
+</style>

package/src/routes/3-Components/3-Block/2-Controls/4-events/+page.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+    import { Block, Instance, Controls, type Prop, type Event } 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, undefined] as [number, string, boolean, any],
+        vObject: {
+            vText: "world",
+            vNumber: 1101,
+            vToggle: false,
+            vAny: undefined
+        } as {
+            vText: string;
+            vNumber: number;
+            vToggle: boolean;
+            vAny: any;
+        }
+    };
+</script>
+
+<div class="root">
+    <Block>
+        <Instance {defaults}>
+            {#snippet children({ values, events: {left_click, right_click} })}
+                <Component
+                    {...values}
+                    tag={"tag"}
+                    {left_click}
+                    {right_click}
+                />
+            {/snippet}
+        </Instance>
+        <Controls events={["left_click", "right_click"]} />
+    </Block>
+</div>
+
+<style>
+    .root {
+        display: grid;
+        grid-auto-flow: column;
+        gap: 10px;
+    }
+</style>

package/src/routes/3-Components/3-Block/Component.svelte

@@ -0,0 +1,87 @@
+<script lang="ts">
+    type OType = { vText: string; vNumber: number; vToggle: boolean; vAny: any; };
+
+    let {
+        tag,
+        vText,
+        vColor,
+        vNumber,
+        vRange,
+        vSelect,
+        vToggle,
+        vArray,
+        vObject,
+        vDefaulted = "default value",
+        left_click,
+        l_click_detail,
+        right_click,
+        r_click_detail
+    }: {
+        tag: string;
+        vText: string;
+        vColor: string;
+        vNumber: number;
+        vRange: number;
+        vSelect: string;
+        vToggle: boolean;
+        vArray: [number, string, boolean, ...any];
+        vObject?: OType;
+        vDefaulted?: string;
+        left_click?: () => void;
+        l_click_detail?: () => void;
+        right_click?: () => void;
+        r_click_detail?: () => void;
+    } = $props();
+</script>
+
+<div
+    onclick={() => {
+        left_click?.();
+        l_click_detail?.();
+    }}
+    oncontextmenu={(e) => {
+        e.preventDefault();
+        right_click?.();
+        r_click_detail?.();
+    }}
+    onkeypress={null}
+    role="none"
+>
+    <table>
+        <thead>
+            <tr><th>{tag}</th><th>Value</th></tr>
+        </thead>
+        <tbody>
+            <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><pre>{JSON.stringify(vArray, null, 4)}</pre></td></tr>
+            <tr><td>vObject</td><td><pre>{JSON.stringify(vObject, null, 4)}</pre></td></tr>
+            <tr><td>vDefaulted</td><td>{vDefaulted}</td></tr>
+        </tbody>
+    </table>
+</div>
+
+<style>
+    div {
+        width: 100%;
+        height: 100%;
+        display: grid;
+        box-sizing: border-box;
+        justify-items: center;
+        align-items: center;
+    }
+
+    div > table {
+        margin: 20px;
+    }
+
+    tr > td > pre {
+        background-color: transparent;
+        padding: 5px;
+        margin: 0px;
+    }
+</style>

package/src/routes/3-Components/4-Theme/+page.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+    import { Layout, Block, Instance, Controls, type PropType, type Unionized } from "$lib";
+
+    import MD from "./MD.svx";
+
+    const data = ["/group1", "/group2", "/group1/subgroup/group1"];
+    let current = $state(data[0]);
+
+    const defaults = {
+        layoutTheme: undefined,
+        blockTheme: undefined
+    } as const;
+
+    const innerControls = [
+        ["range1", "range", 0, 10, 0.001] as Unionized<PropType<"range">>,
+        ["range2", "range", 0, 10, 0.001] as Unionized<PropType<"range">>
+    ];
+
+    const outerControls = [
+        [ "layoutTheme", "select", ["light", "dark"]]  as Unionized<PropType<"select">>,
+        [ "blockTheme", "select", ["light", "dark"]] as Unionized<PropType<"select">>
+    ];
+</script>
+
+<MD></MD>
+
+<Block>
+    <Instance {defaults} noreset>
+        {#snippet children({ values: { layoutTheme, blockTheme } })}
+            <div class="layout">
+                <Layout
+                    {data}
+                    {current}
+                    onnavigate={e => current = e.detail}
+                    theme={layoutTheme}
+                >
+                    {#snippet title()}
+                        <div>title</div>
+                    {/snippet}
+                    <div
+                        class="content"
+                        class:dark={layoutTheme !== "light"}>
+                        <Block>
+                            <Instance defaults={{ range1: 0, range2: 10 }} noreset>
+                                {#snippet children({ values })}
+                                    {current}
+                                    <br/>
+                                    {JSON.stringify(values)}
+                                {/snippet}
+                            </Instance>
+                            <Controls props={innerControls}/>
+                        </Block>
+                    </div>
+                </Layout>
+            </div>
+        {/snippet}
+    </Instance>
+    <Controls props={outerControls}/>
+</Block>
+
+<style>
+    .layout {
+        height: 300px;
+    }
+
+    .content {
+        height: 100%;
+        padding: 10px;
+        box-sizing: border-box;
+    }
+</style>

package/src/routes/3-Components/4-Theme/1-Custom CSS/+page.svelte

@@ -0,0 +1,102 @@
+<script lang="ts">
+    import { Layout, Block, Instance, Controls } from "$lib";
+    import type { Prop } from "$lib";
+
+    const data = ["/group1", "/group2", "/group1/subgroup/group1"];
+    let current = $state(data[0]);
+
+    const defaults = {
+        "--nil-doc-font-family": "",
+        "--nil-doc-color-scheme": "dark",
+        "--nil-doc-color": "hsl(0, 0%, 80%)",
+        "--nil-doc-bg-color": "hsl(210, 6%, 7%)",
+        "--nil-doc-content-outline-color": "hsla(0, 0%, 100%, 0.3)",
+        "--nil-doc-block-bg-color": "hsla(200, 4%, 7%, 0.3)",
+        "--nil-doc-block-outline-color": "hsla(0, 0%, 100%, 0.3)",
+        "--nil-doc-container-p": "hsl(0, 2%, 40%)",
+        "--nil-doc-container-s": "hsl(0, 0%, 100%)",
+        "--nil-doc-controls-p": "hsl(213, 26%, 7%)",
+        "--nil-doc-controls-s": "hsl(213, 26%, 11%)",
+        "--nil-doc-controls-hover": "hsl(203, 100%, 15%)",
+        "--nil-doc-nav-hovered": "hsla(203, 98, 50%, 0.1)",
+        "--nil-doc-nav-page-hovered": "hsla(203, 98, 50%, 0.5)",
+        "--nil-doc-nav-selected": "hsla(203, 98, 50%, 0.85)"
+    };
+
+    const controls: Prop[] = [
+        ["--nil-doc-font-family", "text"],
+        ["--nil-doc-color-scheme", "select", ["dark", "light"]],
+        ["--nil-doc-color", "color", "hsl"],
+        ["--nil-doc-bg-color", "color", "hsl"],
+        ["--nil-doc-content-outline-color", "color", "hsla"],
+        ["--nil-doc-block-bg-color", "color", "hsla"],
+        ["--nil-doc-block-outline-color", "color", "hsla"],
+        ["--nil-doc-container-p", "color", "hsl"],
+        ["--nil-doc-container-s", "color", "hsl"],
+        ["--nil-doc-controls-p", "color", "hsl"],
+        ["--nil-doc-controls-s", "color", "hsl"],
+        ["--nil-doc-controls-hover", "color", "hsl"],
+        ["--nil-doc-nav-hovered", "color", "hsla"],
+        ["--nil-doc-nav-page-hovered", "color", "hsla"],
+        ["--nil-doc-nav-selected", "color", "hsla"]
+    ];
+
+    let theme: "dark" | "light" = $state("dark");
+
+    // eslint-disable-next-line
+    const spread = (props: unknown): string => {
+        return [...Object.entries(props as Record<string, string>)]
+            .map(([k, v]) => `${k}: ${v};`)
+            .join("\n");
+    };
+
+    const navigate = (e: { detail: string }) => {
+        current = e.detail;
+    };
+</script>
+
+<h1>Custom CSS Properties</h1>
+
+<p>Currently a work in progress. hsla is not supported by input[color].</p>
+
+<Block>
+    <Instance {defaults} noreset>
+        {#snippet children({ values })}
+            <pre>{JSON.stringify(values, null, 4)}</pre>
+            <div class="layout" style={spread(values)}>
+                <Layout {data} {current} bind:theme onnavigate={navigate}>
+                    {#snippet title()}
+                        <div>Custom CSS</div>
+                    {/snippet}
+                    <div class="content">
+                        <Block>
+                            <Instance defaults={{ range1: 0, color1: "#ff0000ff" }} noreset>
+                                {#snippet children({ values })}
+                                    {current}
+                                    <br />
+                                    {JSON.stringify(values)}
+                                {/snippet}
+                            </Instance>
+                            <Controls
+                                props={[
+                                    ["range1", "range", 0, 10, 0.001],
+                                    ["color1", "color", "hsla"]
+                                ]}
+                            />
+                        </Block>
+                    </div>
+                </Layout>
+            </div>
+        {/snippet}
+    </Instance>
+    <Controls props={controls} />
+</Block>
+
+<style>
+    .content {
+        width: 100%;
+        height: 100%;
+        padding: 10px;
+        box-sizing: border-box;
+    }
+</style>

package/src/routes/3-Components/4-Theme/MD.svx

@@ -0,0 +1,41 @@
+# Light / Dark Theme
+
+Light and Dark Theme is supported and configurable on the Root Components.
+
+Root Components are:
+- [Layout](/3-Components/1-Layout)
+- [Block](/3-Components/3-Block)
+
+```svelte
+<script>
+    const data = ["/group1", "/group2", "/group1/subgroup/group1"];
+    let current = data[0];
+
+    let layoutTheme = undefined; // "light" | "dark" | undefined
+    let blockTheme = undefined;  // "light" | "dark" | undefined
+</script>
+
+<Layout
+    {data}
+    {current}
+    on:navigate={e => current = e.detail}
+    theme={layoutTheme}
+>
+    <div slot="title">title</div>
+    <div class="content">
+        <Block theme={blockTheme}>
+            <Instance {defaults} let:props noreset>
+                {current}
+                <br/>
+                {JSON.stringify(props)}
+            </Instance>
+            <Controls
+                props={[
+                    [ "range1", "range", 0, 10, 0.001 ],
+                    [ "range2", "range", 0, 10, 0.001 ]
+                ]}
+            />
+        </Block>
+    </div>
+</Layout>
+```

package/src/routes/4-Internals/+page.mdsvelte

@@ -0,0 +1,12 @@
+# Internal Documentation
+
+The succeeding documentation is intended for my personal book keeping.
+
+Will be covering:
+- [Container](/4-Internals/1-Container)
+- [Fuzzy Match](/4-Internals/3-Fuzzy%20Match)
+- Icons
+    - [Nil](/4-Internals/2-Icons/1-Nil)
+    - [Theme](/4-Internals/2-Icons/2-Theme)
+    - [Position](/4-Internals/2-Icons/3-Position)
+    - [ControlView](/4-Internals/2-Icons/4-ControlView)

package/src/routes/4-Internals/1-Container/+page.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+    import { Block, Instance, Controls } from "$lib";
+    import Container from "$lib/components/layout/Container.svelte";
+
+    import MD from "./MD.svx";
+
+    import Content from "./Content.svelte";
+</script>
+
+<MD></MD>
+
+<Block>
+    <Instance defaults={{ vertical: false, b: false }} >
+        {#snippet children({ values: { vertical, b } })}
+            <div class="container">
+                <Container offset={200} {vertical} {b}>
+                    {#snippet side_a()}
+                        <div class="content">
+                            <Content {vertical} name="A" b={b} />
+                        </div>
+                    {/snippet}
+                    {#snippet side_b()}
+                        <div class="content">
+                            <Content {vertical} name="B" b={!b} />
+                        </div>
+                    {/snippet}
+                </Container>
+            </div>
+        {/snippet}
+    </Instance>
+    <Controls
+        props={[
+            [ "vertical", "toggle" ],
+            [ "b", "toggle" ]
+        ]}
+    />
+</Block>
+
+<style>
+    .container {
+        height: 500px;
+        user-select: none;
+    }
+
+    .content {
+        box-sizing: border-box;
+        padding: 10px;
+        min-width: 500px;
+    }
+</style>