git0 0.2.10 → 0.2.11

package/svelte-nodegui/website/docs/guides/styling.md

@@ -0,0 +1,208 @@
+---
+sidebar_label: Styling
+title: Styling
+---
+
+With Svelte NodeGui, you can style a component to your needs. If you are familiar with CSS in the web world you would feel right at home. All components accept the `style` prop for setting inline styles. The style names and values usually match how CSS works on the web.
+
+Here's an example:
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <text style="color: green; background-color: white;">
+    Hello World
+  </text>
+</window>
+```
+
+## Overview
+
+Svelte NodeGui makes use of [Qt's stylesheet](https://doc.qt.io/qt-5/stylesheet-syntax.html) for styling. Qt Style Sheet terminology and syntactic rules are almost identical to those of HTML CSS. Additionally, Svelte NodeGui adds support for layout using flex properties like align-items, justify-content, etc. Flexbox layout support is added using [facebook's yoga library](https://github.com/facebook/yoga).
+
+You would write your style properties in a string and pass it to the Svelte NodeGui components either via global styles or inline styles (similar to how it works in the web).
+
+## Global styles
+
+Lets take a look at an example:
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <view id="rootView">
+    <text id="helloLabel">Hello</text>
+    <text id="worldLabel">World</text>
+  </view>
+</window>
+
+<style>
+  #helloLabel {
+    color: red;
+    padding: 10px;
+  }
+  #worldLabel {
+    color: green;
+    padding: 10px;
+  }
+  #rootView {
+    background-color: black;
+    height: '100%';
+  }
+</style>
+```
+
+
+In the case of global stylesheet you can define all your style properties in a stylesheet string and the tell the root view or window to set it as a stylsheet for it and its child components. The only difference here from web is that you can set a stylesheet on a component at any level in the whole tree of components, the stylesheet will affect the component and its children.
+
+In the above example, in order to reference a component in a stylesheet we will assign it a `id` using id prop. Think of it as similar to an `id` in the case of web (but in reality it calls setObjectName method in nodegui). Now using the id you could reference the component in the stylesheet and set style properties on them. Do not worry about the layout stuff that is going on here, that will be covered in the next section.
+
+Global stylesheet really becomes powerful when you use things like pseudo-selectors (hover, checked, etc). It also has helps in implementing cascaded styles which allow you to style a group of components at once. We will see more about these features below.
+
+> More details on all the features and the syntax can be found here: https://doc.qt.io/qt-5/stylesheet-syntax.html
+
+## Inline styles
+
+Lets look at this example again:
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}>
+  <text style="color: green; background-color: white; height: '100%';">Hello World</text>
+</window>
+```
+
+In most cases it would be easier to style the components inline. Svelte NodeGui supports inline styling using `style` prop. Inline styles will only affect the component to which the style is applied to and is often easier to understand and manage. All properties you use in the global stylesheet are available in inline styles as well.
+
+## Selectors
+
+NodeGui style sheets support all the selectors defined in CSS2.
+Some examples include:
+
+```css
+* {
+  color: blue;
+}
+
+QPushButton {
+  padding: 10px;
+}
+
+#okButton {
+  margin: 10px;
+}
+
+#mainView > QPushButton {
+  margin: 10px;
+}
+```
+
+Note we are using QPushButton here instead of PushButton. This is because `<PushButton />` component internally renders a QPushButton. See PushButton docs for more details.
+
+To see a complete list of selectors see here: https://doc.qt.io/qt-5/stylesheet-syntax.html#selector-types
+
+## Pseudo states
+
+Like in the web, you can style your component based on its state. An example would be, you might want the color of the button text to be red when its hovered upon. These are possible with pseudo states. Pseudo-states appear at the end of the selector, with a colon (:) in between.
+
+```css
+#okButton:hover {
+  color: red;
+}
+```
+
+> More details here : https://doc.qt.io/qt-5/stylesheet-syntax.html#pseudo-states
+
+## Cascading
+
+Style sheets can be set on the parent components and on child components. An arbitrary component's effective style sheet is obtained by merging the style sheets set on the component's ancestors (parent, grandparent, etc.).
+
+When conflicts arise, the component's own inline style sheet is always preferred to any inherited style sheet, irrespective of the specificity of the conflicting rules. Likewise, the parent component's style sheet is preferred to the grandparent's, etc.
+
+The behaviour is similar to what we see on the web.
+
+> For more in depth examples see here: https://doc.qt.io/qt-5/stylesheet-syntax.html#cascading
+
+## Properties
+
+NodeGui style sheet is a css string.
+
+For example:
+
+```typescript
+const textStyle: string = `
+  color: 'green';
+  padding: 12;
+  height: '100%';
+`;
+```
+
+Here if you look carefully, you would notice that there are some differences in the way we write style properties as compared to web.
+The quotes you see around `'green'` and `'100%'` are necessary so that Qt doesnt interpret them as numbers.
+So the rule of thumb is that any integer based property like margin, border, etc can be written without quotes while any string property, it is better to surround them with quotes. PS: Qt does recognise some string based properties without quotes also.
+
+## Supported properties
+
+Since we are not running inside a web browser, there are few differences in the properties you could use in NodeGui vs in web.
+
+The complete list is detailed here: https://doc.qt.io/qt-5/stylesheet-reference.html#list-of-properties
+
+Apart from the properties listed in the link, NodeGui also supports layout properties related to Flex. You can use all flex properties such as align-items, justify-content, flex, etc on all components. [The layout styling will be converted in more detail in the section: Layout.](layout.md)
+
+## Advanced usage (Setting QObject Properties)
+
+In Qt, every component has certain properties set on them using something called as [Q_PROPERTY](https://doc.qt.io/qt-5/qobject.html#Q_PROPERTY). There are many q-properties that are defined on each component already. You can also define custom qproperties in the native C++ code yourself too. What does it have to do with styling ? The thing is some of these properties can be altered using qt stylesheet. In Qt's terminology, these properties are called designable properties.
+
+For example:
+
+```css
+MyLabel {
+  qproperty-alignment: AlignCenter;
+}
+MyGroupBox {
+  qproperty-titlecolor: rgb(100, 200, 100);
+}
+QPushButton {
+  qproperty-iconsize: 20px 20px;
+}
+```
+
+You can discover these properties by following Qt's documentation or by running a simple google search like "center text in QLabel using stylesheet in Qt". These are advanced properties and in practice will come in use rarely but its good to know.
+
+> More details : https://doc.qt.io/qt-5/stylesheet-syntax.html#setting-qobject-properties
+
+---
+
+In this section, we mostly covered the paint properties in the Svelte NodeGui stylesheet. The next section would cover on how you can use flex to layout your components with stylesheet.

package/svelte-nodegui/website/docs/guides/tutorial.md

@@ -0,0 +1,82 @@
+---
+sidebar_label: Learn the Basics
+title: Learn the Basics
+---
+
+Svelte NodeGui uses native components instead of web based components as building blocks. So to understand the basic structure of a Svelte NodeGui app, you need to be familiar with Javascript or Typescript and Svelte. This tutorial is aimed at everyone who has some web experience with web development.
+
+## Svelte NodeGui development in a nutshell
+
+As far as development is concerned, an Svelte NodeGui application is essentially a Node.js application. The starting point is a `package.json` that is identical to that of a Node.js module. A most basic Svelte NodeGui app would have the following
+folder structure:
+
+```text
+your-app/
+├── package.json
+├── index.js
+```
+
+<!--
+All APIs and features found in NodeGui are accessible through the `@nodegui/svelte-nodegui` and `@nodegui/nodegui` modules, which can be required like any other Node.js module. Additionally you have access to all Node.js apis and node modules.
+
+```javascript
+require("@nodegui/svelte-nodegui");
+```
+
+The `@nodegui/svelte-nodegui` module exports widgets and features in namespaces. As an example, a window can be created using the `Window` component. A simple `main.js` file might open a window:
+
+```html
+<script lang="ts">
+  import { onMount } from "svelte";
+
+  onMount(() => {
+    (window as any).win = win; // Prevent garbage collection.
+    win.nativeView.show();
+    return () => {
+      delete (window as any).win;
+    };
+  });
+</script>
+
+<window bind:this={win}/>
+```
+
+The `index.js` should create windows and handle all the system events your
+application might encounter.
+-->
+
+## What's going on here?
+
+Firstly, we are running a Node.js app and not a browser based app. This means we do not have access to any browser APIs. The window you see is actually a native widget created by Qt. Window component is essentially a lightweight javascript wrapper over NodeGui's QMainWindow, which internally is Qt's QMainWindow. Hence every prop you set on Window instance is actually affecting a native window widget. This is very light weight as compared to browser based solutions and hence is more closer to the Operating system.
+
+## Trying out the starter project
+
+Clone and run the code by using the
+[`nodegui/svelte-nodegui-starter`][quick-start] repository.
+
+**Note**: Running this requires [Git](https://git-scm.com) and [npm](https://www.npmjs.com/).
+
+```sh
+# Clone the repository
+$ git clone https://github.com/nodegui/svelte-nodegui-starter
+# Go into the repository
+$ cd svelte-nodegui-starter
+# Install dependencies
+$ npm install
+# Run the dev server
+$ npm run dev
+# Run the app on a separate terminal tab or window
+$ npm start
+```
+
+[quick-start]: https://github.com/nodegui/svelte-nodegui-starter
+
+## What else other than a basic window?
+
+Svelte NodeGui has support for basic components like View (similar to div), CheckBox, PushButton and many more.
+You can take a look at the list of native widgets that Svelte NodeGui currently supports here : [Native widgets in Svelte NodeGui](/docs/api/interfaces/viewprops).
+With time more native components and APIs will be added to Svelte NodeGui. Apart from modules in Svelte NodeGui, you also have access to the entire node modules ecosystem. Thus, any node module that you can use with Node.js, can be used with Svelte NodeGui. This makes it extremely powerful.
+
+Fine, I want something more custom and beautiful than just native looking widgets. What do I do?
+
+To make things more beautiful, you will have to [learn about styling](styling). Lets take a look at that next.

package/svelte-nodegui/website/docs/guides/using-native-node-modules.md

@@ -0,0 +1,55 @@
+---
+sidebar_label: Native Node Modules
+title: Using native Node Modules
+---
+
+Native Node modules are supported by Svelte NodeGui, but since Svelte NodeGui is very
+likely to use a different V8 version from the Node binary installed on your
+system, the modules you use will need to be recompiled for Svelte NodeGui's node/v8 version. Otherwise,
+you will get the following class of error when you try to run your app:
+
+```sh
+Error: The module '/path/to/native/module.node'
+was compiled against a different Node.js version using
+NODE_MODULE_VERSION $XYZ. This version of Node.js requires
+NODE_MODULE_VERSION $ABC. Please try re-compiling or re-installing
+the module (for instance, using `npm rebuild` or `npm install`).
+```
+
+## How to install native modules
+
+To compile native Node modules against a build of NodeGui that doesn't
+match a public release, instruct `npm` to use the version of Qode (NodeJs) you have bundled
+with your custom build.
+
+```sh
+npm rebuild --nodedir=/path/to/qode
+```
+
+or
+
+```sh
+qode /path/to/npm rebuild
+```
+
+## Troubleshooting
+
+If you installed a native module and found it was not working, you need to check
+the following things:
+
+- When in doubt, rebuild native modules with qode first.
+- Make sure the native module is compatible with the target platform and
+  architecture for your NodeGui app.
+- After you upgrade NodeGui, you usually need to rebuild the modules.
+
+## Modules that rely on `node-pre-gyp`
+
+The [`node-pre-gyp` tool][node-pre-gyp] provides a way to deploy native Node
+modules with prebuilt binaries, and many popular modules are using it.
+
+Usually those modules work fine under NodeGui, but sometimes when NodeGui uses
+a newer version of V8 than Node and/or there are ABI changes, bad things may
+happen. So in general, it is recommended to always build native modules from
+source code.
+
+[node-pre-gyp]: https://github.com/mapbox/node-pre-gyp

package/svelte-nodegui/website/docs/mdx.md

@@ -0,0 +1,22 @@
+---
+id: mdx
+title: Powered by MDX
+---
+
+You can write JSX and use React components within your Markdown thanks to [MDX](https://mdxjs.com/).
+
+export const Highlight = ({children, color}) => (
+  <span
+    style={{
+      backgroundColor: color,
+      borderRadius: '2px',
+      color: '#fff',
+      padding: '0.2rem',
+    }}>
+    {children}
+  </span>
+);
+
+<Highlight color="#25c2a0">Docusaurus green</Highlight> and <Highlight color="#1877F2">Facebook blue</Highlight> are my favorite colors.
+
+I can write **Markdown** alongside my _JSX_!

package/svelte-nodegui/website/docs/scripts/fixdocs.js

@@ -0,0 +1,21 @@
+const fs = require('fs');
+const path = require('path');
+
+async function writeFile(filePath, fileContent) {
+    return new Promise((resolve, reject) => {
+        fs.writeFile(filePath, fileContent, (err) => (err ? reject(err) : resolve()));
+    });
+}
+
+async function emptyIndexMd() {
+    const src = path.resolve(__dirname, `../../../website/docs/api/index.md`);
+    await writeFile(src, '');
+}
+
+async function fixDocs() {
+    console.log('Fixing Docs...');
+    await emptyIndexMd();
+    console.log('Docs fixed successfully.');
+}
+
+fixDocs().catch(console.error);

package/svelte-nodegui/website/docusaurus.config.js

@@ -0,0 +1,131 @@
+module.exports = {
+  title: "Svelte NodeGUI",
+  tagline: "Build performant, native, cross-platform desktop apps with Svelte",
+  url: "https://svelte.nodegui.org",
+  baseUrl: "/",
+  favicon: "img/favicon.ico",
+  organizationName: "nodegui", // Usually your GitHub org/user name.
+  projectName: "svelte-nodegui", // Usually your repo name.
+  onBrokenLinks: "warn",
+  onDuplicateRoutes: "warn",
+  themeConfig: {
+    navbar: {
+      title: "Svelte NodeGUI",
+      logo: {
+        alt: "NodeGui Logo",
+        src: "img/logo-circle.png",
+      },
+      items: [
+        { to: "docs/guides/getting-started", label: "Docs", position: "right" },
+        {
+          to: "docs/api/interfaces/buttonprops",
+          label: "API",
+          position: "right",
+        },
+        { to: "blog", label: "Blog", position: "right" },
+        {
+          href: "https://github.com/nodegui/svelte-nodegui",
+          label: "GitHub",
+          position: "right",
+        },
+      ],
+      /**
+       * Prism doesn't yet support Svelte, so Docusaurus can't highlight it.
+       * @see https://github.com/PrismJS/prism/issues/2090
+       * There is a community-made support layer, but I don't see how I'd integrate it with Docusaurus.
+       * The may technically be a convoluted way by importing "prism-svelte" in .docusaurus/client-modules.js,
+       * but life is too short.
+       * @see https://github.com/pngwn/prism-svelte
+       */
+      // prism: {
+      //   additionalLanguages: ['svelte'],
+      // },
+    },
+    footer: {
+      style: "dark",
+      links: [
+        {
+          title: "Docs",
+          items: [
+            { to: "docs/guides/getting-started", label: "Getting Started" },
+            { to: "docs/api/interfaces/buttonprops", label: "API" },
+          ],
+        },
+        {
+          title: "Community",
+          items: [
+            {
+              label: "Spectrum",
+              href: "https://spectrum.chat/nodegui",
+            },
+            {
+              label: "Twitter",
+              to: "https://twitter.com/node_gui",
+            },
+            {
+              label: "Medium",
+              to: "https://medium.com/nodegui",
+            },
+          ],
+        },
+        {
+          title: "More",
+          items: [
+            {
+              label: "Blog",
+              to: "blog",
+            },
+            {
+              label: "NodeGui",
+              to: "https://nodegui.org",
+            },
+            // {
+            //   label: "FAQ",
+            //   to: "https://nodegui.org/faq",
+            // },
+          ],
+        },
+      ],
+      copyright: `Copyright © ${new Date().getFullYear()} NodeGui`,
+    },
+    // googleAnalytics: {
+    //   trackingID: "TODO",
+    // },
+    algolia: {
+      apiKey: "2d5f0b46c971ffb4947697ce645520b0",
+      indexName: "svelte-nodegui",
+      /**
+       * Optional. I've filled in some values in a comment for future reference.
+       */
+      algoliaOptions: {
+        // facetFilters: [
+        //   /**
+        //    * I'm not really sure what these do.
+        //    * There is also: lvl1, lvl2, lvl3, lvl4, lvl5
+        //    */
+        //   "type:content",
+        //
+        //   /**
+        //    * To my understanding, this is irrelevant for now, because we're not supporting multiple versions
+        //    * of the docs simultanteously.
+        //    * There is also: version:current
+        //    */
+        //   "version:latest",
+        // ],
+      },
+    },
+  },
+  presets: [
+    [
+      "@docusaurus/preset-classic",
+      {
+        docs: {
+          sidebarPath: require.resolve("./sidebars.js"),
+        },
+        theme: {
+          customCss: require.resolve("./src/css/custom.css"),
+        },
+      },
+    ],
+  ],
+};

package/svelte-nodegui/website/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "svelte-nodegui",
+  "version": "0.0.0",
+  "private": true,
+  "scripts": {
+    "docusaurus": "docusaurus",
+    "start": "docusaurus start",
+    "build": "docusaurus build",
+    "swizzle": "docusaurus swizzle",
+    "deploy": "docusaurus deploy"
+  },
+  "dependencies": {
+    "@docusaurus/core": "^2.0.0-alpha.64",
+    "@docusaurus/plugin-google-analytics": "^2.0.0-alpha.64",
+    "@docusaurus/preset-classic": "^2.0.0-alpha.64",
+    "classnames": "^2.2.6",
+    "react": "^16.8.4",
+    "react-dom": "^16.8.4",
+    "styled-components": "^4.4.0"
+  },
+  "browserslist": {
+    "production": [
+      ">0.2%",
+      "not dead",
+      "not op_mini all"
+    ],
+    "development": [
+      "last 1 chrome version",
+      "last 1 firefox version",
+      "last 1 safari version"
+    ]
+  }
+}

package/svelte-nodegui/website/sidebars.js

@@ -0,0 +1,77 @@
+module.exports = {
+  api: {
+    Components: [
+      "api/interfaces/buttonprops",
+      "api/interfaces/checkboxprops",
+      "api/interfaces/dialprops",
+      "api/interfaces/imageprops",
+      "api/interfaces/lineeditprops",
+      "api/interfaces/plaintexteditprops",
+      "api/interfaces/progressbarprops",
+      "api/interfaces/radiobuttonprops",
+      "api/interfaces/scrollareaprops",
+      "api/interfaces/spinboxprops",
+      "api/interfaces/textprops",
+      "api/interfaces/viewprops",
+      "api/interfaces/windowprops",
+    ],
+    Others: ["api/globals"],
+    // Modules: ["api/modules/_react_proxy_"],
+    Interfaces: [
+      // "api/interfaces/_react_proxy_.reactproxycomponent",
+      "api/interfaces/abstractbuttonprops",
+      "api/interfaces/actionprops",
+      "api/interfaces/animatedimageprops",
+      "api/interfaces/boxviewprops",
+      "api/interfaces/buttonprops",
+      "api/interfaces/checkboxprops",
+      "api/interfaces/comboboxprops",
+      "api/interfaces/datawithoffset",
+      "api/interfaces/dialprops",
+      "api/interfaces/gridviewprops",
+      "api/interfaces/imageprops",
+      "api/interfaces/lineeditprops",
+      "api/interfaces/menubarprops",
+      "api/interfaces/menuprops",
+      "api/interfaces/plaintexteditprops",
+      "api/interfaces/progressbarprops",
+      "api/interfaces/radiobuttonprops",
+      "api/interfaces/scrollareaprops",
+      "api/interfaces/sliderprops",
+      "api/interfaces/spinboxprops",
+      "api/interfaces/systemtrayiconprops",
+      "api/interfaces/tabitemprops",
+      "api/interfaces/tabprops",
+      "api/interfaces/textprops",
+      "api/interfaces/viewprops",
+      "api/interfaces/windowprops",
+    ],
+    Classes: [
+      "api/classes/rnaction",
+      "api/classes/rngridcolumn",
+      "api/classes/rngridrow",
+      "api/classes/rnmenu",
+      "api/classes/rnmenubar",
+      "api/classes/renderer",
+    ],
+  },
+  guides: {
+    "The Basics": [
+      "guides/getting-started",
+      "guides/tutorial",
+      "guides/styling",
+      "guides/layout",
+      "guides/handle-events",
+      "guides/scroll-view",
+      "guides/images",
+      "guides/networking",
+      "guides/packaging",
+    ],
+    Guides: [
+      "guides/debugging",
+      "guides/debugging-in-vscode",
+      "guides/using-native-node-modules",
+      "guides/custom-nodegui-native-plugin",
+    ],
+  },
+};

package/svelte-nodegui/website/src/components/CodeExample.js

@@ -0,0 +1,42 @@
+import React from "react";
+import { SplitView } from "../components/SplitView";
+import styled from "styled-components";
+
+const Image = styled.img`
+  max-height: 300px;
+  padding-bottom: 40px;
+`;
+
+export const CodeExample = () => {
+  const ColumnOne = () => {
+    return (
+      <div>
+        <Image src="img/code-sample.png" />
+      </div>
+    );
+  };
+  const ColumnTwo = () => {
+    return (
+      <div>
+        <h3>Written in Svelte—rendered with native code by Qt</h3>
+        <p>
+          Apps can be built completely in JavaScript. This enables native app
+          development for whole new teams of developers, and can let existing
+          native teams work much faster.
+        </p>
+
+        <p>
+          With NodeGui you get flexibility of web and performance of Native
+          desktop apps.
+        </p>
+      </div>
+    );
+  };
+  return (
+    <SplitView
+      columnOneClass={"text"}
+      columnOne={<ColumnTwo />}
+      columnTwo={<ColumnOne />}
+    />
+  );
+};