docs: update examples wordings

# What's changed? * Change example pages wordings * Add Acknowledgement banner
2022-04-11 16:43:07 +02:00
parent ae4cefefbc
commit d35eb96c1f
19 changed files with 109 additions and 27 deletions
@@ -0,0 +1,23 @@
+<template>
+  <div class="w-full bg-black text-white border-b-1 border-white">
+    <div class="max-w-11/12 md:max-w-6/12 m-auto py-4 md:(pb-12 pt-6) text-center">
+      <div>
+        <div class="font-bold text-4xl mb-4">Acknowledgement</div>
+        <strong>First off</strong>: A big thank you to the developers of
+        <a href="https://webkid.io" target="_blank" class="text-green-500">Webkid</a>. Their amazing work made it possible for me
+        to create this port to Vue 3 - without them there is no Vue Flow.
+      </div>
+      <br />
+      <div>
+        Vue Flow is built on top of existing features and code taken from
+        <a href="https://reactflow.dev" target="_blank" class="text-green-500">React Flow</a>. It replicates the basic features
+        found in React Flow (zoom, pan, graph, additional components and more) and brings them to the Vue 3 experience, with all
+        the fun reactivity and features like template slots etc. you know and love from Vue. If you're happy with Vue Flow,
+        <br />
+        <a href="https://github.com/sponsors/wbkd" target="_blank" class="text-lg font-bold text-green-500">
+          please consider supporting Webkid by donating.
+        </a>
+      </div>
+    </div>
+  </div>
+</template>
@@ -131,8 +131,8 @@ onPaneReady(({ fitView }) => {
        <div class="max-w-[500px]">
          <BoxNode class="intro">
            <div class="font-mono flex flex-col gap-4 p-4 items-center text-center">
-              <h1 class="pointer-events-none text-2xl lg:text-4xl">Visualize your ideas with Vue Flow</h1>
-              <h2 class="pointer-events-none text-lg lg:text-xl font-normal">
+              <h1 class="text-2xl lg:text-4xl">Vue Flow</h1>
+              <h2 class="text-lg lg:text-xl font-normal !border-0">
                A customizable Vue.js library for building node-based editors and diagrams.
              </h2>
            </div>
@@ -4,6 +4,7 @@

 declare module 'vue' {
  export interface GlobalComponents {
+    Acknowledgement: typeof import('./../../components/home/Acknowledgement.vue')['default']
    Additional: typeof import('./../../components/home/Additional.vue')['default']
    Banner: typeof import('./../../components/home/Banner.vue')['default']
    Basic: typeof import('./../../components/home/Basic.vue')['default']
@@ -5,9 +5,22 @@ pageClass: examples

 # Custom Connection Line

-This example shows how you can implement a custom connection line. 
+If the default connection lines aren't to your liking, or you want to expand on the existing 
+functionality you can pass a custom connection line component to Vue Flow.

-Pass the connection line component into the template slot of the `VueFlow` component.
+Simply pass a component in the designated template slot, and you're good to go.
+
+```vue:no-line-numbers
+<template>
+  <VueFlow>
+    <template #connection-line="props">
+      <MyCustomConnectionLine v-bind="props" />
+    </template>
+  </VueFlow>
+</template>
+```
+
+You can see a working example in the sandbox.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-custom-connection-line-0okgze?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,12 +5,12 @@ pageClass: examples

 # Custom Node

-One of the key features is implementing custom elements (nodes / edges) that allow you to handle any logic you want inside your nodes.
+One of the key features of Vue Flow is implementing custom elements (nodes / edges) that allow you to expand on the basic node functionality (dragging, selection etc).

 You can display any content and functionality inside a custom node. More documentation about how to set
 up a custom node can be found on the [custom nodes page](/guide/node.html#custom-nodes/).

-This example shows a basic implementation of a custom node.
+You can see a working example in the sandbox below.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-custom-node-example-wznb3q?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,12 +5,14 @@ pageClass: examples

 # Drag & Drop

-Drag and Drop Sidebar handling is not built in but can be implemented with the native HTML Drag and Drop API, as this
-example shows.
+Adding nodes to an already existing graph can be done multiple ways. To create an interactive editor, you would probably
+like them to be inserted with drag and drop.
+
+In this example we demonstrate how to build a basic Sidebar and implement drag and drop handlers to create new nodes.

 ## State access

-This example shows another key feature of Vue Flow. You can initialize the Flow state at any point before the Vue Flow
+This example shows another key feature of Vue Flow. You can initialize the Flow state at any point before the `VueFlow` component
 is actually mounted. This can be achieved by using the [`useVueFlow`](/guide/composables.html#usevueflow) composable.

 <div class="mt-6">
@@ -5,8 +5,8 @@ pageClass: examples

 # Edges

-Vue Flow comes with pre-defined edge types - bezier-, step-, smoothstep and straight-edges. In addition to the default
-edge types you can create your own custom edges. You can find more information on edge types [here](/guide/edge.html#default-edge-types).
+Vue Flow comes with four pre-defined edge types - bezier-, step-, smoothstep and straight-edges.
+In addition to the built-in edge types you can create your own custom edges. You can find more information on edge types [here](/guide/edge.html#default-edge-types).

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-edges-3jbddk?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,7 +5,8 @@ pageClass: examples

 # Empty

-You can add elements to your modelValue or push them to the state using the [graph utilities](/guide/utilities/graph).
+Similar to the drag and drop example, we can also add nodes to an empty graph on a button click, 
+which triggers a push into our elements / nodes array.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-empty-example-bcxxdv?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,7 +5,9 @@ pageClass: examples

 This example demonstrates "floating edges".

-The source and target position of the edges are getting calculated dynamically.
+The positions of the source and target nodes are calculated dynamically,
+the caveat here is, that edge-anchors are still tied to Handles (even though invisible in this example),
+so connections would, by default, only be triggered when hovering over the handles (bottom / top by default).

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-floating-edges-zfxdok?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,9 +5,9 @@ pageClass: examples

 # Hidden

-You can toggle the visibility of nodes by simply setting their `hidden` attribute to either `true` or `false`. 
+You can toggle the visibility of nodes by simply setting their `hidden` attribute to either `true` or `false`.

-Edges that are connected to a hidden node will also be hidden as to not show any edges that lead nowhere.
+Edges that are connected to a hidden node will also be hidden.

 If you set the `onlyRenderVisibleElements` prop to `true`, hidden elements will not be rendered at all instead of just hiding them with
 css. This behavior is disabled by default, meaning all elements are rendered whether they are hidden or not.
@@ -5,9 +5,10 @@ pageClass: examples

 # Basic

-This is a basic example to help you quickly get started building your own graphs. On the bottom left you see the
-Controls and on the bottom right the MiniMap component. You can see different node types (input, default, output), edge
-types (bezier, step and smoothstep), edge labels and custom styles.
+This is a basic example to help you familiarize with the basic features of Vue Flow. 
+
+On the bottom left you see the viewport-controls and on the bottom right the minimap.
+You can also see the built-in node (default, input, output) and edge (bezier, straight, step, smoothstep) types.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-basic-example-3hq147?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FBasic.vue&moduleview=1&theme=dark"
@@ -4,7 +4,10 @@ pageClass: examples
 ---
 # Interaction

-This is an example showing the different interaction options Vue Flow provides. 
+Vue Flow provides options to interact and limit interaction with the viewport and graph.
+This includes enabling/disabling zoom-scroll, pan-scroll, dragging etc.
+
+In the sandbox below you can find an example showing you how to toggle interaction options.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-interaction-example-pqzf7p?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,7 +5,7 @@ pageClass: examples

 # Nested Nodes

-One of the big new features in 0.4.0 is nested nodes. 
+Another key feature is nested nodes (or even nested flows).

 You can define parents of a node, which are then nested inside that node. 
 You can also define the boundaries of a node, i.e. if the node can be dragged outside it's parent or if it's contained to the parent 
@@ -10,8 +10,9 @@ __Changes from 0.3.x to 0.4.x__
 The "built-in" storage feature has been fully removed.
 :::

-Storing nodes and loading is easy to handle. 
-This example demonstrates a save & restore functionality using the `LocalStorage` of the browser.
+There is no built-in storage feature, however creating a save & restore feature is simple.
+
+This example demonstrates save & restore functionality using the `LocalStorage` of the browser.
 You are of course free to implement your own logic (for example fetching the data from an API that's connected to a database).

 <div class="mt-6">
@@ -5,7 +5,9 @@ pageClass: examples

 # Stress

-Vue Flow is built to be fast and tries to minimize re-renders so that your application can stay smooth as possible.
+Vue Flow is built to be fast but there are limits.
+
+Try out how many nodes you can get to render before your browser crashes.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-stress-zyr01z?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,10 +5,13 @@ pageClass: examples

 # Updatable Edge

+Existing edges can be updated, meaning their source / target position can be changed interactively.
+
+Update an edge by simply dragging it from one node to another at the edge-anchor (handles).
+
 You can enable updating edges either globally by passing the `edgesUpdatable` prop or you can enable it
 for specific edges by using the `updatable` attribute.

-Edges can be updated by simply dragging them from one node to another at the edge-anchor.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/eager-tree-c7igf6?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,7 +5,13 @@ pageClass: examples

 # Update Node

-Updating internal node data is easy. Just manipulate your node and the changes will be reflected in the graph.
+Updating internal node data is simple.
+After initializing your elements and parsing them into either `GraphNode` or `GraphEdge`
+Vue Flow will emit the changes back into your initial `ref`.
+
+That means you can manipulate any property of your original nodes, and it will trigger changes in the graph.
+
+You can of course also access the nodes directly from the state and change their properties from there.

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-update-node-example-q5hjp3?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -5,8 +5,30 @@ pageClass: examples

 # Connection Validation

-Connections can be validated before edges are created and nodes get connected. This example shows how to use validators
-for handles so only connections that have been validated are created.
+Connections can be validated before edges are created and nodes get connected. 
+
+## Using a handle in a custom node
+```vue:no-line-numbers
+<div>
+  [ ... ]
+
+  <Handle type="source" :is-valid-connection="isValidConnection" />
+</div>
+```
+
+## Passing as node option
+```ts
+const nodes = [
+  {
+    id: '1',
+    label: 'Node 1',
+    position: { x: 0 , y: 0 },
+    isValidSourcePos: (connection) => {
+      return connection.target === '2'
+    }
+  },
+]
+```

 <div class="mt-6">
  <iframe src="https://codesandbox.io/embed/vue-flow-validation-example-zxbyus?eslint=1&fontsize=14&hidenavigation=1&module=%2Fsrc%2Fcomponents%2FFlow.vue&theme=dark"
@@ -11,4 +11,6 @@ footer: MIT Licensed | Copyright © 2021-present Burak Cakmakoglu
  <Banner />
 </Suspense>

+<Acknowledgement />
+
 <Features />