npm - @nil-/doc - Versions diffs - 1.0.0 → 2.0.0 - Mend

@nil-/doc 1.0.0 → 2.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (484) hide show

package/package/package.json ADDED Viewed

@@ -0,0 +1,29 @@
+{
+    "name": "@nil-/doc",
+    "version": "2.0.0",
+    "author": {
+        "email": "njaldea@gmail.com",
+        "name": "Neil Aldea"
+    },
+    "license": "ISC",
+    "peerDependencies": {
+        "svelte": "^5.7.1"
+    },
+    "keywords": [
+        "svelte",
+        "documentation",
+        "component"
+    ],
+    "type": "module",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./index.d.ts",
+            "svelte": "./index.js",
+            "default": "./index.js"
+        }
+    },
+    "dependencies": {
+        "vanilla-picker": "^2.12.3"
+    }
+}

package/package.json CHANGED Viewed

@@ -1,29 +1,58 @@
 {
-  "name": "@nil-/doc",
-  "version": "1.0.0",
-  "author": {
-    "email": "njaldea@gmail.com",
-    "name": "Neil Aldea"
-  },
-  "license": "ISC",
-  "peerDependencies": {
-    "svelte": "^4.0.3"
-  },
-  "keywords": [
-    "svelte",
-    "documentation",
-    "component"
-  ],
-  "type": "module",
-  "exports": {
-    "./package.json": "./package.json",
-    ".": {
-      "types": "./index.d.ts",
-      "svelte": "./index.js",
-      "default": "./index.js"
+    "name": "@nil-/doc",
+    "version": "2.0.0",
+    "author": {
+        "email": "njaldea@gmail.com",
+        "name": "Neil Aldea"
+    },
+    "license": "ISC",
+    "scripts": {
+        "build": "vite build",
+        "check": "svelte-check --tsconfig ./tsconfig.json",
+        "dev": "vite dev",
+        "gen:package": "svelte-package -o package",
+        "gen:meta": "npx @nil-/postpackage ./package",
+        "package": "pnpm run gen:package && pnpm run gen:meta",
+        "sync": "svelte-kit sync",
+        "lint": "eslint . --ignore-path ../../.eslintignore"
+    },
+    "devDependencies": {
+        "@nil-/doc-kit": "workspace:^",
+        "@nil-/postpackage": "workspace:^",
+        "@sveltejs/adapter-vercel": "^5.7.1",
+        "@sveltejs/kit": "^2.20.8",
+        "@sveltejs/package": "^2.3.11",
+        "@sveltejs/vite-plugin-svelte": "5.0.1",
+        "mdsvex": "^0.12.5",
+        "remark-admonitions": "^1.2.1",
+        "svelte-check": "^3.8.6",
+        "tslib": "^2.8.1",
+        "typescript": "^5.8.3",
+        "vite": "^6.3.4",
+        "vitest": "^0.33.0"
+    },
+    "peerDependencies": {
+        "svelte": "^5.7.1"
+    },
+    "publishConfig": {
+        "directory": "package",
+        "linkDirectory": true
+    },
+    "keywords": [
+        "svelte",
+        "documentation",
+        "component"
+    ],
+    "type": "module",
+    "exports": {
+        "./package.json": "./package.json",
+        ".": {
+            "types": "./index.d.ts",
+            "svelte": "./index.js",
+            "default": "./index.js"
+        }
+    },
+    "dependencies": {
+        "vanilla-picker": "^2.12.3"
     }
-  },
-  "dependencies": {
-    "vanilla-picker": "^2.12.1"
-  }
-}
+}

package/src/app.d.ts ADDED Viewed

@@ -0,0 +1,10 @@
+/// <reference types="@sveltejs/kit" />
+// See https://kit.svelte.dev/docs/types#the-app-namespace
+// for information about these interfaces
+declare namespace App {
+    // interface Error {}
+    // interface Locals {}
+    // interface PageData {}
+    // interface Platform {}
+}

package/src/app.html ADDED Viewed

@@ -0,0 +1,33 @@
+<!doctype html>
+<html lang="en">
+    <head>
+        <meta charset="utf-8" />
+        <meta name="author" content="Neil Aldea" />
+        <meta name="description" content="@nil-/doc" />
+        <meta name="keywords" content="svelte, documentation, component" />
+        <meta name="viewport" content="width=device-width, initial-scale=1" />
+        <meta property="og:title" content="@nil-/doc" />
+        <meta
+            property="og:description"
+            content="A Svelte component library to help documentation. Framework agnostic with an adapter library to SvelteKit."
+        />
+        <meta property="og:image" content="https://mono-doc.vercel.app/assets/icon.png" />
+        <meta property="og:type" content="website" />
+        <meta property="og:url" content="https://mono-doc.vercel.app" />
+        <link rel="icon" href="%sveltekit.assets%/assets/favicon.svg" />
+        %sveltekit.head%
+        <style>
+            html,
+            body {
+                width: 100%;
+                height: 100%;
+                margin: 0px;
+                padding: 0px;
+            }
+        </style>
+    </head>
+    <body>
+        <div style="display: contents">%sveltekit.body%</div>
+    </body>
+</html>

package/src/lib/components/Base.svelte ADDED Viewed

@@ -0,0 +1,77 @@
+<script lang="ts">
+    import type { Snippet } from "svelte";
+    let {
+        dark = false,
+        fill = false,
+        children
+    }: {
+        dark?: boolean;
+        fill?: boolean;
+        children?: Snippet
+    } = $props();
+</script>
+<div class:dark class:fill>
+    {@render children?.()}
+</div>
+<!-- prettier-ignore -->
+<style>
+    div {
+        font-family: var(--nil-doc-font-family, ""), Consolas, Courier, 'Courier New', monospace;
+    }
+    .fill {
+        width: 100%;
+        height: 100%;
+    }
+    div {
+        --i-nil-doc-color: var(--nil-doc-color, hsl(0, 0%, 0%));
+        --i-nil-doc-color-scheme: var(--nil-doc-color-scheme, light);
+        --i-nil-doc-bg-color: var(--nil-doc-bg-color, hsl(0, 0%, 98%));
+        --i-nil-doc-content-outline-color: var(--nil-doc-content-outline-color, hsla(0, 0%, 0%, 0.3));
+        --i-nil-doc-block-bg-color: var(--nil-doc-block-bg-color, hsla(0, 0%, 98%, 0.3));
+        --i-nil-doc-block-outline-color: var(--nil-doc-block-outline-color, hsla(0, 0%, 0%, 0.3));
+        --i-nil-doc-container-p: var(--nil-doc-container-p, hsl(0, 2%, 70%));
+        --i-nil-doc-container-s: var(--nil-doc-container-s, hsl(0, 0%, 0%));
+        --i-nil-doc-controls-p: var(--nil-doc-controls-p, hsl(0, 0%, 100%));
+        --i-nil-doc-controls-s: var(--nil-doc-controls-s, hsl(210, 29%, 97%));
+        --i-nil-doc-controls-hover: var(--nil-doc-controls-hover, hsl(210, 100%, 90%));
+    }
+    div.dark {
+        --i-nil-doc-color: var(--nil-doc-color, hsl(0, 0%, 80%));
+        --i-nil-doc-color-scheme: var(--nil-doc-color-scheme, dark);
+        --i-nil-doc-bg-color: var(--nil-doc-bg-color, hsl(210, 6%, 7%));
+        --i-nil-doc-content-outline-color: var(--nil-doc-content-outline-color, hsla(0, 0%, 100%, 0.3));
+        --i-nil-doc-block-bg-color: var(--nil-doc-block-bg-color, hsla(200, 4%, 7%, 0.3));
+        --i-nil-doc-block-outline-color: var(--nil-doc-block-outline-color, hsla(0, 0%, 1000%, 0.3));
+        --i-nil-doc-container-p: var(--nil-doc-container-p, hsl(0, 2%, 40%));
+        --i-nil-doc-container-s: var(--nil-doc-container-s, hsl(0, 0%, 100%));
+        --i-nil-doc-controls-p: var(--nil-doc-controls-p, hsl(213, 26%, 7%));
+        --i-nil-doc-controls-s: var(--nil-doc-controls-s, hsl(213, 26%, 11%));
+        --i-nil-doc-controls-hover: var(--nil-doc-controls-hover, hsl(203, 100%, 15%));
+    }
+    div {
+        --i-nil-doc-nav-hovered: var(--nil-doc-nav-hovered, hsla(203, 98%, 50%, 0.25));
+        --i-nil-doc-nav-page-hovered: var(--nil-doc-nav-page-hovered, hsla(203, 98%, 50%, 0.6));
+        --i-nil-doc-nav-selected: var(--nil-doc-nav-selected, hsla(203, 98%, 50%, 0.85));
+        --i-nil-doc-instance-hovered: var(--nil-doc-instance-hovered, hsla(203, 98%, 50%, 0.25));
+        --i-nil-doc-instance-control-hovered: var(--nil-doc-instance-control-hovered, hsla(203, 98%, 50%, 0.6));
+        --i-nil-doc-instance-selected-color: var(--nil-doc-instance-selected-color, hsla(203, 98%, 50%, 0.85));
+        --i-nil-doc-transition-time: var(--nil-doc-transition-time, 350ms);
+    }
+</style>

package/src/lib/components/block/Block.svelte ADDED Viewed

@@ -0,0 +1,84 @@
+<script lang="ts">
+    import { initParams, initDefaults, initControls, initOrientation } from "./context";
+    import Base from "../Base.svelte";
+    import { getTheme } from "../context";
+    import type { Snippet } from "svelte";
+    initParams();
+    initDefaults();
+    initControls();
+    const columns = initOrientation();
+    const dark = getTheme();
+    let { children }: { children: Snippet } = $props();
+</script>
+<!--
+    @component3-Block
+    See [documentation](https://mono-doc.vercel.app/3-Components/2-Block) for more details.
+-->
+<!-- <svelte:body on:click={unfocus}/> -->
+<Base dark={$dark}>
+    <div class="outer">
+        <div class="scrollable block" class:columns={$columns}>
+            {@render children?.()}
+        </div>
+    </div>
+</Base>
+<style>
+    .outer {
+        position: relative;
+        border-radius: 0.5rem;
+        padding: 1rem 0.2rem 1rem 0.2rem;
+        min-width: 10rem;
+        margin: 1px;
+        outline: solid 1px white;
+    }
+    .block {
+        width: 100%;
+        height: 100%;
+        display: grid;
+        grid-auto-rows: 1fr;
+        grid-auto-columns: auto;
+        grid-auto-flow: row;
+    }
+    .scrollable {
+        overflow: scroll;
+        /* Firefox */
+        scrollbar-width: none;
+        /* IE and Edge */
+        -ms-overflow-style: none;
+    }
+    .scrollable::-webkit-scrollbar {
+        display: none;
+    }
+    .block.columns {
+        grid-auto-rows: auto;
+        grid-auto-columns: 1fr;
+        grid-auto-flow: column;
+    }
+    .outer {
+        color: var(--i-nil-doc-color);
+        color-scheme: var(--i-nil-doc-color-scheme);
+        background-color: var(--i-nil-doc-block-bg-color);
+        box-shadow: 0 0 0.5rem 0 var(--i-nil-doc-block-outline-color);
+        outline: 1px solid var(--i-nil-doc-block-outline-color);
+        transition:
+            color var(--i-nil-doc-transition-time),
+            background-color var(--i-nil-doc-transition-time);
+    }
+    .block {
+        outline: 1px solid var(--i-nil-doc-block-outline-color);
+    }
+</style>

package/src/lib/components/block/Controls.svelte ADDED Viewed

@@ -0,0 +1,20 @@
+<script lang="ts">
+    import type { SpecialProp, Prop, Event } from "./controls/types";
+    import { getControls } from "./context";
+    let {
+        props = [],
+        events = []
+    }: {
+        props?: (Prop | SpecialProp)[];
+        events?: Event[];
+    } = $props();
+    const controls = getControls();
+    $effect(() => controls.set({ props, events }));
+</script>
+<!--
+    @component
+    See [documentation](https://mono-doc.vercel.app/3-Components/3-Block/2-Controls) for more details.
+-->

package/src/lib/components/block/Instance.svelte ADDED Viewed

@@ -0,0 +1,172 @@
+<script lang="ts" module>
+    import type { ValueType } from "./types";
+</script>
+<script lang="ts" generics="Args">
+    import { onDestroy, type Snippet } from "svelte";
+    import { writable } from "svelte/store";
+    import { resolve } from "./utils";
+    import { getControls, getControlInfo, getControlValue, type ControlValue } from "./context";
+    const controls = getControls();
+    const cc = getControlInfo();
+    const vv = getControlValue();
+    let {
+        defaults,
+        noreset =  false,
+        children
+    }: {
+        defaults?: Args;
+        noreset?: boolean;
+        children?: Snippet<[{
+            values: Args;
+            events: Record<string, (ev?: any) => void>;
+            key: boolean
+        }]>;
+    } = $props();
+    /**
+     * This flag is to rerender the whole slot component.
+     * If the control is disabled, we use the default value provided from the defaults field.
+     * If the value of a prop is undefined, we will have to forward this value to the slot.
+     * Problem is, if the slot component has a default value set, it is only
+     * evaluated during component creation, not in subsequent updates.
+     *
+     * The solution is to rerender the whole slot whenever there is an control update.
+     *
+     * Similar case to: https://github.com/sveltejs/svelte/issues/4442
+     */
+    let key = $state(false);
+    $effect(() => {
+        key;
+        return () => { key = !key; }
+    });
+    const s_values = writable<ControlValue>({ props: {}, events: [] });
+    // Need to hide bound from svelte reactivity logic since bound variable is also modified by the control bindings
+    // eslint-disable-next-line
+    const updateBound = (d: Args | undefined) => ($s_values.props = resolve(d ?? {}, {}));
+    $effect(() => { updateBound(defaults); });
+    const focus = () => {
+        if ($vv !== s_values) {
+            $cc = controls;
+            $vv = s_values;
+        }
+    };
+    const unfocus = () => {
+        if ($vv === s_values) {
+            $cc = null;
+            $vv = null;
+        }
+    };
+    onDestroy(unfocus);
+    const populate = (ext: string[] | null): Record<string, (ev: CustomEvent<unknown>) => void> => {
+        const obj: Record<string, (ev: CustomEvent<unknown>) => void> = {};
+        const stringify = (detail: unknown) => {
+            if (detail) {
+                if ("string" === typeof detail) {
+                    return detail;
+                }
+                return JSON.stringify(detail);
+            }
+            return "";
+        };
+        if (null != ext) {
+            for (const name of ext) {
+                obj[name] = (param) => {
+                    const detail = stringify(param);
+                    if ($s_values.events.length > 0) {
+                        const last = $s_values.events[0];
+                        if (last.name === name && last.detail === detail && last.count < 99) {
+                            last.count += 1;
+                            $s_values.events = $s_values.events;
+                            return;
+                        }
+                    }
+                    $s_values.events.unshift({ name, detail, count: 1 });
+                    if ($s_values.events.length > 50) {
+                        $s_values.events.pop();
+                    }
+                    $s_values.events = $s_values.events;
+                };
+            }
+        }
+        return obj;
+    };
+    let values = $state(resolve<Args>(defaults ?? {}, $s_values.props));
+    let events = $state(populate($controls.events));
+    const unsubs: (() => void)[] = [];
+    unsubs.push(s_values.subscribe(v => values = resolve<Args>(defaults ?? {}, v.props)));
+    unsubs.push(controls.subscribe(v => events = populate(v.events)));
+    onDestroy(() => unsubs.forEach(v => v()));
+</script>
+<!--
+    @component
+    See [documentation](https://mono-doc.vercel.app/3-Components/3-Block/1-Content/1-Instance) for more details.
+-->
+<div
+    class="instance"
+    class:selected={$vv === s_values}
+    class:controls={$controls.events.length > 0 || $controls.props.length > 0}
+    role="none"
+    onclick={focus}
+    onkeypress={null}
+>
+    <div class="content">
+        {#if children}
+            {#if noreset}
+                {@render children({ values, events, key })}
+            {:else}
+                {#key key}
+                    {@render children({ values, events, key })}
+                {/key}
+            {/if}
+        {/if}
+    </div>
+</div>
+<style>
+    .instance {
+        width: 100%;
+        height: 100%;
+    }
+    .content {
+        min-height: 6.25rem;
+        border: 1px solid var(--i-nil-doc-block-outline-color);
+    }
+    /* colors */
+    .instance {
+        transition: background-color var(--i-nil-doc-transition-time);
+        color: var(--i-nil-doc-color);
+        background-color: var(--i-nil-doc-bg-color);
+        border-width: 2px;
+        border-style: solid;
+        border-color: transparent;
+        box-sizing: border-box;
+    }
+    .instance:hover {
+        border-color: var(--i-nil-doc-instance-hovered);
+    }
+    .instance.controls:hover {
+        border-color: var(--i-nil-doc-instance-control-hovered);
+    }
+    .instance.selected,
+    .instance.selected:hover {
+        border-color: var(--i-nil-doc-instance-selected-color);
+    }
+</style>

package/src/lib/components/block/Params.svelte ADDED Viewed

@@ -0,0 +1,35 @@
+<script lang="ts">
+    import type { ValueType } from "./types";
+    import { getParams } from "./context";
+    import { resolve } from "./utils";
+    import { get } from "svelte/store";
+    let {
+        tag,
+        props = {}
+    }: {
+        tag?: string | undefined;
+        props?: Record<string, ValueType>;
+    } = $props();
+    const params = getParams();
+    const id = get(params).length;
+    params.update(p => {
+        p.push({
+            id,
+            tag: `${id}`,
+            values: {}
+        });
+        return p;
+    });
+    $effect(() => params.update(p => { p[id].tag = tag ?? `${id}`; return p; }));
+    $effect(() => params.update(p => { p[id].values = resolve(props, {}); return p; }));
+</script>
+<!--
+    @component
+    See [documentation](https://mono-doc.vercel.app/3-Components/3-Block/1-Content/2-Template/1-Params) for more details.
+-->

package/src/lib/components/block/Template.svelte ADDED Viewed

@@ -0,0 +1,78 @@
+<script lang="ts" module>
+    import type { ValueType } from "./types";
+</script>
+<script lang="ts" generics="Args">
+    import { getDefaults, getParams, getOrientation } from "./context";
+    import { resolve } from "./utils";
+    import Instance from "./Instance.svelte";
+    import { type Snippet } from "svelte";
+    const params = getParams();
+    const defaultsStore = getDefaults();
+    const orientation = getOrientation();
+    let {
+        defaults,
+        noreset = false,
+        columns = false,
+        children: cc
+    }: {
+        defaults?: Args;
+        noreset?: boolean;
+        columns?: boolean;
+        children?: Snippet<[{
+            id: number;
+            tag: string;
+            values: Args;
+            events: Record<string, (ev?: any) => void>;
+            key: boolean;
+        }]>;
+    } = $props();
+    $effect(() => { defaultsStore?.set(defaults ?? {} as any); });
+    $effect(() => { orientation.set(columns); });
+    /**
+     * This flag is to rerender the whole slot component.
+     * If the control is disabled, we use the default value provided from the defaults field.
+     * If the value of a prop is undefined, we will have to forward this value to the slot.
+     * Problem is, if the slot component has a default value set, it is only
+     * evaluated during component creation, not in subsequent updates.
+     *
+     * The solution is to rerender the whole slot whenever there is an control update.
+     *
+     * Similar case to: https://github.com/sveltejs/svelte/issues/4442
+     */
+    let key = $state(false);
+    $effect(() => {
+        key;
+        return () => { key = !key; }
+    });
+    const resolveArgs = resolve<Args>;
+</script>
+<!--
+    @component
+    See [documentation](https://mono-doc.vercel.app/3-Components/3-Block/1-Content/2-Template) for more details.
+-->
+{#each $params as param (param.id)}
+    <Instance
+        defaults={resolveArgs($defaultsStore, param.values)}
+        {noreset}
+    >
+        {#snippet children({ values, events, key })}
+            {@render cc?.({
+                id: param.id,
+                tag: param.tag,
+                values: values,
+                events: events,
+                key: key
+            })}
+        {/snippet}
+    </Instance>
+{/each}

package/src/lib/components/block/action.ts ADDED Viewed

@@ -0,0 +1,32 @@
+import type { ActionReturn } from "svelte/action";
+type Options = { class: string; min: number; w: boolean; enabled: boolean };
+/**
+ *  Temporary support for container query until svelte supports it
+ */
+export const cquery = (div: HTMLDivElement, options: Options): ActionReturn<Options> => {
+    let o = options;
+    const check = () =>
+        div.classList.toggle(o.class, (o.w ? div.clientWidth : div.clientHeight) > o.min);
+    const observer = new ResizeObserver(check);
+    if (o.enabled) {
+        observer.observe(div);
+    }
+    return {
+        update: (options) => {
+            if (o.enabled !== options.enabled) {
+                if (!o.enabled && options.enabled) {
+                    observer.observe(div);
+                } else {
+                    observer.disconnect();
+                }
+            }
+            o = options;
+            check();
+        },
+        destroy: () => o.enabled && observer.disconnect()
+    };
+};