@nil-/doc 1.0.0 → 2.0.0

package/src/lib/components/navigation/utils/sorter.ts

@@ -0,0 +1,43 @@
+import type { Sorter } from "../types";
+
+const match = /(\d+)-(.+)/;
+
+const sorterT = <T extends string | number>(l: T, r: T) => {
+    if (l < r) {
+        return -1;
+    }
+    if (l > r) {
+        return +1;
+    }
+    return 0;
+};
+
+/**
+ * Compares two texts for sorting.
+ *
+ * If the texts follows `<I>-<Name>` format,
+ * sorting is done by comparing the numbers in the prefix.
+ *
+ * If only one of the texts follows `<I>-<Name>` format,
+ * the text that follows the format is considered as higher in order.
+ *
+ * Else comparison is done using built-in `string` comparison.
+ */
+export const sorter = ((l: string, r: string): -1 | 0 | 1 => {
+    const lmatch = match.exec(l);
+    const rmatch = match.exec(r);
+
+    if (null == lmatch && null == rmatch) {
+        return sorterT(l, r);
+    }
+
+    if (null == lmatch) {
+        return 1;
+    }
+
+    if (null == rmatch) {
+        return -1;
+    }
+
+    return sorterT(parseInt(lmatch[1]), parseInt(rmatch[1])) || sorterT(lmatch[2], rmatch[2]);
+}) satisfies Sorter;

package/src/lib/index.ts

@@ -0,0 +1,23 @@
+export { renamer } from "./components/navigation/utils/renamer";
+export { sorter } from "./components/navigation/utils/sorter";
+
+export type {
+    Prop,
+    Event,
+    PropType,
+    Detailed,
+    Flattened,
+    Unionized
+} from "./components/block/controls/types";
+
+export { default as Layout } from "./components/layout/Layout.svelte";
+export { default as DocLayout } from "./components/layout/DocLayout.svelte";
+export { default as Instance } from "./components/block/Instance.svelte";
+export { default as Block } from "./components/block/Block.svelte";
+export { default as Template } from "./components/block/Template.svelte";
+export { default as Controls } from "./components/block/Controls.svelte";
+export { default as Params } from "./components/block/Params.svelte";
+
+export { default as Icon } from "./components/layout/icons/Icon.svelte";
+export { default as Nil } from "./components/layout/icons/Nil.svelte";
+export { default as Theme } from "./components/layout/icons/Theme.svelte";

package/src/routes/+layout.server.ts

@@ -0,0 +1 @@
+export const ssr = false;

package/src/routes/+layout.svelte

@@ -0,0 +1,63 @@
+<script lang="ts" module>
+    declare const __VERSION__: string;
+</script>
+
+<script lang="ts">
+    import { DocLayout, renamer, sorter } from "$lib";
+    import { build } from "@nil-/doc-kit";
+    import Icon from "$lib/components/layout/icons/Icon.svelte";
+    import Nil from "$lib/components/layout/icons/Nil.svelte";
+    import { setContext, type Snippet } from "svelte";
+
+    const settings = build(import.meta.glob(["./**/+page.svelte", "./**/+page.svx"]));
+    setContext("urls", settings.data);
+
+    let { children }: { children?: Snippet } = $props();
+</script>
+
+<svelte:head>
+    <title>@nil-/doc</title>
+    <link
+        href="https://cdn.jsdelivr.net/npm/prismjs@1.29.0/themes/prism-solarizedlight.min.css"
+        rel="stylesheet"
+    />
+    <link rel="stylesheet" href="/assets/markdown.css" />
+    <link rel="stylesheet" href="/assets/admonitions.css" />
+</svelte:head>
+
+<DocLayout {settings} {renamer} {sorter}>
+    {#snippet title()}
+        <Icon
+            title="Open @nil-/mono repo: https://github.com/njaldea/mono"
+            onclick={() => window.open("https://github.com/njaldea/mono", "_blank")}
+        >
+            <Nil />
+        </Icon>
+        <span>@nil-/doc {__VERSION__}</span>
+    {/snippet}
+    <div class="markdown-body">
+        {@render children?.()}
+    </div>
+</DocLayout>
+
+<style>
+    .markdown-body {
+        min-width: 600px;
+        max-width: 1000px;
+        width: 100%;
+        margin-top: 0.7rem;
+        margin-left: auto;
+        margin-right: auto;
+        box-sizing: border-box;
+        transition: background-color 350ms;
+        background-color: transparent !important;
+    }
+
+    .markdown-body :global(pre) {
+        transition: background-color 350ms;
+    }
+
+    .markdown-body :global(table) {
+        margin: 0;
+    }
+</style>

package/src/routes/1-Motivation/+page.svx

@@ -0,0 +1,37 @@
+# Motivation
+
+`@nil-/doc` is my experimentation for personal learning experience.
+
+Personally, it would be ideal to use existing tools to do a specific task. Unfortunately, I have the heart of a C++ programmer where in I feel excitement implementing things on my own.
+
+Joking aside, this library (not a framework) is intended to ease documentation by providing components that can be used independently.
+
+This is inspired by <a href="https://storybook.js.org" target="_blank" rel="noopener noreferrer">storybook</a> and <a href="https://bookit.leveluptutorials.com" target="_blank" rel="noopener noreferrer">bookit</a>.
+
+As great as they are, especially on the part that I lack expertise which is styling, I feel hindered in using them because of the following:
+
+Storybook:
+
+-   setup is too heavy to my liking
+-   a little bit slow spawning up
+-   stories structure does not easily sit well with my brain
+
+Bookit:
+
+-   its development is a bit slow and I would like to use something asap
+-   documentation and setup is not that easy to do
+-   follows similar folder structure (story search) with storybook
+
+As such, `@nil-/doc` is my flavor of doing documentation for sveltekit-based projects.
+
+SvelteKit for library projects is actually a very easy setup regardless if the library is composed of Svelte components, or pure vanilla JS.
+
+With this in mind, SvelteKit's routing feature is wasted since it is not really used for the library.
+
+Thus I decided to use everything that SvelteKit provides:
+-   lib folder + `svelte-package` for the actual library
+-   routes folder + `vite dev` for the documentation
+
+:::important Note!!!
+Instead of searching for story files, `@nil-/doc` uses the routes to define the pages of the documentation
+:::

package/src/routes/2-Overview/+page.svx

@@ -0,0 +1,96 @@
+# Overview
+
+## Installation
+
+> pnpm install -D @nil-/doc
+
+## Usage
+
+The examples below showcases how `@nil-/doc` is used with SvelteKit.
+
+All svelte components coming from this library are framework agnostic.
+
+---
+
+### +layout.server.js
+
+ssr would most likely be required to be disabled
+
+```js
+export const ssr = false;
+```
+
+### +layout.svelte
+
+`+layout.svelte` serves as the glue layer between the library and SvelteKit.
+
+[`Layout`](/3-Components/1-Layout) component is provided for the user.
+
+```svelte
+<script>
+    import { type Snippet } from "svelte";
+    import { Layout } from "@nil-/doc";
+    import { build } from "@nil-/doc-kit";
+
+    // see more details in next section
+    const { data, current, navigate, theme, offset, panel } =
+        build(import.meta.glob("./**/+page.svelte"));
+
+    /* @type{{ children:? import("svelte").Snippet }} */
+    let { children } = $props();
+</script>
+
+<Layout
+    {data}
+    current={$current}
+    on:navigate={navigate}
+    bind:theme={$theme}
+    bind:offset={$offset}
+    bind:panel={$panel}
+>
+    <svelte:fragment slot="title">@nil-/doc</svelte:fragment>
+    {@render children.?()}
+</Layout>
+```
+
+---
+
+### @nil-/doc-kit
+
+`@nil-/doc-kit` provides a utility method for sveltekit use as demonstrated by the example above.
+
+Expected arguments:
+
+<div>
+
+    | argument | type                     |          | purpose                                      |
+    | -------- | ------------------------ | -------- | -------------------------------------------- |
+    | detail   | `Record<string, string>` |          | information from `import.meta.glob`          |
+    | prefix   | `string`                 | optional | use when layout is not in the root directory |
+
+</div>
+
+Currently returns an object with the following properties:
+
+<div>
+
+| property  | type                                        | purpose                                                                       |
+| --------- | ------------------------------------------- | ----------------------------------------------------------------------------- |
+| data      | `string[]`                                  | an array of string representing each routes                                   |
+| current   | `Readable<string &#124; null>`              | a store representing the current route post processed to remove group layout  |
+| theme     | `Writable<"light" &#124; "dark">`           | a store responsible in keeping the theme state through localStorage           |
+| offset    | `Writable<number>`                          | a store responsible in keeping the offset (nav width) through localStorage    |
+| panel     | `Writable<"bottom" &#124; "right">`         | a store responsible in keeping the panel position through localStorage        |
+| navigate  | `(e: { detail: string }) => Promise<void>`  | a callback responsible in changing the page                                   |
+
+</div>
+
+---
+
+<style>
+    div {
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+    }
+</style>

package/src/routes/3-Components/1-Layout/+page.svelte

@@ -0,0 +1,46 @@
+<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>
+
+<Block>
+    <Instance noreset>
+        <div class="layout">
+            <Layout
+                data={routes}
+                current={current}
+                onnavigate={e => current = e.detail}
+            >
+                {#snippet title()}
+                    <div>Layout Component</div>
+                {/snippet}
+                <div class="content">content {current}</div>
+            </Layout>
+        </div>
+    </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/1-Layout/1-Sorting/+page.svelte

@@ -0,0 +1,48 @@
+<script lang="ts">
+    import { Layout, sorter, Block, Instance, Controls } from "$lib";
+
+    import MD from "./MD.svx";
+
+    const routes = [ "/02-zephyr", "/banana", "/apple", "/1-random" ];
+    let current = $state(routes[0]);
+</script>
+
+<MD></MD>
+
+<Block>
+    <Instance defaults={{ override: false }} >
+        {#snippet children({ values: { override } })}
+            <div class="layout">
+                <Layout
+                    data={routes}
+                    {current}
+                    onnavigate={e => current = e.detail}
+                    sorter={override ? sorter : undefined}
+                >
+                    {#snippet title()}
+                        <div>Sorting</div>
+                    {/snippet}
+                    <div class="content">
+                        <p>Current: {current}</p>
+                        <p>Using {override ? "custom" : "default"} sorter</p>
+                    </div>
+                </Layout>
+            </div>
+        {/snippet}
+    </Instance>
+    <Controls props={[[ "override", "toggle" ]]} />
+</Block>
+
+<style>
+    .layout {
+        height: 500px;
+    }
+
+    .content {
+        width: 100%;
+        height: 100%;
+        padding: 10px;
+        outline: solid white 1px;
+        box-sizing: border-box;
+    }
+</style>

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

@@ -0,0 +1,32 @@
+# Sorting
+
+Since we are using directory-like structure for navigation, there is a need to be able to control the order of items to be listed in the tree and how it will be presented to the tree.
+
+**By default**, <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/String/localeCompare" target="_blank"  rel="noopener noreferrer">default string ordering</a> is used.
+
+`sorter` prop is the callback used to override how to order the directories in the tree.
+
+For ease of use, `@nil-/doc` provides a `sorter` method where:
+- directories that matches `/(\d+)-(.+)/` `[number]-[text]`
+    - considered higher in the sorting order
+    - when compared with other directories that matches the same format, the number prefix is used for ordering
+
+
+```svelte
+<script>
+    import { sorter } from "$nil-/doc";
+</script>
+
+<Layout
+    data={[ "/02-zephyr", "/banana", "/apple", "/1-random" ]}
+    current={"/02-zephyr"}
+    on:navigate
+    sorter={override ? sorter : undefined}
+>
+    <div slot="title">Sorting</div>
+    <div>
+        <p>Current: {current}</p>
+        <p>Using {override ? "custom" : "default"} sorter</p>
+    </div>
+</Layout>
+```

package/src/routes/3-Components/1-Layout/2-Renaming/+page.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+    import { Layout, renamer, Block, Instance, Controls } from "$lib";
+
+    import MD from "./MD.svx";
+
+    const routes = [ "/02-zephyr", "/banana", "/apple", "/1-random" ];
+    let current = $state(routes[0]);
+</script>
+
+<MD></MD>
+
+<Block>
+    <Instance defaults={{ override_renamer: false }} >
+        {#snippet children({ values: { override_renamer } })}
+            <div class="layout">
+                <Layout
+                    data={routes}
+                    {current}
+                    onnavigate={e => current = e.detail}
+                    renamer={override_renamer ? renamer : undefined}
+                >
+                    {#snippet title()}
+                        <div>Renaming</div>
+                    {/snippet}
+                    <div class="content">
+                        <p>Current: {current}</p>
+                        <p>Using {override_renamer ? "custom" : "default"} renamer</p>
+                    </div>
+                </Layout>
+            </div>
+        {/snippet}
+    </Instance>
+    <Controls
+        props={[[ "override_renamer", "toggle" ]]}
+    />
+</Block>
+
+<style>
+    .layout {
+        height: 500px;
+    }
+
+    .content {
+        width: 100%;
+        height: 100%;
+        padding: 10px;
+        outline: solid white 1px;
+        box-sizing: border-box;
+    }
+</style>

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

@@ -0,0 +1,26 @@
+# Renaming
+
+In cases where the directory name can't be used as it when listed in the tree, `renamer` prop provides a way to rename the directory displayed.
+
+This is most useful when using a `sorter` where parts of the directory name is used to indicate sorting order.
+
+For ease of use, `@nil-/doc` provides a `renamer` method which works hand in hand with the [`sorter`](/3-Components/1-Layout/1-Sorting) method where:
+
+```svelte
+<script>
+    import { renamer } from "$nil-/doc";
+</script>
+
+<Layout
+    data={[ "/02-zephyr", "/banana", "/apple", "/1-random" ]}
+    current={"/02-zephyr"}
+    on:navigate
+    renamer={override_renamer ? renamer : undefined}
+>
+    <div slot="title">Renaming</div>
+    <div>
+        <p>Current: {current}</p>
+        <p>Using {override_renamer ? "custom" : "default"} renamer</p>
+    </div>
+</Layout>
+```

package/src/routes/3-Components/1-Layout/3-Title/1-Icon/+page.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+    import { Layout, Block, Instance, Icon, Theme, Nil } from "$lib";
+
+    import MD from "./MD.svx";
+
+    const routes = ["/group1", "/group2", "/group1/subgroup/group1"];
+    let current = $state(routes[0]);
+</script>
+
+<MD></MD>
+
+<Block>
+    <Instance noreset>
+        <div class="layout">
+            <Layout
+                data={routes}
+                current={current}
+                onnavigate={e => current = e.detail}
+            >
+                {#snippet title()}
+                    <Icon><Nil/></Icon>
+                    <Icon><Theme/></Icon>
+                    <div>Layout Component - Icons</div>
+                    <Icon><Theme/></Icon>
+                    <Icon><Nil/></Icon>
+                {/snippet}
+                {#snippet title_misc()}
+                    <Icon><Nil/></Icon>
+                    <Icon><Theme/></Icon>
+                    <Icon><Nil/></Icon>
+                {/snippet}
+                <div class="content">content {current}</div>
+            </Layout>
+        </div>
+    </Instance>
+</Block>
+
+<style>
+    .layout {
+        height: 500px;
+    }
+
+    .content {
+        width: 100%;
+        height: 100%;
+        padding: 10px;
+        outline: solid white 1px;
+        box-sizing: border-box;
+    }
+</style>

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

@@ -0,0 +1,34 @@
+# Icon component
+
+Icon component is a component intended to match the title bar's sizing.
+
+Intended to be used by Icons provided by @nil-/doc:
+
+- [Nil](/4-Internals/2-Icons/1-Nil)
+- [Theme](/4-Internals/2-Icons/2-Theme)
+
+```svelte
+<script>
+    import { Layout, Icon, Theme, Nil } from "@nil-/doc";
+</script>
+
+<Layout
+    data={[ "/group1", "/group2", "/group1/subgroup/group1" ]}
+    current={"/group1"}
+    on:navigate
+>
+    <svelte:fragment slot="title">
+        <Icon><Nil/></Icon>
+        <Icon><Theme/></Icon>
+        <div>Layout Component - Icons</div>
+        <Icon><Theme/></Icon>
+        <Icon><Nil/></Icon>
+    </svelte:fragment>
+    <svelte:fragment slot="title-misc">
+        <Icon><Nil/></Icon>
+        <Icon><Theme/></Icon>
+        <Icon><Nil/></Icon>
+    </svelte:fragment>
+    <div>content {current}</div>
+</Layout>
+```

package/src/routes/3-Components/1-Layout/3-Title/2-title/+page.svelte

@@ -0,0 +1,41 @@
+<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>
+
+<Block>
+    <Instance noreset>
+        <div class="layout">
+            <Layout
+                data={routes}
+                current={current}
+                onnavigate={e => current = e.detail}
+            >
+                {#snippet title()}
+                    <div style="outline: red solid 1px;">Layout Component - title</div>
+                {/snippet}
+                <div class="content">content {current}</div>
+            </Layout>
+        </div>
+    </Instance>
+</Block>
+
+<style>
+    .layout {
+        height: 500px;
+    }
+
+    .content {
+        width: 100%;
+        height: 100%;
+        padding: 10px;
+        outline: solid white 1px;
+        box-sizing: border-box;
+    }
+</style>

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

@@ -0,0 +1,14 @@
+# title
+
+title slot allows injection of any markup to fill the whole title bar.
+
+```svelte
+<Layout
+    data={[ "/group1", "/group2", "/group1/subgroup/group1" ]}
+    current={"/group1"}
+    on:navigate
+>
+    <div slot="title" style="outline: red solid 1px;">Layout Component - title</div>
+    <div>content {current}</div>
+</Layout>
+```

package/src/routes/3-Components/1-Layout/3-Title/3-title-misc/+page.svelte

@@ -0,0 +1,49 @@
+<script lang="ts">
+    import { Layout, Block, Instance, Icon, Theme } from "$lib";
+
+    import MD from "./MD.svx";
+
+    const routes = ["/group1", "/group2", "/group1/subgroup/group1"];
+    let current = $state(routes[0]);
+
+    let dark = $state(true);
+</script>
+
+<MD></MD>
+
+<Block>
+    <Instance noreset>
+        <div class="layout">
+            <Layout
+                data={routes}
+                theme={dark ? "dark" : "light"}
+                current={current}
+                onnavigate={e => current = e.detail}
+            >
+                {#snippet title()}
+                    <div>Layout Component - title-misc</div>
+                {/snippet}
+                {#snippet title_misc()}
+                    <div style="outline: solid 1px red; text-align: center;">A</div>
+                    <Icon onclick={() => dark = !dark}><Theme {dark} /></Icon>
+                    <div style="outline: solid 1px red; text-align: center;">B</div>
+                {/snippet}
+                <div class="content">content {current}</div>
+            </Layout>
+        </div>
+    </Instance>
+</Block>
+
+<style>
+    .layout {
+        height: 500px;
+    }
+
+    .content {
+        width: 100%;
+        height: 100%;
+        padding: 10px;
+        outline: solid white 1px;
+        box-sizing: border-box;
+    }
+</style>