add: the inline source support (#157)

Author: XiangYyang

.gitignore

@@ -5,4 +5,5 @@ www/kicanvas
 coverage/
 esbuild-meta.json
 
+.pyenv
 .DS_Store

debug/embedded.html

@@ -62,6 +62,50 @@
                 nulla pariatur. Excepteur sint occaecat cupidatat non proident,
                 sunt in culpa qui officia deserunt mollit anim id est laborum.
             </p>
+            <kicanvas-embed>
+                <kicanvas-source>
+                    (kicad_sch (version 20230121) (generator eeschema) (uuid
+                    5d5ad125-5ef1-42a1-a410-a0c4ab262ca6) (paper "A4")
+                    (title_block (title "KiCanvas inline sources test") (date
+                    "2023-11-10") ) (lib_symbols ) (text "KiCanvas inline
+                    sources test" (at 93.98 104.14 0) (effects (font (size 5 5)
+                    (thickness 1) bold) (justify left bottom)) (uuid
+                    27eb63d7-7111-4c0e-9985-c1ed90138e31) ) (sheet_instances
+                    (path "/" (page "1")) ) )
+                </kicanvas-source>
+            </kicanvas-embed>
+            <p>
+                Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do
+                eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut
+                enim ad minim veniam, quis nostrud exercitation ullamco laboris
+                nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor
+                in reprehenderit in voluptate velit esse cillum dolore eu fugiat
+                nulla pariatur. Excepteur sint occaecat cupidatat non proident,
+                sunt in culpa qui officia deserunt mollit anim id est laborum.
+            </p>
+            <kicanvas-embed controls="full">
+                <kicanvas-source name="sch1.kicad_sch">
+                    (kicad_sch (version 20230121) (generator eeschema) (uuid
+                    5d5ad125-5ef1-42a1-a410-a0c4ab262ca6) (paper "A4")
+                    (title_block (title "KiCanvas inline sources test 1") (date
+                    "2023-11-10") ) (lib_symbols ) (text "KiCanvas inline file
+                    SCH1" (at 93.98 104.14 0) (effects (font (size 5 5)
+                    (thickness 1) bold) (justify left bottom)) (uuid
+                    27eb63d7-7111-4c0e-9985-c1ed90138e31) ) (sheet_instances
+                    (path "/" (page "1")) ) )
+                </kicanvas-source>
+                <kicanvas-source name="sch2.kicad_sch">
+                    (kicad_sch (version 20230121) (generator eeschema) (uuid
+                    5d5ad125-5ef1-42a1-a410-a0c4ab262ca6) (paper "A4")
+                    (title_block (title "KiCanvas inline sources test 2") (date
+                    "2023-11-11") ) (lib_symbols ) (text "KiCanvas inline file
+                    SCH2" (at 90 100 0) (effects (font (size 5 5) (thickness 1)
+                    bold) (justify left bottom)) (uuid
+                    27eb63d7-7111-4c0e-9985-c1ed90138e31) ) (sheet_instances
+                    (path "/" (page "1")) ) )
+                </kicanvas-source>
+                <kicanvas-source src="examples/mcu.kicad_sch"></kicanvas-source>
+            </kicanvas-embed>
         </main>
     </body>
 

docs/docs/embedding.md

@@ -1,6 +1,7 @@
 # <kicanvas-embed\>: The KiCanvas embedded viewer element
 
 <!-- load kicanvas -->
+
 <script type="module" src="/kicanvas/kicanvas.js"></script>
 
 !!! warning "Work in progress"
@@ -98,22 +99,37 @@ You can switch between the displayed files using the project panel on the right
 
 ### Inline source
 
-!!! warning "Not yet implemented"
-
-    This functionality hasn't been implemented yet
-
 This example shows how to use `<kicanvas-source>` along with inline KiCAD data. In this case, it's a symbol copied from a schematic and pasted into the HTML source:
 
 ```html
 <kicanvas-embed>
-    <kicanvas-source type="schematic">
-        (lib_symbols (symbol "power:+12V" (power) (pin_names (offset 0)) (in_bom
-        yes) (on_board yes) (property "Reference" "#PWR" (at 0 -3.81 0) (effects
-        (font (size 1.27 1.27)) hide) ) ...
+    <!-- Use it directly -->
+    <kicanvas-source>
+        (kicad_sch (version 20230121) (generator eeschema) (uuid
+        5d5ad125-5ef1-42a1-a410-a0c4ab262ca6) (paper "A4") (title_block (title
+        "KiCanvas inline sources") (date "2023-11-11") ) (lib_symbols ) (text
+        "Hello World !!!" (at 90 100 0) (effects (font (size 5 5) (thickness 1)
+        bold) (justify left bottom)) (uuid 27eb63d7-7111-4c0e-9985-c1ed90138e31)
+        ) (sheet_instances (path "/" (page "1")) ) )
     </kicanvas-source>
+
+    <!-- Or mixed with `src` tag -->
+    <kicanvas-source src="/examples/simple.kicad_sch"></kicanvas-source>
 </kicanvas-embed>
 ```
 
+<kicanvas-embed controls="full">
+    <kicanvas-source src="/examples/simple.kicad_sch"></kicanvas-source>
+    <kicanvas-source name="inline.kicad_sch">
+        (kicad_sch (version 20230121) (generator eeschema) (uuid
+        5d5ad125-5ef1-42a1-a410-a0c4ab262ca6) (paper "A4") (title_block (title
+        "KiCanvas inline sources") (date "2023-11-11") ) (lib_symbols ) (text
+        "Inline source file" (at 90 100 0) (effects (font (size 5 5) (thickness 1)
+        bold) (justify left bottom)) (uuid 27eb63d7-7111-4c0e-9985-c1ed90138e31)
+        ) (sheet_instances (path "/" (page "1")) ) )
+    </kicanvas-source>
+</kicanvas-embed>
+
 ## Attributes
 
 !!! warning "Not yet implemented"
@@ -137,6 +153,8 @@ This example shows how to use `<kicanvas-source>` along with inline KiCAD data.
     - `nopreferences` - don't show the user preferences panel. ⚠️
     - `nohelp` - don't show the help panel. ⚠️
 - `src` - the URL of the document to embed. If you want to show multiple documents within a single viewer, you can use multiple child `<kicanvas-source>` elements.
+- `type` - when providing the file source inline, this explicitly sets the file type. If not specified, KiCanvas will attempt to determine the type automatically. If specified, it should be one of `schematic`, `board`, `project`, or `worksheet`.
+- `name` - when providing the file source inline, this explicitly sets the file name. This is typically only necessary when there are multiple files within a project, as KiCAD uses the file name to link schematic sheets, drawing sheets, and PCBs together. If unspecified, KiCanvas will generate a file name like `inline_0.kicad_sch`.
 - `theme` - sets the color theme to use, valid values are `kicad` and `witchhazel`. ⚠️
 - `zoom` - sets the initial view into the document. ⚠️
     - `objects` - zooms to show all visible objects (default). ⚠️
@@ -150,11 +168,11 @@ This example shows how to use `<kicanvas-source>` along with inline KiCAD data.
 
     This functionality hasn't been implemented yet
 
-| Event Name                   | Fired When                                                                                        |
-| ---------------------------- | ------------------------------------------------------------------------------------------------- |
-| ⚠️ `kicanvas:click`          | The user clicks or taps within the embedded document                                              |
-| ⚠️ `kicanvas:documentchange` | The currently displayed document is changed, either through user interaction or programmatically. |
-| ⚠️ `kicanvas:error`          | An error occurs while loading source files                                                        |
-| ⚠️ `kicanvas:load`           | All sources files have been successfully loaded                                                   |
-| ⚠️ `kicanvas:loadstart`      | KiCanvas begins loading source files                                                              |
-| ⚠️ `kicanvas:select`         | The user selects (or deselects) an object within the document                                     |
+| Event Name                  | Fired When                                                                                        |
+| --------------------------- | ------------------------------------------------------------------------------------------------- |
+| ⚠️`kicanvas:click`          | The user clicks or taps within the embedded document                                              |
+| ⚠️`kicanvas:documentchange` | The currently displayed document is changed, either through user interaction or programmatically. |
+| ⚠️`kicanvas:error`          | An error occurs while loading source files                                                        |
+| ⚠️`kicanvas:load`           | All sources files have been successfully loaded                                                   |
+| ⚠️`kicanvas:loadstart`      | KiCanvas begins loading source files                                                              |
+| ⚠️`kicanvas:select`         | The user selects (or deselects) an object within the document                                     |

src/kicanvas/elements/kicanvas-embed.ts

@@ -5,6 +5,7 @@
 */
 
 import { later } from "../../base/async";
+import { Logger } from "../../base/log";
 import {
     CSS,
     CustomElement,
@@ -15,12 +16,19 @@ import {
 import { KCUIElement } from "../../kc-ui";
 import kc_ui_styles from "../../kc-ui/kc-ui.css";
 import { Project } from "../project";
-import { FetchFileSystem, VirtualFileSystem } from "../services/vfs";
+import {
+    FetchFileSystem,
+    LocalFileSystem,
+    MergedFileSystem,
+    VirtualFileSystem,
+} from "../services/vfs";
 import type { KCBoardAppElement } from "./kc-board/app";
 import type { KCSchematicAppElement } from "./kc-schematic/app";
 
+const log = new Logger("kicanvas:embedtag");
+
 /**
- *
+ * kicanvas-embed tag
  */
 class KiCanvasEmbedElement extends KCUIElement {
     static override styles = [
@@ -99,26 +107,55 @@ class KiCanvasEmbedElement extends KCUIElement {
     async #setup_events() {}
 
     async #load_src() {
-        const sources = [];
+        const url_src = [];
+        const inline_file = [];
 
         if (this.src) {
-            sources.push(this.src);
+            url_src.push(this.src);
         }
 
+        let inline_count = 0;
+
         for (const src_elm of this.querySelectorAll<KiCanvasSourceElement>(
             "kicanvas-source",
         )) {
             if (src_elm.src) {
-                sources.push(src_elm.src);
+                // URL
+                url_src.push(src_elm.src);
+            } else if (src_elm.is_inline_source()) {
+                // inline source
+                const default_name = `inline_${inline_count}`;
+                inline_count += 1;
+
+                const file = src_elm.load_inline_source(default_name);
+
+                if (file) {
+                    log.info(
+                        `Determined inline source ${file.name}, ${file.size} bytes`,
+                    );
+
+                    inline_file.push(file);
+                }
             }
         }
 
-        if (sources.length == 0) {
-            console.warn("No valid sources specified");
+        // maybe we have a better way to merge two VFS
+        // we need load file from File blobs and URLs
+
+        const url_vfs =
+            url_src.length === 0
+                ? null
+                : new FetchFileSystem(url_src, this.custom_resolver);
+
+        const inline_vfs =
+            inline_file.length === 0 ? null : new LocalFileSystem(inline_file);
+
+        if (url_vfs === null && inline_vfs === null) {
+            log.warn("No valid sources specified");
             return;
         }
 
-        const vfs = new FetchFileSystem(sources, this.custom_resolver);
+        const vfs = new MergedFileSystem([url_vfs, inline_vfs]);
         await this.#setup_project(vfs);
     }
 
@@ -173,6 +210,13 @@ class KiCanvasEmbedElement extends KCUIElement {
 
 window.customElements.define("kicanvas-embed", KiCanvasEmbedElement);
 
+enum KiCanvasSourceType {
+    Schematic = "schematic",
+    Board = "board",
+    Project = "project",
+    Worksheet = "worksheet",
+}
+
 class KiCanvasSourceElement extends CustomElement {
     constructor() {
         super();
@@ -181,8 +225,95 @@ class KiCanvasSourceElement extends CustomElement {
         this.style.display = "none";
     }
 
+    is_inline_source(): boolean {
+        return this.src === null && this.childNodes.length > 0;
+    }
+
+    load_inline_source(default_name: string | null = null): File | undefined {
+        let content = "";
+
+        for (const child of this.childNodes) {
+            if (child.nodeType === Node.TEXT_NODE) {
+                // Get the content and triming the CR,LF,space.
+                content += child.nodeValue ?? "";
+            } else {
+                log.warn(
+                    `kicanvas-source children ${child.nodeType} are invaild.`,
+                );
+            }
+        }
+
+        content = content.trimStart();
+
+        // determine the file name
+        let file_name;
+        if (this.name) {
+            file_name = this.name;
+        } else {
+            const typ =
+                this.type ?? KiCanvasSourceElement.determine_file_type(content);
+
+            if (typ === undefined) {
+                log.warn(
+                    `Unknown file type, content: ${content.slice(0, 64)}...`,
+                );
+                return undefined;
+            }
+
+            const ext = KiCanvasSourceElement.get_file_ext(typ);
+
+            file_name = (default_name ?? "noname") + ext;
+        }
+
+        if (content.length === 0) {
+            log.warn(`kicanvas-source content ${file_name} is empty.`);
+            return undefined;
+        }
+
+        const file_blob = new Blob([content], { type: "text/plain" });
+        const file = new File([file_blob], file_name);
+
+        return file;
+    }
+
+    private static determine_file_type(
+        content: string,
+    ): KiCanvasSourceType | undefined {
+        if (content.startsWith("(kicad_sch")) {
+            return KiCanvasSourceType.Schematic;
+        } else if (content.startsWith("(kicad_pcb")) {
+            return KiCanvasSourceType.Board;
+        } else if (content.startsWith("(kicad_wks")) {
+            return KiCanvasSourceType.Worksheet;
+        } else if (content.startsWith("{")) {
+            // project? maybe we need try parsing the json
+            return KiCanvasSourceType.Project;
+        }
+
+        return undefined;
+    }
+
+    private static get_file_ext(typ: KiCanvasSourceType): string {
+        switch (typ) {
+            case KiCanvasSourceType.Schematic:
+                return ".kicad_sch";
+            case KiCanvasSourceType.Board:
+                return ".kicad_pcb";
+            case KiCanvasSourceType.Worksheet:
+                return ".kicad_wks";
+            case KiCanvasSourceType.Project:
+                return ".kicad_prj";
+        }
+    }
+
     @attribute({ type: String })
     src: string | null;
+
+    @attribute({ type: String })
+    type: KiCanvasSourceType | null;
+
+    @attribute({ type: String })
+    name: string | null;
 }
 
 window.customElements.define("kicanvas-source", KiCanvasSourceElement);

src/kicanvas/services/vfs.ts

@@ -229,3 +229,51 @@ export class LocalFileSystem extends VirtualFileSystem {
         initiate_download(await this.get(name));
     }
 }
+
+/**
+ * Merge two virtual file systems into one
+ */
+export class MergedFileSystem extends VirtualFileSystem {
+    private fs_list: VirtualFileSystem[];
+
+    constructor(fs: (VirtualFileSystem | null)[]) {
+        super();
+        this.fs_list = fs.filter((f) => f !== null);
+    }
+
+    override *list() {
+        for (const fs of this.fs_list) {
+            yield* fs.list();
+        }
+    }
+
+    override async has(name: string): Promise<boolean> {
+        for (const fs of this.fs_list) {
+            if (await fs.has(name)) {
+                return true;
+            }
+        }
+
+        return false;
+    }
+
+    override async get(name: string): Promise<File> {
+        for (const fs of this.fs_list) {
+            if (await fs.has(name)) {
+                return await fs.get(name);
+            }
+        }
+
+        throw new Error(`File ${name} not found`);
+    }
+
+    override async download(name: string) {
+        for (const fs of this.fs_list) {
+            if (await fs.has(name)) {
+                return await fs.download(name);
+            }
+        }
+
+        throw new Error(`File ${name} not found`);
+    }
+}