@nil-/doc 2.0.0 → 2.0.1

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

@@ -1,43 +0,0 @@
-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

@@ -1,23 +0,0 @@
-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

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

package/src/routes/+layout.svelte

@@ -1,63 +0,0 @@
-<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

@@ -1,37 +0,0 @@
-# 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

@@ -1,96 +0,0 @@
-# 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

@@ -1,46 +0,0 @@
-<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

@@ -1,48 +0,0 @@
-<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

@@ -1,32 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-<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

@@ -1,26 +0,0 @@
-# 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

@@ -1,50 +0,0 @@
-<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

@@ -1,34 +0,0 @@
-# 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

@@ -1,41 +0,0 @@
-<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

@@ -1,14 +0,0 @@
-# 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

@@ -1,49 +0,0 @@
-<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>